Struct Spi

pub struct Spi<'d, Dm: DriverMode> { /* private fields */ }

SPI peripheral driver

SPI Initialization

let mut spi = Spi::new(
    peripherals.SPI2,
    Config::default().with_frequency(Rate::from_khz(100)).
with_mode(Mode::_0) )?
.with_sck(peripherals.GPIO0)
.with_mosi(peripherals.GPIO1)
.with_miso(peripherals.GPIO2);

Implementations

impl<Dm> Spi<'_, Dm>

where Dm: DriverMode,

pub fn write(&mut self, words: &[u8]) -> Result<(), Error>

Write bytes to SPI. After writing, flush is called to ensure all data has been transmitted.

pub fn read(&mut self, words: &mut [u8]) -> Result<(), Error>

Read bytes from SPI. The provided slice is filled with data received from the slave.

pub fn transfer<'w>(&mut self, words: &'w mut [u8]) -> Result<&'w [u8], Error>

Sends words to the slave. Returns the words received from the slave.

impl<'d> Spi<'d, Blocking>

pub fn new( spi: impl Peripheral<P = impl PeripheralInstance> + 'd, config: Config, ) -> Result<Self, ConfigError>

Constructs an SPI instance in 8bit dataframe mode.

Errors

See Spi::apply_config.

pub fn into_async(self) -> Spi<'d, Async>

Converts the SPI instance into async mode.

pub fn with_dma<CH>( self, channel: impl Peripheral<P = CH> + 'd, ) -> SpiDma<'d, Blocking>

where CH: DmaChannelFor<AnySpi>,

Available on crate feature unstable only.

Configures the SPI instance to use DMA with the specified channel.

This method prepares the SPI instance for DMA transfers using SPI and returns an instance of SpiDma that supports DMA operations.

let dma_channel = peripherals.DMA_CH0;
let (rx_buffer, rx_descriptors, tx_buffer, tx_descriptors) =
    dma_buffers!(32000);

let dma_rx_buf = DmaRxBuf::new(
    rx_descriptors,
    rx_buffer
)?;

let dma_tx_buf = DmaTxBuf::new(
    tx_descriptors,
    tx_buffer
)?;

let mut spi = Spi::new(
    peripherals.SPI2,
    Config::default().with_frequency(Rate::from_khz(100)).
with_mode(Mode::_0) )?
.with_dma(dma_channel)
.with_buffers(dma_rx_buf, dma_tx_buf);

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn set_interrupt_handler(&mut self, handler: InterruptHandler)

Available on crate feature unstable only.

Registers an interrupt handler for the peripheral.

Note that this will replace any previously registered interrupt handlers.

You can restore the default/unhandled interrupt handler by using crate::interrupt::DEFAULT_INTERRUPT_HANDLER

Panics

Panics if passed interrupt handler is invalid (e.g. has priority None)

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl<'d> Spi<'d, Async>

pub fn into_blocking(self) -> Spi<'d, Blocking>

Converts the SPI instance into blocking mode.

pub async fn flush_async(&mut self) -> Result<(), Error>

Waits for the completion of previous operations.

pub async fn transfer_in_place_async( &mut self, words: &mut [u8], ) -> Result<(), Error>

Sends words to the slave. Returns the words received from the slave

impl<'d, Dm> Spi<'d, Dm>

where Dm: DriverMode,

pub fn with_mosi<MOSI: PeripheralOutput>( self, mosi: impl Peripheral<P = MOSI> + 'd, ) -> Self

Assign the MOSI (Master Out Slave In) pin for the SPI instance.

Enables output functionality for the pin, and connects it as the MOSI signal. You want to use this for full-duplex SPI or if you intend to use DataMode::SingleTwoDataLines.

Disconnects the previous pin that was assigned with with_mosi or with_sio0.

pub fn with_sio0<MOSI: PeripheralOutput>( self, mosi: impl Peripheral<P = MOSI> + 'd, ) -> Self

Available on crate feature unstable only.

Assign the SIO0 pin for the SPI instance.

Enables both input and output functionality for the pin, and connects it to the MOSI signal and SIO0 input signal.

Disconnects the previous pin that was assigned with with_sio0 or with_mosi.

Use this if any of the devices on the bus use half-duplex SPI.

The pin is configured to open-drain mode.

Note: You do not need to call Self::with_mosi when this is used.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn with_miso<MISO: PeripheralInput>( self, miso: impl Peripheral<P = MISO> + 'd, ) -> Self

Assign the MISO (Master In Slave Out) pin for the SPI instance.

Enables input functionality for the pin, and connects it to the MISO signal.

You want to use this for full-duplex SPI or DataMode::SingleTwoDataLines

pub fn with_sio1<SIO1: PeripheralOutput>( self, miso: impl Peripheral<P = SIO1> + 'd, ) -> Self

Available on crate feature unstable only.

Assign the SIO1/MISO pin for the SPI instance.

Enables both input and output functionality for the pin, and connects it to the MISO signal and SIO1 input signal.

Disconnects the previous pin that was assigned with with_sio1.

Use this if any of the devices on the bus use half-duplex SPI.

The pin is configured to open-drain mode.

Note: You do not need to call Self::with_miso when this is used.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn with_sck<SCK: PeripheralOutput>( self, sclk: impl Peripheral<P = SCK> + 'd, ) -> Self

Assign the SCK (Serial Clock) pin for the SPI instance.

Configures the specified pin to push-pull output and connects it to the SPI clock signal.

Disconnects the previous pin that was assigned with with_sck.

pub fn with_cs<CS: PeripheralOutput>( self, cs: impl Peripheral<P = CS> + 'd, ) -> Self

Available on crate feature unstable only.

Assign the CS (Chip Select) pin for the SPI instance.

Configures the specified pin to push-pull output and connects it to the SPI CS signal.

Disconnects the previous pin that was assigned with with_cs.

Current Stability Limitations

The hardware chip select functionality is limited; only one CS line can be set, regardless of the total number available. There is no mechanism to select which CS line to use.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError>

Change the bus configuration.

Errors

If frequency passed in config exceeds 80MHz or is below 70kHz, ConfigError::UnsupportedFrequency error will be returned.

impl<'d, Dm> Spi<'d, Dm>

where Dm: DriverMode,

pub fn with_sio2<SIO2: PeripheralOutput>( self, sio2: impl Peripheral<P = SIO2> + 'd, ) -> Self

Available on crate feature unstable only.

Assign the SIO2 pin for the SPI instance.

Enables both input and output functionality for the pin, and connects it to the SIO2 output and input signals.

Current Stability Limitations

QSPI operations are unstable, associated pins configuration is inefficient.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn with_sio3<SIO3: PeripheralOutput>( self, sio3: impl Peripheral<P = SIO3> + 'd, ) -> Self

Available on crate feature unstable only.

Assign the SIO3 pin for the SPI instance.

Enables both input and output functionality for the pin, and connects it to the SIO3 output and input signals.

Current Stability Limitations

QSPI operations are unstable, associated pins configuration is inefficient.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl<Dm> Spi<'_, Dm>

where Dm: DriverMode,

pub fn half_duplex_read( &mut self, data_mode: DataMode, cmd: Command, address: Address, dummy: u8, buffer: &mut [u8], ) -> Result<(), Error>

Available on crate feature unstable only.

Half-duplex read.

Errors

Error::FifoSizeExeeded or Error::Unsupported will be returned if passed buffer is bigger than FIFO size or if buffer is empty (currently unsupported). DataMode::Single cannot be combined with any other DataMode, otherwise Error::Unsupported will be returned.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn half_duplex_write( &mut self, data_mode: DataMode, cmd: Command, address: Address, dummy: u8, buffer: &[u8], ) -> Result<(), Error>

Available on crate feature unstable only.

Half-duplex write.

Errors

Error::FifoSizeExeeded will be returned if passed buffer is bigger than FIFO size.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Trait Implementations

impl<'d, Dm: Debug + DriverMode> Debug for Spi<'d, Dm>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Dm> ErrorType for Spi<'_, Dm>

where Dm: DriverMode,

type Error = Error

Error type.

impl<'d, Dm: DriverMode> Format for Spi<'d, Dm>

where PeripheralRef<'d, AnySpi>: Format, PhantomData<Dm>: Format, PeripheralGuard: Format, SpiPinGuard: Format,

fn format(&self, f: Formatter<'_>)

Writes the defmt representation of self to fmt.

impl InterruptConfigurable for Spi<'_, Blocking>

Available on crate feature unstable only.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

fn set_interrupt_handler(&mut self, handler: InterruptHandler)

Sets the interrupt handler

Interrupts are not enabled at the peripheral level here.

impl<Dm> SetConfig for Spi<'_, Dm>

where Dm: DriverMode,

Available on crate feature unstable only.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

type Config = Config

The configuration type used by this driver.

type ConfigError = ConfigError

The error type that can occur if set_config fails.

fn set_config(&mut self, config: &Self::Config) -> Result<(), Self::ConfigError>

Set the configuration of the driver.

impl SpiBus for Spi<'_, Async>

async fn read(&mut self, words: &mut [u8]) -> Result<(), Self::Error>

Read words from the slave.

async fn write(&mut self, words: &[u8]) -> Result<(), Self::Error>

Write words to the slave, ignoring all the incoming words.

async fn transfer( &mut self, read: &mut [u8], write: &[u8], ) -> Result<(), Self::Error>

Write and read simultaneously. write is written to the slave on MOSI and words received on MISO are stored in read.

async fn transfer_in_place( &mut self, words: &mut [u8], ) -> Result<(), Self::Error>

Write and read simultaneously. The contents of words are written to the slave, and the received words are stored into the same words buffer, overwriting it.

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

Wait until all operations have completed and the bus is idle.

impl<Dm> SpiBus for Spi<'_, Dm>

where Dm: DriverMode,

fn read(&mut self, words: &mut [u8]) -> Result<(), Self::Error>

Read words from the slave.

fn write(&mut self, words: &[u8]) -> Result<(), Self::Error>

Write words to the slave, ignoring all the incoming words.

fn transfer(&mut self, read: &mut [u8], write: &[u8]) -> Result<(), Self::Error>

Write and read simultaneously. write is written to the slave on MOSI and words received on MISO are stored in read.

fn transfer_in_place(&mut self, words: &mut [u8]) -> Result<(), Self::Error>

Write and read simultaneously. The contents of words are written to the slave, and the received words are stored into the same words buffer, overwriting it.

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

Wait until all operations have completed and the bus is idle.