Module sodaq_sara_aff::gpio
source · Expand description
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 inv2
.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 theOUT
bit, which would not be possible in an output mode.v1
does not implement any of the disabled pin modes, i.e. when bothDIR
andINEN
are0
. As a consequence, the state ofv1
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 newAnyPin
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 newbsp_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
- v1DeprecatedVersion 1 of the GPIO module
- Version 2 of the GPIO module
Structs
- PartsDeprecatedHolds the GPIO Port peripheral and broken out pin instances
- PinDeprecated
- PortDeprecatedOpaque port reference
Traits
- GpioExtDeprecatedThe GpioExt trait allows splitting the PORT hardware into its constituent pin parts.
- IntoFunctionDeprecatedA 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. - Type-level enum for pin IDs
- Type-level enum representing pin modes
Type Definitions
- FloatingDeprecatedFloating Input
- InputDeprecatedRepresents a pin configured for input. The MODE type is typically one of
Floating
,PullDown
orPullUp
. - InterruptDeprecatedRepresents a pin configured for interrupt. The MODE type is one of
Floating
,PullDown
orPullUp
. - OpenDrainDeprecatedOpen 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
- OutputDeprecatedRepresents a pin configured for output. The MODE type is typically one of
PushPull
, orOpenDrain
. - Pa0DeprecatedRepresents the IO pin with the matching name
- Pa1DeprecatedRepresents the IO pin with the matching name
- Pa2DeprecatedRepresents the IO pin with the matching name
- Pa3DeprecatedRepresents the IO pin with the matching name
- Pa4DeprecatedRepresents the IO pin with the matching name
- Pa5DeprecatedRepresents the IO pin with the matching name
- Pa6DeprecatedRepresents the IO pin with the matching name
- Pa7DeprecatedRepresents the IO pin with the matching name
- Pa8DeprecatedRepresents the IO pin with the matching name
- Pa9DeprecatedRepresents the IO pin with the matching name
- Pa10DeprecatedRepresents the IO pin with the matching name
- Pa11DeprecatedRepresents the IO pin with the matching name
- Pa12DeprecatedRepresents the IO pin with the matching name
- Pa13DeprecatedRepresents the IO pin with the matching name
- Pa14DeprecatedRepresents the IO pin with the matching name
- Pa15DeprecatedRepresents the IO pin with the matching name
- Pa16DeprecatedRepresents the IO pin with the matching name
- Pa17DeprecatedRepresents the IO pin with the matching name
- Pa18DeprecatedRepresents the IO pin with the matching name
- Pa19DeprecatedRepresents the IO pin with the matching name
- Pa20DeprecatedRepresents the IO pin with the matching name
- Pa21DeprecatedRepresents the IO pin with the matching name
- Pa22DeprecatedRepresents the IO pin with the matching name
- Pa23DeprecatedRepresents the IO pin with the matching name
- Pa24DeprecatedRepresents the IO pin with the matching name
- Pa25DeprecatedRepresents the IO pin with the matching name
- Pa27DeprecatedRepresents the IO pin with the matching name
- Pa28DeprecatedRepresents the IO pin with the matching name
- Pa30DeprecatedRepresents the IO pin with the matching name
- Pa31DeprecatedRepresents the IO pin with the matching name
- Pb0DeprecatedRepresents the IO pin with the matching name
- Pb1DeprecatedRepresents the IO pin with the matching name
- Pb2DeprecatedRepresents the IO pin with the matching name
- Pb3DeprecatedRepresents the IO pin with the matching name
- Pb4DeprecatedRepresents the IO pin with the matching name
- Pb5DeprecatedRepresents the IO pin with the matching name
- Pb6DeprecatedRepresents the IO pin with the matching name
- Pb7DeprecatedRepresents the IO pin with the matching name
- Pb8DeprecatedRepresents the IO pin with the matching name
- Pb9DeprecatedRepresents the IO pin with the matching name
- Pb10DeprecatedRepresents the IO pin with the matching name
- Pb11DeprecatedRepresents the IO pin with the matching name
- Pb12DeprecatedRepresents the IO pin with the matching name
- Pb13DeprecatedRepresents the IO pin with the matching name
- Pb14DeprecatedRepresents the IO pin with the matching name
- Pb15DeprecatedRepresents the IO pin with the matching name
- Pb16DeprecatedRepresents the IO pin with the matching name
- Pb17DeprecatedRepresents the IO pin with the matching name
- Pb22DeprecatedRepresents the IO pin with the matching name
- Pb23DeprecatedRepresents the IO pin with the matching name
- Pb30DeprecatedRepresents the IO pin with the matching name
- Pb31DeprecatedRepresents the IO pin with the matching name
- PfBDeprecatedPeripheral Function B
- PfCDeprecatedPeripheral Function C
- PfDDeprecatedPeripheral Function D
- PfEDeprecatedPeripheral Function E
- PfFDeprecatedPeripheral Function F
- PfGDeprecatedPeripheral Function G
- PfHDeprecatedPeripheral Function H
- PullDownDeprecatedPulled down Input
- PullUpDeprecatedPulled up Input
- PushPullDeprecatedTotem Pole aka Push-Pull
- ReadableOpenDrainDeprecatedOpen 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