SPI Library

Provides support for both hardware and software-base SPI master devices.

Configuration Variables

ENABLE_SPI_DEBUG

default: 0 (disabled)

Enable to print additional debug messages.

API Documentation

enum SpiMode

Values:

enumerator SPI_MODE0
enumerator SPI_MODE1
enumerator SPI_MODE2
enumerator SPI_MODE3
const uint32_t SPI_SPEED_DEFAULT = 4000000UL
static constexpr uint8_t SPI_PIN_DEFAULT = {0xff}

SPI driver uses default pin assignment.

struct SpiPins
#include <SPIBase.h>

SPI pin connections.

class SPIBase
#include <SPIBase.h>

Subclassed by SPIClass, SPISoft

Send/receive some data

SPI transfer is based on a simultaneous send and receive: the received data is returned in receivedVal (or receivedVal16). In case of buffer transfers the received data is stored in the buffer in-place (the old data is replaced with the data received). 

    receivedVal = SPI.transfer(val)
    receivedVal16 = SPI.transfer16(val16)
    SPI.transfer(buffer, size)

inline uint8_t transfer(uint8_t val)

Send/receive one byte of data.

Parameters:

val – The byte to send

Return values:

uint8_t – The received byte

inline uint16_t transfer16(uint16_t val)

Send/receive one 16-bit word of data.

Word is transferred either MSB first (bit 15) or LSB first (bit 0) depending on the currently applied bitOrder setting.

Parameters:

val – The word to send

Return values:

uint16_t – The received word

inline virtual uint32_t transfer32(uint32_t val, uint8_t bits = 32)

Send/receive a word of variable size.

Word is transferred either MSB first (bits-1) or LSB first (bit 0) depending on the currently applied bitOrder setting.

Parameters:

  • val – Word to send

  • bits – Size of word

virtual void transfer(uint8_t *buffer, size_t size) = 0

Send/receive a variable-length block of data.

Parameters:

  • buffer – IN: The data to send; OUT: The received data

  • size – Number of bytes to transfer

Public Functions

virtual bool begin() = 0

Initialize the SPI bus by setting SCK and MOSI to outputs, pulling SCK and MOSI low.

virtual void end() = 0

Disable the SPI bus (leaving pin modes unchanged).

inline void beginTransaction(SPISettings &settings)

Initialize the SPI bus using the defined SPISettings.

inline virtual void endTransaction()

Stop using the SPI bus. Normally this is called after de-asserting the chip select, to allow other libraries to use the SPI bus.

inline virtual uint8_t read8()

Read one byte from SPI without setting up registers.

Used for performance tuning when doing continuous reads this method does not reset the registers, so make sure that a regular transfer(data) call was performed

Note: this method is not found on the Arduino API

USE WITH CARE !!

Parameters:

none –

Return values:

byte – received

virtual bool loopback(bool enable) = 0

For testing, tie MISO <-> MOSI internally.

Note: Not included in std Arduino lib

Public Members

SPISettings SPIDefaultSettings

Default settings used by the SPI bus until reset by beginTransaction(SPISettings)

Note: Not included in std Arduino lib

enum class SpiBus

Identifies bus selection.

Values:

enumerator INVALID
enumerator MIN
enumerator SPI1
enumerator FSPI
enumerator SPI2
enumerator HSPI
enumerator MAX
enumerator DEFAULT
enumerator INVALID
enumerator MIN
enumerator SPI1
enumerator MAX
enumerator DEFAULT
enumerator INVALID
enumerator MIN
enumerator SPI1
enumerator SPI2
enumerator SPI3
enumerator MAX
enumerator DEFAULT
enumerator INVALID
enumerator MIN
enumerator SPI1
enumerator SPI2
enumerator MAX
enumerator DEFAULT
using Callback = bool (*)(Request &request)

SPI completion callback routine.

Param request:

Retval bool:

Return true if request is finished, false to re-queue it immediately

SPIClass SPI

Global instance of SPI class.

struct Data
#include <Data.h>

Specifies a block incoming or outgoing data.

Data can be specified directly within Data, or as a buffer reference.

Command or address are stored in native byte order and rearranged according to the requested byteOrder setting. Data is always sent and received LSB first (as stored in memory) so any re-ordering must be done by the device or application.

Set internal data value of 1-4 bytes

Note

Data is sent LSB, MSB (native byte order)

inline void set8(uint8_t data)

Set to single 8-bit value.

Parameters:

data –

