Struct lpc8xx_hal::swm::Pin

pub struct Pin<T: PinTrait, S: PinState> { /* fields omitted */ }

Main API to control for controlling pins

Pin has two type parameters:

• T, to indicate which specific pin this instance of Pin represents (so, PIO0_0, PIO0_1, and so on)
• S, to indicate which state the represented pin is currently in

A pin instance can be in one of the following states:

• pin_state::Unused, to indicate that the pin is currently not used
• pin_state::Gpio, to indicate that the pin is being used for general-purpose I/O
• pin_state::Swm, to indicate that the pin is available for switch matrix function assignment
• pin_state::Analog, to indicate that the pin is being used for analog input

State Management

All pins start out their initial state, as defined in the user manual. To prevent us from making mistakes, only the methods that induce a valid state transition are available. Code that tries to call a method that would cause an invalid state transition will simply not compile:

// Assign a function to a pin
let (clkout, pio0_12) = swm.movable_functions.clkout.assign(
    swm.pins.pio0_12.into_swm_pin(),
    &mut swm.handle,
);

// As long as the function is assigned, we can't use the pin for
// general-purpose I/O. Therefore the following method call would cause a
// compile-time error.
// let pio0_12 = pio0_12.into_gpio_pin(&p.GPIO);

To use the pin in the above example for GPIO, we first have to unassign the movable function and transition the pin to the unused state:

let (clkout, pio0_12) = clkout.unassign(pio0_12, &mut swm.handle);
let pio0_12 = pio0_12.into_unused_pin();

// Now we can transition the pin into the GPIO state.
let pio0_12 = pio0_12.into_gpio_pin(&p.GPIO);

General Purpose I/O

All pins can be used for general-purpose I/O (GPIO), meaning they can be used for reading digital input signals and writing digital output signals. To set up a pin for GPIO use, you need to call Pin::into_gpio_pin when it is in its unused state.

use lpc82x_hal::Peripherals;

let mut p = Peripherals::take().unwrap();

let mut swm = p.SWM.split();

// The pin takes a shared reference to `GPIO`, which it keeps around as long
// as the pin is in the GPIO state. This ensures the GPIO peripheral can't
// be disabled while we're still using the pin for GPIO.
let pin = swm.pins.pio0_12.into_gpio_pin(&p.GPIO);

Now pin is in the GPIO state. The GPIO state has the following sub-states:

• direction::Unknown, to indicate that the current GPIO configuration is not known
• direction::Input, to indicate that the pin is configured for digital input
• direction::Output, to indicate that the pin is configured for digital output

To use a pin, that we previously configured for GPIO (see example above), for digital output, we need to set the pin direction using Pin::into_output.

use lpc82x_hal::prelude::*;

// Configure pin for digital output. This assumes that the pin is currently
// in the GPIO state.
let mut pin = pin.into_output();

// Now we can change the output signal as we like.
pin.set_high();
pin.set_low();

Using pins for digital input is currently not supported by the API. If you need this feature, please speak up.

Fixed and Movable Functions

Besides general-purpose I/O, pins can be used for a number of more specialized functions. Some of those can be used only on one specific pin (fixed functions), others can be assigned to any pin (movable functions).

Before you can assign any functions to a pin, you need to transition it from the unused state to the SWM state using Pin::into_swm_pin.

let pin = swm.pins.pio0_12
    .into_swm_pin();

// Functions can be assigned now using the methods on `Function`

As mentioned above, a function can be fixed or movable. But there is also another distinction: Functions can be input or output functions. Any number of input functions can be assigned to a pin at the same time, but at most one output function can be assigned to a pin at once (see user manual, section 7.4). These rules are enforced by the API at compile time.

NOTE: There is some uncertainty about whether those rules treat GPIO as just another kind of function, or if they don't apply to it. Currently, this API treats GPIO as something entirely different from the switch matrix functions, which may be too restrictive. If you have any insight on this topic, please help us figure this out.

Once a pin is in the SWM state, you can assign functions to it. Please refer to Function for more information on how to do that.

Analog Input

To use a pin for analog input, you need to assign an ADC function:

use lpc82x_hal::Peripherals;

let p = Peripherals::take().unwrap();

let mut swm = p.SWM.split();

// Transition pin into ADC state
let (adc_2, pio0_14) = swm.fixed_functions.adc_2.assign(
    swm.pins.pio0_14.into_swm_pin(),
    &mut swm.handle,
);

Using the pin for analog input once it is in the ADC state is currently not supported by this API. If you need this feature, please let us know!

As a woraround, you can use the raw register mappings from the lpc82x crate, lpc82x::IOCON and lpc82x::ADC, after you have put the pin into the ADC state.

Methods

impl<'gpio, T, D> Pin<T, Gpio<'gpio, D>> where
    T: PinTrait,
    D: NotOutput, 

pub fn into_output(self) -> Pin<T, Gpio<'gpio, Output>>

Set pin direction to output

This method is only available, if the pin is in the GPIO state and the pin is not already in output mode, i.e. the pin direction is input or unknown. You can enter the GPIO state using Pin::into_gpio_pin.

Consumes the pin instance and returns a new instance that is in output mode, making the methods to set the output level available.

Example

use lpc82x_hal::prelude::*;
use lpc82x_hal::Peripherals;

let p = Peripherals::take().unwrap();

let swm = p.SWM.split();

// Transition pin into GPIO state, then set it to output
let mut pin = swm.pins.pio0_12
    .into_gpio_pin(&p.GPIO)
    .into_output();

// Output level can now be controlled
pin.set_high();
pin.set_low();

