Struct Input 

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

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

impl Input<'_>

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

Available on crate feature unstable only.

Wait until the pin experiences a particular Event.

Example

use esp_hal::gpio::{Event, Input, InputConfig};
let mut input_pin = Input::new(peripherals.GPIO4, InputConfig::default());

input_pin.wait_for(Event::LowLevel).await;

Cancellation

This function is not cancellation-safe.

• Calling this function will overwrite previous listen operations for this pin, making it side-effectful.
• Dropping the [Future] returned by this function will cancel the wait operation. If the event occurs after the future is dropped, a consequent wait operation will ignore the event.

A wait continues through a light sleep, and a pin that waits also ends the sleep, like a listening pin. There is one exception: a wait for an edge on a pin that is already at the level at the end of that edge. See listen.

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.

pub async fn wait_for_high(&mut self)

Wait until the pin is high.

See Self::wait_for for more information.

Example

use esp_hal::gpio::{Event, Input, InputConfig};
let mut input_pin = Input::new(peripherals.GPIO4, InputConfig::default());

input_pin.wait_for_high().await;

pub async fn wait_for_low(&mut self)

Wait until the pin is low.

See Self::wait_for for more information.

Example

use esp_hal::gpio::{Event, Input, InputConfig};
let mut input_pin = Input::new(peripherals.GPIO4, InputConfig::default());

input_pin.wait_for_low().await;

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.

Example

use esp_hal::gpio::{Event, Input, InputConfig};
let mut input_pin = Input::new(peripherals.GPIO4, InputConfig::default());

input_pin.wait_for_rising_edge().await;

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.

Example

use esp_hal::gpio::{Event, Input, InputConfig};
let mut input_pin = Input::new(peripherals.GPIO4, InputConfig::default());

input_pin.wait_for_falling_edge().await;

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.

Example

use esp_hal::gpio::{Event, Input, InputConfig};
let mut input_pin = Input::new(peripherals.GPIO4, InputConfig::default());

input_pin.wait_for_any_edge().await;

impl<'d> Input<'d>

pub fn new(pin: impl InputPin + '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::{
    delay::Delay,
    gpio::{Input, InputConfig, Level, Pull},
};

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);

pub fn peripheral_input(&self) -> InputSignal<'d>

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.

Note that the signal returned by this function is frozen.

Example

use esp_hal::gpio::{Input, InputConfig, Pull};
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.

pub fn is_high(&self) -> bool

Get whether the pin input level is high.

Example

use esp_hal::gpio::{Input, InputConfig};
let pin = Input::new(peripherals.GPIO5, InputConfig::default());
let is_high = pin.is_high();

pub fn is_low(&self) -> bool

Get whether the pin input level is low.

Example

use esp_hal::gpio::{Input, InputConfig};
let pin = Input::new(peripherals.GPIO5, InputConfig::default());
let is_low = pin.is_low();

pub fn level(&self) -> Level

Get the current pin input level.

Example

use esp_hal::gpio::{Input, InputConfig, Level};
let pin = Input::new(peripherals.GPIO5, InputConfig::default());
let level = pin.level();

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

Change the configuration.

Example

use esp_hal::gpio::{Input, InputConfig, Level, Pull};
let mut pin = Input::new(peripherals.GPIO5, InputConfig::default());
pin.apply_config(&InputConfig::default().with_pull(Pull::Up));

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.

A listening pin also ends a light sleep. On most chips, sleep entry must give the trigger as a level, so an edge trigger becomes the level at the end of the edge. A rising edge becomes a high level, a falling edge becomes a low level, and any edge becomes the level that the pin is not at when the sleep starts. A pin that listens for a rising edge on a line that is already high therefore ends each light sleep immediately, and without an interrupt, because no edge occurred. Automatic light sleep then makes no sleep at all.

Examples

Print something when a button is pressed.

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

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;
use esp_hal::gpio::Input;

// 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));

#[esp_hal::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.

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.

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.

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.

pub fn apply_wakeup_config( &mut self, config: &WakeupConfig, ) -> Result<(), WakeConfigError>

Available on crate feature unstable only.

Configures whether the pin can wake the chip from sleep.

Flex::apply_wakeup_config describes the configuration, and the conditions that wake the chip.

Errors

Returns WakeConfigError::NoLowPowerPath if the configuration requests the low-power path for a pad that has no such path.

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.

pub fn caused_wakeup(&self) -> bool

Available on crate feature unstable only.

Returns whether this pin ended the most recent sleep.

See Flex::caused_wakeup.

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.

pub fn set_pad_hold(&mut self, enable: bool)

Available on crate feature unstable only.

Takes or releases the hold of the pad.

A held pad keeps its level, its function and its resistors, and it ignores this 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.

pub fn is_pad_held(&self) -> bool

Available on crate feature unstable only.

Returns whether something holds the pad.

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.

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.

Trait Implementations

impl<'d> Debug for Input<'d>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl ErrorType for Input<'_>

type Error = Infallible

Error type

impl<'d> From<Input<'d>> for InputSignal<'d>

Available on crate feature unstable only.

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.

fn from(pin: Input<'d>) -> Self

Converts to this type from the input type.

impl InputPin for Input<'_>

fn is_high(&mut self) -> Result<bool, Self::Error>

Is the input pin high?

fn is_low(&mut self) -> Result<bool, Self::Error>

Is the input pin low?

impl Wait for Input<'_>

async fn wait_for_high(&mut self) -> Result<(), Self::Error>

Wait until the pin is high. If it is already high, return immediately.

async fn wait_for_low(&mut self) -> Result<(), Self::Error>

Wait until the pin is low. If it is already low, return immediately.

async fn wait_for_rising_edge(&mut self) -> Result<(), Self::Error>

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

async fn wait_for_falling_edge(&mut self) -> Result<(), Self::Error>

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

async fn wait_for_any_edge(&mut self) -> Result<(), Self::Error>

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

impl<'d> PeripheralInput<'d> for Input<'d>

Available on crate feature unstable only.

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.

impl<'d> PeripheralSignal<'d> for Input<'d>

Available on crate feature unstable only.

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.