pub struct Pin<MODE, PIN> { /* private fields */ }
Expand description

Representation of an MCU pin.

Design Rationale

We want individual types per pin to model constraints which depend on a specific pin. For example, some peripherals are internally hard-wired to certain pins of the MCU.

Additionally, the mode of a pin should also be a part of the type to model enforcement of pins being in a certain mode and preventing misuse like for example calling set_high() on a pin configured as input.

To do this, the Pin type is generic over the MODE (input, output, …) and the PIN (pd0, pb5, pc6, …).

Of course, in some applications one does not care about the specific pin used. For these situations, the specific pin types can be “downgraded” into a dynamic type that can represent any pin. See Downgrading for more details.

Instantiation

The Peripherals struct in HAL and board-support crates usually contains a .pins field which is of type Pins. This Pins struct in turn has fields for each individual pin, in its default mode. You can then move the pin out of this struct to reconfigure it (examples in this documentation are for atmega-hal):

use atmega_hal::port::{Pin, mode, self};

let dp = atmega_hal::Peripherals::take().unwrap();
let pins = atmega_hal::pins!(dp);

let output: Pin<mode::Output, port::PD3> = pins.pd3.into_output();

Implementations

Configuration

To change the mode of a pin, use one of the following conversion functions. They consume the original Pin and return one with the desired mode. Only when a pin is in the correct mode, does it have the mode-relevant methods availailable (e.g. set_high() is only available for Output pins).

Convert this pin into an output pin, setting the state to low. See Digital Output.

Convert this pin into an output pin, setting the state to high. See Digital Output.

Convert this pin into an open-drain output pin, setting the state to low. See Digital Output Open Drain

Convert this pin into an open-drain output pin, setting the state to high. See Digital Output Open Drain

Convert this pin into a floating input pin. See Digital Input.

Note: To read deterministic values from the pin, it must be externally pulled to a defined level (either VCC or GND).

Convert this pin into a pulled-up input pin. See Digital Input.

With no external circuit pulling the pin low, it will be read high.

Convert this pin into an analog input (ADC channel). See Analog Input.

Some pins can be repurposed as ADC channels. For those pins, the into_analog_input() method is available.

Downgrading

For applications where the exact pin is irrelevant, a specific pin can be downgraded to a “dynamic pin” which can represent any pin:

use atmega_hal::port::{Pin, mode};

let dp = atmega_hal::Peripherals::take().unwrap();
let pins = atmega_hal::pins!(dp);

let any_output_pin1: Pin<mode::Output> = pins.pd0.into_output().downgrade();
let any_output_pin2: Pin<mode::Output> = pins.pd1.into_output().downgrade();

// Because they now have the same type, you can, for example, stuff them into an array:
let pins: [Pin<mode::Output>; 2] = [any_output_pin1, any_output_pin2];

“Erase” type-level information about which specific pin is represented.

Note: The returned “dynamic” pin has runtime overhead compared to a specific pin.

Input-Mode Downgrading

There is a second kind of downgrading: In some cases it is not important whether an input pin is configured as mode::PullUp or mode::Floating. For this, you can “forget” the concrete input mode, leaving you with a type that is the same for pull-up or floating inputs:

use atmega_hal::port::{Pin, mode};

let dp = atmega_hal::Peripherals::take().unwrap();
let pins = atmega_hal::pins!(dp);

// This demo uses downgraded pins, but it works just as well
// with non-downgraded ones!
let input_pin1: Pin<mode::Input<mode::Floating>> = pins.pd0
    .into_floating_input()
    .downgrade();
let input_pin2: Pin<mode::Input<mode::Floating>> = pins.pd1
    .into_pull_up_input()
    .downgrade();

// With the input mode "forgotten", they have the same type now,
// even if electically different.
let any_inputs: [Pin<mode::Input>; 2] = [
    input_pin1.forget_imode(),
    input_pin2.forget_imode(),
];

“Erase” type-level information about whether the pin is currently a pull-up or a floating input.

Set pin high (pull it to supply voltage).

Set pin low (pull it to GND).

Toggle a high pin to low and a low pin to high.

Check whether the pin is set high.

Note: The electrical state of the pin might differ due to external circuitry.

Check whether the pin is set low.

Note: The electrical state of the pin might differ due to external circuitry.

Set the pin high (Input without PullUp so it is floating)

Set pin low (pull it to GND, Output to low).

Check whether the pin is set high.

Note: The electrical state of the pin might differ due to external circuitry.

Check whether the pin is set low.

Note: The electrical state of the pin might differ due to external circuitry.

Check whether the pin is driven high.

Check whether the pin is driven low.

Analog Input

Some pins can be configured as ADC channels. For those pins, analog_read() can be used to read the voltage. analog_read() corresponds to a blocking ADC read:

let dp = atmega_hal::Peripherals::take().unwrap();
let pins = atmega_hal::pins!(dp);
let mut adc = atmega_hal::Adc::new(dp.ADC, Default::default());

let a0 = dp.pc0.into_analog_input(&mut adc);

let voltage = a0.analog_read(&mut adc);
// ^- this is equivalent to -v
let voltage = adc.read_blocking(&a0);

Convert this pin into a generic Channel type.

The generic channel type can be used to store multiple channels in an array.

Trait Implementations

Error type

Is the input pin high?

Is the input pin low?

Error type

Is the input pin high?

Is the input pin low?

Error type

Drives the pin high Read more

Drives the pin low Read more

Drives the pin high or low depending on the provided value Read more

Error type

Drives the pin high Read more

Drives the pin low Read more

Drives the pin high or low depending on the provided value Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.