docs: document intentional masking in get_str() behavior

[gdellis]

Summary

Document intentional behavior in Config::get_str() - when key is not found, returns default value and ESP_OK.

Changes

• firmware/main/config.hpp: Add docstring note to get_device_name() explaining that callers who need to distinguish "stored value" vs "default" should use nvs_get_str() directly.

Notes

Rebuilt from scratch (PR #67 had unintended BLE/state_machine changes from other PRs).

Closes #49

[github-actions]

PR #68 Review: fix: add error handling to TrackerStateMachine::init()

CI Status

All checks passed:

• ✅ Check Firmware Changed
• ✅ CodeQL (actions, c-cpp, javascript-typescript, python)
• ✅ Lint (pre-commit)
• ✅ Lint C++)
• ✅ Build Firmware
• ✅ Host Tests

---

Issues Found

1. [BUG] ESP_ERROR_CHECK() in check_geofence() may cause unwanted aborts

File: state_machine.cpp:224

ble_.send_alert (alert);

Changed to:

ESP_ERROR_CHECK (ble_.send_alert (alert));

Severity: [MEDIUM]

Problem: In the geofence breach path, ESP_ERROR_CHECK() will cause an abort if send_alert() fails. This is a "fire and forget" notification path - geofence alerting is best-effort, and a BLE failure here shouldn't crash the system. The original code correctly ignored the return value since the alert is non-critical.

Recommendation: Either:

• Remove ESP_ERROR_CHECK() and keep the original behavior (log warning on failure)
• Or add explicit error logging without aborting

---

2. [BUG] Error from state_machine.init() is logged but ignored

File: main.cpp:68-70

esp_err_t sm_err = state_machine.init ();
if (sm_err != ESP_OK) {
    ESP_LOGE (TAG, "State machine init failed: %s", esp_err_to_name (sm_err));
}

Severity: [MEDIUM]

Problem: The error is logged but execution continues unconditionally. After state_machine.init() fails, the code proceeds to call state_machine.run() on an uninitialized/failed state machine, which will likely lead to undefined behavior.

Recommendation: Either:

• Return early on error (exit app_main() or restart)
• Or transition to ERROR state and have run() handle it gracefully

---

3. [BEST PRACTICE] Missing [[nodiscard]] on TrackerStateMachine::init()

File: state_machine.hpp:38

esp_err_t init ();

Severity: [LOW]

Problem: The ble.hpp changes correctly add [[nodiscard]] to all public esp_err_t returning functions, but TrackerStateMachine::init() (also returning esp_err_t) is missing the attribute. This allows callers to accidentally ignore the error.

Recommendation: Add [[nodiscard]] to state_machine.hpp:38:

[[nodiscard]] esp_err_t init ();

---

4. [BEST PRACTICE] Inconsistent error handling patterns in app_main()

File: main.cpp:40-65

Severity: [LOW]

Observation: The code has inconsistent error handling:

• GPS init failure: logged only
• Accel init failure: logged only
• Battery init failure: logged only
• State machine init: logged only (now with error capture, but same issue)
• LoRa/Accel/BLE: ESP_ERROR_CHECK() which aborts on failure

This inconsistency makes it unclear what the intended policy is (continue on non-critical failures vs abort on critical ones).

---

5. [IMPROVEMENT] static_assert byte counts are not validated against protocol

File: ble.hpp:30, 39

static_assert(sizeof(BleLocationData) == 17, "BleLocationData must be 17 bytes for BLE");
static_assert(sizeof(BleAlertData) == 18, "BleAlertData must be 18 bytes for BLE");

Severity: [LOW]

Problem: The assertions document expected sizes but don't verify they match actual protocol specifications or the BLE stack's expectations. If the BLE stack or protocol specification changes, these silently become incorrect.

Recommendation: Add a comment referencing the protocol/spec document that defines these sizes.

---

Summary

Category	Count
BUG	2
BEST PRACTICE	2
IMPROVEMENT	1

Primary concerns: Issues #1 and #2 are the most significant - both can cause unwanted system aborts or undefined behavior. The ESP_ERROR_CHECK() change in geofence is particularly questionable since BLE alerts are non-critical notifications.

opencode session  |  github run

[gdellis]

These review comments reference issues in PR #68 (TrackerStateMachine::init() error handling) and were attached to the wrong PR due to review ordering.

The issues mentioned have been addressed:

• Issue Feature: Deep Sleep with Timer and Button Wakeup #1 (ESP_ERROR_CHECK in check_geofence): Fixed in PR feat: add task watchdog timer to main loop #70 - now logs warning instead of panicking
• Issue Add GPS driver with NMEA parsing #2 (init() error ignored): Addressed in PR fix: add error handling to TrackerStateMachine::init() #68 with proper error logging
• Issue Add Catch2 unit tests for NMEA parsing #3 ([[nodiscard]] on init): Already added in PR fix: add error handling to TrackerStateMachine::init() #68

PR #72 only adds documentation for config.hpp:get_device_name() masking behavior.