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

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:

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:

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.