5.4 KiB
Firmware Debug
Purpose
This document describes the debugging methods used during the development of the OpenParcelBox firmware.
The objective is to provide simple diagnostic tools that work even when a debugger is unavailable.
Debug Methods
The firmware currently supports the following debugging methods:
- UART console (
printf) - On-board RGB LED
- Bluetooth state and command diagnostics
- PN532/NFC UART diagnostics
Additional methods may be added later:
- Zigbee diagnostics
- Home Assistant diagnostic entities
UART Console
The UART console is the primary debugging interface during firmware development.
Example:
printf("Initialization completed.\n");
printf("Key pressed: %c\n", key);
UART should be preferred whenever a serial connection is available.
RGB LED Status Codes
The onboard RGB LED is used to quickly identify the firmware state.
Startup
The LED remains off during early startup, then turns white for one second when the local keypad path is ready. Peripheral failures are reported over UART and do not currently use a dedicated fatal LED state.
Runtime
When the local hardware path is ready, the red, green, and blue LED channels turn on together (white) for one second immediately before the keypad loop starts. Persistent storage and Bluetooth are deliberately initialized afterwards in background threads, so neither can prevent this indication.
RGB LED failure is non-fatal: the firmware continues with keypad and Bluetooth startup instead of returning silently. Persistent credential/history failures are also non-fatal; keypad access falls back to the in-memory development code and keypad initialization is retried once per second.
| Color | Meaning |
|---|---|
| Off | Idle / lock closed |
| Green | Lock state feedback reports open |
| Blue | NFC credential scan mode active |
| Red | Invalid six-digit access code |
Current Diagnostic Sequence
Current startup sequence:
- Install the fallback code and default clock in RAM without reading flash.
- Initialize the RGB LED, lock output, buzzer, lock feedback, and keypad.
- Keep D9 inactive throughout initialization.
- Show white for one second when the local keypad path is ready.
- Start persistent Settings/NVS loading in a dedicated services thread.
- Start Bluetooth in its own thread after the stored application state loads.
- Enter the keypad loop regardless of storage or Bluetooth progress.
Persistent Settings callbacks use static staging buffers. Large history and identity records are never allocated on a thread stack during boot.
While the lock state feedback reports open, the firmware emits one short reminder beep every 2 seconds.
A valid six-digit access code triggers one long success beep before the opening pulse.
UART Examples
Keypad:
Key pressed: 1
Key pressed: 5
Key pressed: 6
Received valid access code
Lock open requested source=keypad timestamp_ms=1784135045000
Door opened timestamp_ms=1784135045050
Lock state:
Door opened timestamp_ms=1784135045050
Door open reminder beep
Door closed
PN532 reader:
Scan NFC: ON
NFC detected: 60:4F:E2:B5
NFC valid
Lock open requested source=nfc timestamp_ms=1784135045000
Scan NFC: OFF
Bluetooth command path:
BLE advertising: OpenParcelBox
BLE clock synchronized: 1784135040000
Lock open requested source=ble timestamp_ms=1784135045000
A repeated BLE command failed: -13 means the encrypted BLE link is working,
but the application identity key in the command is not authorized by the box.
This commonly happens after restoring a phone backup that does not match the
administrator identity still stored in the XIAO NVS area.
Internal identity reset button:
Internal identity reset button pressed
Identity reset requested from internal button
Identity reset complete
BLE bonds cleared after reset
Internal identity reset button released
The internal reset button is wired between GND and GPIO1 pin 11
(P1.11) and uses the firmware pull-up, so the pressed state is active low.
Holding it for three seconds clears
only administrator and guest app identities plus stored BLE bonds. It does not
erase access codes, NFC tags, history, or the box name. The blue LED blinks for
a few seconds after the reset starts. The UF2 bootloader drive does not erase
NVS by itself.
Serial Console
The firmware uses the USB CDC serial console for printf and printk
diagnostics. The interactive Zephyr shell and I2C shell are intentionally
disabled so they cannot compete with the console for the same CDC backend.
Hardware-level I2C, keypad, LED, flash, lock-feedback, settings, and secure-BLE
checks are provided by the standalone diagnostic UF2 under
firmware/diagnostic/.
Production Firmware
The production firmware should not rely on the UART console.
Diagnostics should instead use:
- RGB LED
- Zigbee diagnostic messages
- Home Assistant entities
- Error reporting through the application
Future Improvements
Planned debugging features:
- Configurable log levels
- Persistent error codes
- Diagnostic mode
- Self-test during startup
- Hardware validation report
- Watchdog diagnostics
Notes
Debugging features should remain lightweight to minimize firmware size and power consumption.
Development-only diagnostics should be removable without affecting the application logic.