OpenParcelBox/firmware/README.md

OpenParcelBox Firmware

This directory contains the OpenParcelBox firmware.

---

Goals

The firmware is responsible for:

• Keypad management.
• Access code handling.
• Lock mechanism control.
• Audible and visual feedback.
• PN532 NFC badge reading.
• Secure BLE administration.

Planned responsibilities:

• Battery monitoring and low-power system modes.
• Zigbee and Home Assistant integration.
• Secure firmware updates.

---

Hardware Platform

Main board:

• Seeed Studio XIAO BLE nRF52840

Microcontroller:

• Nordic nRF52840

---

Technologies

Framework:

• Zephyr RTOS

Language:

• C17

Core build tools:

• Zephyr SDK
• west
• CMake
• Ninja

---

Current Structure

firmware/
+-- app/              Main Zephyr application
    +-- include/      Board-level configuration headers
    +-- src/          Firmware modules

---

Current Modules

Core

System startup and module initialization.

RGB LED

On-board status LED driver.

GPIO Expander

PCF8574 I2C GPIO expander abstraction layer.

Keypad

Development keypad matrix scanning through the GPIO expander.

Buzzer

Active buzzer control through a GPIO-driven transistor.

Lock Control

KR-S79 unlock command through a 150 ms active-high pulse on XIAO pin D9. The output is configured inactive and never pulses during initialization.

Lock State

KR-S79 COM/NC feedback contact detection using NC on XIAO D7 and COM on XIAO D8.

Access Codes

Persistent storage for up to 8 permanent and 20 temporary/one-time six-digit unlock codes.

NFC Tags

Persistent storage for NFC tag UIDs and a PN532 passive-badge reader on the shared I2C bus at address 0x24. The first keypad press opens one fixed 15-second scan window; the reader remains in power-down mode otherwise.

Bluetooth

BLE administration service for the Flutter application, with a JSON command characteristic and a readable/notifiable state characteristic. Authenticated state is transferred as 480-byte pages so complete history and credential lists can exceed the 512-byte GATT attribute-value limit safely.

---

Development Philosophy

The firmware should prioritize:

• Simplicity.
• Robustness.
• Low power consumption.
• Maintainability.
• Independence from cloud services.

---

Current Status

The current firmware is a hardware validation application.

Implemented:

• RGB LED status feedback.
• PCF8574 GPIO expander access.
• 4x4 development keypad scanning.
• Active buzzer feedback on accepted key presses.
• Long success beep on valid access code.
• Three short beeps on invalid access code.
• One short reminder beep every 2 seconds while COM/NC reports open.
• Persistent six-digit access code storage.
• Persistent NFC tag UID storage with default development UID 60:4F:E2:B5.
• BLE administration service for clock sync, direct opening, access-code management, NFC tag management, and state readback.
• One-time access codes removed automatically after first successful keypad use.
• Runtime lock-opening logs with phone-synchronized timestamps when available.
• PN532 UID polling, mobile enrollment, stored-tag unlock, history, and I2C-wakeable power-down outside fixed 15-second scan windows.
• Lock command pulse on XIAO pin D9.
• Lock state feedback through the KR-S79 COM/NC contact.
• Door opened / closed debug output.
• Serial debug output.

In progress or planned:

• Production keypad mapping.
• Battery monitoring.
• Physical PN532 range/interference validation and production reader layout.
• Zigbee.
• OTA updates.