Struct Spi

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

SPI peripheral driver

Example

use esp_hal::spi::{
    Mode,
    master::{Config, Spi},
};
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<'d> Spi<'d, Blocking>

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

Constructs an SPI instance in 8bit dataframe mode.

Errors

See Spi::apply_config.

Example

use esp_hal::spi::{
    Mode,
    master::{Config, Spi},
};
let mut spi = Spi::new(peripherals.SPI2, Config::default())?
    .with_sck(peripherals.GPIO0)
    .with_mosi(peripherals.GPIO1)
    .with_miso(peripherals.GPIO2);

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

Reconfigures the driver to operate in Async mode.

See the Async documentation for an example on how to use this method.

pub fn with_dma( self, channel: impl DmaChannelFor<AnySpi<'d>>, ) -> SpiDma<'d, Blocking>

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.

use esp_hal::{
    dma::{DmaRxBuf, DmaTxBuf},
    dma_buffers,
    spi::{
        Mode,
        master::{Config, Spi},
    },
};
let dma_channel = peripherals.DMA_SPI2;
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 on the current core.

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>

Reconfigures the driver to operate in Blocking mode.

See the Blocking documentation for an example on how to use this method.

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

Waits for the completion of previous operations.

Example

use esp_hal::spi::{
    Mode,
    master::{Config, Spi},
};
let mut spi = Spi::new(peripherals.SPI2, Config::default())?
    .with_sck(peripherals.GPIO0)
    .with_mosi(peripherals.GPIO1)
    .with_miso(peripherals.GPIO2)
    .into_async();

let mut buffer = [0; 10];
spi.transfer_in_place_async(&mut buffer).await?;
spi.flush_async().await?;

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.

This function aborts the transfer when its Future is dropped. Some amount of data may have been transferred before the Future is dropped. Dropping the future may block for a short while to ensure the transfer is aborted.

Example

use esp_hal::spi::{
    Mode,
    master::{Config, Spi},
};
let mut spi = Spi::new(peripherals.SPI2, Config::default())?
    .with_sck(peripherals.GPIO0)
    .with_mosi(peripherals.GPIO1)
    .with_miso(peripherals.GPIO2)
    .into_async();

let mut buffer = [0; 10];
spi.transfer_in_place_async(&mut buffer).await?;

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

where Dm: DriverMode,

pub fn with_sck(self, sclk: impl PeripheralOutput<'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.

Example

use esp_hal::spi::{
    Mode,
    master::{Config, Spi},
};
let mut spi = Spi::new(peripherals.SPI2, Config::default())?.with_sck(peripherals.GPIO0);

pub fn with_mosi(self, mosi: impl PeripheralOutput<'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.

Example

use esp_hal::spi::{
    Mode,
    master::{Config, Spi},
};
let mut spi = Spi::new(peripherals.SPI2, Config::default())?.with_mosi(peripherals.GPIO1);

pub fn with_miso(self, miso: impl PeripheralInput<'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

Example

use esp_hal::spi::{
    Mode,
    master::{Config, Spi},
};
let mut spi = Spi::new(peripherals.SPI2, Config::default())?.with_miso(peripherals.GPIO2);

pub fn with_sio0(self, mosi: impl PeripheralOutput<'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 output 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.

See also Self::with_mosi when you only need a one-directional MOSI signal.

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_sio1(self, sio1: impl PeripheralOutput<'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 input signal and SIO1 output 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.

See also Self::with_miso when you only need a one-directional MISO signal.

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_sio2(self, sio: impl PeripheralOutput<'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.

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(self, sio: impl PeripheralOutput<'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.

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_cs(self, cs: impl PeripheralOutput<'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::FrequencyOutOfRange error will be returned.

Example

use esp_hal::spi::{
    Mode,
    master::{Config, Spi},
};
let mut spi = Spi::new(peripherals.SPI2, Config::default())?;

spi.apply_config(&Config::default().with_frequency(Rate::from_khz(100)));

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.

Example

use esp_hal::spi::{
    Mode,
    master::{Config, Spi},
};
let mut spi = Spi::new(peripherals.SPI2, Config::default())?
    .with_sck(peripherals.GPIO0)
    .with_mosi(peripherals.GPIO1)
    .with_miso(peripherals.GPIO2)
    .into_async();

let buffer = [0; 10];
spi.write(&buffer)?;

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.

Example

use esp_hal::spi::{
    Mode,
    master::{Config, Spi},
};
let mut spi = Spi::new(peripherals.SPI2, Config::default())?
    .with_sck(peripherals.GPIO0)
    .with_mosi(peripherals.GPIO1)
    .with_miso(peripherals.GPIO2)
    .into_async();

let mut buffer = [0; 10];
spi.read(&mut buffer)?;

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

Sends words to the slave. The received data will be written to words, overwriting its contents.

Example

use esp_hal::spi::{
    Mode,
    master::{Config, Spi},
};
let mut spi = Spi::new(peripherals.SPI2, Config::default())?
    .with_sck(peripherals.GPIO0)
    .with_mosi(peripherals.GPIO1)
    .with_miso(peripherals.GPIO2)
    .into_async();

let mut buffer = [0; 10];
spi.transfer(&mut buffer)?;

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. Dummy phase configuration is currently not supported, only value 0 is valid (see issue #2240).

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 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.