Project/sergiu.lefter (#1427)

* Add initial documentation for Smart Lockbox project

* Add architecture diagram for Smart Lockbox project

* Refactor protoboard setup in project documentation: updated wiring descriptions, clarified component assembly on two 7x9 protoboards, and revised bill of materials for accuracy.

* Added images and update documentation

* Fixed image format to be webp instead of jpg

* Renamed images with lowercase

Author: sergiulefter

website/versioned_docs/version-fils_en/project/2026/sergiu.lefter/esp32_working.webp

@@ -15,63 +15,48 @@ A Rust-based electronic lockbox with keypad PIN access, servo lock control, loca
 This project is a smart lockbox controlled by an STM32 Nucleo board.
 The user enters a PIN on a 3x4 keypad. If the PIN is correct, an SG90 servo unlocks the box. If it is wrong, access is denied and a passive buzzer gives warning feedback.
 
-I also use a mechanical endstop to detect when the lid is closed, so the lock can return automatically to the locked position.
-For the extended version, I added an ESP32 for network logging and a possible admin reset flow for the PIN.
+For the extended version, I added an ESP32 for network logging, remote commands, and a local admin panel for PIN management.
 
 ## Motivation
 
 I chose this project because it is practical and also a good embedded Rust challenge.
-It combines hardware and software in one system: keypad input, control logic, servo actuation, sensor feedback, and communication.
+It combines hardware and software in one system: keypad input, control logic, servo actuation, user feedback, and communication.
 I also wanted to build something physical that I can test and improve step by step.
 
 ## Architecture
 
 Main architecture components:
-- Input: 3x4 keypad, admin button, mechanical endstop.
-- Main control: STM32 Nucleo (rental) running the lock logic and state machine.
-- Output: SG90 servo for lock movement, LCD1602 (I2C) for messages, passive buzzer for alerts.
-- Network side: ESP32 DevKitC for logging and possible admin reset/dashboard.
-- Wiring setup: STM32 connects through a 7x9 interface protoboard (female headers), then to a second 7x9 main protoboard where modules are connected.
-
-How components connect:
-- Keypad, button, and endstop send inputs to the STM32.
-- STM32 controls the servo, buzzer, and LCD.
-- ESP32 communicates with STM32 over serial/UART for logging/admin features.
-- Components are assembled on two 7x9 protoboard/PCB prototyping boards using silicone stranded wires.
+- Input: 3x4 keypad and one admin button.
+- Main controller: STM32 Nucleo.
+- Output: SG90 servo, LCD1602 with I2C backpack, passive buzzer.
+- Network side: ESP32 DevKitC with a small web admin panel.
+- Assembly: one 7x9 interface protoboard for the STM32 connection and one 7x9 main protoboard for the rest of the circuit.
+
+How the system works:
+- The keypad sends the PIN to the STM32.
+- The STM32 checks the PIN, controls the servo, updates the LCD, and triggers the buzzer.
+- The admin button is used for local override/reset actions.
+- The ESP32 talks to the STM32 over UART and provides logging plus a simple Wi-Fi admin panel.
+- I used two protoboards so I would not solder directly on the rental STM32 board.
 
 ### Software State Machine
 
-The software is organized as a state machine with the following states:
-- `LOCKED`
-- `ENTERING_PIN`
-- `UNLOCKED`
-- `WAIT_FOR_CLOSE`
-- `ADMIN_MODE`
-- `ALARM`
-
-### Architecture Diagram
-
-```text
-Input Block (3x4 Keypad, Admin Button, Mechanical Endstop)
-        |
-        | GPIO
-        v
-STM32 Nucleo (Main Control: PIN + State Machine)
-        |
-        | via 7x9 interface protoboard (female headers)
-        v
-Main 7x9 Protoboard (distribution for components)
-   |                 |                    |
-   | I2C             | PWM                | GPIO/PWM
-   v                 v                    v
-LCD1602 + I2C     SG90 Servo         Passive Buzzer
-
-STM32 Nucleo
-        |
-        | UART / Serial
-        v
-ESP32 DevKitC (Logging + optional Admin PIN reset)
-```
+The software is organized around a small access-control state machine:
+- `PIN_SETUP`: active when no valid PIN is stored yet. The box stays accessible and the user must define a new PIN.
+- `LOCKED`: normal idle state after a PIN exists. The system waits for keypad input and compares it with the saved code.
+- `UNLOCKED`: entered after a valid PIN or an admin override. In this state the servo opens the mechanism and the UI shows that access is granted.
+
+The implementation is split into two software parts:
+- STM32 firmware written in Rust with Embassy. This side handles keypad scanning, servo control, LCD updates, buzzer patterns, UART communication, and flash-backed PIN persistence.
+- ESP32 admin-panel firmware written as an Arduino sketch. This side creates a local Wi-Fi access point, serves the web panel, forwards commands over UART, and keeps temporary logs in RAM.
+
+For hardware bring-up and debugging, the STM32 firmware also includes multiple `FirmwareMode` test modes:
+- `BuzzerTest`
+- `ServoTest`
+- `KeypadTest`
+- `AdminButtonTest`
+- `UartTest`
+- `FullApp`
 
 ## Log
 
@@ -81,10 +66,31 @@ ESP32 DevKitC (Logging + optional Admin PIN reset)
 Researched smart lockbox implementations and decided on the final project direction. Chose the main architecture around STM32 + keypad + servo and started the documentation page.
 
 ### Week 6-7
-Updated the hardware plan and replaced several components: breadboard with protoboard, 4x4 keypad with 3x4 keypad, reed switch with mechanical endstop, and active buzzer with passive buzzer. Ordered all required parts and checked compatibility.
+Updated the hardware plan and replaced several components: breadboard with protoboard, 4x4 keypad with 3x4 keypad, and active buzzer with passive buzzer. Ordered all required parts and checked compatibility.
 
 ### Week 8
-Defined the interface-board approach to avoid soldering on the rental STM32 board (female header bridge through a dedicated 7x9 protoboard). Added ESP32 networking scope for event logging and possible admin PIN reset flow.
+Defined the interface-board approach to avoid soldering on the rental STM32 board (female header bridge through a dedicated 7x9 protoboard). Added ESP32 networking scope for event logging and a local admin control flow.
+
+### Week 9-10
+Started putting together the hardware and moving from planning to real assembly. A big part of this stage was debugging early hardware issues, especially the LCD, which initially powered on but did not show text correctly.
+
+![LCD not working yet](./lcd_not_working.webp)
+
+### Week 11-12
+Continued debugging all hardware components until they became reliable. I discovered that I had badly soldered the I2C backpack onto the LCD, so I had to buy a new one and solder it again correctly on the second attempt. After that, I got almost all major components working on a breadboard, with the ESP being the first one I brought up successfully.
+
+![LCD working after fixing the backpack](./lcd_working.webp)
+![Second LCD working test](./lcd_working_2.webp)
+![ESP32 working on the breadboard](./esp32_working.webp)
+
+### Week 13-14
+Implemented software testing modes through `FirmwareMode` and also built the ESP32 web admin panel. During final hardware assembly I badly soldered one keypad pin and burned the keypad, so I had to rethink the keypad concept and adapt the layout creatively using symbols instead of the original numeric-only interaction.
+
+![Locked mode with entered code](./locked_mode_entered_code.webp)
+![Locked mode after wrong code](./locked_mode_code_wrong.webp)
+![Unlock with admin button](./unlock_with_admin_button.webp)
+![Broken keypad pin after soldering](./keypad_broken_pin.webp)
+![Restructured keypad with symbols](./keypad_restructured_with_symbols.webp)
 
 ## Hardware
 
@@ -111,7 +117,6 @@ The rest of the circuit is assembled using two 7x9 protoboard/PCB prototyping bo
 | [Header de Pini Mama 6p 2.54 mm](https://www.optimusdigital.ro/ro/componente-electronice-headere-de-pini/4156-header-de-pini-mama-6p-254-mm.html?search_query=0104210000035032&results=1) | Female headers for detachable wiring/interfaces | 0,49 RON |
 | [Tastatura numerica 4x3, 12 butoane](https://sigmanortec.ro/tastatura-numerica-4x3-12-butoane) | PIN entry keypad (3x4) | 18.76 RON |
 | [Buton 12x12x7.3](https://sigmanortec.ro/Buton-12x12x7-3-p160373654) | Local control/input button | 1.33 RON |
-| [Endstop mecanic SS-5GL2](https://sigmanortec.ro/Endstop-mecanic-SS-5GL2-p136284192) | Position sensing (replaces reed switch) | 5.23 RON |
 | [Servomotor SG90, 180 grade, cu limitator](https://sigmanortec.ro/Servomotor-SG90-limit-switch-p141662062) | Mechanical lock actuation | 9.49 RON |
 | [Buzzer pasiv 5V](https://sigmanortec.ro/Buzzer-pasiv-5v-p172425809) | Audio feedback for success/error events | 1.45 RON |
 | [LCD 1602](https://sigmanortec.ro/LCD-1602-p125700685) | Status display for prompts and lock messages | 11.18 RON |
@@ -125,14 +130,13 @@ The rest of the circuit is assembled using two 7x9 protoboard/PCB prototyping bo
 | [Embassy](https://embassy.dev/) | Async embedded Rust framework | Main embedded architecture and task scheduling |
 | [embassy-stm32](https://docs.embassy.dev/embassy-stm32/) | STM32 peripheral support for Embassy | GPIO/I2C/PWM integration on STM32 |
 | [embassy-executor](https://docs.embassy.dev/embassy-executor/) | Async executor | Runs concurrent embedded tasks |
-| [embassy-time](https://docs.embassy.dev/embassy-time/) | Timing, delays, and timeouts | Debounce logic, lock timers, alarm timing |
+| [embassy-time](https://docs.embassy.dev/embassy-time/) | Timing, delays, and timeouts | Debounce logic, unlock timers, and UI timing |
+| [embassy-sync](https://docs.embassy.dev/embassy-sync/) | Synchronization primitives for Embassy | Background buzzer event channel between tasks |
 | [embedded-hal](https://github.com/rust-embedded/embedded-hal) | Hardware abstraction traits | Portable driver interfaces |
-| [embedded-hal-async](https://github.com/rust-embedded/embedded-hal) | Async HAL traits | Async peripheral operations |
 | [defmt](https://github.com/knurling-rs/defmt) | Lightweight logging for embedded Rust | Structured firmware logs during development |
 | [defmt-rtt](https://github.com/knurling-rs/defmt) | RTT transport for defmt | Real-time debug output |
 | [panic-probe](https://github.com/knurling-rs/probe-run/tree/main/panic-probe) | Panic reporting | Panic handling during debugging |
 | [heapless](https://github.com/rust-embedded/heapless) | `no_std` data structures | Fixed-capacity buffers/queues for embedded-safe logic |
-| [esp-idf-svc](https://github.com/esp-rs/esp-idf-svc) | ESP32 service layer in Rust | Networking/logging and admin-side integration |
 
 ## Links