191 lines
5.9 KiB
Markdown
191 lines
5.9 KiB
Markdown
|
|
|
|
# OpenParcelBox
|
|
|
|
OpenParcelBox is an open-source project that replaces the proprietary electronics of the Boks One connected parcel box with a documented, local-first, and sustainable solution.
|
|
|
|
The goal is to preserve as much of the original hardware as possible while removing dependencies on proprietary cloud services and mobile applications.
|
|
|
|
## Goals
|
|
|
|
- Local-first operation
|
|
- No subscription
|
|
- No vendor lock-in
|
|
- Open firmware
|
|
- Open hardware documentation
|
|
- Home Assistant integration
|
|
- Battery-powered design
|
|
- Reproducible hardware and software
|
|
|
|
## Current Status
|
|
|
|
The project is under active development.
|
|
|
|
Completed or validated:
|
|
|
|
- Zephyr RTOS application skeleton
|
|
- Seeed Studio XIAO nRF52840 development target
|
|
- RGB LED driver
|
|
- PCF8574 GPIO expander driver
|
|
- Development keypad scanning
|
|
- Active buzzer feedback
|
|
- Persistent six-digit access codes
|
|
- Keypad unlock flow with default development code `784512`
|
|
- Persistent NFC tag UID table and scan-mode firmware API
|
|
- Flutter mobile application with branded Android icon/splash, bilingual dark
|
|
interface, secure registration, encrypted backups, and role-aware modals
|
|
- Mobile BLE automatic reconnection and command UI for clock sync, lock
|
|
opening, history, access codes, NFC tags, and guest invitations
|
|
- Firmware BLE service for those mobile commands plus stored-state readback
|
|
- One-time access codes with automatic removal after first successful keypad use
|
|
- Phone-synchronized runtime timestamps for lock-opening logs
|
|
- Persistent seven-day opening history with power-loss time continuity
|
|
- Eight permanent and twenty temporary access-code slots, with unique random
|
|
generation and administrator-confirmed temporary-to-permanent conversion
|
|
- BLE LE Secure Connections, encrypted GATT access, and 128-bit phone identities
|
|
- First-phone administrator provisioning and named guest identities
|
|
- App-triggered NFC enrollment with stored tag names
|
|
- PN532 passive-badge reader over I2C at `0x24`, with a fixed non-renewable
|
|
15-second keypad-triggered scan window and power-down between windows
|
|
- 150 ms lock command pulse on XIAO `D9`, inactive throughout startup
|
|
- KR-S79 `COM/NC` lock state feedback on XIAO `D7` / `D8`
|
|
- Internal identity-reset button on XIAO `P1.11`
|
|
- Green-open, off-closed, red-invalid LED feedback
|
|
- Short key beeps, long valid-code beep, invalid-code beep sequence, and 2-second
|
|
open reminder beep
|
|
- Door opened / closed serial debug messages
|
|
- Firmware debug output over serial console
|
|
- One-second white RGB confirmation when the local keypad path is ready
|
|
|
|
In progress:
|
|
|
|
- Original hardware reverse engineering
|
|
- Production keypad mapping
|
|
- PN532 reader hardware validation and production integration
|
|
- Hardware validation
|
|
- BLE security and hardware interoperability validation
|
|
|
|
Planned:
|
|
|
|
- Firmware update from the mobile application
|
|
- Battery management
|
|
- Zigbee
|
|
- OTA updates
|
|
- Home Assistant integration
|
|
- Custom PCB
|
|
|
|
## Repository Structure
|
|
|
|
```text
|
|
OpenParcelBox/
|
|
+-- docs/ Project documentation
|
|
| +-- firmware/ Firmware notes and module documentation
|
|
| +-- hardware/ Hardware documentation assets
|
|
| +-- architecture.md System architecture
|
|
+-- firmware/ Zephyr firmware
|
|
| +-- app/ Main firmware application
|
|
+-- hardware/ Hardware documentation and reverse engineering
|
|
+-- homeassistant/ Home Assistant integration notes
|
|
+-- mobile-app/ Flutter mobile application and notes
|
|
+-- images/ Project logo and application background assets
|
|
+-- CHANGELOG.md
|
|
+-- LICENSE
|
|
+-- README.md
|
|
+-- ROADMAP.md
|
|
+-- TODO.md
|
|
```
|
|
|
|
Local workspace support directories such as `.vscode/`, `.venv/`, `.west/`, `tools/`, `external/`, and build directories are not part of the OpenParcelBox project source.
|
|
|
|
## Firmware
|
|
|
|
The firmware is written in C17 and uses Zephyr RTOS.
|
|
|
|
Current firmware modules:
|
|
|
|
- RGB LED
|
|
- PCF8574 GPIO expander
|
|
- Matrix keypad
|
|
- Active buzzer
|
|
- Lock control
|
|
- Lock state feedback
|
|
- Persistent access codes
|
|
- Persistent NFC tag UID storage
|
|
- BLE administration service
|
|
|
|
## Mobile App
|
|
|
|
The mobile application is developed with Flutter in:
|
|
|
|
```text
|
|
mobile-app/app/
|
|
```
|
|
|
|
The application provides local-first administrator and guest surfaces for
|
|
secure Bluetooth registration, automatic reconnection, XIAO date/time
|
|
synchronization, access-code management, NFC enrollment, guest invitation QR
|
|
codes, opening history, encrypted backup/restore, direct opening, and
|
|
authoritative firmware state readback.
|
|
|
|
Firmware documentation is available in:
|
|
|
|
```text
|
|
docs/firmware/
|
|
firmware/README.md
|
|
```
|
|
|
|
## Hardware
|
|
|
|
Current development platform:
|
|
|
|
- Seeed Studio XIAO BLE nRF52840
|
|
- PCF8574 GPIO expander
|
|
- Freenove 4x4 matrix keypad for development validation
|
|
- KR-S79 lock command on XIAO `D9`
|
|
- KR-S79 `NC` feedback on XIAO `D7`
|
|
- KR-S79 `COM` feedback reference on XIAO `D8`
|
|
- Internal identity-reset button between `GND` and XIAO `P1.11`
|
|
|
|
The XIAO nRF52840 exposes tag-side Nordic NFCT pins, which are not used as a
|
|
passive-badge reader. Badge UID reading uses a PN532 module on the shared I2C
|
|
bus at address `0x24` during development.
|
|
|
|
The production hardware is planned around a custom PCB and the original parcel box mechanical parts.
|
|
|
|
## Documentation
|
|
|
|
General project tracking:
|
|
|
|
- `ROADMAP.md`
|
|
- `TODO.md`
|
|
- `CHANGELOG.md`
|
|
|
|
Hardware and reverse-engineering notes:
|
|
|
|
- `hardware/`
|
|
- `docs/hardware/`
|
|
|
|
Firmware notes:
|
|
|
|
- `firmware/`
|
|
- `docs/firmware/`
|
|
|
|
## License
|
|
|
|
OpenParcelBox is an open-source project.
|
|
|
|
Different project components may use different licenses depending on their nature.
|
|
|
|
| Component | License |
|
|
| ------------- | ------------------ |
|
|
| Project | `LICENSE` |
|
|
| Firmware | `firmware/LICENSE` |
|
|
| Hardware | `hardware/LICENSE` |
|
|
| Documentation | `docs/LICENSE` |
|
|
|
|
## Disclaimer
|
|
|
|
OpenParcelBox is an independent open-source project.
|
|
|
|
It is not affiliated with, endorsed by, or supported by the manufacturer of the Boks One parcel box.
|