484 lines
10 KiB
Markdown
484 lines
10 KiB
Markdown
# 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.
|