Struct Button

Source

pub struct Button { /* private fields */ }

Expand description

Represents a simple push button as an input of the board. https://docs.arduino.cc/built-in-examples/digital/Button

This structure is very similar to DigitalInput but exposes convenience methods to handle two sorts of buttons:

pull-down: when the button is configured with a pin to ground by default (ie button press => pin becomes high)
pull-up: when the button is configured with a pin to +Vin by default (ie button press => pin becomes low)

Implementations§

Source §

impl Button

Source

pub fn new<T: Into<PinIdOrName>>( board: &dyn Hardware, pin: T, ) -> Result<Self, Error>

Creates an instance of a PULL-DOWN button attached to a given board: https://docs.arduino.cc/built-in-examples/digital/Button/

Button pressed => pin state HIGH
Button released => pin state LOW

§Errors

UnknownPin: this function will bail an error if the Button pin does not exist for this board.
IncompatiblePin: this function will bail an error if the Button pin does not support INPUT mode.

Source

pub fn new_inverted<T: Into<PinIdOrName>>( board: &dyn Hardware, pin: T, ) -> Result<Self, Error>

Creates an instance of an inverted PULL-DOWN button attached to a given board: https://docs.arduino.cc/built-in-examples/digital/Button/

/!\ The state value is inverted compared to HIGH/LOW electrical value of the pin.

Inverted button pressed => pin state LOW
Inverted button released => pin state HIGH

§Errors

UnknownPin: this function will bail an error if the Button pin does not exist for this board.
IncompatiblePin: this function will bail an error if the Button pin does not support INPUT mode.

Source

pub fn new_pullup<T: Into<PinIdOrName>>( board: &dyn Hardware, pin: T, ) -> Result<Self, Error>

Creates an instance of a PULL-UP button attached to a given board: https://docs.arduino.cc/tutorials/generic/digital-input-pullup/

Pullup button pressed => pin state LOW
Pullup button released => pin state HIGH

§Errors

UnknownPin: this function will bail an error if the Button pin does not exist for this board.
IncompatiblePin: this function will bail an error if the Button pin does not support INPUT mode.

Source

pub fn new_inverted_pullup<T: Into<PinIdOrName>>( board: &dyn Hardware, pin: T, ) -> Result<Self, Error>

Creates an instance of an inverted PULL-UP button attached to a given board: https://docs.arduino.cc/tutorials/generic/digital-input-pullup/

/!\ The state value is inverted compared to HIGH/LOW electrical value of the pin (therefore equivalent to a standard pull-down button)

Inverted pullup button pressed => pin state HIGH
Inverted pullup button released => pin state LOW

§Errors

UnknownPin: this function will bail an error if the Button pin does not exist for this board.
IncompatiblePin: this function will bail an error if the Button pin does not support INPUT mode.

Source

pub fn get_pin(&self) -> u8

Returns the pin (id) used by the device.

Source

pub fn is_pullup(&self) -> bool

Returns if the button is configured in PULL-UP mode.

Source

pub fn is_inverted(&self) -> bool

Returns if the logical button value is inverted.

Source

pub fn attach(&self)

Manually attaches the button with the value change events. This should never be needed unless you manually detach() the button first for some reason and want it to start being reactive to events again.

Source

pub fn detach(&self)

Detaches the interval associated with the button. This means the button won’t react anymore to value changes.

Source

pub fn on<S, F, T, Fut>(&self, event: S, callback: F) -> EventHandler
where S: Into<String>, T: 'static + Send + Sync + Clone, F: FnMut(T) -> Fut + Send + 'static, Fut: Future<Output = Result<(), Error>> + Send + 'static,

Registers a callback to be executed on a given event on the Button.

Available events for a button are:

InputEvent::OnChange | change: Triggered when the button value changes.
The callback must receive the following parameter: |value: u16| { ... }
InputEvent::OnRelease | released: Triggered when the button value changes.
The callback must receive the void parameter: |_:()| { ... }
InputEvent::OnPress | pressed: Triggered when the button value changes.
The callback must receive the void parameter: |_:()| { ... }

§Example

use hermes_five::devices::{Button, InputEvent};
use hermes_five::hardware::{Board, BoardEvent};

#[hermes_five::runtime]
async fn main() {
    let board = Board::run();
    board.on(BoardEvent::OnReady, |board: Board| async move {

        // Register a Button on pin 2.
        let button = Button::new(&board, 2)?;
        // Triggered function when the button is pressed.
        button.on(InputEvent::OnPress, |_: ()| async move {
            println!("Push button pressed");
            Ok(())
        });

        // The above code will run forever.
        // <do something useful>

        // The above code will run forever runs a listener on the pin state under-the-hood.
        // It means the program will run forever listening to the InputEvent,
        // until we detach the device and close the board.
        button.detach();
        board.close();

        Ok(())
    });
}