Show page

Differences

This shows you the differences between two versions of the page.

--- pm:prj2026:bianca.popa1106:rares.goidescu [2026/05/09 17:01]
rares.goidescu created
+++ pm:prj2026:bianca.popa1106:rares.goidescu [2026/05/25 05:47] (current)
rares.goidescu
@@ Line 9: / Line 9: @@
 But what if you could have a digital piece of paper? An encrypted piece of paper that only you can read? A device that lets you access your passwords with just a fingerprint, without the need for a master password or cloud storage? A device that can be easily carried around and used on multiple devices?
-That’s the idea behind **B.A.U.B.A.U.** (Biometric Authentication Unit & Bluetooth Accesss Utility), a local first password manager that uses biometric authentication to keep your passwords safe and, at the same time, easily accessible.
+That's the idea behind **B.A.U.B.A.U.** (Biometric Authentication Unit & Bluetooth Accesss Utility), a local first password manager that uses biometric authentication to keep your passwords safe and, at the same time, easily accessible.
 ===== Description =====
@@ Line 16: / Line 16: @@
 {{ :pm:prj2026:bianca.popa1106:block_diagram_baubau_rares332ca.png?nolink&600 |}}
 ==== How do the components interact? ====
@@ Line 24: / Line 23: @@
 Here is what interfaces with the microcontroller:
-  * **AS608 Optical Fingerprint Sensor**: This sensor is used for biometric authentication. It captures the user’s fingerprint and sends the data to the microcontroller for processing and verification. The communication between the microcontroller and the fingerprint sensor is done using a serial interface (UART).
+  * **AS608 Optical Fingerprint Sensor**: This sensor is used for biometric authentication. It captures the user's fingerprint and sends the data to the microcontroller for processing and verification. The communication between the microcontroller and the fingerprint sensor is done using a serial interface (UART).
   * **SSD1306 OLED Display**: This display is used to show the user interface and the stored passwords. It communicates with the microcontroller using the I2C protocol.
-  * **Rotary Encoder with Push Button**: This component is used for user input, allowing the user to navigate through the menu and select options. The rotary encoder has two pins for the two signals (A and B) and a switch pin for the push button.
+  * **Rotary Encoder with Push Button**: This component is used for user input, allowing the user to navigate through the menu and select options. The rotary encoder has two pins for the two signals (A and B) and a switch pin for the push button. Physical interaction with the rotary encoder generates interrupts that the microcontroller can detect and respond to accordingly.
   * **microSD Card Module**: This module is used for storing the encrypted passwords on a microSD card. It communicates with the microcontroller using the SPI protocol.
@@ Line 38: / Line 37: @@
 |''%%GPIO25%%''              |Rotary Encoder Signal A   |Rotary Encoder with Push Button |Input        |Receives the signal A from the rotary encoder.                                   |
 |''%%GPIO26%%''              |Rotary Encoder Signal B   |Rotary Encoder with Push Button |Input        |Receives the signal B from the rotary encoder.                                   |
-|''%%GPIO27%%''              |Rotary Encoder Push Button|Rotary Encoder with Push Button |Input        |Receives the signal from the push button of the rotary encoder.                  |
+|''%%GPIO14%%''              |Rotary Encoder Push Button|Rotary Encoder with Push Button |Input        |Receives the signal from the push button of the rotary encoder.                  |
 |''%%GPIO5%%''               |SPI CS                    |microSD Card Module             |Output       |Used to select the microSD card module for SPI communication.                    |
 |''%%GPIO18%%''              |SPI SCK                   |microSD Card Module             |Output       |Provides the clock signal for the SPI communication with the microSD card module.|
@@ Line 48: / Line 47: @@
 ==== Bill of Materials ====
