OpenParcelBox/docs/fr/architecture.md

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

                    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 :

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.