Crate debouncr

Expand description

§Debouncr

A simple and efficient no_std input debouncer that uses integer bit shifting to debounce inputs. The basic algorithm can detect rising and falling edges and only requires 1 byte of RAM for detecting up to 8 consecutive high/low states or 2 bytes of RAM for detecting up to 16 consecutive high/low states.

While the regular algorithm will detect any change from “bouncing” to “stable high/low” as an edge, there is also a variant that will only detect changes from “stable high” to “stable low” and vice versa as an edge (see section “Stateful Debouncing”).

The algorithm is based on the Ganssle Guide to Debouncing (section “An Alternative”).

§API

§Instantiate

First, decide how many consecutive states you want to detect. For example, if you poll the input pin every 5 ms and require 4 consecutive logical-high states to trigger a debounced press event, that event will happen after 20 ms.

On initialization, you also need to specify the initial state: true for logical-high, false for logical-low.

use debouncr::debounce_4;

let mut debouncer = debounce_4(false); // Type: Debouncer<u8, Repeat4>

§Update

In regular intervals, call the update(pressed) function to update the internal state.

use debouncr::{debounce_3, Edge};

let mut debouncer = debounce_3(false);
assert_eq!(debouncer.update(poll_button()), None);
assert_eq!(debouncer.update(poll_button()), None);
assert_eq!(debouncer.update(poll_button()), Some(Edge::Rising));

The update function will return a rising/falling edge, or None if the input is still bouncing.

§Query Debounced State

You can also query the current debounced state. If none of the n recent updates were pressed, then the debounced state will be low. If all n recent updates were pressed, then the debounced state will be high.

use debouncr::debounce_3;

let mut debouncer = debounce_3(false);

// Initially low
assert!(debouncer.is_low());
assert!(!debouncer.is_high());

// Update, now it's neither high nor low
debouncer.update(true);
assert!(!debouncer.is_low());
assert!(!debouncer.is_high());

// After two more updates, it's high
debouncer.update(true);
debouncer.update(true);
assert!(debouncer.is_high());

§Stateful Debouncing

By default, the debouncer will report any change from “bouncing” to “stable high/low” as an edge. If instead you want to detect only changes from a stable state to the opposite stable state, use the stateful debouncer instead. It has slightly higher (but still tiny) memory overhead than the regular debouncer, because it also stores the previous state in addition to the debouncing updates.

use debouncr::{debounce_stateful_3, Edge};

let mut debouncer = debounce_stateful_3(false);

// Ensure initial low state
assert!(debouncer.is_low());

// Temporary bouncing states will not trigger an edge
assert_eq!(debouncer.update(true), None);
assert_eq!(debouncer.update(false), None);
assert_eq!(debouncer.update(false), None);
assert_eq!(debouncer.update(false), None);

// However, stable opposite states will trigger an edge
assert_eq!(debouncer.update(true), None);
assert_eq!(debouncer.update(true), None);
assert_eq!(debouncer.update(true), Some(Edge::Rising));

§Example: RTIC

If you want to debounce a pin in an RTIC project, register a resource and a timer.

use debouncr::{Debouncer, debounce_12, Edge, Repeat12};

#[app(..., monotonic = rtic::cyccnt::CYCCNT)]
const APP: () = {
    struct Resources {
        button: gpioa::PA11<Input<PullUp>>,
        button_state: Debouncer<u16, Repeat12>,
    }

    #[init(spawn = [poll_button])]
    fn init(ctx: init::Context) -> init::LateResources {
        // ...
        ctx.spawn.poll_button().unwrap();
        init::LateResources {
            button,
            button_state: debounce_12(false),
        }
    }

    /// Regularly called task that polls the buttons and debounces them.
    #[task(
        resources = [button, button_state],
        spawn = [button_pressed, button_released],
        schedule = [poll_button],
    )]
    fn poll_button(ctx: poll_button::Context) {
        // Poll button
        let pressed: bool = ctx.resources.button.is_low().unwrap();

        // Update state
        let edge = ctx.resources.button_state.update(pressed);

        // Dispatch event
        if edge == Some(Edge::Rising) {
            ctx.spawn.button_pressed().unwrap();
        } else if edge == Some(Edge::Falling) {
            ctx.spawn.button_released().unwrap();
        }

        // Re-schedule the timer interrupt
        ctx.schedule
            .poll_button(ctx.scheduled + POLL_PERIOD.cycles())
            .unwrap();
    }

    /// The button was pressed.
    #[task]
    fn button_pressed(ctx: button_pressed::Context) {
        // Button was pressed, handle event somehow
    }

    /// The button was released.
    #[task]
    fn button_released(ctx: button_pressed::Context) {
        // Button was released, handle event somehow
    }

};

