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

10 KiB
Raw Permalink Blame History

OpenParcelBox Roadmap

Presentation

OpenParcelBox is an open-source project that replaces the proprietary electronics of connected parcel boxes with an autonomous, local, and sustainable solution.

The project is currently developed and validated on a Boks One, but the architecture should remain portable to other parcel boxes by adapting the hardware layer.

The firmware is based on Zephyr RTOS and follows a modular architecture to simplify maintenance and future extensions.

Project Goals

  • No cloud dependency.
  • No subscription.
  • Local-first operation.
  • Battery-powered design.
  • NFC badge support through dedicated reader hardware.
  • Bluetooth support.
  • Zigbee support.
  • Home Assistant compatibility.
  • Android and iOS application.
  • Beginner-friendly hardware.
  • Maximum reuse of existing hardware.
  • Fully documented hardware and firmware.
  • Fully open source.

Current Progress

Phase Status
Project initialization Done
Documentation structure Done
Firmware architecture In progress
RGB LED driver Done
GPIO expander driver Done
Matrix keypad driver Done
Active buzzer driver Done
Lock driver Done
Door or lock state feedback Done
Persistent access code storage Done
Battery driver Pending
NFC credential storage and scan API Done
PN532 NFC reader driver Done
Power management Pending
Bluetooth configuration In progress
Zigbee integration Pending
Home Assistant integration Pending
PCB V1 Pending
Flutter mobile application In progress

Phase 0 - Project Foundation

Objectives:

  • Create the repository.
  • Define the project architecture.
  • Define coding conventions.
  • Define the documentation structure.
  • Configure the Zephyr development baseline.

Status: done.

Phase 1 - Reverse Engineering

Objective: document every reusable component of the original Boks One hardware.

Scope:

  • Enclosure.
  • Front panel.
  • Keypad layout.
  • Lock mechanism.
  • Battery compartment.
  • Connectors and wiring.
  • PCB analysis.

Status: in progress.

Phase 2 - Development Platform

Objective: validate the development hardware and low-level firmware modules.

Hardware:

  • Seeed Studio XIAO BLE nRF52840.
  • Development keypad.
  • PCF8574 GPIO expander.
  • Active buzzer through transistor driver.

Firmware modules:

  • RGB LED.
  • GPIO expander.
  • Matrix keypad.
  • Active buzzer.
  • Lock control.
  • Door or lock state feedback.
  • Persistent access codes.

Status: in progress.

Phase 3 - Hardware Validation

Objective: validate every reusable or newly added hardware component before integration.

Components:

  • 150 ms active-high lock command pulse, inactive throughout startup.
  • Door or lock state feedback through the KR-S79 COM/NC contact.
  • Battery monitoring.
  • PN532 development reader and production antenna/placement validation.
  • Buzzer.
  • External LEDs.

Validated so far:

  • KR-S79 opening command through XIAO D9.
  • KR-S79 COM/NC state detection through XIAO D7 / D8.
  • Door opened and door closed UART events.
  • Open-state reminder beep every 2 seconds.
  • Valid-code long beep and invalid-code beep sequence.

Status: in progress.

Phase 4 - Firmware Core

Objective: create the autonomous firmware.

Components:

  • System initialization.
  • GPIO expander.
  • Keypad.
  • Lock.
  • Door or lock state feedback.
  • Persistent six-digit access codes.
  • Battery.
  • Buzzer.
  • NFC credential storage.
  • PN532 I2C reader backend.

Security:

  • Administrator PIN.
  • Development six-digit unlock code.
  • PIN timeout.
  • Anti brute-force logic.
  • Configuration storage.

Status: in progress.

Phase 5 - Power Management

Objective: optimize battery life.

Features:

  • Deep sleep.
  • Wake-up on keypad.
  • Wake-up on dedicated NFC reader.
  • Battery monitoring.
  • Low battery warning.

Status: planned.

Phase 6 - Bluetooth

Objective: provide local configuration through Bluetooth.

Features:

  • Initial pairing.
  • Administrator PIN configuration.
  • NFC badge enrollment.
  • Device information.
  • Firmware information.

Implemented so far:

  • Flutter-side BLE scan and connection flow.
  • Draft JSON command transport for clock sync, lock opening, access-code management, and NFC tag management.
  • Firmware-side BLE command characteristic and state readback characteristic.
  • Phone-synchronized volatile firmware clock for timestamped lock-opening logs.
  • BLE LE Secure Connections, encrypted GATT permissions, and bonded peers.
  • First-phone administrator plus named guest application identities.
  • App-triggered named NFC enrollment.
  • Persistent seven-day opening history and reboot time continuity.
  • Persistent box identifier, guest invitation/revocation commands, and administrator factory reset with BLE bond removal.

Status: in progress.

MVP - Standalone OpenParcelBox

Required features:

  • Standalone firmware.
  • Battery-powered operation.
  • Keypad.
  • Lock.
  • Door or lock state feedback.
  • Battery monitoring.
  • Administrator PIN.
  • Administrator NFC badge through dedicated reader hardware.
  • Bluetooth configuration.
  • No cloud.
  • No subscription.

