Crate rppal_mcp23s17

MCP23S17 driver

A driver for the MCP23S17 I/O expander which is accessed over an SPI bus. Note that this driver depends on RPPAL and is therefore specific to the Raspberry Pi.

Example usage

use rppal_mcp23s17::{ChipSelect, HardwareAddress, Level, Mcp23s17, Port, RegisterAddress, SpiBus, SpiMode};

// Create an instance of the driver for the device with the hardware address
// (A2, A1, A0) of 0b000.
let mcp23s17 = Mcp23s17::new(
    HardwareAddress::new(0).expect("Invalid hardware address"),
    SpiBus::Spi0,
    ChipSelect::Cs0,
    100_000,
    SpiMode::Mode0,
)
.expect("Failed to create MCP23S17");

// Take ownership of the pin on bit 4 of GPIOA and then convert it into an
// OutputPin. Initialisation of the OutputPin ensures that the MCP23S17
// registers (e.g. IODIRA) are set accordingly.
let pin = mcp23s17
    .get(Port::GpioA, 4)
    .expect("Failed to get Pin")
    .into_output_pin()
    .expect("Failed to convert to OutputPin");

// Set the pin to logic-level low.
pin.write(Level::Low).expect("Bad pin write");

Concurrency Warning

Note that the rppal::spi::Spi contained in the Mcp23s17 is !Send so that the device can only be used within the context of a single thread. However, there is nothing to stop separate instances on separate threads accessing the same MCP23S17. We could possibly do something smarter to enforce uniqueness of Pins between threads but currently it is down to the user to ensure if multiple instances are in use they don’t tread on each other’s toes!

Indeed, there is nothing to stop separate processes accessing the MCP23S17 over the SPI bus at the same time and given that many bit-flipping operations are implemented as a read-modify-write on the relevant registers there are huge windows for race hazards between processes/threads. Clearly much more reliable for everyone if a single process “owns” the MCP23S17 device and a single thread within that process instantiates a singleton Mcp23s17 object.

Acknowledgements

Many of the documentation comments in this library are taken direct from the MCP23S17 datasheet and are © 2005-2022 Microchip Technology Inc. and its subsidiaries.

This library not only uses, but has also taken a lot of inspiration from, the RPPAL crate.

Re-exports

pub use self::pin::InputPin;

pub use self::pin::InterruptMode;

pub use self::pin::Level;

pub use self::pin::OutputPin;

pub use self::pin::Pin;

Modules

pin

Various flavours of “Pin” that the I/O Expander GPIO ports support.

Structs

HardwareAddress

The hardware address of the device - three bits.

IOCON

I/O Expander Configuration Register (IOCON) bit definitions.

Mcp23s17

A structure that represents an instance of the MCP23S17 I/O expander chip.

Enums

ChipSelect

Which Chip Select line to use on the SPI bus.

Mcp23s17Error

Errors that operation of the MCP23S17 can raise.

Port

The MCP23S17 has two GPIO ports, GPIOA and GPIOB.

RegisterAddress

The register address within the device.

SpiBus

Re-exports of rppal::spi module APIs used on this crate’s APIs. Renamed to make sure that the intended usage is clear. SPI buses.

SpiMode

Re-exports of rppal::spi module APIs used on this crate’s APIs. Renamed to make sure that the intended usage is clear. SPI modes indicating the clock polarity and phase.

Type Definitions

Result

Convenient wrapper for Result types can have Mcp23s17Errors.