tony/OpenParcelBox
1
0
Fork 0
Code Actions Packages Releases Wiki Activity
Files
main
OpenParcelBox/docs/architecture.md
T

5.3 KiB
Raw Permalink Blame History

OpenParcelBox Architecture

Project Goal

OpenParcelBox is an open-source project that replaces the proprietary electronics of the Boks One parcel box while reusing as much of the original mechanical, electromechanical, and visual design as possible.

Main goals:

  • Fully local operation.
  • Native Home Assistant integration.
  • Zigbee communication.
  • OTA updates.
  • Complete documentation.
  • Reproducible hardware and software.
  • Low power consumption.
  • Maximum reuse of original components.

Overview

Flutter mobile application
    |
Secure BLE administration
    |
OpenParcelBox firmware on Zephyr RTOS
    +-- Keypad and access codes
    +-- PN532 NFC reader and stored tags
    +-- Lock command and COM/NC feedback
    +-- Audible, visual, and serial diagnostics

Planned: Home Assistant via Zigbee (ZHA / Zigbee2MQTT)
Planned: battery manager and secure firmware update

Design Principles

Reuse Original Hardware

The project keeps original parts whenever doing so is useful and reliable.

Reused parts:

  • KR-S79 lock mechanism.
  • Front panel layout.
  • Battery compartment.
  • Internal wiring where appropriate.
  • Keypad physical layout.

The original PCB is replaced by new electronics.

Keypad

The production keypad will be redesigned electrically while preserving the original front panel layout.

Constraints:

  • Vertical 2x6 layout.
  • Original front panel retained.
  • Matrix keypad compatible with the Zephyr firmware.

The current development firmware uses a Freenove 4x4 keypad through a PCF8574 GPIO expander.

Hardware Architecture

The system is centered around one microcontroller:

  • Seeed Studio XIAO BLE nRF52840

Responsibilities:

  • Keypad scanning.
  • NFC credential coordination.
  • Lock control.
  • RGB LED status.
  • Active buzzer feedback.

Planned responsibilities:

  • Battery monitoring and system sleep.
  • Zigbee communication.
  • Secure firmware updates.

Firmware Architecture

The firmware is organized into independent modules.

Core

  • Initialization.
  • Configuration.
  • Module coordination.

Keypad

  • Matrix scanning.
  • Debounce.
  • User input.

Buzzer

  • Short audible feedback.
  • Active buzzer GPIO control.

NFC

  • UID validation.
  • Fixed 15-second keypad-triggered scan windows.
  • Administrator-triggered enrollment through the mobile application.
  • PN532 power-down outside active scan windows.

The nRF52840 integrated NFCT peripheral is tag-side NFC-A hardware. Passive badge UID reading currently uses a PN532 module on the shared I2C bus; its production placement and antenna implementation remain to be validated.

Access Control

  • Eight permanent six-digit codes.
  • Twenty one-time six-digit codes.
  • Ten named NFC tags.
  • Administrator and named guest mobile identities.

Attempt limiting and more granular credential ownership remain planned.

Lock Controller

  • 150 ms lock actuation pulse.
  • Continuous COM/NC state feedback.
  • Open-state LED, serial, and buzzer feedback.

The current implementation provides actuation and continuous feedback. The time-bounded command-result validation and explicit error path remain planned.

Bluetooth

  • BLE LE Secure Connections and encrypted GATT access.
  • Administrator and named guest application identities.
  • Paginated authoritative state readback for the Flutter application.
  • Commands for opening, clock synchronization, credentials, guests, NFC enrollment, and factory reset.

Opening History

  • Persistent storage of the newest 64 successful openings.
  • Seven-day retention.
  • Permanent-code, temporary-code, NFC-tag, or mobile-identity source.

Power Manager (Planned)

  • Battery monitoring.
  • Deep sleep.
  • Wake-up handling.
  • Power optimization.

Zigbee (Planned)

  • Home Assistant communication.
  • State publication.
  • Command reception.

OTA (Planned)

  • Download.
  • Verification.
  • Secure update.

Opening Feedback and Planned Validation

The current firmware sends a 150 ms command pulse and independently monitors the KR-S79 COM/NC contact. That feedback drives the green open indicator, door transition logs, and the reminder beep every 2 seconds.

Correlating an opening request with a time-bounded COM/NC transition and reporting an explicit opening failure remain to be implemented. The target sequence is:

Sequence:

SIG command
    |
Opening pulse
    |
Wait for COM/NC state change
    |
    +-- State changed: opening confirmed
    |
    +-- Timeout: opening error

This ensures the firmware validates a real mechanical unlock event.

Home Assistant

Planned entities:

  • Lock.
  • Battery.
  • Last opening event.
  • Diagnostics.
  • Firmware version.
  • Zigbee link quality.

Planned services:

  • Open lock.
  • Lock control.
  • Code management.
  • Restart.
  • Diagnostics.

Security

Principles:

  • Local-first operation.
  • No mandatory cloud service.
  • Strict command validation.
  • Event logging.
  • Attempt limiting.
  • Administrator and user role separation.

Development

Firmware:

  • Zephyr RTOS.

Language:

  • C17.

Core build tools:

  • Zephyr SDK.
  • west.
  • CMake.
  • Ninja.

Future Work

  • Advanced user management.
  • Hardware diagnostics.
  • Battery monitoring and power optimization.
  • Zigbee and Home Assistant integration.
  • Secure firmware updates.
  • Support for multiple parcel box variants.
View Git Blame Copy Permalink