OpenParcelBox/CHANGELOG.md

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.

---

[Unreleased]

Fixed

• Aligned project documentation with the implemented PN532, BLE, mobile, opening-history, user-role, one-time-code, 150 ms lock-pulse, and diagnostic behavior, while keeping unfinished timeout, power, Zigbee, and Home Assistant work explicitly marked as pending.
• Restored explicit 2-second open-door reminder diagnostics and increased the D9 lock-control pulse from 100 ms to 150 ms so mechanical relay stages have more time to present SIG without excessive coil-on time.
• Added a clipboard action to permanent and temporary access-code rows in the mobile application, positioned before the edit action.
• Matched NFC access feedback to keypad-code feedback: authorized badges use the long success beep, while unauthorized badges and duplicate enrollment attempts use the same three-beep invalid sequence.
• Reworked box-reader NFC enrollment into an administrator-only 15-second BLE flow with an active waiting modal, in-modal errors, post-detection naming, cancellation, duplicate detection, and authoritative tag-list refresh.
• Prevented generated permanent and temporary codes from colliding with any active code, including across code kinds, and made firmware reject exclusive creation when the value already exists.
• Added manual six-digit permanent-code editing with a numeric OTP-style input, continuous multi-digit backspace behavior, and explicit confirmation before converting a matching temporary code to permanent.
• Kept the final code card above the Android navigation area with the same visible bottom inset as the modal's side spacing.
• Persisted each box's last authenticated BLE state in secure mobile storage so history, permanent and one-time codes, NFC tags, and guests remain visible after restarting the application while the box is out of range.
• Marked restored backups and guest QR invitations for BLE rediscovery so a new phone creates its own Android bond before authenticating with the transferred OpenParcelBox identity key.
• Removed the matching Android Bluetooth bond when a user forgets a box from the application, while leaving firmware data unchanged unless factory reset was explicitly selected.
• Kept the cached dashboard immediately available while startup reconnection runs in the background or the box remains out of range.
• Prevented ordinary Android BLE connection timeouts from deleting a valid bond, and added scan-based recovery when a saved private BLE address changes.
• Reassembled authenticated BLE state from 480-byte pages so code, NFC-tag, opening-history, and guest data no longer produce JSON truncated at the 512-byte GATT attribute limit.
• Removed redundant state-change notifications after mobile BLE commands to prevent explicit and automatic state reads from racing each other.

Added

• Added PN532 passive-tag detection over the shared I2C bus at 7-bit address 0x24, including firmware-version probing, ISO/IEC 14443-A UID reads, mobile enrollment, stored-tag unlock, history, and UART diagnostics.
• Added a fixed 15-second NFC scan window started only by the first keypad press; additional presses cannot extend it, and the PN532 enters I2C-wakeable power-down mode outside scan windows.
• Internal identity-reset button on XIAO P1.11: holding it for three seconds clears administrator and guest app identities plus BLE bonds without erasing access codes, NFC tags, history, or the box name.
• One-second white RGB indication when firmware initialization completes and the keypad loop is ready.
• Branded Android launcher icon and native splash screen using the project assets.
• French and English mobile UI with automatic phone-language selection and a manual override.
• Dark mobile dashboard, shortcut bar, styled modals, code limits, opening history, phone-side NFC UID scanning, and administrator/guest role controls.
• Secure saved-box records, automatic BLE reconnection, invitation QR generation/scanning, and guest revocation.
• AES-256-GCM password-protected mobile backup and restore using a PBKDF2-SHA256 derived key.
• Persistent box names and administrator factory reset with BLE bond removal.
• Persistent seven-day opening history for permanent codes, temporary codes, named NFC tags, and named mobile identities.
• Fallback time 2026-06-01T00:00:00Z and reboot continuity from the newest persisted opening event.
• Eight permanent and twenty temporary access-code slots.
• BLE LE Secure Connections, AES-CCM encrypted GATT access, persistent bonding, and 128-bit administrator/guest application identities.
• First-phone administrator provisioning without exposing the stored key.
• App-triggered NFC enrollment with persistent tag names.
• Dashboard synchronization shortcut and automatic mobile refresh from compact firmware state-change notifications.
• Persistent administrator-registration progress and error screen with an explicit return action.
• Persistent timestamp for the most recent successful mobile settings backup.
• Mobile offline dashboard banner with a reconnect shortcut and read-only access to cached history, codes, NFC tags, and guests.
• Initial project structure.
• Zephyr RTOS firmware baseline.
• Standardized project architecture.
• Firmware coding conventions.
• Documentation structure.
• RGB LED driver.
• GPIO expander abstraction layer.
• Matrix keypad driver.
• Active buzzer driver.
• Firmware component documentation.
• Firmware debugging documentation.
• Firmware buzzer documentation.
• Firmware lock control documentation.
• English architecture documentation in docs/architecture.md.
• Persistent six-digit access code storage.
• Persistent NFC tag UID storage with default development UID 60:4F:E2:B5.
• NFC scan-mode application flow triggered by keypad activity.
• Flutter mobile application shell in mobile-app/app.
• Mobile application use of the root images/ logo and background.jpg assets.
• Mobile BLE scan/connect flow targeting the OpenParcelBox XIAO service.
• Mobile commands for XIAO clock synchronization, direct lock opening, access-code management, and NFC tag management.
• Firmware BLE administration service with JSON command writes and stored-state readback.
• Volatile phone-synchronized firmware clock for lock-opening log timestamps.
• One-time access codes that are removed after first successful keypad use.
• Lock control pulse on XIAO pin D9.
• Lock state feedback detection using KR-S79 COM/NC on XIAO D7 / D8.
• Long buzzer success beep for accepted unlock codes.
• Door opened and door closed UART messages.
• NFC scan and UID validation UART messages.

