Expand description

Type-level module for GPIO pins

This module provides a type-level API for GPIO pins. It uses the type system to track the state of pins at compile-time. Representing GPIO pins in this manner incurs no run-time overhead. Each Pin struct is zero-sized, so there is no data to copy around. Instead, real code is generated as a side effect of type transformations, and the resulting assembly is nearly identical to the equivalent, hand-written C.

To track the state of pins at compile-time, this module uses traits to represent type classes and types as instances of those type classes. For example, the trait InputConfig acts as a type-level enum of the available input configurations, and the types Floating, PullDown and PullUp are its type-level variants.

Type-level Pins are parameterized by two type-level enums, PinId and PinMode.

pub struct Pin<I, M>
where
    I: PinId,
    M: PinMode,
{
    // ...
}

A PinId identifies a pin by it’s group (A, B, C or D) and pin number. Each PinId instance is named according to its datasheet identifier, e.g. PA02.

A PinMode represents the various pin modes. The available PinMode variants are Disabled, Input, Interrupt, Output and Alternate, each with its own corresponding configurations.

It is not possible for users to create new instances of a Pin. Singleton instances of each pin are made available to users through the Pins struct.

To create the Pins struct, users must supply the PAC PORT peripheral. The Pins struct takes ownership of the PORT and provides the corresponding pins. Each Pin within the Pins struct can be moved out and used individually.

let mut peripherals = Peripherals::take().unwrap();
let pins = Pins::new(peripherals.PORT);

Pins can be converted between modes using several different methods.

// Use one of the literal function names
let pa27 = pins.pa27.into_floating_input();
// Use a generic method and one of the `PinMode` variant types
let pa27 = pins.pa27.into_mode::<FloatingInput>();
// Specify the target type and use `From`/`Into`
let pa27: Pin<PA27, FloatingInput> = pins.pa27.into();

Embedded HAL traits

This module implements all of the embedded HAL GPIO traits for each Pin in the corresponding PinModes, namely: InputPin, OutputPin, ToggleableOutputPin and StatefulOutputPin.

For example, you can control the logic level of an OutputPin like so

use atsamd_hal::pac::Peripherals;
use atsamd_hal::gpio::Pins;
use embedded_hal::digital::v2::OutputPin;

let mut peripherals = Peripherals::take().unwrap();
let mut pins = Pins::new(peripherals.PORT);
pins.pa27.set_high();

Type-level features

This module also provides additional, type-level tools to work with GPIO pins.

The OptionalPinId and OptionalPin traits use the OptionalKind pattern to act as type-level versions of Option for PinId and Pin respectively. And the AnyPin trait defines an AnyKind type class for all Pin types.

Structs

Type-level variant of PinMode for alternate peripheral functions
Type-level variant of PinMode for disabled modes
Type-level variant of PinMode for input modes
Type-level variant of PinMode for Interrupt modes
Type-level variant of PinMode for output modes
A type-level GPIO pin, parameterized by PinId and PinMode types
Collection of all the individual Pins

Enums

