Use SPI in high-level applications

  • Article

Azure Sphere supports Serial Peripheral Interface (SPI) in master mode. SPI is a serial interface used for communication between peripherals and integrated circuits. SPI uses a master/subordinate model where a master device controls a set of subordinate devices. In contrast to I2C, SPI can be used with more complex higher speed peripherals.

Applications can access peripherals through SPI by calling Applibs SPI APIs to perform operations on an SPI master interface. The LSM6DS3 SPI sample describes how to configure the hardware for SPI on an MT3620 device and use SPI in an application.

Chip select

Chip select manages the connection between an SPI master interface and a set of subordinate devices; and allows the master interface to send and receive data to each subordinate device independently. Azure Sphere supports the active-low and active-high settings for chip select, with active-low as the default setting. Each SPI master interface can be used exclusively by one application. The application must open the SPI master interface and identify each connected subordinate device before performing read and write operations on the interface. The SPI read and write operations on Azure Sphere use blocking APIs.

SPI requirements

Applications that use SPI must include the appropriate header files for SPI, and add SPI settings to the application manifest.

All applications must set their target hardware and include the corresponding hardware definition header file.

Header files

 #define SPI_STRUCTS_VERSION 1
 #include <applibs/spi.h>
 #include "path-to-your-target-hardware.h"

Declare the SPI_STRUCTS_VERSION preprocessor definition before including the header file. This specifies the struct version that is used by the application.

Replace "path-to-your-target-hardware.h" with the path to the header file for your hardware.

Application manifest settings

To use the SPI APIs, you must add the SpiMaster capability to the application manifest, and then add each SPI master controller to the capability. This enables the application to access the controller. Azure Sphere application manifest has more details about the application manifest.

In your code, use the constants that are defined for your hardware to identify the SPI master interfaces. The compiler will translate these values to raw values when you build the app.

For example, here's an excerpt from an application manifest that targets an MT3620 reference development board (RDB) and configures two SPI master interfaces:

"SpiMaster": [ "$MT3620_RDB_HEADER2_ISU0_SPI", "$MT3620_RDB_HEADER4_ISU1_SPI" ],

The following excerpt shows how to specify the same SPI master interfaces in an application that targets the Avnet MT3620 Starter Kit:

"SpiMaster": [ "$AVNET_MT3620_SK_ISU0_SPI", "$AVNET_MT3620_SK_ISU1_SPI" ]

Configure chip select and open an SPI master interface

Before you perform operations on an SPI master interface, you must configure chip select and open the interface. To configure chip select, call the SPIMaster_InitConfig function to initialize the SPIMaster_Config Struct struct. After you initialize SPIMaster_Config, update the csPolarity field with the SPI_ChipSelectPolarity_ActiveLow../reference/applibs/ity_Activ../reference/applibs/rence/applibs/applibs-spi/enum-spi-chipselectpolarity.md).

To open an SPI master interface, call the SPIMaster_Openfunction. This will apply the default settings to the interface and apply your chip select settings:

  • SPI_Mode_0 for the SPI bit order
  • SPI_BitOrder_MsbFirst for the communication mode

Update the settings for an SPI master interface

After initialization you can change the settings for the interface:

Perform read and write operations on the SPI master interface

Azure Sphere supports several options for performing read and write operations with SPI. For one-way read or write operations and to maintain interoperability with some POSIX APIs, you can call the POSIX read(2) and write(2) functions.

You can call the SPIMaster_WriteThenRead function to perform a combined write then read operation in a single bus transaction without interruption from another transaction.

Call the SPIMaster_TransferSequential function when you need more precise control over the timing between read or write operations. This allows you to perform multiple read and write operations between a pair of CS enable and disable states.

Close the SPI interface

To close the interface, call the standard POSIX function close().

MT3620 support

This section describes the SPI options that only apply when running Azure Sphere on the MT3620 development board.

The SPI specifications for the MT3620 are listed in MT3620 Support Status. The MT3620 development board user guide describes the pin layout and functions for wiring.

The HardwareDefinitions folder in the Microsoft Azure Sphere SDK installation directory contains definitions for common Azure Sphere development boards, modules, and chips. It contains header and JSON files that define the master interfaces for the MT3620, MT3620 RDB, along with other MT3620 hardware. The default location for the HardwareDefinitions folder is C:\Program Files (x86)\Microsoft Azure Sphere SDK\Hardware Definitions on Windows and /opt/azurespheresdk/HardwareDefinitions on Linux.

  • When you configure the MT3620 dev board, you can use any ISU port as an SPI master interface. You can connect up to two subordinate devices to each ISU. When you use an ISU port as an SPI master interface, you can't use the same port as an I2C or UART interface.
  • The MT3620 supports SPI transactions that are up to 40 MHz.
  • The MT3620 doesn't support simultaneous bidirectional read and write (full-duplex) SPI operations within a single bus transaction.