Changed

• Android BLE reconnection now removes a stale phone-side bond and retries when secure pairing reports that it did not complete after the box cleared bonds.
• Android administrator registration now initiates bonding from the app before GATT discovery instead of racing a firmware-triggered security request.
• Mobile BLE write authorization failures now explain that the restored application identity no longer matches the identity stored in the box.
• Android administrator registration now waits for firmware-triggered BLE bonding before falling back to an explicit bond request.
• Mobile administrator registration now explains when the box already has an administrator instead of surfacing a raw Bad state error.
• Firmware now stores up to four BLE bonds and can replace the oldest unused bond, avoiding stale Android pairing keys blocking reconnection.
• Firmware now clears stale BLE bonds before first administrator provisioning when no administrator identity exists yet.
• Refactored firmware into independent components.
• Standardized source file headers.
• Standardized project coding style.
• 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.
• Disabled mobile box-mutating actions while offline, including open, synchronization-only, code, NFC, guest, and factory-reset actions.
• 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.
• Updated keypad unlock user feedback with off-at-rest LEDs, green-open indication, red invalid-code feedback, and B entry cancellation.
• Updated runtime LED feedback with blue NFC scan-mode indication.
• Updated open-lock reminder beep interval to 2 seconds.
• Updated the mobile application to reload access codes and NFC tags from the firmware BLE state characteristic.
• Reworked NFC actions into a three-item shortcut bar, kept scan guidance visible inside the modal, and clarified manual UID entry and pairing labels.
• Improved mobile settings with immediate language changes, language flags, visible backup-location state, and explanatory input-dialog text.
• Replaced the solid mobile page background with the project background image and grouped the logo, box name, active identity, and Bluetooth indicator in a solid dashboard header.
• Anchored dashboard actions to equal 20-pixel side and bottom margins and arranged NFC tags, guests, and settings as a compact three-card row.
• Doubled the separation between the dashboard shortcut bar and the action cards, and added show/hide controls to password fields.
• Restored guest access to global opening history and code lists, allowed guest management of temporary codes, hid permanent-code mutation and firmware update actions, and displayed modal errors above the active modal.
• Merged the separate mobile factory-reset action into box removal: guests see a local-data warning, while administrators receive a detailed warning and an optional checkbox to reset the physical box as well.
• Corrected NFC hardware documentation: the nRF52840 integrated NFCT peripheral is tag-side NFC-A hardware, while passive badge UID reading requires a dedicated NFC reader circuit.

Fixed

• Fixed Android box registration discovery by scanning nearby BLE advertisements before applying the OpenParcelBox name/service filter in the application, waiting for the actual scan timeout, and refreshing registration results as advertisements arrive.

• Replaced the per-device registration icon with radio-button box selection and an explicit add button, with inline errors and terminal diagnostics for provisioning failures.

• Kept a completed administrator registration when the following clock synchronization fails instead of reporting the whole addition as failed.

• Serialized Android BLE connection, secure bonding, MTU negotiation, and GATT discovery before the first encrypted state read.

• Added one-time stale-bond recovery when Android disconnects during the first encrypted provisioning read.

• Removed the Android BLE bond after a successful administrator factory reset, preventing the stale bond from rejecting the next administrator registration.