Type-level variant of AlternateConfig for alternate peripheral function B
Type-level variant of AlternateConfig for alternate peripheral function C
Type-level variant of AlternateConfig for alternate peripheral function D
Type-level variant of AlternateConfig for alternate peripheral function E
Type-level variant of AlternateConfig for alternate peripheral function F
Type-level variant of both DisabledConfig and InputConfig
Type-level variant of AlternateConfig for alternate peripheral function G
Type-level variant of AlternateConfig for alternate peripheral function H
Type-level variant of AlternateConfig for alternate peripheral function I
Type-level variant of AlternateConfig for alternate peripheral function J
Type-level variant of AlternateConfig for alternate peripheral function K
Type-level variant of AlternateConfig for alternate peripheral function L
Type-level variant of AlternateConfig for alternate peripheral function M
Type-level variant of AlternateConfig for alternate peripheral function N
Pin ID representing pin PA00
Pin ID representing pin PA01
Pin ID representing pin PA02
Pin ID representing pin PA03
Pin ID representing pin PA04
Pin ID representing pin PA05
Pin ID representing pin PA06
Pin ID representing pin PA07
Pin ID representing pin PA08
Pin ID representing pin PA09
Pin ID representing pin PA10
Pin ID representing pin PA11
Pin ID representing pin PA12
Pin ID representing pin PA13
Pin ID representing pin PA14
Pin ID representing pin PA15
Pin ID representing pin PA16
Pin ID representing pin PA17
Pin ID representing pin PA18
Pin ID representing pin PA19
Pin ID representing pin PA20
Pin ID representing pin PA21
Pin ID representing pin PA22
Pin ID representing pin PA23
Pin ID representing pin PA24
Pin ID representing pin PA25
Pin ID representing pin PA27
Pin ID representing pin PA30
Pin ID representing pin PA31
Pin ID representing pin PB00
Pin ID representing pin PB01
Pin ID representing pin PB02
Pin ID representing pin PB03
Pin ID representing pin PB04
Pin ID representing pin PB05
Pin ID representing pin PB06
Pin ID representing pin PB07
Pin ID representing pin PB08
Pin ID representing pin PB09
Pin ID representing pin PB10
Pin ID representing pin PB11
Pin ID representing pin PB12
Pin ID representing pin PB13
Pin ID representing pin PB14
Pin ID representing pin PB15
Pin ID representing pin PB16
Pin ID representing pin PB17
Pin ID representing pin PB18
Pin ID representing pin PB19
Pin ID representing pin PB20
Pin ID representing pin PB21
Pin ID representing pin PB22
Pin ID representing pin PB23
Pin ID representing pin PB24
Pin ID representing pin PB25
Pin ID representing pin PB30
Pin ID representing pin PB31
Pin ID representing pin PC00
Pin ID representing pin PC01
Pin ID representing pin PC02
Pin ID representing pin PC03
Pin ID representing pin PC05
Pin ID representing pin PC06
Pin ID representing pin PC07
Pin ID representing pin PC10
Pin ID representing pin PC11
Pin ID representing pin PC12
Pin ID representing pin PC13
Pin ID representing pin PC14
Pin ID representing pin PC15
Pin ID representing pin PC16
Pin ID representing pin PC17
Pin ID representing pin PC18
Pin ID representing pin PC19
Pin ID representing pin PC20
Pin ID representing pin PC21
Pin ID representing pin PC24
Pin ID representing pin PC25
Pin ID representing pin PC26
Pin ID representing pin PC27
Pin ID representing pin PC28
Type-level variant of both DisabledConfig and InputConfig
Type-level variant of both DisabledConfig and InputConfig
Type-level variant of OutputConfig for a push-pull configuration
Type-level variant of OutputConfig for a readable push-pull configuration

Traits

Type-level enum for alternate peripheral function configurations
Type class for Pin types
Type-level enum for disabled configurations
Type-level enum for input configurations
Type-level enum for Interrupt configurations
Type-level equivalent of Option<PinId>
Type-level equivalent of Option<PinId>
Type-level enum for output configurations
Type-level enum for pin IDs
Type-level enum representing pin modes
Type-level equivalent of Some(PinId)
Type-level equivalent of Some(PinId)

Type Definitions

Type-level variant of PinMode for alternate peripheral function B
Type-level variant of PinMode for alternate peripheral function C
Type-level variant of PinMode for alternate peripheral function D
Type-level variant of PinMode for alternate peripheral function E
Type-level variant of PinMode for alternate peripheral function F
Type-level variant of PinMode for alternate peripheral function G
Type-level variant of PinMode for alternate peripheral function H
Type-level variant of PinMode for alternate peripheral function I
Type-level variant of PinMode for alternate peripheral function J
Type-level variant of PinMode for alternate peripheral function K
Type-level variant of PinMode for alternate peripheral function L
Type-level variant of PinMode for alternate peripheral function M
Type-level variant of PinMode for alternate peripheral function N
Type-level variant of PinMode for floating disabled mode
Type-level variant of PinMode for floating input mode
Type-level variant of PinMode for floating Interrupt mode
Type-level variant of PinMode for pull-down disabled mode
Type-level variant of PinMode for pull-down input mode
Type-level variant of PinMode for pull-down Interrupt mode
Type-level variant of PinMode for pull-up disabled mode
Type-level variant of PinMode for pull-up input mode
Type-level variant of PinMode for pull-up Interrupt mode
Type-level variant of PinMode for push-pull output mode
Type-level variant of PinMode for readable push-pull output mode
Type alias for the PinMode at reset
Type alias to recover the specific Pin type from an implementation of AnyPin