Struct Input

Help

pub struct Input<'d> { /* private fields */ }

Expand description

Digital input.

This driver configures the GPIO pin to be an input. Input drivers read the voltage of their pins and convert it to a logical Level.

Implementations§

Source §

impl Input<'_>

Source

pub async fn wait_for(&mut self, event: Event)

Wait until the pin experiences a particular Event.

The GPIO driver will disable listening for the event once it occurs, or if the Future is dropped.

Note that calling this function will overwrite previous listen operations for this pin.

Source

pub async fn wait_for_high(&mut self)

Wait until the pin is high.

See Self::wait_for for more information.

Source

pub async fn wait_for_low(&mut self)

Wait until the pin is low.

See Self::wait_for for more information.

Source

pub async fn wait_for_rising_edge(&mut self)

Wait for the pin to undergo a transition from low to high.

See Self::wait_for for more information.

Source

pub async fn wait_for_falling_edge(&mut self)

Wait for the pin to undergo a transition from high to low.

See Self::wait_for for more information.

Source

pub async fn wait_for_any_edge(&mut self)

Wait for the pin to undergo any transition, i.e low to high OR high to low.

See Self::wait_for for more information.

Source §

impl<'d> Input<'d>

Source

pub fn new( pin: impl Peripheral + 'd, config: InputConfig, ) -> Self

Creates a new GPIO input.

The pull parameter configures internal pull-up or pull-down resistors.

§Example

The following example configures GPIO5 to read a button press. The example assumes that the button is connected such that the pin is low when the button is pressed.

use esp_hal::gpio::{Level, Input, InputConfig, Pull};
use esp_hal::delay::Delay;

fn print_when_pressed(button: &mut Input<'_>, delay: &mut Delay) {
    let mut was_pressed = false;
    loop {
        let is_pressed = button.is_low();
        if is_pressed && !was_pressed {
            println!("Button pressed!");
        }
        was_pressed = is_pressed;
        delay.delay_millis(100);
    }
}

let config = InputConfig::default().with_pull(Pull::Up);
let mut button = Input::new(peripherals.GPIO5, config);
let mut delay = Delay::new();

print_when_pressed(&mut button, &mut delay);

Source

pub fn peripheral_input(&self) -> InputSignal

Available on crate feature unstable only.

Returns a peripheral input connected to this pin.

The input signal can be passed to peripherals in place of an input pin.

let config = InputConfig::default().with_pull(Pull::Up);
let pin1_gpio = Input::new(peripherals.GPIO1, config);
let pin1 = pin1_gpio.peripheral_input();

§Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Source

pub fn is_high(&self) -> bool

Get whether the pin input level is high.

Source

pub fn is_low(&self) -> bool

Get whether the pin input level is low.

Source

pub fn level(&self) -> Level

Get the current pin input level.

Source

pub fn apply_config(&mut self, config: &InputConfig)

Change the configuration.

Source

pub fn listen(&mut self, event: Event)

Available on crate feature unstable only.

Listen for interrupts.

The interrupts will be handled by the handler set using Io::set_interrupt_handler. All GPIO pins share the same interrupt handler.

Note that Event::LowLevel and Event::HighLevel are fired continuously when the pin is low or high, respectively. You must use a custom interrupt handler to stop listening for these events, otherwise your program will be stuck in a loop as long as the pin is reading the corresponding level.

§Examples

§Print something when a button is pressed.

use esp_hal::gpio::{Event, Input, InputConfig, Pull, Io};

let mut io = Io::new(peripherals.IO_MUX);
io.set_interrupt_handler(handler);

// Set up the input and store it in the static variable.
// This example uses a push button that is high when not
// pressed and low when pressed.
let config = InputConfig::default().with_pull(Pull::Up);
let mut button = Input::new(peripherals.GPIO5, config);

critical_section::with(|cs| {
    // Here we are listening for a low level to demonstrate
    // that you need to stop listening for level interrupts,
    // but usually you'd probably use `FallingEdge`.
    button.listen(Event::LowLevel);
    BUTTON.borrow_ref_mut(cs).replace(button);
});

// Outside of your `main` function:

use core::cell::RefCell;
use critical_section::Mutex;

// You will need to store the `Input` object in a static variable so
// that the interrupt handler can access it.
static BUTTON: Mutex<RefCell<Option<Input>>> =
    Mutex::new(RefCell::new(None));

#[handler]
fn handler() {
    critical_section::with(|cs| {
        let mut button = BUTTON.borrow_ref_mut(cs);
        let Some(button) = button.as_mut() else {
            // Some other interrupt has occurred
            // before the button was set up.
            return;
        };

        if button.is_interrupt_set() {
            print!("Button pressed");

            // If you want to stop listening for interrupts, you need to
            // call `unlisten` here. If you comment this line, the
            // interrupt will fire continuously while the button
            // is pressed.
            button.unlisten();
        }
    });
}

§Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Source

pub fn unlisten(&mut self)

Available on crate feature unstable only.

Stop listening for interrupts

§Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Source

pub fn clear_interrupt(&mut self)

Available on crate feature unstable only.

Clear the interrupt status bit for this Pin

§Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Source

pub fn is_interrupt_set(&self) -> bool

Available on crate feature unstable only.

Checks if the interrupt status bit for this Pin is set

§Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Source

pub fn wakeup_enable( &mut self, enable: bool, event: WakeEvent, ) -> Result<(), WakeConfigError>

Available on crate feature unstable only.

Enable as a wake-up source.

This will unlisten for interrupts

§Error

Configuring pin to wake up from light sleep on an edge trigger is currently not supported, corresponding variant of WakeConfigError will be returned.

§Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Source

pub fn split(self) -> (InputSignal, OutputSignal)

Available on crate feature unstable only.

Split the pin into an input and output signal.

Peripheral signals allow connecting peripherals together without using external hardware.

let config = InputConfig::default().with_pull(Pull::Up);
let pin1 = Input::new(peripherals.GPIO1, config);
let (input, output) = pin1.split();

§Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Source

pub fn into_peripheral_output(self) -> OutputSignal

Available on crate feature unstable only.

Turns the pin object into a peripheral output.

The output signal can be passed to peripherals in place of an output pin.

let config = InputConfig::default().with_pull(Pull::Up);
let pin1_gpio = Input::new(peripherals.GPIO1, config);
// Can be passed as an output.
let pin1 = pin1_gpio.into_peripheral_output();

§Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Source

pub fn into_flex(self) -> Flex<'d>

Available on crate feature unstable only.

Converts the pin driver into a Flex driver.

§Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.