Struct Spi 

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

SPI peripheral driver

Examples

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 with_dma( self, channel: impl SpiMasterDmaChannel<'d, AnySpi<'d>>, ) -> SpiDma<'d, Blocking>

Available on crate feature unstable only.

Converts the driver into an SpiDma driver that uses the specified DMA channel.

use esp_hal::spi::{
    Mode,
    master::{Config, Spi},
};

let mut spi_dma = Spi::new(
    peripherals.SPI2,
    Config::default()
        .with_frequency(Rate::from_khz(100))
        .with_mode(Mode::_0),
)?
.with_dma(peripherals.DMA_CH0);

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, Blocking>

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

Creates a new SPI instance in 8-bit data-frame mode.

Examples

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);

Errors

See Spi::apply_config

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 set_interrupt_handler(&mut self, handler: InterruptHandler)

Available on crate feature unstable only.

Registers an interrupt handler for the peripheral on the current core.

Replaces any previously registered interrupt handlers.

The default/unhandled interrupt handler can be restored with 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.

Examples

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.

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.

Examples

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?;

pub async fn half_duplex_read_async( &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.

Transfers larger than the hardware FIFO are split into chunks. CS remains asserted across chunks, but the clock pauses while the CPU prepares each subsequent chunk.

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.

Errors

Error::Unsupported when the buffer is empty (currently unsupported). DataMode::Single cannot be combined with any other DataMode, otherwise Error::Unsupported.

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 async fn half_duplex_write_async( &mut self, data_mode: DataMode, cmd: Command, address: Address, dummy: u8, buffer: &[u8], ) -> Result<(), Error>

Available on crate feature unstable only.

Half-duplex write.

Transfers larger than the hardware FIFO are split into chunks. CS remains asserted across chunks, but the clock pauses while the CPU prepares each subsequent chunk.

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.

Errors

Error::Unsupported for unsupported combinations of command, address, dummy, and data modes.

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, Dm> Spi<'d, Dm>

where Dm: DriverMode,

pub fn with_sck(self, sclk: impl PeripheralOutput<'d>) -> Self

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

Examples

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

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

Enables output functionality for the pin, and connects it as the MOSI signal. Use this for full-duplex SPI or when using DataMode::SingleTwoDataLines.

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

Examples

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

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

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

Use this for full-duplex SPI or DataMode::SingleTwoDataLines

Examples

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 PeripheralInput<'d> + PeripheralOutput<'d>, ) -> Self

Available on crate feature unstable only.

Assigns 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 for 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 PeripheralInput<'d> + PeripheralOutput<'d>, ) -> Self

Available on crate feature unstable only.

Assigns 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 for 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 PeripheralInput<'d> + 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 PeripheralInput<'d> + 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_sio4( self, sio: impl PeripheralInput<'d> + PeripheralOutput<'d>, ) -> Self

Available on crate feature unstable only.

Assign the SIO4 pin for the SPI instance.

Enables both input and output functionality for the pin, and connects it to the SIO4 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_sio5( self, sio: impl PeripheralInput<'d> + PeripheralOutput<'d>, ) -> Self

Available on crate feature unstable only.

Assign the SIO5 pin for the SPI instance.

Enables both input and output functionality for the pin, and connects it to the SIO5 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_sio6( self, sio: impl PeripheralInput<'d> + PeripheralOutput<'d>, ) -> Self

Available on crate feature unstable only.

Assign the SIO6 pin for the SPI instance.

Enables both input and output functionality for the pin, and connects it to the SIO6 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_sio7( self, sio: impl PeripheralInput<'d> + PeripheralOutput<'d>, ) -> Self

Available on crate feature unstable only.

Assign the SIO7 pin for the SPI instance.

Enables both input and output functionality for the pin, and connects it to the SIO7 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.

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

Changes the bus configuration.

Examples

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)));

Errors

ConfigError::FrequencyOutOfRange when frequency passed in config exceeds 80MHz or is below 70 kHz.

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

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

Examples

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>

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

Examples

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.

Examples

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.

Transfers larger than the hardware FIFO are split into chunks. CS remains asserted across chunks, but the clock pauses while the CPU prepares each subsequent chunk.

Errors

Error::Unsupported when the buffer is empty (currently unsupported). DataMode::Single cannot be combined with any other DataMode, otherwise Error::Unsupported.

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.

Transfers larger than the hardware FIFO are split into chunks. CS remains asserted across chunks, but the clock pauses while the CPU prepares each subsequent chunk.

Errors

Error::Unsupported for unsupported combinations of command, address, dummy, and data modes.

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.