Implemented MVP pieces:

  • Keypad-based unlock flow.
  • Persistent six-digit code table.
  • Default development unlock code.
  • 150 ms active-high lock command pulse with no startup pulse.
  • Lock state feedback.
  • Audible and visual feedback for valid codes, invalid codes, and open state.
  • PN532 badge unlock with persistent named tags and low-power scan windows.
  • Local BLE administration with administrator and guest identities.
  • One-time access codes and persistent opening history.

At this stage, the original proprietary electronics are no longer required.

Phase 7 - Flutter Application

Platforms:

  • Android.
  • iOS.

Features:

  • Bluetooth connection.
  • Device configuration.
  • Administrator management.
  • Device status.
  • Firmware update.

Implemented so far:

  • Application shell using the project logo and background image.
  • Bluetooth scan/connect UI targeting the XIAO BLE service.
  • Phone-to-XIAO date/time sync command.
  • Direct lock-open command.
  • Random six-digit numeric code generation.
  • Permanent code management screen.
  • One-time temporary code management screen.
  • NFC tag add/remove screen.
  • Box-reader NFC enrollment with timeout, duplicate handling, and tag naming.
  • Stored code and NFC tag readback from the firmware BLE state characteristic.
  • Branded Android launcher icon and native splash screen.
  • Automatic French/English selection with a manual override.
  • Dark modal dashboard with separate administrator and guest capabilities.
  • Secure box registration, invitation QR scanning/generation, and automatic BLE reconnection.
  • AES-256-GCM password-protected application backup and restore.
  • Opening history, code limits, phone-side NFC scans, and destructive-action warnings.
  • Permanent-code editing and clipboard actions for permanent and temporary codes.
  • Secure offline state cache keyed by application identity and BLE rediscovery after backup restoration.

Status: in progress.

Phase 8 - User Management

Objective: support multiple users.

Features:

  • User creation.
  • User deletion.
  • Permanent PINs.
  • Permanent NFC badges through dedicated reader hardware.
  • User permissions.

Implemented so far:

  • One administrator identity and named guest identities stored in firmware.
  • Administrator-generated guest invitation QR codes and guest revocation.
  • Firmware-enforced administrator/guest permissions.

Remaining work:

  • Associate individual keypad codes and NFC tags with user records.
  • Expand permission granularity beyond the current administrator/guest roles.

Status: in progress.

Phase 9 - Local Event History

Objective: store important events locally.

Events:

  • PIN unlock.
  • NFC unlock through dedicated reader hardware.
  • Invalid PIN.
  • Invalid badge.
  • Low battery.
  • Door opened.
  • Door closed.

Implemented so far:

  • Persistent history of the newest 64 successful openings.
  • Seven-day retention with permanent-code, temporary-code, NFC-tag, or mobile identity source information.
  • Mobile readback and offline caching.

Remaining work:

  • Invalid credential, low-battery, and explicit door transition events.

Status: in progress.

Phase 10 - Zigbee

Objective: add Zigbee connectivity.

Features:

  • Lock state.
  • Door state.
  • Battery level.
  • Event reporting.

Compatibility:

  • Zigbee Home Automation.
  • Zigbee2MQTT.

Status: planned.

Phase 11 - Home Assistant

Objective: provide native Home Assistant integration.

Compatibility:

  • ZHA.
  • Zigbee2MQTT.

Features:

  • Lock control.
  • Door state.
  • Battery.
  • Event history.
  • User management.
  • Configuration.

Status: planned.

Phase 12 - Temporary Access

Objective: support temporary access credentials.

Features:

  • Expiration date.
  • Expiration time.
  • Usage counter.
  • One-time PINs.
  • Temporary NFC badges through dedicated reader hardware.

Implemented so far:

  • One-time six-digit PINs removed after their first successful keypad use.
  • Guest creation and removal of temporary PINs.

Remaining work:

  • Date/time expiration.
  • Configurable usage counters.
  • Temporary NFC badges.

Status: in progress.

Phase 13 - OpenParcelBox PCB

Objective: design a dedicated PCB.

Requirements:

  • Based on XIAO nRF52840.
  • Easy to assemble.
  • Beginner friendly.
  • Low power consumption.

Status: planned.

Phase 14 - Field Validation

Objective: validate the complete system.

Tests:

  • Long-term reliability.
  • Battery autonomy.
  • Environmental testing.
  • Lock endurance.
  • Zigbee stability.
  • Bluetooth stability.
  • Recovery after power loss.

Status: planned.

Phase 15 - Documentation

Scope:

  • User documentation.
  • Maker documentation.
  • Developer documentation.
  • Hardware documentation.
  • Firmware documentation.

Implemented so far:

  • Firmware module and BLE protocol documentation.
  • Development hardware pinout, BOM, interfaces, and lock reverse engineering.
  • Mobile application behavior and build documentation.

Status: in progress.

Version 1.0

Expected features:

  • Standalone firmware.
  • Battery-powered operation.
  • Bluetooth.
  • NFC badge support through dedicated reader hardware.
  • Zigbee.
  • Home Assistant.
  • Flutter application.
  • Local history.
  • Permanent users.
  • Temporary users.
  • No cloud.
  • No subscription.
  • Fully open source.
View Git Blame Copy Permalink