fsm-engine
Timestamp-driven button debouncing and multi-gesture recognition for embedded input subsystems.
fsm-engine provides a complete physical-to-semantic recognition pipeline:
- Asymmetric press/release debounce — independent durations, zero polling
- Multi-tap detection — single, double, and higher-order taps, configurable tap timeout and multi-tap window
- Hold with milestones — strictly increasing thresholds, each emitted as a distinct event
- Coalesced repeat — one event per update carrying the number of elapsed repeat intervals, avoiding unbounded catch-up bursts
- Multi-key chord arbitration — eager matching with priority-based overlap resolution, configurable release policies (AnyMember / AllMembers)
- Virtual chord controls — chords reuse the same tap/hold/repeat gesture recognizer as physical keys
- Owned event batches — every event carries
occurred_atandrecognized_attimestamps, with explicitprocessed_atper batch - Lossless input adapter —
VecDeque-backed queue with retryable fallible sinks, atomic batch commit on mapping success
Internally, the pipeline stages are built on a generic HashMap-driven Mealy state-machine engine that remains part of the public API for use in other contexts.
Quick start
use Duration;
use ;
// One active-low button with 20 ms debounce
let config = new;
let mut engine = new?;
// Feed two consecutive GPIO snapshots (20 ms apart) to confirm a press
engine.update?;
let batch = engine.update?;
// batch.physical contains one ButtonEdge { phase: Down, ... }
// batch.events contains one ButtonEvent { kind: State { phase: Down }, ... }
# Ok::
When the engine has a pending chord or gesture deadline, call advance_to()
even if no GPIO levels changed. Check EventBatch::next_wakeup (or
ButtonEngine::next_wakeup()) for the earliest deadline.
Gesture example
use Duration;
use ;
let mut config = new;
config.default_gestures = GestureConfig ;
let mut engine = new?;
// Press at 0 ms, release at 100 ms
engine.update?;
engine.update?;
// Advance past the multi-tap window (100 + 300 = 400 ms)
let batch = engine.advance_to?;
assert!;
# Ok::
Chord example
use Duration;
use ;
let mut config = new;
config.chords = vec!;
let mut engine = new?;
// Both keys pressed simultaneously → chord activated
let batch = engine.update?;
assert!;
// Individual key-down events are suppressed — only the chord appears
# Ok::
Generic Mealy FSM
The underlying state-machine engine is also public:
use Fsm;
let mut fsm = builder
.initial_state
.on
.build?;
let = fsm.step?;
assert_eq!;
# Ok::
Architecture
| Stage | Input | Output |
|---|---|---|
DebounceBank |
ButtonSnapshot (GPIO levels) |
ButtonEdge (confirmed physical edges) |
ChordResolver |
ButtonEdge |
ControlEdge (Key or Chord, with arbitration) |
GestureBank |
ControlEdge |
ButtonEvent (State / Tap / Hold / Repeat) |
| Input adapter | ButtonEvent |
application events with codes and sequence numbers |
All stages reject time regression. Every event satisfies
occurred_at ≤ recognized_at ≤ processed_at.
Documentation
- Architecture overview — data flow, time model, contracts
- Design document — detailed software architecture
- Testing strategy — verification contract and test conventions
- Changelog
License
MIT