kinetic-key

A gesture-based combination lock on the STM32L475 Discovery board (B-L475E-IOT01A). Set a three-gesture (or more - tunable in config) password using the onboard IMU, then replicate it to unlock.

Built with Mbed RTOS on PlatformIO.

---

How it works

The onboard LSM6DSL IMU samples at 104 Hz across all six axes (3-axis gyroscope + 3-axis accelerometer). Each gesture is a button-gated capture window of configurable duration. At unlock time, the attempt is compared against the stored password using joint 6D Dynamic Time Warping with a Sakoe-Chiba band constraint - an algorithm that finds the optimal time alignment between two sequences before measuring distance, making the lock robust to the same gesture performed at slightly different speeds and starting delays.

Before comparison, each capture is z-score normalized using the stored gesture's statistics. A fast energy pre-filter rejects obviously wrong inputs before the DTW computation runs. See docs/algorithm.md for the full treatment.

---

Hardware

Board: STM32L475VG Discovery (B-L475E-IOT01A)

Peripheral	Role
LSM6DSL	Gesture input - 3D accel + 3D gyro over I2C
SPBTLE-RF	BLE status output over SPI
User button	Hold to begin unlock; short press to record/submit gestures
LED1, LED2	State and progress feedback

---

Controls

First boot (default passwords set): for default settings, device starts in locked mode with 3 default passwords - these are pre-recorded and follow the shapes of "1", "2", and "3" performed from the top, hodling the board level, with buttons facing the user. The user can disable the default passwords by setting USE_STORED_PASSWORD=0 in the build flags, or modify them (see instructions in build section).

First boot (no default passwords): If passwords are not set or disabled, device boots into password setting state. Short press to begin capturing each gesture; press again to stop. After the third gesture is saved, the device unlocks.

Unlocking: long press the button to enter recording mode, perform a gesture, then short press to submit. Use short presses to advance and repeat for each gesture in sequence. Any mismatch resets to locked state.

Cancelling mid-unlock: long press the button during recording to step back. Long press while not recording to abort back to locked.

Changing the password: double-click while unlocked to enter set mode. Long press locks immediately without clearing the password.

Locking: hold the button from any state while not actively recording, or wait for the time-based auto-lock.

Progress is indicated on LEDs, serial, and BLE. A web interface at https://tonykorycki.github.io/kinetic-key/ connects over BLE and displays lock state and available actions. Android: Chrome. iOS: Bluefy.

---

Build

pio run -t upload

All tunable parameters (gesture duration, DTW band width, unlock threshold, pre-filter bounds) live in include/config.h. A PRODUCTION_MODE flag enables BLE and disables serial output.

To bake a password into the firmware so the device boots pre-locked:

pio test -e tuning_capture   # flash capture firmware
python tuning/record_password.py
pio run -t upload             # rebuild and flash main firmware

Set USE_STORED_PASSWORD=0 in build flags to ignore any baked-in password and boot into set mode.

---

Repo layout

kinetic-key/
├── src/
│   ├── main.cpp
│   ├── drivers/        imu.cpp, button.cpp, bluetooth.cpp
│   ├── logic/          fsm.cpp, dtw.cpp, normalize.cpp
│   └── ui/             ui.cpp, led.cpp, notifications.cpp
├── include/
│   ├── config.h        all tunable parameters and build flags
│   ├── shared/types.h  IMUSample, State enum, InputEvent
│   ├── drivers/        imu.h, button.h, bluetooth.h
│   ├── logic/          fsm.h, dtw.h, normalize.h, saved_password.h
│   └── ui/             ui.h, led.h, notifications.h
├── tuning/
│   ├── collect_data.py    capture password + legit + impostor attempts over serial
│   ├── golden_model.py    compute DTW distances, FAR/FRR at a given threshold
│   ├── sweep.py           grid search over algorithm parameters
│   ├── record_password.py capture gestures and write saved_password.h
│   └── config.py          algorithm parameters (keep in sync with config.h)
├── test/
│   └── tuning_capture/   standalone firmware for data collection
│   └── other             firmware unit tests
└── docs/                  algorithm, architecture, testing docs, web interface

---

Docs

• docs/algorithm.md - DTW algorithm, normalization scheme, and design rationale
• docs/architecture.md - software architecture, threading model, FSM design
• docs/testing_plan.md - testing methodology and procedure
• docs/testing.md - testing results, threshold selection, and error rates