• Moved modal close controls fully inside their hit-test area and increased the touch target so closing a mobile modal is reliable.

• Removed the duplicate visible Android 12 splash icon before the branded Flutter splash frame.

• Enabled administrator registration as soon as a box and name are selected, stopped active BLE scanning before connecting, and increased the registration connection window from 12 to 20 seconds.

• Closed the administrator-registration progress modal immediately after provisioning instead of waiting for the secondary clock synchronization.

• Removed the exact registration modal route as soon as the controller publishes the newly saved box, preventing the loading overlay from remaining above an already rendered dashboard.

• Requested BLE security immediately on firmware connection and restarted connectable advertising after every recycled connection, including failed initial pairing attempts.

• Replaced Zephyr Secure Connections Only Mode, which implicitly required unavailable level-4 passkey/OOB authentication, with Secure Connections pairing-only mode and encrypted level-2 bonding for the headless XIAO.

• Added a Material surface behind registration radio rows so Android ink and selection rendering no longer emits an invisible-background warning.

• Increased the firmware ATT MTU to 247 bytes with matching ACL buffers so the 120-byte administrator provisioning JSON fits in one acknowledged GATT write instead of exceeding the previous 62-byte payload limit.

• Fixed the Android startup logo safe area so the complete logo remains centered instead of being cropped by the system splash icon mask, while restoring background.jpg and increasing the visible logo size.

• Removed oversized Settings callback allocations that exceeded the 1024-byte main stack once opening-history or application-identity records existed.

• Moved Settings/NVS loading to a dedicated 4096-byte services thread and increased the main, system-workqueue, and Bluetooth RX stack margins.

• Kept the keypad fallback code and default clock available from RAM before any flash or Bluetooth operation can run.

• Added bounded retries when Bluetooth advertising temporarily returns -EAGAIN, and no longer abort advertising solely because stored Bluetooth settings report a load error.

• Prevented invalid persisted box settings from overwriting the active default configuration before validation.

• Kept opening-history timestamps monotonic after an older phone clock sync so one descending event cannot invalidate the complete table on reboot.

• Provided Flutter's Material localization delegates so input fields and registration dialogs work when the phone language is French.

• Prevented incompatible persistent development-table layouts from blocking firmware startup before keypad initialization; affected tables now recover through their safe defaults.

• Made Bluetooth initialization asynchronous so keypad operation and USB availability no longer wait for BLE controller startup.

• Removed the silent early exit when RGB LED initialization fails.

• Kept keypad access available with in-memory default credentials when persistent settings fail, and added background keypad initialization retries.

• Fixed secure BLE startup ordering: the persisted bt/* settings and identity are now loaded after bt_enable() and before advertising, preventing BLE advertising failed: -11.

• Moved secure BLE initialization to a dedicated thread started after the local keypad-ready indication, so Bluetooth or bond restoration can never block keypad access, lock control, or the main application loop.

• Removed the interactive Zephyr/I2C shell and its competing serial backend; USB CDC is now owned exclusively by the firmware console, matching the validated standalone diagnostic configuration.

• Restricted guest BLE sessions to authentication, clock synchronization, lock opening, and temporary-code management; permanent-code, NFC, identity, and destructive administration remain blocked. Replaced oversized full-state notifications with a compact change marker.

• Added strict validation of persisted identity and opening-history records before they can be used or serialized.

• Removed automatic NVS writes and migrations from the boot path. Default tables are now available immediately in RAM and are persisted only after a real credential, identity, tag, box-name, or history change.

• Replaced the coupled application loop with a resilient local-first entry point: keypad input, code validation, lock control, buzzer, LEDs, and door feedback run independently from BLE and NFC processing.

• Temporarily removed NFC polling from the production main loop while retaining NFC storage and BLE management initialization; it will be restored after the validated keypad/BLE baseline is confirmed on hardware.

• Fixed Flutter inherited-widget assertions when closing input modals by keeping text controllers alive until their dialog widgets are actually unmounted.

• Changed encrypted-backup restoration to select the backup file before asking for its password.

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

• Prevented unintended lock command pulses at startup or after flashing by declaring D9 in Devicetree and configuring it directly inactive.

---

[0.1.0] - TBD

Added

• First public development release.
• Zephyr RTOS firmware.
• RGB LED driver.
• GPIO expander driver.
• Matrix keypad driver.
• Active buzzer driver.
• Initial documentation.
• Project roadmap.
• TODO list.