§Memory Consumption

Memory size of a debouncer instance:

Debouncer	Repetitions	Bytes
`Debouncer`	2..8	1
`DebouncerStateful`	2..8	2
`Debouncer`	9..16	2
`DebouncerStateful`	9..16	4

Structs§

Debouncer: A debouncer.
DebouncerStateful: A stateful debouncer.
Repeat2: Detect 2 consecutive logical-high states.
Repeat3: Detect 3 consecutive logical-high states.
Repeat4: Detect 4 consecutive logical-high states.
Repeat5: Detect 5 consecutive logical-high states.
Repeat6: Detect 6 consecutive logical-high states.
Repeat7: Detect 7 consecutive logical-high states.
Repeat8: Detect 8 consecutive logical-high states.
Repeat9: Detect 9 consecutive logical-high states.
Repeat10: Detect 10 consecutive logical-high states.
Repeat11: Detect 11 consecutive logical-high states.
Repeat12: Detect 12 consecutive logical-high states.
Repeat13: Detect 13 consecutive logical-high states.
Repeat14: Detect 14 consecutive logical-high states.
Repeat15: Detect 15 consecutive logical-high states.
Repeat16: Detect 16 consecutive logical-high states.

Enums§

Edge: Rising or falling edge.

Functions§

debounce_2: Create a new debouncer that can detect a rising or falling edge of 2 consecutive logical states.
debounce_3: Create a new debouncer that can detect a rising or falling edge of 3 consecutive logical states.
debounce_4: Create a new debouncer that can detect a rising or falling edge of 4 consecutive logical states.
debounce_5: Create a new debouncer that can detect a rising or falling edge of 5 consecutive logical states.
debounce_6: Create a new debouncer that can detect a rising or falling edge of 6 consecutive logical states.
debounce_7: Create a new debouncer that can detect a rising or falling edge of 7 consecutive logical states.
debounce_8: Create a new debouncer that can detect a rising or falling edge of 8 consecutive logical states.
debounce_9: Create a new debouncer that can detect a rising or falling edge of 9 consecutive logical states.
debounce_10: Create a new debouncer that can detect a rising or falling edge of 10 consecutive logical states.
debounce_11: Create a new debouncer that can detect a rising or falling edge of 11 consecutive logical states.
debounce_12: Create a new debouncer that can detect a rising or falling edge of 12 consecutive logical states.
debounce_13: Create a new debouncer that can detect a rising or falling edge of 13 consecutive logical states.
debounce_14: Create a new debouncer that can detect a rising or falling edge of 14 consecutive logical states.
debounce_15: Create a new debouncer that can detect a rising or falling edge of 15 consecutive logical states.
debounce_16: Create a new debouncer that can detect a rising or falling edge of 16 consecutive logical states.
debounce_stateful_2: Create a new stateful debouncer that can detect stable state changes after 2 consecutive logical states.
debounce_stateful_3: Create a new stateful debouncer that can detect stable state changes after 3 consecutive logical states.
debounce_stateful_4: Create a new stateful debouncer that can detect stable state changes after 4 consecutive logical states.
debounce_stateful_5: Create a new stateful debouncer that can detect stable state changes after 5 consecutive logical states.
debounce_stateful_6: Create a new stateful debouncer that can detect stable state changes after 6 consecutive logical states.
debounce_stateful_7: Create a new stateful debouncer that can detect stable state changes after 7 consecutive logical states.
debounce_stateful_8: Create a new stateful debouncer that can detect stable state changes after 8 consecutive logical states.
debounce_stateful_9: Create a new stateful debouncer that can detect stable state changes after 9 consecutive logical states.
debounce_stateful_10: Create a new stateful debouncer that can detect stable state changes after 10 consecutive logical states.
debounce_stateful_11: Create a new stateful debouncer that can detect stable state changes after 11 consecutive logical states.
debounce_stateful_12: Create a new stateful debouncer that can detect stable state changes after 12 consecutive logical states.
debounce_stateful_13: Create a new stateful debouncer that can detect stable state changes after 13 consecutive logical states.
debounce_stateful_14: Create a new stateful debouncer that can detect stable state changes after 14 consecutive logical states.
debounce_stateful_15: Create a new stateful debouncer that can detect stable state changes after 15 consecutive logical states.
debounce_stateful_16: Create a new stateful debouncer that can detect stable state changes after 16 consecutive logical states.

Crate debouncrCopy item path