impl<T> Pin<T, Unused> where
    T: PinTrait, 

pub fn into_gpio_pin(self, gpio: &GPIO) -> Pin<T, Gpio<Unknown>>

Transition pin to GPIO state

This method is only available while the pin is in the unused state. Code that attempts to call this method while the pin is in any other state will not compile. See State Management for more information on managing pin states.

Consumes this pin instance and returns a new instance that is in the GPIO state, allowing you to use the pin for general-purpose I/O. As long as the pin is in the GPIO state, it needs the GPIO peripheral to be enabled to function correctly. To statically guarantee that this is the case, this method takes a shared reference to GPIO, which the pin keeps around until it leaves the GPIO state.

Example

use lpc82x_hal::Peripherals;

let p = Peripherals::take().unwrap();

let swm = p.SWM.split();

let pin = swm.pins.pio0_12
    .into_gpio_pin(&p.GPIO);

// `pin` is now available for general-purpose I/O

pub fn into_swm_pin(self) -> Pin<T, Swm<(), ()>>

Transition pin to SWM state

This method is only available while the pin is in the unused state. Code that attempts to call this method while the pin is in any other state will not compile. See State Management for more information on managing pin states.

Consumes this pin instance and returns a new instance that is in the SWM state, making this pin available for switch matrix function assignment.

Please refer Function to learn more about SWM function assignment.

Example

use lpc82x_hal::Peripherals;

let p = Peripherals::take().unwrap();

let swm = p.SWM.split();

let pin = swm.pins.pio0_12
    .into_swm_pin();

// `pin` is now ready for function assignment

impl<T> Pin<T, Swm<(), ()>> where
    T: PinTrait, 

pub fn into_unused_pin(self) -> Pin<T, Unused>

Transitions this pin from the SWM state to the unused state

This method is only available, if two conditions are met:

• The pin is in the SWM state.
• No functions are assigned to this pin.

Unless both of these conditions are met, code trying to call this method will not compile.

Consumes the pin instance and returns a new pin instance, its type state indicating it is unused. This makes it possible to use the pin for something else. See State Management for more information on managing pin states.

Trait Implementations

impl<T, F, O, Is> AssignFunction<F, Input> for Pin<T, Swm<O, Is>> where
    T: PinTrait,
    F: FunctionTrait<T, Kind = Input>, 

type Assigned = Pin<T, Swm<O, (Is,)>>

The type of the pin after the function has been assigned

fn assign(self) -> Self::Assigned

Internal method for assigning a function to a pin

impl<T, F, Is> AssignFunction<F, Output> for Pin<T, Swm<(), Is>> where
    T: PinTrait,
    F: FunctionTrait<T, Kind = Output>, 

type Assigned = Pin<T, Swm<((),), Is>>

The type of the pin after the function has been assigned

fn assign(self) -> Self::Assigned

Internal method for assigning a function to a pin

impl<T, F> AssignFunction<F, Analog> for Pin<T, Swm<(), ()>> where
    T: PinTrait,
    F: FunctionTrait<T, Kind = Analog>, 

type Assigned = Pin<T, Analog>

The type of the pin after the function has been assigned

fn assign(self) -> Self::Assigned

Internal method for assigning a function to a pin

impl<T, F, O, Is> UnassignFunction<F, Input> for Pin<T, Swm<O, (Is,)>> where
    T: PinTrait,
    F: FunctionTrait<T, Kind = Input>, 

type Unassigned = Pin<T, Swm<O, Is>>

The type of the pin after the function has been unassigned

fn unassign(self) -> Self::Unassigned

Internal method for unassigning a function from a pin

impl<T, F, Is> UnassignFunction<F, Output> for Pin<T, Swm<((),), Is>> where
    T: PinTrait,
    F: FunctionTrait<T, Kind = Output>, 

type Unassigned = Pin<T, Swm<(), Is>>

The type of the pin after the function has been unassigned

fn unassign(self) -> Self::Unassigned

Internal method for unassigning a function from a pin

impl<'gpio, T> OutputPin for Pin<T, Gpio<'gpio, Output>> where
    T: PinTrait, 

type Error = Void

Error type

fn set_high(&mut self) -> Result<(), Self::Error>

Set the pin output to HIGH

This method is only available, if two conditions are met:

• The pin is in the GPIO state. Use into_gpio_pin to achieve this.
• The pin direction is set to output. See into_output.

Unless both of these conditions are met, code trying to call this method will not compile.

fn set_low(&mut self) -> Result<(), Self::Error>

Set the pin output to LOW

This method is only available, if two conditions are met:

• The pin is in the GPIO state. Use into_gpio_pin to achieve this.
• The pin direction is set to output. See into_output.

Unless both of these conditions are met, code trying to call this method will not compile.

impl<'gpio, T> StatefulOutputPin for Pin<T, Gpio<'gpio, Output>> where
    T: PinTrait, 

fn is_set_high(&self) -> Result<bool, Self::Error>

Indicates whether the pin output is currently set to HIGH

This method is only available, if two conditions are met:

• The pin is in the GPIO state. Use into_gpio_pin to achieve this.
• The pin direction is set to output. See into_output.

Unless both of these conditions are met, code trying to call this method will not compile.

fn is_set_low(&self) -> Result<bool, Self::Error>

Indicates whether the pin output is currently set to LOW

This method is only available, if two conditions are met:

• The pin is in the GPIO state. Use into_gpio_pin to achieve this.
• The pin direction is set to output. See into_output.

Unless both of these conditions are met, code trying to call this method will not compile.