Module sodaq_sara_aff::gpio

GPIO

The GPIO module is used to configure GPIO pins through the PORT interface.

Versions

There are currently two versions of the GPIO module. The inital GPIO API used a macro-heavy implementation, and it contained a few mistakes. The discussion in issue #214 spurred the creation of a new module with fewer macros and a corrected, refactored API.

The new module is provided in v2. The old module was removed, but a compatibility shim is provided in v1 to support existing code. Users should expect to eventually migrate to v2.

Errors in v1

v2 fixes a number of errors in v1:

• v1 implements an open-drain output mode, but SAMD chips do not have open-drain outputs. There is (almost) no mention of “open-drain” anywhere in the datasheets. In fact, the SAMD21 datasheet notes a removal of the term in Rev. E. Open-drain outputs have been has been removed in v2.
• v1 allows users to enable a pull-up resistor while in an output mode, but this is not possible for SAMD chips. There is no corresponding entry in the “Pin Configurations Summary” table in any of the three datasheets. Moreover, when a pull resistor is enabled for inputs, its direction is set using the OUT bit, which would not be possible in an output mode.
• v1 does not implement any of the disabled pin modes, i.e. when both DIR and INEN are 0. As a consequence, the state of v1 pins at reset is incorrect. v1 assumes they are in floating input mode, but they are actually in floating disabled mode.

New features

The v2 module has several new features:

• Converting between pin modes no longer requires access to the Port type.

For example, the follow code in v1,

let pins = peripherals.PORT.split();
let pa8 = pins.pa8.into_push_pull_output(&mut pins.port);

would look like this in v2.

let pins = v2::Pins::new(peripherals.PORT);
let pa08 = pins.pa08.into_push_pull_output();

As a consequence, pin mode conversions can now be implemented using From/Into.

let pins = Pins::new(peripherals.PORT);
let pa08: Pin<PA08, PushPullOutput> = pins.pa08.into();

• v2 defines a new AnyPin trait that can be used to simplify function arguments and reduce the number of type parameters required when dealing with GPIO pins.
• v2 offers a type-erased, DynPin type, for run-time tracking of pins.
• v2 provides a new bsp_pins macro to help BSP authors provide meaningful names and type aliases for their GPIO pins.

Compatibility

The original v1 module has been removed. It has been replaced with a compatibility shim to support existing code. The shim implements all v1 pin types in terms of v2::Pin. In fact, it declares its own v1::Pin type as a newtype wrapper around a v2::Pin, and it defines the individual Pa0, Pa1, etc. pin types as type aliases of the new v1::Pin type.

As a consequence, it is easy to define the conversion between a v1::Pin and its corresponding v2::Pin using From/Into.

let pins = peripherals.PORT.split();
let pa8: v1::Pa8<_> = pins.pa8;
let pa08 = v2::Pin<_, _> = pa8.into();

Moreover, all v1::Pin and v2::Pin types implement the AnyPin trait, which is particularly useful for supporting both module versions simultaneously. See the AnyPin documentation for more details.

/// Take the v1 or v2 representation of pin PA08, in any mode, then convert
/// it to a push-pull output and set it high
fn example(pin: impl AnyPin<Id = PA08>) {
    let mut pin = pin.into().into_push_pull_output();
    pin.set_high().ok();
}

Modules

• v1Deprecated
  Version 1 of the GPIO module
• v2
  Version 2 of the GPIO module

Structs

• PartsDeprecated
  Holds the GPIO Port peripheral and broken out pin instances
• PinDeprecated
  Represents a GPIO pin with a corresponding PinId and PinMode
• PortDeprecated
  Opaque port reference

Traits

• GpioExtDeprecated
  The GpioExt trait allows splitting the PORT hardware into its constituent pin parts.
• IntoFunctionDeprecated
  A trait that makes it easier to generically manage converting a pin from its current state into some other functional mode. The configuration change requires exclusive access to the Port hardware, which is why this isn’t simply the standard Into trait.
• PinId
  Type-level enum for pin IDs
• PinMode
  Type-level enum representing pin modes

Type Definitions

• FloatingDeprecated
  Floating Input
• InputDeprecated
  Represents a pin configured for input. The MODE type is typically one of Floating, PullDown or PullUp.
• InterruptDeprecated
  Represents a pin configured for interrupt. The MODE type is one of Floating, PullDown or PullUp.