-^Componenent                     ^Description                                                                                                ^Procurement                                                                                                                ^Quantity^Datasheet     ^
+^Componenent                     ^Description                                                                                                ^Procurement                                                                                                                ^Quantity^Datasheet                                                                                        ^
-|Wemos D1 R32                    |A microcontroller board based on the ESP32 chip, used as the main processing unit for the password manager.|[[https://sigmanortec.ro/placa-dezvoltare-wemos-d1-r32-espduino-32-esp32-wifi-si-bluetooth|Sigmanortec]]                   |1       |[[|Datasheet]]|
+|Wemos D1 R32                    |A microcontroller board based on the ESP32 chip, used as the main processing unit for the password manager.|[[https://sigmanortec.ro/placa-dezvoltare-wemos-d1-r32-espduino-32-esp32-wifi-si-bluetooth|Sigmanortec]]                   |1       |[[https://drive.google.com/file/d/1JTzyLH7v0MgjwvOnUrzih87RpIXkxrZg/view|Datasheet]]             |
-|AS608 Optical Fingerprint Sensor|A biometric sensor used for fingerprint recognition to authenticate users.                                 |[[https://www.optimusdigital.ro/ro/senzori-senzori-optici/12995-modul-senzor-optic-de-amprenta-as608.html|Optimus Digital]]|1       |[[|Datasheet]]|
+|AS608 Optical Fingerprint Sensor|A biometric sensor used for fingerprint recognition to authenticate users.                                 |[[https://www.optimusdigital.ro/ro/senzori-senzori-optici/12995-modul-senzor-optic-de-amprenta-as608.html|Optimus Digital]]|1       |[[https://www.optimusdigital.ro/ro/index.php?controller=attachment&id_attachment=4959|Datasheet]]|
-|OLED Display                    |A small display used to show information such as the stored passwords and user interface.                  |[[https://sigmanortec.ro/Display-OLED-0-96-I2C-IIC-Albastru-p135055705|Sigmanortec]]                                       |1       |[[|Datasheet]]|
+|OLED Display                    |A small display used to show information such as the stored passwords and user interface.                  |[[https://sigmanortec.ro/Display-OLED-IIC-I2C-0-91-128x32-p126091015|Sigmanortec]]                                         |1       |[[https://www.lcdwiki.com/res/MC091GX/SSD1306-Revision%201.5.pdf|Datasheet]]                     |
-|Rotary Encoder with Push Button |A rotary encoder used for navigation and selection in the user interface.                                  |[[https://sigmanortec.ro/Encoder-rotativ-cu-click-20mm-EC11-p128736611|Sigmanortec]]                                       |1       |[[|Datasheet]]|
+|Rotary Encoder with Push Button |A rotary encoder used for navigation and selection in the user interface.                                  |[[https://sigmanortec.ro/Encoder-rotativ-cu-click-20mm-EC11-p128736611|Sigmanortec]]                                       |1       |-                                                                                                |
-|(Soon) microSD Card Module      |A module used for storing the encrypted passwords on a microSD card.                                       |[[https://sigmanortec.ro/Modul-MicroSD-p126079625|Sigmanortec]]                                                            |1       |[[|Datasheet]]|
+|microSD Card Module             |A module used for storing the encrypted passwords on a microSD card.                                       |[[https://sigmanortec.ro/Modul-MicroSD-p126079625|Sigmanortec]]                                                            |1       |-                                                                                                |
-|microSD Card                    |A storage device used for storing the encrypted passwords.                                                 |Any                                                                                                                        |1       |-             |
+|microSDHC Card                  |A storage device used for storing the encrypted passwords.                                                 |Any                                                                                                                        |1       |-                                                                                                |
-|Jumper Wires                    |Used for connecting the components together.                                                               |-                                                                                                                          |Too many|-             |
+|22 AWG Solid Wires              |Used for connecting the components together.                                                               |-                                                                                                                          |Too many|-                                                                                                |
-|Breadboard/Development Board    |Used for prototyping and testing the circuit.                                                              |-                                                                                                                          |1/1     |-             |
+|Perfboard                       |A one-sided FR4 perfboard used for connecting the components.                                              |-                                                                                                                          |1       |-                                                                                                |
 ==== Schematic ====
 {{ :pm:prj2026:bianca.popa1106:schematic_baubau_rares332ca.png?nolink&600 |}}
 ===== Software Design =====
@@ Line 74: / Line 72: @@
   * ''%%adafruit/Adafruit GFX Library%%'': A graphics library for drawing shapes, text, and images on the OLED display.
   * ''%%adafruit/Adafruit Fingerprint Sensor Library%%'': A library used for interfacing with the AS608 Optical Fingerprint Sensor, providing functions for enrolling fingerprints, searching for matches, and managing the fingerprint database.
-  * TBD: A library for handling encryption/decryption of the passwords before storing them on the microSD card.
+  * [[https://github.com/T-vK/ESP32-BLE-Keyboard|T-vK/ESP32-BLE-Keyboard]]: A library for HID keyboard over bluetooth
-  * TBD: A library for handling the file system on the microSD card.
+  * ''%%SD%%'' / ''%%FS%%'' (bundled with the ESP32 Arduino core): used to talk to the microSD card over SPI and read/write the vault file.
-  * TBD: A library for bluetooth communication
+  * ''%%mbedtls%%'' (also bundled with the ESP32 core): provides the AES-256 implementation used to encrypt the vault before it ever touches the card. No extra dependency needed, the ESP32 already ships with it.
-  * TBD: A library for HID keyboard over bluetooth
+==== Code Structure ====
+The firmware is split into small, single-responsibility modules so it stays easy to navigate. Every module is a ''%%.h%%''/''%%.cpp%%'' pair under [[https://github.com/raresgoidescu/baubau/tree/main/src|src/]], and all of them pull their pins and tunables from a single [[https://github.com/raresgoidescu/baubau/blob/main/src/config.h|config.h]].
+^Module             ^Responsibility                                                                                                     ^
+|''%%main%%''       |The state machine (''%%LOCKED%%'' > ''%%MENU%%'' > ''%%ENTRY%%'') and the main loop that glues everything together.|
+|''%%config%%''     |Every pin assignment, timeout and feature flag, in one place.                                                      |
+|''%%logger%%''     |Tiny ''%%LOG%%''/''%%LOGF%%'' macros that compile to nothing when ''%%DEBUG_ENABLED%%'' is off.                    |
+|''%%display%%''    |Everything that gets drawn on the OLED.                                                                            |
+|''%%encoder%%''    |Reads the rotary encoder and its button, debounced, as a single ''%%encoderPoll()%%'' snapshot per loop.           |
+|''%%fingerprint%%''|Talks to the AS608 sensor: authenticates a finger, and enrolls/deletes templates for the admin menu.               |
+|''%%ble%%''        |Advertises the BLE keyboard and types out a password on the host device.                                           |
+|''%%store%%''      |The password store. Keeps the entries in RAM and persists them, encrypted, to the microSD card.                    |
+|''%%admin%%''      |The on-device management menu: enroll/delete a fingerprint, delete an entry, wipe the vault.                       |
+Every function and field is documented with Doxygen comments, so the headers double as the API reference.
 ==== Software Architecture ====
-The way it is supposed to work is that when the user wants to access their passwords, they will be prompted to scan their fingerprint using the fingerprint sensor. The microcontroller fetches the fingerprint data from the microSD card, compares it with the scanned fingerprint, and if a match is found, it unlocks the password store and lets the user browse through the entries using the rotary encoder. Once the user selects a password entry, the microcontroller sends the password to the connected device via Bluetooth, emulating a keyboard input to automatically fill in the password field on the user’s device.
+The whole device is a small state machine with one knob and one button, so it is worth describing exactly what each gesture does.
+When idle, the device sits locked and asks for a finger. Scan an enrolled fingerprint and it unlocks into the menu, where turning the encoder browses the stored entries (the name in big letters, the account and a ''%%<current>/<total>%%'' position underneath).
+From the menu you can:
+  * Tap an entry to open it. On the entry screen the password is shown masked (''%%********%%''), you never see it on the display by accident (darn shoulder surfing). A quick tap types it on the paired device over Bluetooth (emulating a keyboard, works even on Apple devices); holding the button instead peeks the password, showing it in clear only for as long as you keep the button down. Turning the knob backs out to the menu.
+  * Hold the button (a long press) to open the admin menu.
+The admin menu is where everything that would normally need a computer happens, all on-device:
+  * Enroll finger: register a new fingerprint (two scans of the same finger).
+  * Delete finger: remove a stored fingerprint by id.
+  * Delete entry: drop a password entry from the vault.
+  * Wipe vault: erase every entry at once.
+If there is no input for a while (''%%AUTOLOCK_TIMEOUT%%'', 30s by default), the device locks itself again.
+=== Where the passwords live ===
+The passwords never sit in plaintext on the card, duh. The ''%%store%%'' module keeps the entries in RAM (I know, not ideal) while the device is unlocked, and writes them out to a single encrypted file, ''%%/vault.dat%%'', on the microSD card.
+The file format is intentionally boring:
+<code>
+[16 bytes IV][4 bytes plaintext length][AES-256-CBC ciphertext...]
+</code>
+The entries are first flattened into a plain ''%%name<TAB>email<TAB>password%%'' line per entry, then encrypted as one block with AES-256-CBC using a fresh random IV on every save. On boot, ''%%storeBegin()%%'' mounts the card and decrypts the file straight back into the in-RAM ''%%vault%%''. If the card is blank (no ''%%/vault.dat%%'' yet), it seeds a default set of entries and saves them, so a fresh card just works.
+The AES key lives in the firmware (see ''%%STORE_KEY%%'' in [[https://github.com/raresgoidescu/baubau/blob/main/src/config.h|config.h]]) rather than on the card, so popping the microSD into a reader gives you nothing but ciphertext. The known limitation is that the key is a build-time constant; a production build would move it into the ESP32's secure storage instead of source.
+===== Tutorial =====
+The whole interface is one knob you can turn (move), tap (select / send) and hold (admin menu / peek a password). In short:
+  * Unlock by resting an enrolled finger on the sensor.
+  * Turn to browse entries, tap one to send its password over Bluetooth (shown masked, never in clear).
+  * Hold on an entry to peek the password while you keep the button down.
+  * Hold in the menu to open the admin menu (enroll/delete a finger, delete an entry, wipe the vault).
+First run: with no fingerprints enrolled the lock screen shows //"Tap to set up"//; tap, then open the admin menu and enroll your finger.
 ===== Results =====
+Ended up with a working prototype that demonstrates the core features:
+  * Fingerprint authentication to unlock the device.
+  * Browsing stored password entries using the rotary encoder.
+  * Sending a password over Bluetooth by tapping an entry.
+  * Peeking a password by holding the button on an entry.
+  * An admin menu for enrolling/deleting fingerprints and managing entries.
+  * AES-encrypted vault stored on the microSD card, with a build-time constant key.
+The fingerprint authentication is reasonably reliable, with a quick response time for unlocking. Confidence of the fingerprint match is printed to the serial console for debugging purposes, and in practice it seems to work well with the enrolled fingers.
+To my surprise, but also obviously, the BLE typing works on all tested host devices (PC, Android and Apple). (well, it's just a standard HID keyboard, so it should).
 ===== Conclusions =====
+Well, this was quite a wild ride.
+Started off using a breadboard and jumper wires, quickly got a working proof of concept with the OLED, the encoder and the fingerprint sensor, tested each component, and as soon as I had everything working, I coded a simple state machine to glue it all together.
+With everything working on the breadboard, I moved on to soldering it all together on a perfboard.
+Here comes the fun part, I did the soldering immediately after getting it working on the breadboard.
+I was obliviously working with the solder wire that my dad had lying around (spoiler alert: it was lead free) and with a soldering iron that was not very good. All I knew is that using more solder and lots of flux would help, so I ended up with a perfboard that looked like a crime scene, with solder blobs everywhere, but as per the multimeter, there were no shorts.
+With the board looking like that, I wanted to remove the excess flux so I tried cleaning it with isopropyl alcohol.
+That was a mistake and when I powered it on, the MCU would reset in a loop, and lo and behold, there was the magic smoke coming out from under the OLED.
+Residue flux + isopropyl between many pins of the OLED and the MCU was causing shorts, and the OLED was fried.
+That was the biggest setback, and such a lesson learned.
+One OLED later, I started looking up how to properly do this and found out about leaded solder, which is much easier to work with, how to properly use a soldering iron, and about solid AWG wires for perfboard projects, so I ordered all the necessary materials and redid the whole thing with much better results.
+Gotta say, this was the most fun I've had within this project, and I learned a lot about soldering and hardware assembly in general.
+Last problem faced was that at the end, the OLED and the fingerprint sensor were not powering on and after hours of debugging with the multimeter, I found out that the pin header I used for the 3V3 line was not making good contact so I had to resort to some proper Romanian engineering.
+Software wise, the project went pretty smoothly, I had a clear vision of how I wanted the interface to work and how the user would interact with it, so I just had to implement it.
+===== Source Code & Resources =====
+All sources live in [[https://github.com/raresgoidescu/baubau|this repository]], organized into directories:
+  * [[https://github.com/raresgoidescu/baubau/tree/main/src|src/]]: firmware source, one ''%%.h%%''/''%%.cpp%%'' pair per module (see [[#code_structure|Code Structure]]).
+  * [[https://github.com/raresgoidescu/baubau/tree/main/assets|assets/]]: block diagram, schematic and images.
+  * [[https://github.com/raresgoidescu/baubau/tree/main/datasheets|datasheets/]]: component datasheets.
+  * [[https://github.com/raresgoidescu/baubau/blob/main/platformio.ini|platformio.ini]]: board, framework and 3rd-party library dependencies.
+==== Demo ====
+[[https://youtube.com/shorts/ZleIQnNWBvM|{{https://img.youtube.com/vi/ZleIQnNWBvM/1.jpg|Demo}}]]
 ===== Bibliography/Resources =====
+==== Software ====
+  * [[https://github.com/adafruit/Adafruit-Fingerprint-Sensor-Library|Adafruit Fingerprint Sensor Library]]
+  * [[https://github.com/adafruit/Adafruit_SSD1306|Adafruit SSD1306 Library]]
+  * [[https://github.com/T-vK/ESP32-BLE-Keyboard|T-vK/ESP32-BLE-Keyboard]]
+  * [[https://mbed-tls.readthedocs.io/|mbedTLS AES documentation]]
+==== Hardware ====
   * [[https://api.riot-os.org/group__boards__esp32__wemos__d1__r32.html|Support for the Wemos D1 R32 Board]]
+  * All the datasheets that are linked in the [[#bill_of_materials|Bill of Materials]] section.
+==== Both ====
+  * Anthropic's Claude for stupid questions.