inline void set16(uint16_t data)

Set to single 16-bit value.

Parameters:

data –

inline void set32(uint32_t data, uint8_t len = 4)

Set to 32-bit data.

Parameters:

  • data –

  • len – Length in bytes (1 - 4)

Public Functions

inline void clear()

Reset to zero-length.

inline void set(const void *data, uint16_t count)

Set to reference external data block.

Parameters:

  • data – Location of data

  • count – Number of bytes

Public Members

void *ptr

Pointer to data.

uint16_t length

Number of bytes of data.

uint16_t isPointer

If set, data is referenced indirectly, otherwise it’s stored directly.

class Device
#include <Device.h>

Manages a specific SPI device instance attached to a controller.

Subclassed by Graphics::SpiDisplay, Graphics::XPT2046, HSPI::MemoryDevice

Public Functions

inline bool begin(PinSet pinSet, uint8_t chipSelect, uint32_t clockSpeed)

Register device with controller and prepare for action.

Parameters:

  • pinSet – Use PinSet::normal for Esp32, other values for Esp8266

  • chipSelect – Identifies the CS number for ESP8266, or the GPIO pin for ESP32

  • clockSpeed – Bus speed

inline bool isReady() const

Determine if the device is initialised.

Return values:

bool –

virtual IoModes getSupportedIoModes() const = 0

Return set of IO modes supported by a device implementation.

inline bool isSupported(IoMode mode) const

Determine if the device/controller combination supports an IO mode Must be called after begin() as other settings (e.g. pinset) can affect support.

inline void onTransfer(Callback callback)

Set a callback to be invoked before a request is started, and when it has finished.

Parameters:

callback – Invoked in interrupt context, MUST be in IRAM

class MemoryDevice : public HSPI::Device
#include <MemoryDevice.h>

Base class for read/write addressable devices.

Subclassed by HSPI::RAM::IS62_65, HSPI::RAM::PSRAM64

Prepare a write request

virtual void prepareWrite(HSPI::Request &req, uint32_t address) = 0

Prepare request without data.

inline void prepareWrite(HSPI::Request &req, uint32_t address, const void *data, size_t len)

Prepare request with data.

Parameters:

  • data – Data to send

  • len – Size of data in bytes

Prepare a read request

virtual void prepareRead(HSPI::Request &req, uint32_t address) = 0

Prepare without buffer.

inline void prepareRead(HSPI::Request &req, uint32_t address, void *buffer, size_t len)

Prepare with buffer.

Parameters:

  • buffer – Where to write incoming data

  • len – Size of buffer

Public Functions

inline void write(uint32_t address, const void *data, size_t len)

Write a block of data.

Note

Limited by current operating mode

Parameters:

  • address –

  • data –

  • len –

inline void read(uint32_t address, void *buffer, size_t len)

Read a block of data.

Note

Limited by current operating mode

Parameters:

  • address –

  • data –

  • len –

class IS62_65 : public HSPI::MemoryDevice
#include <IS62-65.h>

IS62/65WVS2568GALL fast serial RAM.

Public Types

enum class OpMode

Memory operating mode determines how read/write operations are performed.

Values:

enumerator Byte

Limited to one byte.

enumerator Page

Limited to single 32-bit page.

enumerator Sequential

Access entire memory array (DEFAULT)

Public Functions

inline virtual IoModes getSupportedIoModes() const override

Return set of IO modes supported by a device implementation.

inline bool begin(PinSet pinSet, uint8_t chipSelect, uint32_t clockSpeed)

Configure the RAM into a known operating mode.

inline OpMode getOpMode() const

Get current operating mode (cached value)

Return values:

OpMode – No device access is performed.

inline OpMode readOpMode()

Read current operating mode from device.

Return values:

OpMode –

inline virtual void prepareWrite(HSPI::Request &req, uint32_t address) override

Prepare request without data.

inline virtual void prepareRead(HSPI::Request &req, uint32_t address) override

Prepare without buffer.

class PSRAM64 : public HSPI::MemoryDevice
#include <PSRAM64.h>

PSRAM64(H) pseudo-SRAM.

Public Functions

inline virtual IoModes getSupportedIoModes() const override

Return set of IO modes supported by a device implementation.

inline bool begin(PinSet pinSet, uint8_t chipSelect, uint32_t clockSpeed)

Configure the RAM into a known operating mode.

inline virtual void prepareWrite(HSPI::Request &req, uint32_t address) override

Prepare request without data.

