arduino_mkrvidor4000

Module 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 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 Aliases§

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
Pb2Deprecated
Represents the IO pin with the matching name
Pb3Deprecated
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
Pb22Deprecated
Represents the IO pin with the matching name
Pb23Deprecated
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