Final documentation (#1359)

* Added documentation for the project

* Final documentation

Author: vasilescuradu

website/versioned_docs/version-acs_cc/project/2026/radu.vasilescu0510/arhitectura_proiect.svg

@@ -1,7 +1,7 @@
 # Randomness-audited Wheel-of-Fortune
 A motorized wheel that randomly chooses its output and also proves how fair it is.
 
-:::info 
+:::info 
 
 **Author**: Radu-Alexandru Vasilescu \
 **GitHub Project Link**: https://github.com/UPB-PMRust-Students/acs-project-2026-vasilescuradu
@@ -11,10 +11,9 @@ A motorized wheel that randomly chooses its output and also proves how fair it i
 ## Description
 
 The Randomness-audited Wheel-of-Fortune is an arcade-like
-product, designed to be fun and interesting. The user chooses the wheel speed,
-presses the “start game” button and the wheel begins to rotate, while specific
-visual and sound effects are running. The result is displayed on the LCD screen,
-along with statistics. The project uses an entropy source - the jitter from an
+product, designed to be fun and interesting. The user chooses the number of full rotations,
+presses the “start game” button and the wheel begins to rotate. When it stops, the result is displayed on the LCD screen,
+along with fairness statistics. The project uses an entropy source - the jitter from an
 unconnected analog pin – to create a carnival experience. At the same time,
 fairness is guaranteed by the chi-square test and the distribution of the results is
 logged on an SD card for external audit.
@@ -29,49 +28,66 @@ ways to show that mathematics is not only about theory, but also about
 real-life situations.
 
 ## Architecture
-![Arhitectura Proiectului](arhitectura_proiect.svg)
+![Project architecture](final_architecture_schematic.webp)
 
 ## Log
 
 ### Week 27 April - 3 May
 
 I created the documentation, containing a lot of details about the
 project.
-### Week 12 - 18 May
+### Week 10 - 17 May
+
+I created the motorized wheel and presented a spin demo
+for the hardware milestone. Also, I wired the pot and the button.
+
+### Week 18 - 24 May
+
+I wired the SD card reader, the EEPROM and the LEDs.
+I implemented most of the required software and presented a demo for the software milestone.
+
+### Week 25 - 31 May
+
+I replaced the DC gear motor and VNH2SP30 driver with a 28BYJ-48 stepper motor and ULN2003 driver, which lets the wheel land exactly on the target slot without speed/brake calibration. I added a 16x2 LCD (4-bit mode) that shows the result and the chi-square fairness verdict after each spin, moved the start button to an analog input, and repurposed the potentiometer to select the number of full rotations.
 
-### Week 19 - 25 May
 
 ## Hardware
 
-The hardware architecture revolves around the STM32 microcontroller. The physical rotation of the wheel is powered by a 6V DC Gear Motor controlled via a VNH2SP30 motor driver using PWM signals. The system is powered via a 5V USB connection, utilizing a DC-DC Boost Converter to step up the voltage for the motor. User inputs are handled by a physical push button to start the game and a 50k potentiometer to configure the spinning speed. All components are prototyped and connected using a standard 830-point breadboard and a dedicated jumper wire set.
+The hardware architecture revolves around the STM32 microcontroller. The physical rotation of the wheel is powered by a 28BYJ-48 stepper motor controlled via a ULN2003 driver, which gives exact, repeatable positioning on the target slot without any speed or brake calibration. The system is powered via a 5V USB connection. User inputs are handled by a 50k potentiometer to configure the number of full rotations and a physical push button (read as an analog voltage level) to start the game. A 16x2 LCD displays the resulting slot and the fairness verdict after each spin. The AT24C256 I2C EEPROM is used for stats logging. The MicroSDHC 8GB card and the SD card reader nano module are used for external audit. All components are prototyped and connected using a standard 830-point breadboard and a dedicated jumper wire set.
 
 ### Schematics
 
-![KiCAD Schematic](schema_1.svg)
+![KiCAD Schematic](final_kicad_schematic.webp)
 
 ### Bill of Materials
 
 | Device | Usage | Price |
 |--------|--------|-------|
 | [STM32 Nucleo Board](https://www.st.com/en/evaluation-tools/stm32-nucleo-boards.html) | The main microcontroller running the logic | ~ 100.00 RON |
-| [6V 96 RPM Plastic Geared Motor](https://www.optimusdigital.ro/ro/motoare-altele/5833-motor-cu-reductor-din-plastic-i-ax-cu-diametrul-de-4-mm-6-v-96-rpm.html?srsltid=AfmBOop9PXG0G7C-zHNTAhXIJz2r2rfr9kBAst5gFgeA-74S_rmirAKH) | Physically rotates the wheel | 11.99 RON |
-| [2A DC-DC Boost Module](https://www.optimusdigital.ro/ro/surse-ridicatoare-reglabile/169-modul-dc-dc-boost-de-2a.html?srsltid=AfmBOoox6WjCYDuuwY0qRSkYvsngnhVKMo9N3AZCa5qBWSvFPmQlqV2-) | Steps up the 5V USB voltage to power the DC motor | 9.99 RON |
-| [VNH2SP30 Motor Driver Module](https://www.optimusdigital.ro/ro/drivere-de-motoare-cu-perii/477-modul-driver-pentru-motoare-vnh2sp30.html?srsltid=AfmBOorCpeoK8NdSGiNEunGo-vjNDS64Qik-48tXZOUHw1bAlmUx0eQT) | Controls the speed (via PWM) and direction of the DC motor | 29.94 RON |
-| [50k Mono Potentiometer](https://www.optimusdigital.ro/ro/componente-electronice-potentiometre/1885-potentiometru-mono-50k.html?srsltid=AfmBOopsy_OdVFuYxkBoo1D9JZx9zzn1B3piJ1i7kABN3P_O6AsyTs_w) | Analog input to adjust the rotation speed | 1.49 RON |
-| [White Round Cap Push Button](https://www.optimusdigital.ro/ro/butoane-i-comutatoare/1115-buton-cu-capac-rotund-alb.html?srsltid=AfmBOorTSdiSNy5lCZLD_elUSRuKveDm7G4lwfxWsktSIJ8Z76j-wwe5) | Digital input to trigger the spin event | 1.99 RON |
+| [28BYJ-48 5V Stepper Motor and Blue ULN2003 Driver Set](https://www.optimusdigital.ro/ro/motoare-motoare-pas-cu-pas/101-driver-uln2003-motor-pas-cu-pas-de-5-v-.html?srsltid=AfmBOoo7z2oDRYsy1MbzxaFBLjm9ummjQTLPcTV45-iWbfMgyH3tTVms) | Physically rotates the wheel | 16.97 RON | 
+| [50k Mono Potentiometer](https://www.optimusdigital.ro/ro/componente-electronice-potentiometre/1885-potentiometru-mono-50k.html?srsltid=AfmBOopsy_OdVFuYxkBoo1D9JZx9zzn1B3piJ1i7kABN3P_O6AsyTs_w) | Analog input to select the number of rotations | 1.49 RON |
+| [White Round Cap Push Button](https://www.optimusdigital.ro/ro/butoane-i-comutatoare/1115-buton-cu-capac-rotund-alb.html?srsltid=AfmBOorTSdiSNy5lCZLD_elUSRuKveDm7G4lwfxWsktSIJ8Z76j-wwe5) | Analog input to trigger the spin event | 1.99 RON |
 | [830 Tie-Point Breadboard and Jumper Wire Kit](https://sogest.ro/accesorii-multimetre/set-placa-test-breadboard-830-165x55x085cm-set-cabluri-breadboard-si-alimentat) | Prototyping and interconnecting all electronic modules | 39.00 RON |
+| [SD card reader nano module](https://sogest.ro/module-diverse/modul-nano-cititor-de-card-sd) | Interfaces with the SD card for data logging | 16.00 RON |
+| [AT24C256 I2C EEPROM Module](https://www.optimusdigital.ro/en/memories/632-modul-eeprom-at24c256.html?search_query=EEPROM&results=64) | Persistent storage for statistics across reboots | 9 RON |
+| [MicroSDHC 8GB card](https://sogest.ro/carduri-microsd/card-microsdhc-8gb-clasa10-maxell-cu-adaptor-sd-x-series-micro-sdhc-8gb-ad-class10) | Physical storage medium for the external audit logs | 38 RON |
+| [Display LCD1602 HD44780](https://www.bitmi.ro/display-lcd1602-hd44780-albastru-iluminat-10486.html?gad_source=1&gad_campaignid=21312430054&gbraid=0AAAAADLag-l9Mrse7Pa8BnYa5ZS0HyDMY&gclid=CjwKCAjwrNrQBhBjEiwAoR4VO28wxRhXikjyxuW3njLUfpud9TIIGEJrlRJMqJKEM_28ANK_kKp9whoCWFsQAvD_BwE) | Used for displaying results and statistics | 14 RON |
 
 ## Software
 
-The software architecture is written entirely in **Rust**, utilizing the **Embassy** asynchronous execution framework. This allows the microcontroller to handle multiple concurrent tasks—such as generating precise PWM signals, managing user inputs, and logging data—without blocking the CPU.
+The software architecture is written entirely in **Rust**, utilizing the **Embassy** asynchronous execution framework. This allows the microcontroller to handle multiple concurrent tasks—such as driving the stepper motor, managing user inputs, and logging data to the SD card—without blocking the CPU.
 
 | Library | Description | Usage |
 |---------|-------------|-------|
-| [embassy-stm32](https://github.com/embassy-rs/embassy) | Async HAL & Execution framework | Hardware abstraction and async scheduling. |
-| [embedded-hal](https://github.com/rust-embedded/embedded-hal) | Standard hardware traits | Traits for external peripherals (I2C, SPI). |
+| [embassy-stm32](https://github.com/embassy-rs/embassy) | Async HAL | Hardware abstraction (GPIO, ADC, I2C, SPI). The EEPROM (raw I2C) and the 16x2 LCD (4-bit GPIO bit-banging) are driven directly through this HAL, without a dedicated driver crate. |
+| [embassy-executor](https://github.com/embassy-rs/embassy) | Async task executor | Runs the main loop and the SD logger as concurrent async tasks. |
+| [embassy-sync](https://github.com/embassy-rs/embassy) | Async synchronization primitives | Signal that passes the latest stats snapshot to the SD logger task. |
+| [embassy-time](https://github.com/embassy-rs/embassy) | Timekeeping, delays and timeouts | Stepper step timing, button debounce, LCD timing. |
+| [embedded-hal](https://github.com/rust-embedded/embedded-hal) | Standard hardware traits | SPI/GPIO traits for the SD card interface. |
+| [embedded-hal-bus](https://github.com/rust-embedded/embedded-hal) | SPI/I2C bus-sharing helpers | ExclusiveDevice wrapper for the SD card on the SPI bus. |
 | [embedded-sdmmc](https://github.com/rust-embedded-community/embedded-sdmmc-rs) | FAT filesystem & SD card driver | Writing CSV audit logs to the SD card. |
-| [eeprom24x](https://github.com/eldruin/eeprom24x-rs) | AT24C* series EEPROM driver | Saving stats persistently across reboots. |
-| [hd44780-driver](https://github.com/JohnDoneth/hd44780-driver) | HD44780 LCD controller driver | Displaying results and stats on the LCD. |
+| [defmt](https://github.com/knurling-rs/defmt) | Efficient logging framework | Debug/info logging over RTT during development. |
+| [cortex-m](https://github.com/rust-embedded/cortex-m) | Cortex-M core access | Cycle-accurate short delays (asm::delay) for the LCD enable pulse. |
 
 ## Links