inline virtual void prepareRead(HSPI::Request &req, uint32_t address) override

Prepare without buffer.

struct Request
#include <Request.h>

Defines an SPI Request Packet.

Request fields may be accessed directly or by use of helper methods.

Application is responsible for managing Request object construction/destruction. Queuing is managed as a linked list so the objects aren’t copied.

Applications will typically only require a couple of Request objects, so one can be prepared whilst the other is in flight. This helps to minimises the setup latency between SPI transactions.

Set value for command phase

inline void setCommand(uint16_t command, uint8_t bitCount)
Parameters:

  • command –

  • bitCount – Length of command in bits

inline void setCommand8(uint8_t command)

Set 8-bit command.

Parameters:

command –

inline void setCommand16(uint16_t command)

Set 16-bit command.

Parameters:

command –

Set value for address phase

inline void setAddress(uint32_t address, uint8_t bitCount)
Parameters:

  • address –

  • bitCount – Length of address in bits

inline void setAddress24(uint32_t address)

Set 24-bit address.

Parameters:

address –

Public Functions

inline void setAsync(Callback callback = nullptr, void *param = nullptr)

Set request to asynchronous execution with optional callback.

Public Members

Device *device = {nullptr}

Target device for this request.

Request *next = {nullptr}

Controller uses this to queue requests.

uint16_t cmd = {0}

Command value.

uint8_t cmdLen = {0}

Command bits, 0 - 16.

uint8_t async

Set for asynchronous operation.

uint8_t task

Controller will execute this request in task mode.

uint8_t busy

Request in progress.

uint32_t addr = {0}

Address value.

uint8_t addrLen = {0}

Address bits, 0 - 32.

uint8_t dummyLen = {0}

Dummy read bits between address and read data, 0 - 255.

uint8_t sizeAlign = {0}

Required size alignment of each transaction (if split up)

Data out

Outgoing data.

Data in

Incoming data.

Callback callback = {nullptr}

Completion routine.

void *param = {nullptr}

User parameter.

class StreamAdapter
#include <StreamAdapter.h>

Helper class for streaming data to/from SPI devices.

class SPIClass : public SPIBase
#include <SPI.h>

Hardware SPI class.

Public Types

using IoCallback = void (*)(uint16_t c, uint8_t bits, bool read)

Used for testing purposes only.

Param c:

Value being read/written

Param bits:

Size of value in bits

Param read:

true for incoming value, false for outgoing

Public Functions

bool setup(SpiBus id, SpiPins pins = {})

Alternative to defining bus and pin set in constructor. Use this method to change global SPI instance setup.

IMPORTANT: Must be called before begin().

virtual bool begin() override

Initialize the SPI bus by setting SCK and MOSI to outputs, pulling SCK and MOSI low.

virtual void end() override

Disable the SPI bus (leaving pin modes unchanged).

virtual uint8_t read8() override

Read one byte from SPI without setting up registers.

Used for performance tuning when doing continuous reads this method does not reset the registers, so make sure that a regular transfer(data) call was performed

Note: this method is not found on the Arduino API

USE WITH CARE !!

Parameters:

none –

Return values:

byte – received

virtual uint32_t transfer32(uint32_t val, uint8_t bits = 32) override

Send/receive a word of variable size.

Word is transferred either MSB first (bits-1) or LSB first (bit 0) depending on the currently applied bitOrder setting.

Parameters:

  • val – Word to send

  • bits – Size of word

virtual void transfer(uint8_t *buffer, size_t numberBytes) override

Send/receive a variable-length block of data.

Parameters:

  • buffer – IN: The data to send; OUT: The received data

  • size – Number of bytes to transfer

virtual bool loopback(bool enable) override

For testing, tie MISO <-> MOSI internally.

Note: Not included in std Arduino lib

void setDebugIoCallback(IoCallback callback)

Used for testing purposes only Must be called after begin().

Used to verify serialisation/de-searialisation bit ordering

inline uint8_t transfer(uint8_t val)

Send/receive one byte of data.

Parameters:

val – The byte to send

Return values:

uint8_t – The received byte

void transfer(uint8_t *buffer, size_t size) = 0

Send/receive a variable-length block of data.

Parameters:

  • buffer – IN: The data to send; OUT: The received data

  • size – Number of bytes to transfer

References

Used by

Environment Variables

SoC support

  • esp32

  • esp32c2

  • esp32c3

  • esp32s2

  • esp32s3

  • esp8266

  • host

  • rp2040