• OpenDrainDeprecated
  Open drain output. The SAMD5x/E5x chips don’t actually have open drain outputs. This option was added by mistake. It is currently an alias of PushPull
• OutputDeprecated
  Represents a pin configured for output. The MODE type is typically one of PushPull, or OpenDrain.
• Pa0Deprecated
  Represents the IO pin with the matching name
• Pa1Deprecated
  Represents the IO pin with the matching name
• Pa2Deprecated
  Represents the IO pin with the matching name
• Pa3Deprecated
  Represents the IO pin with the matching name
• Pa4Deprecated
  Represents the IO pin with the matching name
• Pa5Deprecated
  Represents the IO pin with the matching name
• Pa6Deprecated
  Represents the IO pin with the matching name
• Pa7Deprecated
  Represents the IO pin with the matching name
• Pa8Deprecated
  Represents the IO pin with the matching name
• Pa9Deprecated
  Represents the IO pin with the matching name
• Pa10Deprecated
  Represents the IO pin with the matching name
• Pa11Deprecated
  Represents the IO pin with the matching name
• Pa12Deprecated
  Represents the IO pin with the matching name
• Pa13Deprecated
  Represents the IO pin with the matching name
• Pa14Deprecated
  Represents the IO pin with the matching name
• Pa15Deprecated
  Represents the IO pin with the matching name
• Pa16Deprecated
  Represents the IO pin with the matching name
• Pa17Deprecated
  Represents the IO pin with the matching name
• Pa18Deprecated
  Represents the IO pin with the matching name
• Pa19Deprecated
  Represents the IO pin with the matching name
• Pa20Deprecated
  Represents the IO pin with the matching name
• Pa21Deprecated
  Represents the IO pin with the matching name
• Pa22Deprecated
  Represents the IO pin with the matching name
• Pa23Deprecated
  Represents the IO pin with the matching name
• Pa24Deprecated
  Represents the IO pin with the matching name
• Pa25Deprecated
  Represents the IO pin with the matching name
• Pa27Deprecated
  Represents the IO pin with the matching name
• Pa28Deprecated
  Represents the IO pin with the matching name
• Pa30Deprecated
  Represents the IO pin with the matching name
• Pa31Deprecated
  Represents the IO pin with the matching name
• Pb0Deprecated
  Represents the IO pin with the matching name
• Pb1Deprecated
  Represents the IO pin with the matching name
• Pb2Deprecated
  Represents the IO pin with the matching name
• Pb3Deprecated
  Represents the IO pin with the matching name
• Pb4Deprecated
  Represents the IO pin with the matching name
• Pb5Deprecated
  Represents the IO pin with the matching name
• Pb6Deprecated
  Represents the IO pin with the matching name
• Pb7Deprecated
  Represents the IO pin with the matching name
• Pb8Deprecated
  Represents the IO pin with the matching name
• Pb9Deprecated
  Represents the IO pin with the matching name
• Pb10Deprecated
  Represents the IO pin with the matching name
• Pb11Deprecated
  Represents the IO pin with the matching name
• Pb12Deprecated
  Represents the IO pin with the matching name
• Pb13Deprecated
  Represents the IO pin with the matching name
• Pb14Deprecated
  Represents the IO pin with the matching name
• Pb15Deprecated
  Represents the IO pin with the matching name
• Pb16Deprecated
  Represents the IO pin with the matching name
• Pb17Deprecated
  Represents the IO pin with the matching name
• Pb22Deprecated
  Represents the IO pin with the matching name
• Pb23Deprecated
  Represents the IO pin with the matching name
• Pb30Deprecated
  Represents the IO pin with the matching name
• Pb31Deprecated
  Represents the IO pin with the matching name
• PfBDeprecated
  Peripheral Function B
• PfCDeprecated
  Peripheral Function C
• PfDDeprecated
  Peripheral Function D
• PfEDeprecated
  Peripheral Function E
• PfFDeprecated
  Peripheral Function F
• PfGDeprecated
  Peripheral Function G
• PfHDeprecated
  Peripheral Function H
• PullDownDeprecated
  Pulled down Input
• PullUpDeprecated
  Pulled up Input
• PushPullDeprecated
  Totem Pole aka Push-Pull
• ReadableOpenDrainDeprecated
  Open drain output, which can be read when not driven The SAMD5x/E5x chips don’t actually have open drain outputs. This option actually represents a readable PushPull output
• SpecificPinDeprecated
  Type alias to recover the specific v1 Pin type from an implementation of AnyPin