Struct esp_idf_svc::hal::gpio::PinDriver

pub struct PinDriver<'d, T, MODE>
where
    T: Pin,
{ /* private fields */ }

A driver for a GPIO pin.

The driver can set the pin as a disconnected/disabled one, input, or output pin, or both or analog. On some chips (i.e. esp32 and esp32s*), the driver can also set the pin in RTC IO mode. Depending on the current operating mode, different sets of functions are available.

The mode-setting depends on the capabilities of the pin as well, i.e. input-only pins cannot be set into output or input-output mode.

Implementations

impl<'d, T> PinDriver<'d, T, Disabled>

where T: Pin,

pub fn disabled( pin: impl Peripheral<P = T> + 'd, ) -> Result<PinDriver<'d, T, Disabled>, EspError>

Creates the driver for a pin in disabled state.

impl<'d, T> PinDriver<'d, T, Input>

where T: InputPin,

pub fn input( pin: impl Peripheral<P = T> + 'd, ) -> Result<PinDriver<'d, T, Input>, EspError>

Creates the driver for a pin in input state.

impl<'d, T> PinDriver<'d, T, InputOutput>

where T: InputPin + OutputPin,

pub fn input_output( pin: impl Peripheral<P = T> + 'd, ) -> Result<PinDriver<'d, T, InputOutput>, EspError>

Creates the driver for a pin in input-output state.

impl<'d, T> PinDriver<'d, T, InputOutput>

where T: InputPin + OutputPin,

pub fn input_output_od( pin: impl Peripheral<P = T> + 'd, ) -> Result<PinDriver<'d, T, InputOutput>, EspError>

Creates the driver for a pin in input-output open-drain state.

impl<'d, T> PinDriver<'d, T, Output>

where T: OutputPin,

pub fn output( pin: impl Peripheral<P = T> + 'd, ) -> Result<PinDriver<'d, T, Output>, EspError>

Creates the driver for a pin in output state.

impl<'d, T> PinDriver<'d, T, Output>

where T: OutputPin,

pub fn output_od( pin: impl Peripheral<P = T> + 'd, ) -> Result<PinDriver<'d, T, Output>, EspError>

Creates the driver for a pin in output open-drain state.

impl<'d, T, MODE> PinDriver<'d, T, MODE>

where T: Pin,

pub fn pin(&self) -> i32

Returns the pin number.

pub fn into_disabled(self) -> Result<PinDriver<'d, T, Disabled>, EspError>

Put the pin into disabled mode.

pub fn into_input(self) -> Result<PinDriver<'d, T, Input>, EspError>

where T: InputPin,

Put the pin into input mode.

pub fn into_input_output( self, ) -> Result<PinDriver<'d, T, InputOutput>, EspError>

where T: InputPin + OutputPin,

Put the pin into input + output mode.

pub fn into_input_output_od( self, ) -> Result<PinDriver<'d, T, InputOutput>, EspError>

where T: InputPin + OutputPin,

Put the pin into input + output Open Drain mode.

This is commonly used for “open drain” mode. the hardware will drive the line low if you set it to low, and will leave it floating if you set it to high, in which case you can read the input to figure out whether another device is driving the line low.

pub fn into_output(self) -> Result<PinDriver<'d, T, Output>, EspError>

where T: OutputPin,

Put the pin into output mode.

pub fn into_output_od(self) -> Result<PinDriver<'d, T, Output>, EspError>

where T: OutputPin,

Put the pin into output Open Drain mode.

pub fn get_drive_strength(&self) -> Result<DriveStrength, EspError>

where MODE: OutputMode,

pub fn set_drive_strength( &mut self, strength: DriveStrength, ) -> Result<(), EspError>

where MODE: OutputMode,

pub fn is_high(&self) -> bool

where MODE: InputMode,

pub fn is_low(&self) -> bool

where MODE: InputMode,

pub fn get_level(&self) -> Level

where MODE: InputMode,

pub fn is_set_high(&self) -> bool

where MODE: OutputMode,

pub fn is_set_low(&self) -> bool

where MODE: OutputMode,

Is the output pin set as low?

pub fn set_high(&mut self) -> Result<(), EspError>

where MODE: OutputMode,

pub fn set_low(&mut self) -> Result<(), EspError>

where MODE: OutputMode,

Set the output as low.

pub fn set_level(&mut self, level: Level) -> Result<(), EspError>

where MODE: OutputMode,

pub fn toggle(&mut self) -> Result<(), EspError>

where MODE: OutputMode,

Toggle pin output

pub fn set_pull(&mut self, pull: Pull) -> Result<(), EspError>

where T: InputPin + OutputPin, MODE: InputMode,

pub unsafe fn subscribe<F>(&mut self, callback: F) -> Result<(), EspError>

where F: FnMut() + Send + 'static, MODE: InputMode,

Subscribes the provided callback for ISR notifications. As a side effect, interrupts will be disabled, so to receive a notification, one has to also call PinDriver::enable_interrupt after calling this method.

Note that PinDriver::enable_interrupt should also be called after each received notification from non-ISR context, because the driver will automatically disable ISR interrupts on each received ISR notification (so as to avoid IWDT triggers).

Safety

Care should be taken not to call STD, libc or FreeRTOS APIs (except for a few allowed ones) in the callback passed to this function, as it is executed in an ISR context.

pub unsafe fn subscribe_nonstatic<F>( &mut self, callback: F, ) -> Result<(), EspError>

where F: FnMut() + Send + 'd, MODE: InputMode,

Subscribes the provided callback for ISR notifications. As a side effect, interrupts will be disabled, so to receive a notification, one has to also call PinDriver::enable_interrupt after calling this method.

Note that PinDriver::enable_interrupt should also be called after each received notification from non-ISR context, because the driver will automatically disable ISR interrupts on each received ISR notification (so as to avoid IWDT triggers).

Safety

Care should be taken not to call STD, libc or FreeRTOS APIs (except for a few allowed ones) in the callback passed to this function, as it is executed in an ISR context.

Additionally, this method - in contrast to method subscribe - allows the passed-in callback/closure to be non-'static. This enables users to borrow

• in the closure - variables that live on the stack - or more generally - in the same scope where the driver is created.

HOWEVER: care should be taken NOT to call core::mem::forget() on the driver, as that would immediately lead to an UB (crash). Also note that forgetting the driver might happen with Rc and Arc when circular references are introduced: https://github.com/rust-lang/rust/issues/24456

The reason is that the closure is actually sent and owned by an ISR routine, which means that if the driver is forgotten, Rust is free to e.g. unwind the stack and the ISR routine will end up with references to variables that no longer exist.

The destructor of the driver takes care - prior to the driver being dropped and e.g. the stack being unwind - to unsubscribe the ISR routine. Unfortunately, when the driver is forgotten, the un-subscription does not happen and invalid references are left dangling.

This “local borrowing” will only be possible to express in a safe way once/if !Leak types are introduced to Rust (i.e. the impossibility to “forget” a type and thus not call its destructor).

pub fn unsubscribe(&mut self) -> Result<(), EspError>

where MODE: InputMode,

pub fn enable_interrupt(&mut self) -> Result<(), EspError>

where MODE: InputMode,

Enables or re-enables the interrupt

Note that the interrupt is automatically disabled each time an interrupt is triggered (or else we risk entering a constant interrupt processing loop while the pin is in low/high state and the interrupt type is set to non-edge)

Therefore - to continue receiving ISR interrupts - user needs to call enable_interrupt

• from a non-ISR context - after each successful interrupt triggering.

pub fn disable_interrupt(&mut self) -> Result<(), EspError>

where MODE: InputMode,

pub fn set_interrupt_type( &mut self, interrupt_type: InterruptType, ) -> Result<(), EspError>

where MODE: InputMode,

impl<T, MODE> PinDriver<'_, T, MODE>

where T: Pin, MODE: InputMode,

pub async fn wait_for( &mut self, interrupt_type: InterruptType, ) -> Result<(), EspError>

pub async fn wait_for_high(&mut self) -> Result<(), EspError>

pub async fn wait_for_low(&mut self) -> Result<(), EspError>

pub async fn wait_for_rising_edge(&mut self) -> Result<(), EspError>

pub async fn wait_for_falling_edge(&mut self) -> Result<(), EspError>

pub async fn wait_for_any_edge(&mut self) -> Result<(), EspError>

Trait Implementations

impl<'d, T, MODE> Drop for PinDriver<'d, T, MODE>

where T: Pin,

fn drop(&mut self)

Executes the destructor for this type.

impl<'d, T, MODE> ErrorType for PinDriver<'d, T, MODE>

where T: Pin,

type Error = GpioError

Error type

impl<'d, T, MODE> InputPin for &PinDriver<'d, T, MODE>

where T: Pin, MODE: InputMode,

fn is_high( &mut self, ) -> Result<bool, <&PinDriver<'d, T, MODE> as ErrorType>::Error>

Is the input pin high?

fn is_low( &mut self, ) -> Result<bool, <&PinDriver<'d, T, MODE> as ErrorType>::Error>

Is the input pin low?

impl<'d, T, MODE> InputPin for PinDriver<'d, T, MODE>

where T: Pin, MODE: InputMode,

fn is_high( &mut self, ) -> Result<bool, <PinDriver<'d, T, MODE> as ErrorType>::Error>

Is the input pin high?

fn is_low( &mut self, ) -> Result<bool, <PinDriver<'d, T, MODE> as ErrorType>::Error>

Is the input pin low?

impl<'d, T, MODE> InputPin for PinDriver<'d, T, MODE>

where T: Pin, MODE: InputMode,

type Error = EspError

Error type

fn is_high(&self) -> Result<bool, <PinDriver<'d, T, MODE> as InputPin>::Error>

Is the input pin high?

fn is_low(&self) -> Result<bool, <PinDriver<'d, T, MODE> as InputPin>::Error>

Is the input pin low?

impl<'d, T, MODE> OutputPin for PinDriver<'d, T, MODE>

where T: Pin, MODE: OutputMode,

type Error = EspError

Error type

fn set_high( &mut self, ) -> Result<(), <PinDriver<'d, T, MODE> as OutputPin>::Error>

Drives the pin high

fn set_low( &mut self, ) -> Result<(), <PinDriver<'d, T, MODE> as OutputPin>::Error>

Drives the pin low

fn set_state(&mut self, state: PinState) -> Result<(), Self::Error>

Drives the pin high or low depending on the provided value

impl<'d, T, MODE> OutputPin for PinDriver<'d, T, MODE>

where T: Pin, MODE: OutputMode,

fn set_high( &mut self, ) -> Result<(), <PinDriver<'d, T, MODE> as ErrorType>::Error>

Drives the pin high.

fn set_low( &mut self, ) -> Result<(), <PinDriver<'d, T, MODE> as ErrorType>::Error>

Drives the pin low.

fn set_state(&mut self, state: PinState) -> Result<(), Self::Error>

Drives the pin high or low depending on the provided value.

impl<'d, T, MODE> StatefulOutputPin for PinDriver<'d, T, MODE>

where T: Pin, MODE: OutputMode,

fn is_set_high( &mut self, ) -> Result<bool, <PinDriver<'d, T, MODE> as ErrorType>::Error>

Is the pin in drive high mode?

fn is_set_low( &mut self, ) -> Result<bool, <PinDriver<'d, T, MODE> as ErrorType>::Error>

Is the pin in drive low mode?

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

Toggle pin output.

impl<'d, T, MODE> StatefulOutputPin for PinDriver<'d, T, MODE>

where T: Pin, MODE: OutputMode,

fn is_set_high( &self, ) -> Result<bool, <PinDriver<'d, T, MODE> as OutputPin>::Error>

Is the pin in drive high mode?

fn is_set_low( &self, ) -> Result<bool, <PinDriver<'d, T, MODE> as OutputPin>::Error>

Is the pin in drive low mode?

impl<'d, T, MODE> ToggleableOutputPin for PinDriver<'d, T, MODE>

where T: Pin, MODE: OutputMode,

type Error = EspError

Error type

fn toggle( &mut self, ) -> Result<(), <PinDriver<'d, T, MODE> as ToggleableOutputPin>::Error>

Toggle pin output.

impl<T, MODE> Wait for PinDriver<'_, T, MODE>

where T: Pin, MODE: InputMode,

async fn wait_for_high(&mut self) -> Result<(), GpioError>

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

async fn wait_for_low(&mut self) -> Result<(), GpioError>

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

async fn wait_for_rising_edge(&mut self) -> Result<(), GpioError>

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

async fn wait_for_falling_edge(&mut self) -> Result<(), GpioError>

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

async fn wait_for_any_edge(&mut self) -> Result<(), GpioError>

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

impl<'d, T, MODE> Send for PinDriver<'d, T, MODE>

where T: Pin,