# 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.