Struct PinDriver 

pub struct PinDriver<'d, MODE> { /* 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, MODE> PinDriver<'d, MODE>

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

Try to convert the pin driver into a disabled pin driver.

Return an error if the pin cannot be disabled.

pub fn try_into_input( self, pull: Pull, ) -> Result<PinDriver<'d, Input>, EspError>

Try to convert the pin driver into an input pin driver.

Return an error if the pin cannot be set as input.

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

Try to convert the pin driver into an output pin driver.

Return an error if the pin cannot be set as output.

pub fn try_into_input_output( self, pull: Pull, ) -> Result<PinDriver<'d, InputOutput>, EspError>

Try to convert the pin driver into an input-output pin driver.

Return an error if the pin cannot be set as input-output.

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

Try to convert the pin driver into an output open-drain pin driver.

Return an error if the pin cannot be set as output open-drain.

pub fn try_into_input_output_od( self, pull: Pull, ) -> Result<PinDriver<'d, InputOutput>, EspError>

Try to convert the pin driver into an input-output open-drain pin driver.

Return an error if the pin cannot be set as input-output open-drain.

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

pub fn disabled<T: Pin + 'd>(pin: T) -> Result<Self, EspError>

Creates the driver for a pin in disabled state.

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

pub fn input<T: InputPin + 'd>(pin: T, pull: Pull) -> Result<Self, EspError>

Creates the driver for a pin in input state.

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

pub fn input_output<T: InputPin + OutputPin + 'd>( pin: T, pull: Pull, ) -> Result<Self, EspError>

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

pub fn input_output_od<T: InputPin + OutputPin + 'd>( pin: T, pull: Pull, ) -> Result<Self, EspError>

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

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

pub fn output<T: OutputPin + 'd>(pin: T) -> Result<Self, EspError>

Creates the driver for a pin in output state.

pub fn output_od<T: OutputPin + 'd>(pin: T) -> Result<Self, EspError>

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

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

pub fn pin(&self) -> PinId

Returns the pin number.

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 unsafe fn subscribe<F: FnMut() + Send + 'static>( &mut self, callback: F, ) -> Result<(), EspError>

where 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: FnMut() + Send + 'd>( &mut self, callback: F, ) -> Result<(), EspError>

where 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<MODE: InputMode> PinDriver<'_, MODE>

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<MODE> Drop for PinDriver<'_, MODE>

fn drop(&mut self)

Executes the destructor for this type.

impl<MODE> ErrorType for PinDriver<'_, MODE>

type Error = GpioError

Error type

impl<MODE> InputPin for &PinDriver<'_, MODE>

where MODE: InputMode,

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<MODE> InputPin for PinDriver<'_, MODE>

where MODE: InputMode,

type Error = EspError

Error type

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

Is the input pin high?

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

Is the input pin low?

impl<MODE> InputPin for PinDriver<'_, MODE>

where MODE: InputMode,

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<MODE> OutputPin for PinDriver<'_, MODE>

where MODE: OutputMode,

type Error = EspError

Error type

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

Drives the pin high

fn set_low(&mut self) -> Result<(), Self::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<MODE> OutputPin for PinDriver<'_, MODE>

where MODE: OutputMode,

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

Drives the pin high.

fn set_low(&mut self) -> Result<(), Self::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<MODE> StatefulOutputPin for PinDriver<'_, MODE>

where MODE: OutputMode,

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

Is the pin in drive high mode?

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

Is the pin in drive low mode?

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

Toggle pin output.

impl<MODE> StatefulOutputPin for PinDriver<'_, MODE>

where MODE: OutputMode,

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

Is the pin in drive high mode?

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

Is the pin in drive low mode?

impl<MODE> ToggleableOutputPin for PinDriver<'_, MODE>

where MODE: OutputMode,

type Error = EspError

Error type

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

Toggle pin output.

impl<MODE: InputMode> Wait for PinDriver<'_, MODE>

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<MODE> Send for PinDriver<'_, MODE>