btn-recognizer 0.2.2

Timestamp-driven button debouncing with multi-tap, hold, repeat, and multi-key chord gesture recognition
Documentation
use std::time::Duration;

use fsm_engine::key::{ButtonPhase, DebounceConfig, Debouncer, Timestamp};

#[derive(Debug, Clone)]
struct ReferenceDebouncer {
    stable_pressed: bool,
    candidate: Option<(bool, u64)>,
    press_ms: u64,
    release_ms: u64,
}

impl ReferenceDebouncer {
    fn new(config: DebounceConfig, initially_pressed: bool) -> Self {
        Self {
            stable_pressed: initially_pressed,
            candidate: None,
            press_ms: config.press.as_millis() as u64,
            release_ms: config.release.as_millis() as u64,
        }
    }

    fn update(&mut self, sample_pressed: bool, now_ms: u64) -> Option<ButtonPhase> {
        if sample_pressed == self.stable_pressed {
            self.candidate = None;
            return None;
        }

        match self.candidate {
            Some((candidate, _)) if candidate == sample_pressed => {}
            _ => self.candidate = Some((sample_pressed, now_ms)),
        }

        let (_, since_ms) = self.candidate.expect("an unstable sample arms a candidate");
        let required_ms = if sample_pressed {
            self.press_ms
        } else {
            self.release_ms
        };
        if now_ms - since_ms < required_ms {
            return None;
        }

        self.stable_pressed = sample_pressed;
        self.candidate = None;
        Some(if sample_pressed {
            ButtonPhase::Down
        } else {
            ButtonPhase::Up
        })
    }
}

fn time(ms: u64) -> Timestamp {
    Timestamp::from_millis(ms)
}

fn config(press_ms: u64, release_ms: u64) -> DebounceConfig {
    DebounceConfig {
        press: Duration::from_millis(press_ms),
        release: Duration::from_millis(release_ms),
    }
}

fn assert_step(
    dut: &mut Debouncer,
    reference: &mut ReferenceDebouncer,
    sample_pressed: bool,
    now_ms: u64,
) -> Option<ButtonPhase> {
    let expected = reference.update(sample_pressed, now_ms);
    let actual = dut.update(sample_pressed, time(now_ms)).unwrap();
    assert_eq!(
        actual, expected,
        "sample={sample_pressed} at {now_ms}ms, reference={reference:?}"
    );
    assert_eq!(dut.stable_pressed(), reference.stable_pressed);
    actual
}

#[test]
fn opposite_sample_at_each_deadline_cancels_without_a_false_edge() {
    let config = config(7, 13);
    let mut dut = Debouncer::new(config, false);
    let mut reference = ReferenceDebouncer::new(config, false);

    assert_eq!(assert_step(&mut dut, &mut reference, true, 10), None);
    assert_eq!(assert_step(&mut dut, &mut reference, false, 17), None);
    assert!(!dut.stable_pressed());

    assert_eq!(assert_step(&mut dut, &mut reference, true, 20), None);
    assert_eq!(
        assert_step(&mut dut, &mut reference, true, 27),
        Some(ButtonPhase::Down)
    );
    assert!(dut.stable_pressed());

    assert_eq!(assert_step(&mut dut, &mut reference, false, 40), None);
    assert_eq!(assert_step(&mut dut, &mut reference, true, 53), None);
    assert!(dut.stable_pressed());

    assert_eq!(assert_step(&mut dut, &mut reference, false, 60), None);
    assert_eq!(
        assert_step(&mut dut, &mut reference, false, 73),
        Some(ButtonPhase::Up)
    );
    assert!(!dut.stable_pressed());
}

#[test]
fn asymmetric_durations_are_exact_and_stable_samples_do_not_repeat() {
    let config = config(5, 17);
    let mut dut = Debouncer::new(config, false);
    let mut reference = ReferenceDebouncer::new(config, false);
    let trace = [
        (true, 0),
        (true, 4),
        (true, 5),
        (true, 6),
        (true, 100),
        (false, 101),
        (false, 117),
        (false, 118),
        (false, 119),
        (false, 200),
    ];

    let events: Vec<_> = trace
        .into_iter()
        .filter_map(|(sample, at)| assert_step(&mut dut, &mut reference, sample, at))
        .collect();
    assert_eq!(events, vec![ButtonPhase::Down, ButtonPhase::Up]);
}

#[test]
fn exhaustive_short_traces_match_an_independent_model() {
    const TRACE_LEN: usize = 10;
    let config = config(6, 9);

    for initially_pressed in [false, true] {
        for mask in 0_u16..(1_u16 << TRACE_LEN) {
            let mut dut = Debouncer::new(config, initially_pressed);
            let mut reference = ReferenceDebouncer::new(config, initially_pressed);
            let mut expected_next = if initially_pressed {
                ButtonPhase::Up
            } else {
                ButtonPhase::Down
            };

            for step in 0..TRACE_LEN {
                let sample_pressed = mask & (1 << step) != 0;
                let event = assert_step(&mut dut, &mut reference, sample_pressed, step as u64 * 3);
                if let Some(phase) = event {
                    assert_eq!(
                        phase, expected_next,
                        "non-alternating edge for initial={initially_pressed}, mask={mask:#05x}"
                    );
                    expected_next = match phase {
                        ButtonPhase::Down => ButtonPhase::Up,
                        ButtonPhase::Up => ButtonPhase::Down,
                    };
                }
            }
        }
    }
}

fn next_random(state: &mut u64) -> u64 {
    *state = state
        .wrapping_mul(6_364_136_223_846_793_005)
        .wrapping_add(1_442_695_040_888_963_407);
    *state
}

#[test]
fn deterministic_irregular_traces_match_reference_and_alternate() {
    let configurations = [(0, 0), (3, 19), (17, 5), (11, 11)];

    for (press_ms, release_ms) in configurations {
        let config = config(press_ms, release_ms);
        for seed in 0..32_u64 {
            let initially_pressed = seed & 1 != 0;
            let mut dut = Debouncer::new(config, initially_pressed);
            let mut reference = ReferenceDebouncer::new(config, initially_pressed);
            let mut rng = seed ^ 0x9e37_79b9_7f4a_7c15;
            let mut now_ms = 0;
            let mut sample_pressed = initially_pressed;
            let mut expected_next = if initially_pressed {
                ButtonPhase::Up
            } else {
                ButtonPhase::Down
            };

            for _ in 0..512 {
                let random = next_random(&mut rng);
                now_ms += random % 8;
                if random.rotate_left(17) % 5 <= 1 {
                    sample_pressed = !sample_pressed;
                }

                if let Some(phase) = assert_step(&mut dut, &mut reference, sample_pressed, now_ms) {
                    assert_eq!(phase, expected_next, "seed={seed}, at={now_ms}ms");
                    expected_next = match phase {
                        ButtonPhase::Down => ButtonPhase::Up,
                        ButtonPhase::Up => ButtonPhase::Down,
                    };
                }
            }
        }
    }
}