Skip to main content

Crate btn_recognizer

Crate btn_recognizer 

Source
Expand description

Hash-table-driven Mealy machines and a timestamp-driven button framework.

§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_at and recognized_at timestamps, with explicit processed_at per 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 std::time::Duration;
use fsm_engine::key::{
    ButtonConfig, ButtonEngine, ButtonSnapshot, FrameworkConfig, KeyId, RawLevel, Timestamp,
};

// One active-low button with 20 ms debounce
let config = FrameworkConfig::new(vec![ButtonConfig::active_low(
    KeyId(1),
    Duration::from_millis(20),
)]);
let mut engine = ButtonEngine::new(config)?;

// Feed two consecutive GPIO snapshots (20 ms apart) to confirm a press
engine.update(ButtonSnapshot {
    at: Timestamp::from_millis(0),
    levels: &[RawLevel::Low],
})?;

let batch = engine.update(ButtonSnapshot {
    at: Timestamp::from_millis(20),
    levels: &[RawLevel::Low],
})?;
// batch.physical contains one ButtonEdge { phase: Down, ... }
// batch.events   contains one ButtonEvent { kind: State { phase: Down }, ... }

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 std::time::Duration;
use fsm_engine::key::{
    ButtonConfig, ButtonEngine, ButtonEventKind, ButtonPhase, ButtonSnapshot, ControlId,
    FrameworkConfig, GestureConfig, GestureKind, KeyId, RawLevel, Timestamp,
};

let mut config = FrameworkConfig::new(vec![ButtonConfig::active_low(
    KeyId(1),
    Duration::ZERO, // zero debounce for illustration
)]);
config.default_gestures = GestureConfig {
    tap_max: Duration::from_millis(200),
    multi_tap_window: Duration::from_millis(300),
    max_taps: 2,
    hold_thresholds: vec![Duration::from_millis(500), Duration::from_millis(1500)],
    ..Default::default()
};

let mut engine = ButtonEngine::new(config)?;

// Press at 0 ms, release at 100 ms
engine.update(ButtonSnapshot { at: Timestamp::from_millis(0),   levels: &[RawLevel::Low] })?;
engine.update(ButtonSnapshot { at: Timestamp::from_millis(100), levels: &[RawLevel::High] })?;

// Advance past the multi-tap window (100 + 300 = 400 ms)
let batch = engine.advance_to(Timestamp::from_millis(400))?;
assert!(batch.events.iter().any(|e| matches!(e.kind, ButtonEventKind::Gesture {
    kind: GestureKind::Tap { count: 1 }, ..
})));

§Chord example

use std::time::Duration;
use fsm_engine::key::{
    ButtonConfig, ButtonEngine, ButtonEventKind, ButtonPhase, ButtonSnapshot, ChordConfig,
    ChordId, ChordReleasePolicy, ControlId, FrameworkConfig, KeyId, RawLevel, Timestamp,
};

let mut config = FrameworkConfig::new(vec![
    ButtonConfig::active_low(KeyId(1), Duration::ZERO),
    ButtonConfig::active_low(KeyId(2), Duration::ZERO),
]);
config.chords = vec![ChordConfig {
    id: ChordId(10),
    members: vec![KeyId(1), KeyId(2)],
    window: Duration::from_millis(50),
    priority: 0,
    release: ChordReleasePolicy::AnyMember,
}];

let mut engine = ButtonEngine::new(config)?;

// Both keys pressed simultaneously → chord activated
let batch = engine.update(ButtonSnapshot {
    at: Timestamp::from_millis(10),
    levels: &[RawLevel::Low, RawLevel::Low],
})?;
assert!(batch.events.iter().any(|e| matches!(e.kind, ButtonEventKind::State {
    control: ControlId::Chord(ChordId(10)), phase: ButtonPhase::Down,
})));
// Individual key-down events are suppressed — only the chord appears

§Generic Mealy FSM

The underlying state-machine engine is also public:

use fsm_engine::Fsm;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
enum State { Idle, Running }

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
enum Event { Start }

let mut fsm = Fsm::builder()
    .initial_state(State::Idle)
    .on(State::Idle, Event::Start, State::Running, "started")
    .build()?;

let (state, motion) = fsm.step(&Event::Start)?;
assert_eq!((*state, *motion), (State::Running, "started"));

§Architecture

StageInputOutput
DebounceBankButtonSnapshot (GPIO levels)ButtonEdge (confirmed physical edges)
ChordResolverButtonEdgeControlEdge (Key or Chord, with arbitration)
GestureBankControlEdgeButtonEvent (State / Tap / Hold / Repeat)
Input adapterButtonEventapplication events with codes and sequence numbers

All stages reject time regression. Every event satisfies occurred_at ≤ recognized_at ≤ processed_at.

§Documentation

§License

MIT

Re-exports§

pub use fsm_engine::BuildError;
pub use fsm_engine::Fsm;
pub use fsm_engine::FsmBuilder;
pub use fsm_engine::FsmError;

Modules§

fsm_engine
哈希表驱动的有限状态机引擎
key
Timestamp-driven multi-button recognition framework.