![OpenParcelBox Logo](images/openparcelbox-logo-256.png)

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