Module rmicrobit::buttons

Support for hardware buttons.

Scope

This module provides:

• a lower-level interface for reading a button or switch's state
• optional 'debouncing'
• a higher-level interface for retrieving button events, including:
  • simple 'click' events
  • support for treating two buttons as a single device, with a 'clicked both' event
  • support for detecting 'hold' (long press) events
• convenience APIs for using these features with the built-in buttons

Polling model

This module's client is responsible for calling polling functions at regular intervals (nothing in this module itself uses interrupts or timers).

The intended polling interval is 6ms.

In practice it appears no debouncing is needed for the micro:bit's built-in buttons given this polling interval, so by default no debouncing is applied.

With a 6ms polling interval, the 'with hold' drivers report a hold event after a press 1.5s long.

Usage

The simplest way to access the higher-level features is via one of the high-level driver modules:

• single_eager
• single_lazy
• single_with_hold
• dual
• dual_with_hold

Each of these modules defines a similar interface, including a ButtonEvent enum and either a Monitor type for each button or a Monitor type for both buttons treated as a single device.

Each Monitor type defines a new() method which expects a ButtonA, a ButtonB, or one of each.

Use the from_pins() function to retrieve ButtonA and ButtonB.

Each Monitor type defines a poll() method which returns an Option(ButtonEvent); this method should be called at regular intervals (in practice every 6ms).

Lower-level access

See the core module if none of the event types above are suitable for your purposes, or to use an external button.

See the debouncing module if you need to control debouncing behaviour.

Examples

use rmicrobit::prelude::*;
use rmicrobit::gpio::PinsByKind;
use rmicrobit::buttons;
use rmicrobit::buttons::dual::{ABMonitor, ButtonEvent};
let p: nrf51::Peripherals = _;
let PinsByKind {button_pins, ..} = p.GPIO.split_by_kind();
let (button_a, button_b) = buttons::from_pins(button_pins);
let monitor = ABMonitor::new(button_a, button_b);
loop {
    // every 6ms
    match monitor.poll() {
        Some(ButtonEvent::ClickA) => { ... }
        Some(ButtonEvent::ClickB) => { ... }
        Some(ButtonEvent::ClickAB) => { ... }
        None => {}
    }
}

See examples/use_single_button_monitor.rs and examples/use_dual_button_monitor.rs for complete examples.

Re-exports

pub use crate::buttons::builtin::from_pins;

Modules

builtin	Access to the micro:bit's built-in buttons.
core	Low-level button drivers.
debouncing	Algorithms for debouncing buttons.
dual	High-level driver for two buttons together.
dual_with_hold	High-level driver for two buttons together, with 'hold' support.
monitors	Implementations of the high-level button drivers.
single_eager	High-level driver for a single button, with events on press.
single_lazy	High-level driver for a single button, with events on release.
single_with_hold	High-level driver for a single button, with 'hold' support.