diff --git a/.gitignore b/.gitignore index 59758b8..434a6f5 100644 --- a/.gitignore +++ b/.gitignore @@ -3,10 +3,26 @@ # ---------------------------- .vscode/ +# ---------------------------- +# Codex +# ---------------------------- +.agents/ +.codex/ +AGENTS.md + +# ---------------------------- +# Clang +# ---------------------------- +.clangd + # ---------------------------- # Zephyr # ---------------------------- -firmware/build/ +firmware/app/build/ +external/ +west-manifest/ +.venv/ +.west/ # ---------------------------- # CMake cache @@ -48,6 +64,7 @@ _autosave-* *.temp # ---------------------------- -# Archives +# Divers # ---------------------------- -archives/ \ No newline at end of file +archives/ +tools/ \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 139afd7..fe37761 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,8 @@ -# Changelog +# Changelog All notable changes to this project will be documented in this file. -The format is based on **Keep a Changelog** and this project follows **Semantic Versioning**. +The format is based on Keep a Changelog and this project follows Semantic Versioning. --- @@ -11,28 +11,41 @@ The format is based on **Keep a Changelog** and this project follows **Semantic ### Added - Initial project structure. -- Zephyr RTOS development environment. +- Zephyr RTOS firmware baseline. - Standardized project architecture. - Firmware coding conventions. - Documentation structure. - RGB LED driver. -- GPIO Expander abstraction layer. +- GPIO expander abstraction layer. - Matrix keypad driver. +- Active buzzer driver. - Firmware component documentation. - Firmware debugging documentation. +- Firmware buzzer documentation. +- English architecture documentation in `docs/architecture.md`. ### Changed - Refactored firmware into independent components. - Standardized source file headers. - Standardized project coding style. -- Centralized board-specific definitions into `board_pins.h`. +- Centralized board-specific definitions into `board_config.h`. +- Updated project documentation to English. +- Renamed project constraint documents from `contraintes.md` to `constraints.md`. +- Updated firmware, hardware, Home Assistant, and mobile application documentation. +- Aligned hardware documentation with the active buzzer transistor driver. +- Aligned firmware documentation with C17 and the current Zephyr build tools. +- Updated project tracking documents to reflect completed RGB LED, GPIO expander, keypad, and active buzzer work. ### Fixed - Matrix keypad scanning. - GPIO expander abstraction. - Firmware build configuration. +- Removed obsolete documentation references to `board_pins.h`. +- Removed obsolete documentation references to PWM buzzer control. +- Removed stale development-environment references from project documentation. +- Removed corrupted text encoding artifacts from Markdown documentation. --- @@ -41,11 +54,11 @@ The format is based on **Keep a Changelog** and this project follows **Semantic ### Added - First public development release. - - Zephyr RTOS firmware. - RGB LED driver. -- GPIO Expander driver. +- GPIO expander driver. - Matrix keypad driver. +- Active buzzer driver. - Initial documentation. - Project roadmap. - TODO list. diff --git a/README.md b/README.md index e3ac575..3f1be1c 100644 --- a/README.md +++ b/README.md @@ -1,236 +1,135 @@ # OpenParcelBox -> 🚧 **Project Status:** Active development +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. -OpenParcelBox is an open-source project that replaces the proprietary electronics of the **Boks One** connected parcel box with a fully 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. -The project aims to preserve as much of the original hardware as possible while removing every dependency on proprietary cloud services and mobile applications. +## Goals ---- - -# Goals - -OpenParcelBox has been designed around a few simple principles. - -- No cloud dependency +- Local-first operation - No subscription - No vendor lock-in -- Fully local operation -- Battery powered -- Open hardware - Open firmware -- Fully documented -- Easy to reproduce -- Beginner-friendly +- Open hardware documentation +- Home Assistant integration +- Battery-powered design +- Reproducible hardware and software ---- - -# Current Status +## Current Status The project is under active development. -## Completed +Completed or validated: -- Development environment -- Zephyr RTOS integration -- Firmware architecture +- Zephyr RTOS application skeleton +- Seeed Studio XIAO nRF52840 development target - RGB LED driver -- GPIO Expander driver -- Matrix keypad driver -- Project documentation +- PCF8574 GPIO expander driver +- Development keypad scanning +- Active buzzer feedback +- Firmware debug output over serial console -## In Progress +In progress: +- Original hardware reverse engineering - Lock driver -- Reverse engineering +- Production keypad mapping - Hardware validation -## Planned +Planned: +- Access control - NFC - Battery management -- Bluetooth configuration -- Flutter application - Zigbee +- OTA updates - Home Assistant integration +- Mobile configuration application - Custom PCB ---- +## Repository Structure -# Features +```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/ Mobile application notes ++-- 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 -- Modular architecture -- Zephyr RTOS -- Battery powered -- Administrator PIN -- NFC support -- Bluetooth configuration -- Zigbee support -- OTA updates +The firmware is written in C17 and uses Zephyr RTOS. + +Current firmware modules: + +- RGB LED +- PCF8574 GPIO expander +- Matrix keypad +- Active buzzer + +Firmware documentation is available in: + +```text +docs/firmware/ +firmware/README.md +``` ## Hardware -- Reuse of the original lock -- Reuse of the original enclosure -- Reuse of the original keypad -- Custom PCB based on Seeed Studio XIAO BLE nRF52840 - -## Home Assistant - -- Native Zigbee integration -- ZHA compatibility -- Zigbee2MQTT compatibility -- Local control only - ---- - -# Hardware Platform - Current development platform: - Seeed Studio XIAO BLE nRF52840 -- Zephyr RTOS -- Freenove development kit -- PCF8574 GPIO Expander +- PCF8574 GPIO expander +- Freenove 4x4 matrix keypad for development validation -The production hardware will use a custom PCB specifically designed for OpenParcelBox. +The production hardware is planned around a custom PCB and the original parcel box mechanical parts. ---- +## Documentation -# Firmware Architecture +General project tracking: -The firmware follows a modular architecture. +- `ROADMAP.md` +- `TODO.md` +- `CHANGELOG.md` -Current components: +Hardware and reverse-engineering notes: -- RGB LED -- GPIO Expander -- Matrix Keypad +- `hardware/` +- `docs/hardware/` -Planned components: +Firmware notes: -- Lock -- Door Sensor -- Battery -- NFC -- Buzzer -- Zigbee +- `firmware/` +- `docs/firmware/` -Each component is fully documented and independently testable. - ---- - -# Repository Structure - -```text -OpenParcelBox -├── app/ -├── board/ -├── docs/ -│ ├── firmware/ -│ ├── hardware/ -│ ├── development/ -│ └── protocols/ -├── hardware/ -├── CHANGELOG.md -├── CONTRIBUTING.md -├── LICENSE -├── README.md -├── ROADMAP.md -└── TODO.md -``` - ---- - -# Documentation - -## General - -- ROADMAP.md -- TODO.md -- CHANGELOG.md - -## Firmware - -Documentation is available in: - -```text -docs/firmware/ -``` - -Each firmware component has its own documentation. - -## Hardware - -Reverse engineering and PCB documentation are available in: - -```text -docs/hardware/ -``` - -## Development - -Development environment documentation is available in: - -```text -docs/development/ -``` - ---- - -# Development - -Firmware development uses: - -- Zephyr RTOS -- West -- CMake -- GCC -- VSCodium - -The coding style, project structure and documentation are standardized across the entire project. - ---- - -# Roadmap - -The complete development roadmap is available in: - -- ROADMAP.md - -The current task list is available in: - -- TODO.md - ---- - -# License +## 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 | +| Component | License | +| --- | --- | +| Project | `LICENSE` | +| Firmware | `firmware/LICENSE` | +| Hardware | `hardware/LICENSE` | +| Documentation | `docs/LICENSE` | ---- - -# Contributing - -Contributions are welcome. - -Please read **CONTRIBUTING.md** before submitting issues or pull requests. - ---- - -# Disclaimer +## 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. \ No newline at end of file +It is not affiliated with, endorsed by, or supported by the manufacturer of the Boks One parcel box. diff --git a/ROADMAP.md b/ROADMAP.md index b94f8ec..c058728 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,517 +1,376 @@ -# OpenParcelBox - Roadmap +# 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. +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 is designed to be portable to other parcel boxes by adapting only the hardware layer. +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. +The firmware is based on Zephyr RTOS and follows a modular architecture to simplify maintenance and future extensions. --- -# Project Goals +## Project Goals -- No cloud dependency -- No subscription -- Local-first operation -- Battery powered -- NFC support -- 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 +- No cloud dependency. +- No subscription. +- Local-first operation. +- Battery-powered design. +- NFC support. +- 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 +## Current Progress -| Phase | Status | -| -------------------------- | :----: | -| Project initialization | ✅ | -| Documentation structure | ✅ | -| Development environment | ✅ | -| Firmware architecture | ✅ | -| RGB LED driver | ✅ | -| GPIO Expander driver | ✅ | -| Matrix keypad driver | ✅ | -| Lock driver | ⏳ | -| Battery driver | ⏳ | -| NFC driver | ⏳ | -| Buzzer driver | ⏳ | -| Power management | ⏳ | -| Bluetooth configuration | ⏳ | -| Zigbee integration | ⏳ | -| Home Assistant integration | ⏳ | -| PCB V1 | ⏳ | +| 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 | Pending | +| Battery driver | Pending | +| NFC driver | Pending | +| Power management | Pending | +| Bluetooth configuration | Pending | +| Zigbee integration | Pending | +| Home Assistant integration | Pending | +| PCB V1 | Pending | --- -# Phase 0 - Project Foundation +## Phase 0 - Project Foundation -## Objectives +Objectives: -- Create Git repository -- Define project architecture -- Define coding conventions -- Define documentation structure -- Configure Zephyr development environment +- Create the repository. +- Define the project architecture. +- Define coding conventions. +- Define the documentation structure. +- Configure the Zephyr development baseline. -## Deliverables - -- README.md -- ROADMAP.md -- TODO.md -- LICENSE -- CONTRIBUTING.md -- Documentation structure - -## Status - -- [x] Completed +Status: done. --- -# Phase 1 - Reverse Engineering +## Phase 1 - Reverse Engineering -## Objectives +Objective: document every reusable component of the original Boks One hardware. -Document every reusable component of the original Boks One hardware. +Scope: -## Hardware +- Enclosure. +- Front panel. +- Keypad layout. +- Lock mechanism. +- Battery compartment. +- Connectors and wiring. +- PCB analysis. -### Enclosure - -- External dimensions -- Internal dimensions -- Battery compartment -- Electronic compartment - -### Front Panel - -- Keypad layout -- LED locations -- NFC area -- Mechanical fixation - -### Lock - -- Mechanical operation -- Motor characteristics -- Position sensor - -### Electronics - -- Connectors -- Wiring -- PCB analysis - -## Deliverables - -- Mechanical drawings -- Reverse engineering documentation -- Electrical documentation - -## Status - -- [ ] In progress +Status: in progress. --- -# Phase 2 - Development Platform +## Phase 2 - Development Platform -## Objectives +Objective: validate the development hardware and low-level firmware modules. -Validate the development hardware. +Hardware: -## Hardware +- Seeed Studio XIAO BLE nRF52840. +- Development keypad. +- PCF8574 GPIO expander. +- Active buzzer through transistor driver. -- Seeed Studio XIAO BLE nRF52840 -- Development keypad -- PCF8574 GPIO expander +Firmware modules: -## Firmware +- RGB LED. +- GPIO expander. +- Matrix keypad. +- Active buzzer. -- Zephyr RTOS -- West -- CMake -- VSCodium - -## Drivers - -- RGB LED -- GPIO Expander -- Matrix Keypad - -## Status - -- [x] Completed +Status: in progress. --- -# Phase 3 - Hardware Validation +## Phase 3 - Hardware Validation -## Objectives +Objective: validate every reusable or newly added hardware component before integration. -Validate every reusable hardware component. +Components: -## Components +- Lock. +- Door or lock state feedback. +- Battery monitoring. +- NFC antenna. +- Buzzer. +- External LEDs. -- Lock -- Door sensor -- Battery monitoring -- NFC reader -- Buzzer - -## Validation - -Each component must be individually tested before integration. - -## Status - -- [ ] In progress +Status: in progress. --- -# Phase 4 - Firmware Core +## Phase 4 - Firmware Core -## Objectives +Objective: create the autonomous firmware. -Create the autonomous firmware. +Components: -## Components +- System initialization. +- GPIO expander. +- Keypad. +- Lock. +- Door or lock state feedback. +- Battery. +- Buzzer. +- NFC. -- System initialization -- GPIO Expander -- Keypad -- Lock -- Door sensor -- Battery -- Buzzer -- NFC +Security: -## Security +- Administrator PIN. +- PIN timeout. +- Anti brute-force logic. +- Configuration storage. -- Administrator PIN -- PIN timeout -- Anti brute-force -- Configuration storage - -## Validation - -Standalone operation without any external system. - -## Status - -- [ ] In progress +Status: planned. --- -# Phase 5 - Power Management +## Phase 5 - Power Management -## Objectives +Objective: optimize battery life. -Optimize battery life. +Features: -## Features +- Deep sleep. +- Wake-up on keypad. +- Wake-up on NFC. +- Battery monitoring. +- Low battery warning. -- Deep Sleep -- Wake-up on keypad -- Wake-up on NFC -- Battery monitoring -- Low battery warning - -## Validation - -Daily usage with long battery life. - -## Status - -- [ ] Planned +Status: planned. --- -# Phase 6 - Bluetooth +## Phase 6 - Bluetooth -## Objectives +Objective: provide local configuration through Bluetooth. -Provide local configuration through Bluetooth. +Features: -## Features +- Initial pairing. +- Administrator PIN configuration. +- NFC enrollment. +- Device information. +- Firmware information. -- Initial pairing -- Administrator PIN configuration -- NFC enrollment -- Device information -- Firmware information - -## Validation - -Complete local configuration without Home Assistant. - -## Status - -- [ ] Planned +Status: planned. --- -# MVP - Standalone OpenParcelBox +## MVP - Standalone OpenParcelBox -## Required Features +Required features: -- [ ] Standalone firmware -- [ ] Battery powered -- [ ] Keypad -- [ ] Lock -- [ ] Door sensor -- [ ] Battery monitoring -- [ ] Administrator PIN -- [ ] Administrator NFC badge -- [ ] Bluetooth configuration -- [ ] No cloud -- [ ] No subscription +- Standalone firmware. +- Battery-powered operation. +- Keypad. +- Lock. +- Door or lock state feedback. +- Battery monitoring. +- Administrator PIN. +- Administrator NFC badge. +- Bluetooth configuration. +- No cloud. +- No subscription. At this stage, the original proprietary electronics are no longer required. --- -# Phase 7 - Flutter Application +## Phase 7 - Flutter Application -## Platforms +Platforms: -- Android -- iOS +- Android. +- iOS. -## Features +Features: -- Bluetooth connection -- Device configuration -- Administrator management -- Device status -- Firmware update +- Bluetooth connection. +- Device configuration. +- Administrator management. +- Device status. +- Firmware update. -## Status - -- [ ] Planned +Status: planned. --- -# Phase 8 - User Management +## Phase 8 - User Management -## Objectives +Objective: support multiple users. -Support multiple users. +Features: -## Features +- User creation. +- User deletion. +- Permanent PINs. +- Permanent NFC badges. +- User permissions. -- User creation -- User deletion -- Permanent PINs -- Permanent NFC badges -- User permissions - -## Status - -- [ ] Planned +Status: planned. --- -# Phase 9 - Local Event History +## Phase 9 - Local Event History -## Objectives +Objective: store important events locally. -Store important events locally. +Events: -## Events +- PIN unlock. +- NFC unlock. +- Invalid PIN. +- Invalid badge. +- Low battery. +- Door opened. +- Door closed. -- PIN unlock -- NFC unlock -- Invalid PIN -- Invalid badge -- Low battery -- Door opened -- Door closed - -## Status - -- [ ] Planned +Status: planned. --- -# Standalone Product +## Phase 10 - Zigbee -## Features +Objective: add Zigbee connectivity. -- Multi-user support -- NFC -- Bluetooth -- Local history -- Complete local administration +Features: + +- Lock state. +- Door state. +- Battery level. +- Event reporting. + +Compatibility: + +- Zigbee Home Automation. +- Zigbee2MQTT. + +Status: planned. --- -# Phase 10 - Zigbee +## Phase 11 - Home Assistant -## Objectives +Objective: provide native Home Assistant integration. -Add Zigbee connectivity. +Compatibility: -## Features +- ZHA. +- Zigbee2MQTT. -- Lock state -- Door state -- Battery level -- Event reporting +Features: -## Compatibility +- Lock control. +- Door state. +- Battery. +- Event history. +- User management. +- Configuration. -- Zigbee Home Automation -- Zigbee2MQTT - -## Status - -- [ ] Planned +Status: planned. --- -# Phase 11 - Home Assistant +## Phase 12 - Temporary Access -## Objectives +Objective: support temporary access credentials. -Native Home Assistant integration. +Features: -## Compatibility +- Expiration date. +- Expiration time. +- Usage counter. +- One-time PINs. +- Temporary NFC badges. -- ZHA -- Zigbee2MQTT - -## Features - -- Lock control -- Door state -- Battery -- Event history -- User management -- Configuration - -## Status - -- [ ] Planned +Status: planned. --- -# Phase 12 - Temporary Access +## Phase 13 - OpenParcelBox PCB -## Objectives +Objective: design a dedicated PCB. -Support temporary access credentials. +Requirements: -## Features +- Based on XIAO nRF52840. +- Easy to assemble. +- Beginner friendly. +- Low power consumption. -- Expiration date -- Expiration time -- Usage counter -- One-time PINs -- Temporary NFC badges - -## Status - -- [ ] Planned +Status: planned. --- -# Phase 13 - OpenParcelBox PCB +## Phase 14 - Field Validation -## Objectives +Objective: validate the complete system. -Design a dedicated PCB. +Tests: -## Requirements +- Long-term reliability. +- Battery autonomy. +- Environmental testing. +- Lock endurance. +- Zigbee stability. +- Bluetooth stability. +- Recovery after power loss. -- Based on XIAO nRF52840 -- Easy to assemble -- Beginner friendly -- Low power consumption - -## Validation - -Fully reproducible assembly. - -## Status - -- [ ] Planned +Status: planned. --- -# Phase 14 - Field Validation +## Phase 15 - Documentation -## Objectives +Scope: -Validate the complete system. +- User documentation. +- Maker documentation. +- Developer documentation. +- Hardware documentation. +- Firmware documentation. -## Tests - -- Long-term reliability -- Battery autonomy -- Environmental testing -- Hundreds of lock cycles -- Zigbee stability -- Bluetooth stability -- Recovery after power loss - -## Status - -- [ ] Planned +Status: planned. --- -# Phase 15 - Documentation +## Version 1.0 -## User Documentation +Expected features: -- Installation -- Configuration -- Troubleshooting - -## Maker Documentation - -- Assembly -- Flashing -- PCB -- Hardware - -## Developer Documentation - -- Firmware architecture -- Hardware architecture -- APIs -- Coding conventions -- Contribution guide - -## Status - -- [ ] Planned - ---- - -# Version 1.0 - -## Expected Features - -- Standalone firmware -- Battery powered -- Bluetooth -- NFC -- Zigbee -- Home Assistant -- Flutter application -- Local history -- Permanent users -- Temporary users -- No cloud -- No subscription -- Fully open-source \ No newline at end of file +- Standalone firmware. +- Battery-powered operation. +- Bluetooth. +- NFC. +- Zigbee. +- Home Assistant. +- Flutter application. +- Local history. +- Permanent users. +- Temporary users. +- No cloud. +- No subscription. +- Fully open source. diff --git a/TODO.md b/TODO.md index a7e4c87..33e00cb 100644 --- a/TODO.md +++ b/TODO.md @@ -1,4 +1,4 @@ -# TODO - OpenParcelBox +# TODO - OpenParcelBox This document tracks the remaining work required to reach the first stable release of OpenParcelBox. @@ -6,365 +6,187 @@ Tasks are grouped by development phase and updated throughout the project. --- -# Phase 0 - Project Foundation +## Phase 0 - Project Foundation -## Repository +### Repository -- [x] Create Git repository -- [x] Create project structure -- [x] Configure Git -- [x] Create README -- [x] Create ROADMAP -- [x] Create TODO -- [x] Add LICENSE -- [x] Add CONTRIBUTING +- [x] Create repository. +- [x] Create project structure. +- [x] Create README. +- [x] Create ROADMAP. +- [x] Create TODO. +- [x] Add LICENSE files. -## Documentation +### Documentation -- [x] Create documentation tree -- [x] Create firmware documentation -- [ ] Create hardware documentation -- [ ] Create development documentation -- [ ] Create protocol documentation +- [x] Create documentation tree. +- [x] Create firmware documentation. +- [x] Create hardware documentation baseline. +- [ ] Create development documentation. +- [ ] Create protocol documentation. -## Development Environment +### Firmware Baseline -- [x] Configure Zephyr -- [x] Configure West -- [x] Configure CMake -- [x] Configure VSCodium -- [x] Configure formatting conventions -- [x] Define firmware architecture +- [x] Configure Zephyr. +- [x] Configure west and CMake. +- [x] Define firmware architecture. +- [x] Configure formatting conventions. --- -# Phase 1 - Reverse Engineering +## Phase 1 - Reverse Engineering -## Mechanical +### Mechanical -- [ ] Measure enclosure -- [ ] Measure internal space -- [ ] Measure mounting points -- [ ] Measure keypad -- [ ] Measure NFC area +- [ ] Measure enclosure. +- [ ] Measure internal space. +- [ ] Measure mounting points. +- [ ] Measure keypad. +- [ ] Measure NFC area. -## Lock +### Lock -- [ ] Validate lock mechanism -- [ ] Validate motor characteristics -- [ ] Validate limit switch +- [x] Identify lock mechanism. +- [x] Validate lock command behavior. +- [x] Validate feedback contact behavior. +- [ ] Design production lock driver circuit. -## Electronics +### Electronics -- [ ] Identify every connector -- [ ] Document PCB -- [ ] Document wiring -- [ ] Document LEDs -- [ ] Document buzzer +- [ ] Identify every connector. +- [ ] Document original PCB. +- [ ] Document wiring. +- [ ] Document LEDs. +- [x] Validate active buzzer approach. --- -# Phase 2 - Development Platform +## Phase 2 - Development Platform -## Firmware Infrastructure +### Firmware Infrastructure -- [x] RGB LED driver -- [x] GPIO Expander driver -- [x] Matrix Keypad driver -- [ ] Lock driver -- [ ] Door sensor driver -- [ ] Battery driver -- [ ] NFC driver -- [ ] Buzzer driver +- [x] RGB LED driver. +- [x] GPIO expander driver. +- [x] Matrix keypad driver. +- [x] Active buzzer driver. +- [ ] Lock driver. +- [ ] Door or lock state driver. +- [ ] Battery driver. +- [ ] NFC driver. -## Documentation +### Documentation -- [x] keypad.md -- [x] gpio_expander.md -- [ ] led.md -- [ ] lock.md -- [ ] battery.md -- [ ] nfc.md -- [ ] buzzer.md -- [ ] debug.md +- [x] keypad.md. +- [x] gpio_expander.md. +- [x] buzzer.md. +- [x] debug.md. +- [ ] led.md. +- [ ] lock.md. +- [ ] battery.md. +- [ ] nfc.md. --- -# Phase 3 - Hardware Validation +## Phase 3 - Hardware Validation -## Lock +### Lock -- [ ] Drive motor -- [ ] Validate opening pulse -- [ ] Validate opening detection -- [ ] Validate timeout -- [ ] Validate error handling +- [ ] Drive lock through the selected circuit. +- [ ] Validate opening pulse. +- [ ] Validate opening detection. +- [ ] Validate timeout. +- [ ] Validate error handling. -## Door Sensor +### Door or Lock State -- [ ] Read sensor -- [ ] Validate state changes -- [ ] Validate debounce +- [ ] Read feedback contact. +- [ ] Validate state changes. +- [ ] Validate debounce. -## Battery +### Battery -- [ ] Read voltage -- [ ] Low battery detection -- [ ] Battery calibration +- [ ] Read voltage. +- [ ] Implement low battery detection. +- [ ] Calibrate battery measurement. -## NFC +### NFC -- [ ] Initialize reader -- [ ] Read UID -- [ ] Detect badge removal +- [ ] Design antenna. +- [ ] Validate tuning network. +- [ ] Read UID. +- [ ] Detect badge removal. -## Buzzer +### Buzzer -- [ ] Single beep -- [ ] Double beep -- [ ] Error beep -- [ ] Success beep +- [x] Single keypad beep. +- [ ] Double beep. +- [ ] Error beep. +- [ ] Success beep. --- -# Phase 4 - Firmware Core +## Phase 4 - Firmware Core -## Initialization +### Initialization -- [ ] System startup -- [ ] Peripheral initialization -- [ ] Error handling +- [ ] Complete startup sequence. +- [ ] Initialize all peripherals. +- [ ] Standardize error handling. -## Access Control +### Access Control -- [ ] Administrator PIN -- [ ] PIN verification -- [ ] PIN timeout -- [ ] Anti brute-force -- [ ] Lock sequence -- [ ] Door state validation +- [ ] Administrator PIN. +- [ ] PIN verification. +- [ ] PIN timeout. +- [ ] Anti brute-force logic. +- [ ] Lock opening sequence. +- [ ] Door or lock state validation. -## Configuration +### Configuration -- [ ] Persistent storage -- [ ] Factory reset -- [ ] Version information +- [ ] Persistent storage. +- [ ] Factory reset. +- [ ] Version information. --- -# Phase 5 - Power Management +## Phase 5 - Power Management -## Battery - -- [ ] Battery monitoring -- [ ] Battery warnings - -## Low Power - -- [ ] Sleep mode -- [ ] Wake on keypad -- [ ] Wake on NFC - -## Validation - -- [ ] Measure sleep current -- [ ] Measure battery life +- [ ] Battery monitoring. +- [ ] Battery warnings. +- [ ] Sleep mode. +- [ ] Wake on keypad. +- [ ] Wake on NFC. +- [ ] Measure sleep current. +- [ ] Measure battery life. --- -# MVP - Standalone Firmware +## MVP - Standalone Firmware -## Firmware - -- [ ] Complete firmware startup -- [ ] Lock opening -- [ ] Door detection -- [ ] Battery monitoring -- [ ] Administrator PIN -- [ ] Administrator NFC badge -- [ ] Audible feedback - -## Hardware - -- [ ] Standalone operation -- [ ] Battery powered -- [ ] No cloud -- [ ] No subscription +- [ ] Complete firmware startup. +- [ ] Lock opening. +- [ ] Door or lock feedback. +- [ ] Battery monitoring. +- [ ] Administrator PIN. +- [ ] Administrator NFC badge. +- [ ] Audible feedback. +- [ ] Standalone operation. +- [ ] Battery-powered operation. +- [ ] No cloud. +- [ ] No subscription. --- -# Phase 6 - Bluetooth +## Later Phases -## Communication - -- [ ] BLE initialization -- [ ] Pairing -- [ ] Secure connection - -## Configuration - -- [ ] Administrator PIN -- [ ] Administrator badge -- [ ] Device information - ---- - -# Phase 7 - Flutter Application - -## Mobile - -- [ ] Android -- [ ] iOS - -## Features - -- [ ] Device discovery -- [ ] Bluetooth pairing -- [ ] Device configuration -- [ ] Firmware information - ---- - -# Phase 8 - User Management - -## Users - -- [ ] Create user -- [ ] Edit user -- [ ] Delete user - -## Credentials - -- [ ] Permanent PIN -- [ ] Permanent NFC badge - ---- - -# Phase 9 - Local History - -## Events - -- [ ] PIN unlock -- [ ] NFC unlock -- [ ] Invalid PIN -- [ ] Invalid badge -- [ ] Door opened -- [ ] Door closed -- [ ] Low battery - ---- - -# Phase 10 - Zigbee - -## Connectivity - -- [ ] Zigbee stack -- [ ] Network join -- [ ] Device discovery - -## Entities - -- [ ] Lock -- [ ] Door -- [ ] Battery -- [ ] Events - ---- - -# Phase 11 - Home Assistant - -## Compatibility - -- [ ] ZHA -- [ ] Zigbee2MQTT - -## Features - -- [ ] Lock control -- [ ] Door state -- [ ] Battery level -- [ ] Event reporting -- [ ] User management - ---- - -# Phase 12 - Temporary Access - -## Access Management - -- [ ] Temporary PIN -- [ ] Temporary NFC badge -- [ ] Expiration date -- [ ] Usage counter -- [ ] One-time credentials - ---- - -# Phase 13 - PCB - -## Design - -- [ ] Schematic -- [ ] ERC validation -- [ ] PCB routing -- [ ] DRC validation - -## Prototype - -- [ ] Assembly -- [ ] Electrical validation -- [ ] Mechanical validation - ---- - -# Phase 14 - Field Validation - -## Reliability - -- [ ] Long-term testing -- [ ] Battery endurance -- [ ] Lock endurance -- [ ] Recovery after reset - -## Connectivity - -- [ ] Bluetooth validation -- [ ] Zigbee validation -- [ ] Home Assistant validation - ---- - -# Phase 15 - Documentation - -## User - -- [ ] Installation guide -- [ ] Configuration guide -- [ ] Troubleshooting guide - -## Maker - -- [ ] Hardware assembly -- [ ] Firmware flashing -- [ ] PCB assembly - -## Developer - -- [ ] Firmware architecture -- [ ] Hardware architecture -- [ ] API reference -- [ ] Coding conventions - ---- - -# Version 1.0 - -## Release Checklist - -- [ ] Firmware complete -- [ ] Flutter application complete -- [ ] Zigbee complete -- [ ] Home Assistant integration complete -- [ ] PCB validated -- [ ] Documentation complete -- [ ] First public release \ No newline at end of file +- [ ] Bluetooth communication. +- [ ] Flutter mobile application. +- [ ] User management. +- [ ] Local event history. +- [ ] Zigbee connectivity. +- [ ] Home Assistant integration. +- [ ] Temporary access. +- [ ] Dedicated PCB. +- [ ] Field validation. +- [ ] Complete user, maker, and developer documentation. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..1e85fe9 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,235 @@ +# OpenParcelBox Architecture + +## Project Goal + +OpenParcelBox is an open-source project that replaces the proprietary electronics of the Boks One parcel box while reusing as much of the original mechanical, electromechanical, and visual design as possible. + +Main goals: + +- Fully local operation. +- Native Home Assistant integration. +- Zigbee communication. +- OTA updates. +- Complete documentation. +- Reproducible hardware and software. +- Low power consumption. +- Maximum reuse of original components. + +--- + +## Overview + +```text +Home Assistant + | +Zigbee (ZHA / Zigbee2MQTT) + | +OpenParcelBox + | + +-- Zephyr RTOS + +-- Seeed Studio XIAO nRF52840 + +-- Access Control + +-- Keypad + +-- NFC + +-- Lock Controller + +-- Power Manager + +-- Diagnostics + +-- OTA +``` + +--- + +## Design Principles + +### Reuse Original Hardware + +The project keeps original parts whenever doing so is useful and reliable. + +Reused parts: + +- KR-S79 lock mechanism. +- Front panel layout. +- Battery compartment. +- Internal wiring where appropriate. +- Keypad physical layout. + +The original PCB is replaced by new electronics. + +--- + +## Keypad + +The production keypad will be redesigned electrically while preserving the original front panel layout. + +Constraints: + +- Vertical 2x6 layout. +- Original front panel retained. +- Matrix keypad compatible with the Zephyr firmware. + +The current development firmware uses a Freenove 4x4 keypad through a PCF8574 GPIO expander. + +--- + +## Hardware Architecture + +The system is centered around one microcontroller: + +- Seeed Studio XIAO BLE nRF52840 + +Responsibilities: + +- Keypad scanning. +- NFC reading. +- Lock control. +- Battery monitoring. +- RGB LED status. +- Active buzzer feedback. +- Zigbee communication. +- OTA updates. + +--- + +## Firmware Architecture + +The firmware is organized into independent modules. + +### Core + +- Initialization. +- Configuration. +- Module coordination. + +### Keypad + +- Matrix scanning. +- Debounce. +- User input. + +### Buzzer + +- Short audible feedback. +- Active buzzer GPIO control. + +### NFC + +- Badge reading. +- UID validation. +- Low-power wake-up. + +### Access Control + +- Administrator codes. +- Permanent codes. +- Temporary codes. +- Anti brute-force logic. + +### Lock Controller + +- Lock actuation. +- Opening validation. +- Error handling. + +### Power Manager + +- Battery monitoring. +- Deep sleep. +- Wake-up handling. +- Power optimization. + +### Zigbee + +- Home Assistant communication. +- State publication. +- Command reception. + +### OTA + +- Download. +- Verification. +- Secure update. + +--- + +## Opening Validation + +Opening must never be validated by a fixed delay alone. + +Sequence: + +```text +SIG command + | +Opening pulse + | +Wait for COM/NC state change + | + +-- State changed: opening confirmed + | + +-- Timeout: opening error +``` + +This ensures the firmware validates a real mechanical unlock event. + +--- + +## Home Assistant + +Planned entities: + +- Lock. +- Battery. +- Last opening event. +- Diagnostics. +- Firmware version. +- Zigbee link quality. + +Planned services: + +- Open lock. +- Lock control. +- Code management. +- Restart. +- Diagnostics. + +--- + +## Security + +Principles: + +- Local-first operation. +- No mandatory cloud service. +- Strict command validation. +- Event logging. +- Attempt limiting. +- Administrator and user role separation. + +--- + +## Development + +Firmware: + +- Zephyr RTOS. + +Language: + +- C17. + +Core build tools: + +- Zephyr SDK. +- west. +- CMake. +- Ninja. + +--- + +## Future Work + +- Local event history. +- Advanced user management. +- Hardware diagnostics. +- Bluetooth Low Energy configuration. +- Support for multiple parcel box variants. diff --git a/docs/constraints.md b/docs/constraints.md new file mode 100644 index 0000000..2a2459b --- /dev/null +++ b/docs/constraints.md @@ -0,0 +1,25 @@ +# Documentation Constraints + +## Language + +- Main project documentation must be written in English. +- Additional translations may be added later if needed. + +## Durability + +- Documentation must be versioned with the project. +- Only open formats should be used. + +## Reproducibility + +- Every manufacturing step must be documented. +- Every installation step must be documented. + +## Illustrations + +- Prefer vector diagrams when possible. +- Photos must be archived in the repository when they are required for reproduction or validation. + +## Open Source + +- No proprietary document should be required to reproduce the project. diff --git a/docs/contraintes.md b/docs/contraintes.md deleted file mode 100644 index 04b243b..0000000 --- a/docs/contraintes.md +++ /dev/null @@ -1,25 +0,0 @@ -# Contraintes documentation - -## Langue - -- Documentation principale en français. -- Traductions possibles dans le futur. - -## Pérennité - -- Documentation versionnée dans Git. -- Formats ouverts uniquement. - -## Reproductibilité - -- Chaque étape de fabrication doit être documentée. -- Chaque étape d'installation doit être documentée. - -## Illustrations - -- Privilégier les schémas vectoriels. -- Les photos doivent être archivées dans le dépôt. - -## Open Source - -- Aucun document propriétaire requis pour reproduire le projet. \ No newline at end of file diff --git a/docs/fr/architecture.md b/docs/fr/architecture.md deleted file mode 100644 index b6c045f..0000000 --- a/docs/fr/architecture.md +++ /dev/null @@ -1,243 +0,0 @@ -# Architecture OpenParcelBox - -## Objectif du projet - -OpenParcelBox est un projet open source visant à remplacer l'électronique propriétaire de la Boks One tout en conservant autant que possible les éléments mécaniques, électromécaniques et esthétiques d'origine. - -Les objectifs principaux sont : - -- Fonctionnement entièrement local. -- Intégration native avec Home Assistant. -- Communication Zigbee. -- Mises à jour OTA. -- Documentation complète. -- Reproductibilité du matériel et du logiciel. -- Faible consommation énergétique. -- Réutilisation maximale des composants d'origine. - ---- - -# Vue d'ensemble - -```text - Home Assistant - │ - Zigbee (ZHA / Zigbee2MQTT) - │ - ▼ - ┌─────────────────────┐ - │ OpenParcelBox │ - │ │ - │ Zephyr RTOS │ - │ XIAO nRF52840 │ - │ │ - ├── Access Control │ - ├── Keyboard │ - ├── NFC │ - ├── Lock Controller │ - ├── Power Manager │ - ├── Diagnostics │ - └── OTA │ - └─────────────────────┘ -``` - ---- - -# Principes de conception - -## Réutilisation du matériel d'origine - -Le projet privilégie la conservation des éléments existants lorsque cela est pertinent. - -Éléments conservés : - -- Mécanisme de verrouillage KR-S79. -- Lecteur NFC. -- LEDs de façade. -- Compartiment batterie. -- Connectique interne. -- Implantation du clavier. - -Le PCB d'origine est remplacé par une nouvelle électronique. - ---- - -## Clavier - -Le clavier est entièrement redéveloppé. - -Le PCB d'origine n'est pas réutilisé. - -Contraintes : - -- disposition verticale 2 × 6 ; -- façade d'origine conservée ; -- matrice de touches compatible firmware Zephyr. - ---- - -## Architecture matérielle - -Le système repose sur un unique microcontrôleur : - -- Seeed Studio XIAO BLE nRF52840 - -Responsabilités : - -- lecture du clavier ; -- lecture NFC ; -- contrôle du verrou ; -- surveillance batterie ; -- gestion des LEDs ; -- gestion du buzzer ; -- communication Zigbee ; -- mises à jour OTA. - ---- - -## Architecture logicielle - -Le firmware est organisé en modules indépendants. - -### Core - -- Initialisation -- Configuration -- Gestion des modules - -### Keyboard - -- Lecture de la matrice -- Anti-rebond -- Saisie utilisateur - -### NFC - -- Lecture des badges -- Validation des UID -- Réveil basse consommation - -### Access Control - -- Codes administrateur -- Codes permanents -- Codes temporaires -- Anti brute-force - -### Lock Controller - -- Pilotage de la serrure -- Validation de l'ouverture -- Gestion des erreurs - -### Power Manager - -- Batterie -- Veille profonde -- Réveil -- Optimisation énergétique - -### Zigbee - -- Communication Home Assistant -- Publication des états -- Réception des commandes - -### OTA - -- Téléchargement -- Vérification -- Mise à jour sécurisée - ---- - -# Validation d'ouverture - -L'ouverture n'est jamais validée par une temporisation fixe. - -La séquence est : - -```text -Commande SIG - │ - ▼ -Impulsion d'ouverture - │ - ▼ -Attente du changement d'état COM/NC - │ - ├── OK - │ ▼ - │ Ouverture validée - │ - └── Timeout - ▼ - Erreur -``` - -Cette méthode garantit que le firmware valide une ouverture réelle du mécanisme. - ---- - -# Home Assistant - -Entités prévues : - -- verrou -- batterie -- dernière ouverture -- diagnostic -- version firmware -- qualité du lien Zigbee - -Services : - -- ouverture -- verrouillage -- gestion des codes -- redémarrage -- diagnostic - ---- - -# Sécurité - -Principes : - -- fonctionnement local ; -- aucun cloud obligatoire ; -- validation stricte des commandes ; -- journalisation des événements ; -- limitation des tentatives ; -- séparation administrateur / utilisateur. - ---- - -# Développement - -Firmware : - -- Zephyr RTOS - -Langage : - -- C++ - -Outils : - -- Zephyr SDK -- west -- CMake -- Git -- Gitea -- VSCodium - ---- - -# Évolutions futures - -- historique des événements ; -- gestion avancée des utilisateurs ; -- diagnostic matériel ; -- support Bluetooth Low Energy ; -- prise en charge de plusieurs boîtes. \ No newline at end of file diff --git a/hardware/BOM.md b/hardware/BOM.md index 13ce458..beceb46 100644 --- a/hardware/BOM.md +++ b/hardware/BOM.md @@ -1,179 +1,181 @@ -# Bill Of Materials (BOM) +# Bill of Materials (BOM) -Cette nomenclature regroupe l'ensemble des composants nécessaires à la réalisation d'OpenParcelBox. +This bill of materials lists the components currently required or planned for OpenParcelBox. -Les éléments réutilisés de la Boks One sont distingués des nouveaux composants afin de faciliter le reverse engineering et la conception du PCB. +Reused Boks One parts are separated from new components to make reverse engineering and PCB design easier to track. --- -# Contrôleur principal +## Main Controller -| Référence | Désignation | Quantité | Statut | -| ------------- | ------------------------------ | -------- | ------ | -| XIAO-NRF52840 | Seeed Studio XIAO BLE nRF52840 | 1 | Validé | +| Reference | Description | Quantity | Status | +| --- | --- | --- | --- | +| XIAO-NRF52840 | Seeed Studio XIAO BLE nRF52840 | 1 | Validated | --- -# Éléments conservés de la Boks One +## Reused Boks One Parts -| Désignation | Quantité | Statut | -| -------------------------------- | ------------ | --------- | -| Façade | 1 | Conservée | -| Mécanisme de verrouillage KR-S79 | 1 | Conservé | -| Compartiment piles (8 × AAA) | 1 | Conservé | -| Connectique interne | Selon besoin | Conservée | +| Description | Quantity | Status | +| --- | --- | --- | +| Front panel | 1 | Reused | +| KR-S79 lock mechanism | 1 | Reused | +| Battery compartment, 8x AAA | 1 | Reused | +| Internal wiring | As needed | Reused when suitable | --- -# Clavier +## Keypad -Le PCB d'origine est remplacé par un nouveau PCB compatible avec la façade d'origine. +The original keypad PCB is replaced by a new PCB compatible with the original front panel. -| Désignation | Quantité | Statut | -| --------------------- | -------- | ----------- | -| Boutons poussoirs | 12 | Nouveau PCB | -| Matrice clavier 4 × 3 | 1 | Validée | +| Description | Quantity | Status | +| --- | --- | --- | +| Push buttons | 12 | New PCB | +| 2x6 physical keypad layout | 1 | Planned production layout | +| 4x4 development matrix keypad | 1 | Validated for firmware development | --- -# NFC - -Le contrôleur NFC est assuré par le nRF52840 intégré au Seeed Studio XIAO. - -| Désignation | Quantité | Statut | -| -------------------------------------- | -------- | ----------- | -| Antenne NFC 13,56 MHz | 1 | À concevoir | -| Réseau d'accord NFC (Matching Network) | 1 | À concevoir | - ---- - -# Commande de la serrure - -L'ouverture de la serrure est réalisée par une impulsion de **+12 V** appliquée sur l'entrée **SIG**. - -| Référence | Désignation | Quantité | Statut | -| -------------------------------------------------------------- | ------------------------ | --------- | -------------- | -| MOSFET P-Channel (Logic Level) ou circuit High-Side équivalent | Commande de l'entrée SIG | 1 | À sélectionner | -| Résistances de polarisation | Selon schéma | À définir | - ---- - -# Signalisation - -Les LEDs CMS du PCB d'origine ne sont pas réutilisables. - -| Désignation | Quantité | Statut | -| ------------------ | -------- | -------------- | -| LED Rouge | 1 | À sélectionner | -| LED Verte | 1 | À sélectionner | -| LED Bleue | 1 | À sélectionner | -| Buzzer actif 3,3 V | 1 | Validé | - ---- - -# Alimentation - -| Référence | Désignation | Quantité | Statut | -| ---------------------------------------- | ------------------- | ----------- | -------------- | -| Buck 12 V → 5 V | Convertisseur DC/DC | 1 | À sélectionner | -| Circuit de mesure de la tension batterie | 1 | À concevoir | -| Protection d'alimentation | 1 | À définir | - ---- - -# Protection électrique - -| Référence | Désignation | Quantité | Statut | -| --------- | ----------------------------------------- | -------- | -------------- | -| TBD | Protection contre l'inversion de polarité | 1 | À sélectionner | - ---- - -# Connectique - -| Référence | Désignation | Quantité | Statut | -| ------------------- | ----------- | --------- | ------ | -| Connecteur clavier | 1 | À définir | -| Connecteur serrure | 1 | À définir | -| Connecteur batterie | 1 | À définir | - ---- - -# PCB - -| Référence | Désignation | Quantité | Statut | -| ---------- | ------------------------------ | -------- | ------------- | -| OPB-PCB-V1 | Carte principale OpenParcelBox | 1 | En conception | - ---- - -# Contraintes matérielles - -## Alimentation - -- Alimentation par **8 piles AAA** d'origine. -- La serrure est alimentée directement par le pack de piles. -- Le Seeed Studio XIAO est alimenté par un convertisseur **Buck 12 V → 5 V**. -- Une masse commune est utilisée pour l'ensemble du système. - -## Serrure - -- Alimentation : **8 piles AAA**. -- Ouverture par impulsion de **+12 V** sur l'entrée **SIG**. -- Validation de l'ouverture par le changement d'état du contact **COM/NC**. -- Aucune temporisation fixe n'est utilisée pour confirmer une ouverture. - -## Clavier - -- Matrice **4 × 3**. -- 12 touches. -- Disposition verticale **2 × 6**. -- Nouveau PCB compatible avec la façade d'origine. - ## NFC -- Utilisation du contrôleur NFC intégré au **nRF52840**. -- Antenne NFC intégrée au PCB. +The preferred NFC design uses the controller integrated in the nRF52840. + +| Description | Quantity | Status | +| --- | --- | --- | +| NFC antenna, 13.56 MHz | 1 | To design | +| NFC matching network | 1 | To design | --- -# Informations restant à déterminer +## Lock Control -## Priorité haute +The lock opens when a positive 8 to 24 V pulse is applied to the `SIG` input. -- Conception de l'antenne NFC. -- Sélection du composant de commande High-Side (MOSFET ou circuit dédié). -- Choix du convertisseur Buck. -- Choix des LEDs. -- Conception du circuit de mesure batterie. - -## Priorité moyenne - -- Choix des connecteurs. -- Implantation du PCB. -- Protection ESD. - -## Priorité basse - -- Optimisation de la consommation. -- Réduction du nombre de composants. -- Compatibilité avec d'autres variantes matérielles. +| Reference | Description | Quantity | Status | +| --- | --- | --- | --- | +| Logic-level P-channel MOSFET or equivalent high-side driver | `SIG` input driver | 1 | To select | +| Bias resistors | According to schematic | TBD | To define | --- -# Historique des validations +## Indicators and Audible Feedback -## V0 +The original PCB LEDs are not considered reusable in the current plan. -- Seeed Studio XIAO BLE nRF52840 retenu. -- Zephyr RTOS retenu. -- Communication Zigbee retenue. -- Façade conservée sans modification. -- Mécanisme de verrouillage KR-S79 conservé. -- Compartiment piles 8 × AAA conservé. -- Validation de l'ouverture par le contact COM/NC. -- Commande de la serrure par impulsion de +12 V sur SIG. -- Clavier redéveloppé sous forme d'une matrice 4 × 3. -- Contrôleur NFC intégré au nRF52840 retenu. -- Buzzer actif retenu. -- Alimentation du XIAO via un convertisseur Buck 12 V → 5 V. \ No newline at end of file +| Description | Quantity | Status | +| --- | --- | --- | +| Red LED | 1 | To select | +| Green LED | 1 | To select | +| Blue LED | 1 | To select | +| Active 3.3 V buzzer | 1 | Validated | +| Buzzer transistor driver | 1 | Validated concept | + +--- + +## Power Supply + +| Reference | Description | Quantity | Status | +| --- | --- | --- | --- | +| 12 V to 5 V buck converter | DC/DC converter | 1 | To select | +| Battery voltage measurement circuit | Battery monitor | 1 | To design | +| Power protection circuit | Input protection | 1 | To define | + +--- + +## Electrical Protection + +| Reference | Description | Quantity | Status | +| --- | --- | --- | --- | +| TBD | Reverse-polarity protection | 1 | To select | +| TBD | ESD protection | TBD | To select | + +--- + +## Connectors + +| Reference | Description | Quantity | Status | +| --- | --- | --- | --- | +| TBD | Keypad connector | 1 | To define | +| TBD | Lock connector | 1 | To define | +| TBD | Battery connector | 1 | To define | + +--- + +## PCB + +| Reference | Description | Quantity | Status | +| --- | --- | --- | --- | +| OPB-PCB-V1 | OpenParcelBox main board | 1 | In design | + +--- + +## Hardware Constraints + +### Power Supply + +- Power is provided by the original 8x AAA battery pack. +- The lock is powered directly by the battery pack. +- The Seeed Studio XIAO is powered through a 12 V to 5 V buck converter. +- A common ground is used across the whole system. + +### Lock + +- Supply: 8x AAA battery pack. +- Opening command: positive pulse on `SIG`. +- Opening validation: `COM/NC` state change. +- A fixed delay must not be used as the only opening confirmation. + +### Keypad + +- Production physical layout: 2x6. +- Development keypad: 4x4 matrix. +- The production keypad will use a custom PCB compatible with the original front panel. + +### NFC + +- Use the NFC controller integrated in the nRF52840. +- Integrate the NFC antenna on the PCB if validation confirms this path. + +--- + +## Remaining Decisions + +High priority: + +- NFC antenna design. +- High-side lock driver selection. +- Buck converter selection. +- LED selection. +- Battery measurement circuit design. + +Medium priority: + +- Connector selection. +- PCB placement. +- ESD protection. + +Low priority: + +- Power optimization. +- Component count reduction. +- Compatibility with other hardware variants. + +--- + +## Validation History + +### V0 + +- Seeed Studio XIAO BLE nRF52840 selected. +- Zephyr RTOS selected. +- Zigbee communication selected. +- Original front panel retained without irreversible modification. +- KR-S79 lock mechanism retained. +- 8x AAA battery compartment retained. +- Opening validation through `COM/NC` selected. +- Lock command through a positive pulse on `SIG` selected. +- Production keypad planned as a 2x6 physical layout on a custom matrix PCB. +- nRF52840 integrated NFC controller selected as the preferred path. +- Active buzzer selected and validated through a transistor driver. +- XIAO power through a 12 V to 5 V buck converter selected. diff --git a/hardware/README.md b/hardware/README.md index 6676fb1..f975108 100644 --- a/hardware/README.md +++ b/hardware/README.md @@ -1,15 +1,16 @@ -# Hardware +# Hardware -Ce dossier contient toute la partie matérielle du projet. +This directory contains the hardware documentation for OpenParcelBox. -## Contenu prévu +## Planned Content -* Schémas KiCad -* PCB -* Fichiers Gerber -* BOM (Bill Of Materials) -* Modèles 3D -* Plans mécaniques -* Documentation de câblage +- KiCad schematics. +- PCB files. +- Gerber files. +- Bill of materials. +- 3D models. +- Mechanical drawings. +- Wiring documentation. +- Reverse-engineering notes. -L'objectif est de permettre la reproduction complète de la carte électronique. +The goal is to make the electronics fully reproducible while reusing as much of the original Boks One hardware as possible. diff --git a/hardware/constraints.md b/hardware/constraints.md new file mode 100644 index 0000000..a0b787b --- /dev/null +++ b/hardware/constraints.md @@ -0,0 +1,27 @@ +# Hardware Constraints + +## Boks One V1 Compatibility + +- Reuse the original electronics enclosure when possible. +- Reuse the original external front panel. +- Reuse the original 2x6 keypad layout. +- Reuse the original battery compartment. +- Reuse the original lock mechanism when technically possible. +- Avoid irreversible modifications to the parcel box. + +## Mechanical Integration + +- The new PCB must fit inside the available volume of the original enclosure. +- Existing mounting points should be reused when possible. +- Components should remain accessible for maintenance. + +## Manufacturing + +- No 3D-printed part should be mandatory. +- 3D-printed parts are considered optional. +- Heat-sensitive materials such as PLA must not be required for outdoor installation. + +## Power Supply + +- Battery-powered operation. +- Optimized current consumption to maximize battery life. diff --git a/hardware/contraintes.md b/hardware/contraintes.md deleted file mode 100644 index 1953bbe..0000000 --- a/hardware/contraintes.md +++ /dev/null @@ -1,27 +0,0 @@ -# Contraintes matérielles - -## Compatibilité Boks One V1 - -- Réutilisation du boîtier électronique d'origine. -- Réutilisation de la façade extérieure d'origine. -- Réutilisation du clavier d'origine au format 2 × 6. -- Réutilisation du logement des piles d'origine. -- Réutilisation du système de verrouillage d'origine lorsque cela est techniquement possible. -- Aucune modification irréversible de la boîte. - -## Intégration mécanique - -- Le nouveau PCB doit tenir dans le volume disponible du boîtier d'origine. -- Les points de fixation existants doivent être réutilisés lorsque cela est possible. -- Les composants doivent rester accessibles pour la maintenance. - -## Fabrication - -- Aucune pièce imprimée en 3D ne doit être obligatoire. -- Les pièces imprimées en 3D sont considérées comme optionnelles. -- Les matériaux sensibles à la chaleur (PLA) ne doivent pas être requis pour une installation extérieure. - -## Alimentation - -- Fonctionnement sur piles. -- Consommation optimisée pour maximiser l'autonomie. \ No newline at end of file diff --git a/hardware/interfaces.md b/hardware/interfaces.md index 5000f71..b30ad59 100644 --- a/hardware/interfaces.md +++ b/hardware/interfaces.md @@ -1,121 +1,121 @@ -# Interfaces matérielles +# Hardware Interfaces -Ce document décrit le fonctionnement des interfaces matérielles indépendamment des GPIO utilisés. +This document describes the hardware interfaces independently from the GPIO assignments used by a specific board revision. --- -# Clavier +## Keypad -Type : +Production target: -- matrice 4 × 4 +- Vertical 2x6 physical layout. +- Matrix keypad implemented on a custom PCB. -Fonctionnalités : +Development target: -- anti-rebond logiciel ; -- détection des appuis ; -- compatible Zephyr. +- Freenove 4x4 matrix keypad. +- PCF8574 GPIO expander. + +Features: + +- Software debounce. +- Key press detection. +- Zephyr-compatible driver. --- -# Lecteur NFC +## NFC Reader -Le lecteur NFC d'origine est conservé. +The nRF52840 integrated NFC controller is the preferred design path. -Le protocole sera documenté dans le dossier `hardware/nfc/`. +Functions: -Fonction : +- UID reading. +- Badge validation. +- Unlock request trigger. -- lecture UID ; -- validation des badges ; -- déclenchement d'ouverture. +The antenna and matching network still need to be designed and validated. --- -# Serrure KR-S79 +## KR-S79 Lock -Commande : +Command: -- impulsion sur SIG. +- Positive pulse on `SIG`. -Validation : +Validation: -Le firmware ne valide jamais l'ouverture sur une temporisation. +The firmware must not validate opening based on a fixed delay. -La validation repose exclusivement sur le changement d'état du contact COM/NC. +Opening validation relies on the `COM/NC` contact state change. -Séquence : +Sequence: ```text -SIG - │ - ▼ -Impulsion - │ - ▼ -Attente COM/NC - │ - ├── changement détecté - │ ▼ - │ ouverture validée - │ - └── timeout - ▼ - erreur +SIG command + | +Opening pulse + | +Wait for COM/NC + | + +-- State change detected: opening confirmed + | + +-- Timeout: opening error ``` --- -# LEDs +## RGB LEDs -Les trois LEDs de façade sont conservées. +The original front LEDs are not considered reusable in the current hardware plan. -Leur pilotage sera assuré par le nouveau PCB. - -Le comportement sera défini par le firmware. +The new PCB will provide replacement red, green, and blue indicators. --- -# Buzzer +## Buzzer -Le buzzer fournit les retours sonores. +The buzzer provides audible feedback. -Exemples : +The current validated design uses an active buzzer driven through a transistor. -- ouverture validée ; -- erreur ; -- confirmation ; -- diagnostic. +Examples: + +- Key press feedback. +- Opening confirmed. +- Error feedback. +- Diagnostic feedback. --- -# Batterie +## Battery -Le compartiment batterie d'origine est conservé. +The original battery compartment is retained. -Le firmware assure : +The firmware will provide: -- mesure de tension ; -- estimation du niveau ; -- remontée des alertes. +- Voltage measurement. +- Battery level estimation. +- Low battery alerts. --- -# Zigbee +## Zigbee -Communication native avec Home Assistant. +OpenParcelBox is intended to communicate natively with Home Assistant over Zigbee. -Le firmware ne dépend pas directement d'un broker MQTT. +The firmware should not depend directly on an MQTT broker. -La conversion éventuelle est réalisée par : +Zigbee integration may be exposed through: -- ZHA ; +- ZHA. - Zigbee2MQTT. --- -# OTA +## OTA -Les mises à jour sont réalisées de manière sécurisée. +Updates must be performed securely. -Chaque image est vérifiée avant installation. \ No newline at end of file +Each firmware image must be verified before installation. diff --git a/hardware/pinout.md b/hardware/pinout.md index 9e60094..2a2b466 100644 --- a/hardware/pinout.md +++ b/hardware/pinout.md @@ -1,60 +1,50 @@ -# Pinout OpenParcelBox +# OpenParcelBox Pinout -Ce document définit l'affectation des E/S matérielles. +This document records the current hardware pin assignments. -Il constitue la référence unique pour : +It is the reference for: -- le firmware Zephyr ; -- le schéma KiCad ; -- le PCB. +- Zephyr firmware. +- KiCad schematics. +- PCB design. --- -# Microcontrôleur +## Microcontroller Seeed Studio XIAO BLE nRF52840 --- -# Affectation des GPIO +## Current Development Pin Assignments -| Fonction | Direction | Broche | -|----------|-----------|---------| -| Clavier Ligne 1 | Sortie | D0 | -| Clavier Ligne 2 | Sortie | D1 | -| Clavier Ligne 3 | Sortie | D2 | -| Clavier Ligne 4 | Sortie | D3 | -| Retour serrure COM/NC | Entrée | D4 | -| Buzzer | Sortie PWM | D5 | -| Clavier Colonne 1 | Entrée | D6 | -| Clavier Colonne 2 | Entrée | D7 | -| Clavier Colonne 3 | Entrée | D8 | -| Commande serrure SIG | Sortie | D9 | - -## GPIO réservés - -À affecter après finalisation du reverse engineering : - -- Lecteur NFC -- LEDs -- Batterie -- Extensions +| Function | Direction | Pin | Notes | +| --- | --- | --- | --- | +| Active buzzer control | Output | D0 | GPIO signal to transistor driver | +| PCF8574 I2C SDA | I/O | SDA | Development keypad GPIO expander | +| PCF8574 I2C SCL | Output | SCL | Development keypad GPIO expander | +| RGB LED red | Output | Board LED alias `led0` | On-board validation LED | +| RGB LED green | Output | Board LED alias `led1` | On-board validation LED | +| RGB LED blue | Output | Board LED alias `led2` | On-board validation LED | --- -# GPIO libres +## Planned Production Assignments -- A0 -- A1 -- A2 -- A3 -- SDA -- SCL +These signals still need to be assigned after hardware validation: + +- Lock `SIG` command. +- Lock `COM/NC` feedback. +- Production keypad matrix. +- NFC antenna and matching network. +- Battery voltage measurement. +- External status LEDs. +- Additional expansion signals. --- -Toute modification de ce document devra être répercutée : +Any modification to this document must be reflected in: -- dans le firmware ; -- dans le schéma KiCad ; -- dans le PCB. \ No newline at end of file +- The firmware board configuration. +- The KiCad schematic. +- The PCB design. diff --git a/hardware/reverse-engineering/kerong-kr-s79-20-jst.md b/hardware/reverse-engineering/kerong-kr-s79-20-jst.md index 33439e5..8d33465 100644 --- a/hardware/reverse-engineering/kerong-kr-s79-20-jst.md +++ b/hardware/reverse-engineering/kerong-kr-s79-20-jst.md @@ -1,181 +1,170 @@ -# KERONG KR-S79_20-JST +# KERONG KR-S79_20-JST -> **Statut :** Caractérisation électrique validée expérimentalement. +> **Status:** Electrical characterization experimentally validated. > -> Les informations de cette page proviennent de mesures réalisées sur une serrure neuve d'origine Boks. Elles peuvent différer d'autres variantes du KR-S79. +> The information on this page comes from measurements performed on a new original Boks replacement lock. It may differ from other KR-S79 variants. --- -# Identification +## Identification -| Élément | Valeur | -|---------|--------| -| Fabricant | KERONG | -| Modèle | KR-S79 | -| Variante | KR-S79_20-JST | -| Révision | 2023.10_KERONG | -| Date de fabrication | 17-10-2023 | -| Brevet | ZL.201821837049.2 | +| Item | Value | +| --- | --- | +| Manufacturer | KERONG | +| Model | KR-S79 | +| Variant | KR-S79_20-JST | +| Revision | 2023.10_KERONG | +| Manufacturing date | 17-10-2023 | +| Patent | ZL.201821837049.2 | --- -# Caractéristiques +## Characteristics -| Paramètre | Valeur | -|-----------|--------| -| Tension d'alimentation | 8 à 24 V DC | -| Courant maximal | 100 mA | -| Contact auxiliaire | 3 A max | -| Connecteur | JST | -| Longueur du faisceau | 20 cm | +| Parameter | Value | +| --- | --- | +| Supply voltage | 8 to 24 V DC | +| Maximum current | 100 mA | +| Auxiliary contact | 3 A max | +| Connector | JST | +| Harness length | 20 cm | --- -# Brochage constructeur +## Manufacturer Pinout -| Couleur | Fonction | -|----------|----------| -| Rouge | +V (8 à 24 V) | +| Color | Function | +| --- | --- | +| Red | +V, 8 to 24 V | | Orange | GND | -| Jaune | SIG | -| Noir | COM | -| Vert | NO | -| Blanc | NC | +| Yellow | SIG | +| Black | COM | +| Green | NO | +| White | NC | --- -# Correspondance avec le faisceau Boks +## Boks Harness Mapping -| Côté Boks | Côté serrure | Fonction | -|------------|--------------|----------| -| Bleu | Rouge | +V | -| Blanc | Orange | GND | -| Vert | Jaune | SIG | -| Jaune | Noir | COM | -| Noir | Vert | NO | -| Rouge | Blanc | NC | +| Boks Side | Lock Side | Function | +| --- | --- | --- | +| Blue | Red | +V | +| White | Orange | GND | +| Green | Yellow | SIG | +| Yellow | Black | COM | +| Black | Green | NO | +| Red | White | NC | --- -# Fonctionnement +## Operation -## Alimentation +### Power Supply -La serrure est alimentée en permanence entre : +The lock is continuously powered between: -| Broche | Fonction | -|---------|----------| -| Rouge | +8 à +24 V | +| Pin | Function | +| --- | --- | +| Red | +8 to +24 V | | Orange | GND | -Au repos, la serrure reste verrouillée. +At rest, the lock remains closed. --- -## Commande d'ouverture +### Opening Command -L'ouverture est déclenchée par une impulsion positive sur l'entrée **SIG**. +Opening is triggered by a positive pulse on the `SIG` input. -### Test validé +Validated test: -| Action | Résultat | -|--------|----------| -| SIG relié au +V | ✅ Ouverture | -| SIG relié au GND | ❌ Aucun effet | +| Action | Result | +| --- | --- | +| SIG connected to +V | Opens | +| SIG connected to GND | No effect | -Le verrou intègre donc son propre circuit de commande. +The lock therefore includes its own control electronics. --- -# Contact de retour d'état +## Feedback Contact -Le verrou possède un contact inverseur. +The lock includes a changeover contact. -## Mesures expérimentales +### Experimental Measurements -### Verrou verrouillé +#### Locked -| Mesure | Résultat | -|---------|----------| -| COM ↔ NO | Continuité | -| COM ↔ NC | Ouvert | +| Measurement | Result | +| --- | --- | +| COM to NO | Continuity | +| COM to NC | Open | -### Verrou déverrouillé +#### Unlocked -| Mesure | Résultat | -|---------|----------| -| COM ↔ NO | Ouvert | -| COM ↔ NC | Continuité | +| Measurement | Result | +| --- | --- | +| COM to NO | Open | +| COM to NC | Continuity | -> **Remarque :** +> **Note:** > -> Bien que les bornes soient sérigraphiées **NO** et **NC**, leur comportement est inversé par rapport à la convention électrique habituelle. -> -> Pour OpenParcelBox, il est recommandé de se fier aux mesures expérimentales plutôt qu'au marquage. +> OpenParcelBox relies on the experimentally measured behavior rather than assumptions from markings alone. --- -# Détection de l'état +## State Detection -Le contact change d'état dès que le loquet quitte sa position verrouillée. +The contact changes state as soon as the latch leaves the locked position. -Il n'est donc pas nécessaire d'attendre la fin complète de la course du mécanisme pour détecter le déverrouillage. +It is therefore not necessary to wait for the mechanism to complete its full travel before detecting unlocking. -Cela permet de connaître quasiment instantanément l'état du verrou. +This allows the firmware to detect the lock state almost immediately. --- -# Schéma de câblage +## Wiring Diagram ```text - +8 à 24 V - │ - │ - Rouge (+) - │ - ┌───────────────┐ - │ │ - │ KR-S79 │ - │ │ -Orange (GND) │ │ -─────────────┘ │ - │ -Jaune (SIG) ─────► Impulsion +V = ouverture - │ -Noir (COM) ──────────────────┐ - │ -Vert (NO) ───── Fermé lorsque le verrou est verrouillé - │ -Blanc (NC) ─── Fermé lorsque le verrou est déverrouillé ++8 to 24 V + | + +-- Red (+) + KR-S79 + +-- Orange (GND) + +Yellow (SIG): positive pulse to +V opens the lock +Black (COM): common feedback contact +Green (NO): closed when locked +White (NC): closed when unlocked ``` --- -# Validation +## Validation -| Fonction | Statut | -|----------|--------| -| Alimentation | ✅ Validée | -| Tension | ✅ Validée | -| Commande SIG | ✅ Validée | -| Polarité de commande | ✅ Validée | -| Contact COM | ✅ Validé | -| Contact NO | ✅ Validé | -| Contact NC | ✅ Validé | -| Détection de l'ouverture | ✅ Validée | +| Function | Status | +| --- | --- | +| Power supply | Validated | +| Voltage | Validated | +| SIG command | Validated | +| Command polarity | Validated | +| COM contact | Validated | +| NO contact | Validated | +| NC contact | Validated | +| Opening detection | Validated | --- -# Utilisation dans OpenParcelBox +## Use in OpenParcelBox -Cette serrure est entièrement compatible avec l'architecture d'OpenParcelBox. +This lock is compatible with the OpenParcelBox architecture. -Le microcontrôleur **Seeed Studio XIAO BLE nRF52840** devra : +The Seeed Studio XIAO BLE nRF52840 must: -- maintenir l'alimentation de la serrure ; -- générer une impulsion positive sur l'entrée **SIG** lors d'une demande d'ouverture ; -- surveiller le contact **COM/NC** afin de confirmer que le verrou a bien quitté sa position verrouillée. +- Keep the lock powered. +- Generate a positive pulse on `SIG` when opening is requested. +- Monitor the `COM/NC` contact to confirm that the latch has left the locked position. -Le contact **COM/NC** change d'état dès que le loquet est libéré. Il constitue donc un retour d'information fiable permettant de confirmer l'ouverture sans attendre un délai fixe. +The `COM/NC` contact changes state as soon as the latch is released. It provides reliable feedback for confirming opening without waiting for a fixed delay. -Le contact **COM/NO** n'est pas utilisé par OpenParcelBox. \ No newline at end of file +The `COM/NO` contact is not currently used by OpenParcelBox. diff --git a/hardware/reverse-engineering/reverse-engineering.md b/hardware/reverse-engineering/reverse-engineering.md index d0e85d0..e3cd8ac 100644 --- a/hardware/reverse-engineering/reverse-engineering.md +++ b/hardware/reverse-engineering/reverse-engineering.md @@ -1,185 +1,185 @@ -# Reverse Engineering Boks One +# Boks One Reverse Engineering -## Objectif +## Objective -Ce document centralise toutes les informations collectées lors de l'analyse du matériel d'origine. +This document centralizes information collected during analysis of the original Boks One hardware. -Aucune hypothèse ne doit être considérée comme validée tant qu'elle n'a pas été vérifiée expérimentalement. +No assumption should be considered validated until it has been experimentally verified. --- -# Informations générales +## General Information -| Élément | Valeur | Statut | -|---------|--------|--------| -| Modèle | Boks One | Confirmé | -| Révision | À déterminer | En attente | +| Item | Value | Status | +| --- | --- | --- | +| Model | Boks One | Confirmed | +| Revision | TBD | Pending | --- -# Alimentation +## Power Supply -## Batterie +### Battery -| Information | Valeur | Statut | -|-------------|--------|--------| -| Technologie | 8 × piles AAA | Confirmé | -| Tension nominale | 12 V (8 × 1,5 V) | Confirmé | -| Capacité | Dépend des piles utilisées | Confirmé | +| Information | Value | Status | +| --- | --- | --- | +| Technology | 8x AAA cells | Confirmed | +| Nominal voltage | 12 V, 8x 1.5 V | Confirmed | +| Capacity | Depends on selected cells | Confirmed | --- -# Clavier +## Keypad -## Configuration +### Configuration -- Format vertical **2 × 6**. +- Vertical 2x6 physical format. -## Brochage +### Pinout -| Broche | Fonction | Statut | -|---------|----------|--------| -| TBD | TBD | À identifier | +| Pin | Function | Status | +| --- | --- | --- | +| TBD | TBD | To identify | --- -# Mécanisme de verrouillage +## Lock Mechanism -## Modèle +### Model -| Information | Valeur | Statut | -|-------------|--------|--------| -| Fabricant | KERONG | Confirmé | -| Modèle | KR-S79 | Confirmé | -| Variante | KR-S79_20-JST | Confirmé | -| Révision | 2023.10_KERONG | Confirmé | -| Date de fabrication | 17-10-2023 | Confirmé | -| Brevet | ZL.201821837049.2 | Confirmé | +| Information | Value | Status | +| --- | --- | --- | +| Manufacturer | KERONG | Confirmed | +| Model | KR-S79 | Confirmed | +| Variant | KR-S79_20-JST | Confirmed | +| Revision | 2023.10_KERONG | Confirmed | +| Manufacturing date | 17-10-2023 | Confirmed | +| Patent | ZL.201821837049.2 | Confirmed | -## Caractéristiques +### Characteristics -| Paramètre | Valeur | Statut | -|-----------|--------|--------| -| Alimentation | 8 à 24 V DC | Confirmé | -| Courant maximal | 100 mA | Confirmé | -| Contact auxiliaire | COM / NO / NC (3 A max) | Confirmé | -| Connecteur | JST | Confirmé | -| Longueur du faisceau | 20 cm | Confirmé | +| Parameter | Value | Status | +| --- | --- | --- | +| Supply voltage | 8 to 24 V DC | Confirmed | +| Maximum current | 100 mA | Confirmed | +| Auxiliary contact | COM / NO / NC, 3 A max | Confirmed | +| Connector | JST | Confirmed | +| Harness length | 20 cm | Confirmed | -## Brochage constructeur +### Manufacturer Pinout -| Couleur | Fonction | -|----------|----------| -| Rouge | +V | +| Color | Function | +| --- | --- | +| Red | +V | | Orange | GND | -| Jaune | SIG | -| Noir | COM | -| Vert | NO | -| Blanc | NC | +| Yellow | SIG | +| Black | COM | +| Green | NO | +| White | NC | -## Correspondance avec le faisceau Boks +### Boks Harness Mapping -| Côté Boks | Côté serrure | Fonction | -|------------|--------------|----------| -| Bleu | Rouge | +V | -| Blanc | Orange | GND | -| Vert | Jaune | SIG | -| Jaune | Noir | COM | -| Noir | Vert | NO | -| Rouge | Blanc | NC | +| Boks Side | Lock Side | Function | +| --- | --- | --- | +| Blue | Red | +V | +| White | Orange | GND | +| Green | Yellow | SIG | +| Yellow | Black | COM | +| Black | Green | NO | +| Red | White | NC | -## Fonctionnement validé +### Validated Behavior -### Commande +#### Command -| Action | Résultat | -|--------|----------| -| Alimentation entre +V et GND | Verrou fermé | -| Impulsion SIG → +V | Ouverture | -| Impulsion SIG → GND | Aucun effet | +| Action | Result | +| --- | --- | +| Supply between +V and GND | Lock remains closed | +| Pulse SIG to +V | Opens | +| Pulse SIG to GND | No effect | -### Contact de retour +#### Feedback Contact -| État du verrou | COM ↔ NO | COM ↔ NC | -|----------------|----------|----------| -| Verrouillé | Fermé | Ouvert | -| Déverrouillé | Ouvert | Fermé | +| Lock State | COM to NO | COM to NC | +| --- | --- | --- | +| Locked | Closed | Open | +| Unlocked | Open | Closed | -### Comportement +### Behavior -Le contact **COM/NC** change d'état dès que le loquet quitte sa position verrouillée. +The `COM/NC` contact changes state as soon as the latch leaves the locked position. -Ce retour d'information permet de confirmer immédiatement le déverrouillage sans attendre la fin de la course du mécanisme. +This feedback confirms unlocking immediately without waiting for the full mechanism travel. --- -# Capteur +## Sensor -Le retour d'état est directement intégré à la serrure KERONG KR-S79 sous la forme d'un contact inverseur **COM / NO / NC**. +State feedback is integrated directly into the KERONG KR-S79 lock through a `COM / NO / NC` changeover contact. -Aucun capteur externe n'a été identifié. +No external sensor has been identified. --- -# Connecteurs +## Connectors -| Connecteur | Nombre de broches | Fonction | Statut | -|------------|-------------------|----------|--------| -| JST | 6 | Serrure KR-S79_20-JST | Confirmé | -| Clavier | À déterminer | Clavier matriciel | À identifier | +| Connector | Pin Count | Function | Status | +| --- | --- | --- | --- | +| JST | 6 | KR-S79_20-JST lock | Confirmed | +| Keypad | TBD | Matrix keypad | To identify | --- -# Mesures électriques +## Electrical Measurements -| Mesure | Valeur | Date | Commentaire | -|---------|--------|------|-------------| -| Tension alimentation verrou | 13,36 V | 2026-07 | Boîtier de 8 piles AAA neuves | -| SIG au repos | 13,36 V | 2026-07 | Mesuré par rapport au GND | -| SIG → +V | Ouverture | 2026-07 | Validation expérimentale | -| SIG → GND | Aucun effet | 2026-07 | Validation expérimentale | +| Measurement | Value | Date | Comment | +| --- | --- | --- | --- | +| Lock supply voltage | 13.36 V | 2026-07 | New 8x AAA battery pack | +| SIG at rest | 13.36 V | 2026-07 | Measured against GND | +| SIG to +V | Opens | 2026-07 | Experimentally validated | +| SIG to GND | No effect | 2026-07 | Experimentally validated | --- -# Photos +## Photos -## Carte électronique +### Electronic Board -À compléter. +To be completed. -## Clavier +### Keypad -À compléter. +To be completed. -## Serrure KR-S79_20-JST +### KR-S79_20-JST Lock -À compléter. +To be completed. -## Connecteur JST +### JST Connector -À compléter. +To be completed. --- -# Utilisation dans OpenParcelBox +## Use in OpenParcelBox -La serrure est pilotée par le **Seeed Studio XIAO BLE nRF52840**. +The lock is controlled by the Seeed Studio XIAO BLE nRF52840. -Principe retenu : +Selected principle: -1. Génération d'une impulsion positive sur **SIG**. -2. Démarrage d'un délai d'attente (timeout). -3. Surveillance du contact **COM/NC**. -4. Si **COM/NC** change d'état avant le timeout → ouverture confirmée. -5. Sinon → échec de l'ouverture. +1. Generate a positive pulse on `SIG`. +2. Start a timeout. +3. Monitor the `COM/NC` contact. +4. If `COM/NC` changes before the timeout, confirm opening. +5. Otherwise, report an opening failure. -Cette stratégie permet de confirmer le déverrouillage réel plutôt que de supposer l'ouverture après un délai fixe. +This strategy confirms a real unlock event instead of assuming opening after a fixed delay. --- -# Notes diverses +## Notes -- La variante installée par Boks est **KR-S79_20-JST**. -- Le marquage **NO / NC** correspond au comportement observé expérimentalement. -- Le verrou intègre sa propre électronique de commande ; seule une impulsion positive sur **SIG** est nécessaire pour déclencher l'ouverture. -- Toutes les informations ci-dessus ont été validées expérimentalement sur une serrure de remplacement d'origine Boks. \ No newline at end of file +- The Boks-installed variant is `KR-S79_20-JST`. +- The `NO / NC` markings match the experimentally observed behavior documented here. +- The lock includes its own control electronics; only a positive pulse on `SIG` is required to trigger opening. +- All information above was experimentally validated on an original Boks replacement lock. diff --git a/homeassistant/README.md b/homeassistant/README.md index 48d0caa..9e49cdc 100644 --- a/homeassistant/README.md +++ b/homeassistant/README.md @@ -1,10 +1,12 @@ -# Home Assistant +# Home Assistant -Ce dossier contient les éléments permettant l'intégration avec Home Assistant : +This directory contains the documentation and future integration files for Home Assistant. -- Configuration ZHA -- Configuration Zigbee2MQTT -- Automatisations -- Scripts -- Tableaux de bord -- Exemples d'intégration \ No newline at end of file +Planned content: + +- ZHA configuration notes. +- Zigbee2MQTT configuration notes. +- Automations. +- Scripts. +- Dashboards. +- Integration examples. diff --git a/homeassistant/constraints.md b/homeassistant/constraints.md new file mode 100644 index 0000000..7c7eebd --- /dev/null +++ b/homeassistant/constraints.md @@ -0,0 +1,21 @@ +# Home Assistant Constraints + +## Integration + +- Native Home Assistant integration. +- Simple installation. +- Configuration through the Home Assistant interface whenever possible. + +## Features + +- Temporary code creation. +- Permanent code creation. +- Code deletion. +- Parcel box state monitoring. +- Event history. + +## Entities + +- Entities must be clearly named. +- Entities must be compatible with Home Assistant dashboards. +- Entities must be compatible with Home Assistant automations. diff --git a/homeassistant/contraintes.md b/homeassistant/contraintes.md deleted file mode 100644 index e00c261..0000000 --- a/homeassistant/contraintes.md +++ /dev/null @@ -1,21 +0,0 @@ -# Contraintes Home Assistant - -## Intégration - -- Intégration native Home Assistant. -- Installation simple. -- Configuration via l'interface Home Assistant lorsque possible. - -## Fonctionnalités - -- Création de codes temporaires. -- Création de codes permanents. -- Suppression de codes. -- Consultation de l'état de la boîte. -- Historique des événements. - -## Entités - -- Entités clairement nommées. -- Compatibilité avec les tableaux de bord Home Assistant. -- Compatibilité avec les automatisations Home Assistant. \ No newline at end of file diff --git a/mobile-app/constraints.md b/mobile-app/constraints.md new file mode 100644 index 0000000..26333b0 --- /dev/null +++ b/mobile-app/constraints.md @@ -0,0 +1,47 @@ +# Mobile Application Constraints + +## Technologies + +- Development with Flutter. +- Android-compatible code. +- iOS compatibility is desired but not a priority for V1. +- No mandatory dependency on a cloud service. + +## Architecture + +- Clear separation between user interface, business logic, and communications. +- Modular and maintainable code. +- Centralized configuration management. + +## Operation + +- Local-first operation. +- Direct communication with OpenParcelBox whenever possible. +- Graceful degradation when the connection is lost. + +## V1 Features + +- Parcel box state display. +- Access code management. +- Temporary code creation. +- Permanent code creation. +- Code deletion. +- Recent event display. + +## User Experience + +- Simple interface for non-technical users. +- Fast access to common actions. +- Smartphone and tablet compatibility. + +## Security + +- Mandatory authentication. +- Secure storage for sensitive data. +- No user data sent to third-party services. + +## Maintenance + +- Error logging. +- Documented configuration. +- Documented build procedure. diff --git a/mobile-app/contraintes.md b/mobile-app/contraintes.md deleted file mode 100644 index e16b7b4..0000000 --- a/mobile-app/contraintes.md +++ /dev/null @@ -1,47 +0,0 @@ -# Contraintes application - -## Technologies - -- Développement avec Flutter. -- Code compatible Android. -- Compatibilité iOS souhaitée mais non prioritaire pour la V1. -- Aucune dépendance obligatoire à un service cloud. - -## Architecture - -- Séparation claire entre interface utilisateur, logique métier et communications. -- Code modulaire et maintenable. -- Gestion centralisée de la configuration. - -## Fonctionnement - -- Fonctionnement local prioritaire. -- Communication directe avec OpenParcelBox lorsque possible. -- Dégradation propre en cas de perte de connexion. - -## Fonctionnalités V1 - -- Visualisation de l'état de la boîte. -- Gestion des codes d'accès. -- Création de codes temporaires. -- Création de codes permanents. -- Suppression des codes. -- Consultation des événements récents. - -## Expérience utilisateur - -- Interface simple pour les utilisateurs non techniques. -- Temps d'accès rapide aux fonctions courantes. -- Compatibilité smartphone et tablette. - -## Sécurité - -- Authentification obligatoire. -- Stockage sécurisé des données sensibles. -- Aucune donnée utilisateur transmise à un service tiers. - -## Maintenance - -- Journalisation des erreurs. -- Configuration documentée. -- Procédure de compilation documentée. \ No newline at end of file diff --git a/zephyr-env.bat b/zephyr-env.bat deleted file mode 100644 index f4f0c13..0000000 --- a/zephyr-env.bat +++ /dev/null @@ -1,8 +0,0 @@ -@echo off - -call "%USERPROFILE%\Dev\.venv\Scripts\activate.bat" - -set ZEPHYR_BASE=%USERPROFILE%\dev\zephyrproject\zephyr -set ZEPHYR_SDK_INSTALL_DIR=%USERPROFILE%\dev\zephyr-sdk-1.0.1 - -cmd \ No newline at end of file