OpenParcelBox/docs/architecture.md

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

Home Assistant
    |
Zigbee (ZHA / Zigbee2MQTT)
    |
OpenParcelBox
    |
    +-- Zephyr RTOS
    +-- Seeed Studio XIAO nRF52840
    +-- Access Control
    +-- Keypad
    +-- NFC
    +-- Lock Controller
    +-- Power Manager
    +-- Diagnostics
    +-- OTA

---

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 reading.
• Lock control.
• Battery monitoring.
• RGB LED status.
• Active buzzer feedback.
• Zigbee communication.
• OTA 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

• Badge reading.
• UID validation.
• Low-power wake-up.

Access Control

• Administrator codes.
• Permanent codes.
• Temporary codes.
• Anti brute-force logic.

Lock Controller

• Lock actuation.
• Opening validation.
• Error handling.

Power Manager

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

Zigbee

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

OTA

• Download.
• Verification.
• Secure update.

---

Opening Validation

Opening must never be validated by a fixed delay alone.

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

• Local event history.
• Advanced user management.
• Hardware diagnostics.
• Bluetooth Low Energy configuration.
• Support for multiple parcel box variants.