device

R2026b

Connection to device on SPI bus on Arduino or ESP32 hardware

Description

Add-On Required: This feature requires the MATLAB Support Package for Arduino Hardware add-on.

This object represents a connection to the SPI device on Arduino^® or ESP32 hardware. Attach an SPI device to the appropriate pins on the Arduino or ESP32 hardware. You can interact with the SPI device using the functions listed in Object Functions.

Creation

Syntax

deviceObj = device(arduinoObj,'SPIChipSelectPin',SPIChipSelectPin,Name=Value)

Description

deviceObj = device(arduinoObj,'SPIChipSelectPin',SPIChipSelectPin,Name=Value) creates an object that represents the connection between SPI device connected to the SPI bus on the Arduino or ESP32 hardware. The Arduino or ESP32 hardware is represented by an arduino object. You can also customize the connection further using one or more name-value arguments. The 'SPIChipSelectPin' name-value argument is mandatory for creating the SPI device connection.

Input Arguments

arduinoObj — Arduino or ESP32 hardware connection

arduino object

Arduino or ESP32 hardware connection created using arduino, specified as an arduino object.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: deviceObj = device(arduinoObj,'SPIChipSelectPin','D8');

SPIChipSelectPin — Chip select pin number for SPI communication

character vector | string

This is a mandatory name value pair argument if you are connecting to an SPI device. Represents pin number that is used as the chip select pin on the Arduino hardware to communicate with the SPI device.

To identify the pins that can be used as chip select pins, see Chip Select Pins.

Example: deviceObj = device(arduinoObj,'SPIChipSelectPin','D10')

SPIMode — SPI communication mode

0 (default) | 1 | 2 | 3

SPI communication mode, specified as a number between 0 and 3. Specify the clock polarity and phase by setting the mode.

SPI Mode	Clock Polarity	Clock Phase
0	0	0
1	0	1
2	1	0
3	1	1

Example: deviceObj = device(arduinoObj,'SPIChipSelectPin','D4',SPIMode=3) creates a connection to the SPI device and sets the clock polarity to 1 and clock phase to 1.

BitOrder — SPI communication bit order

'msbfirst' (default) | 'lsbfirst'

SPI communication bit order, specified as:

• 'msbfirst' - The most significant bit is transmitted first.

• 'lsbfirst' - The least significant bit is transmitted first.

Example: deviceObj = device(arduinoObj,'SPIChipSelectPin','D4',BitOrder='lsbfirst') creates a connection to the SPI device and sets the least significant bit in the first column.

BitRate — Maximum speed of SPI communication

4000000 (default) | positive integer in range [1, 4000000]

The maximum speed of SPI communication in bits/s, specified as a positive integer.

Example: deviceObj = device(arduinoObj,'SPIChipSelectPin','D4',BitRate=2000000) creates a connection to the SPI device and sets the bitrate to 2000000 bits/s.

Properties

Interface — Type of interface used for communication

Read-only: 'SPI'

This property is read-only.

Specifies the type of interface used for communication.

Example:

>> d.Interface

ans = 

  InterfaceEnum enumeration

    Serial

SPIChipSelectPin — Chip select pin for SPI communication

Read-only: character vector

This property is read-only.

Arduino pin connected to chip select line on the SPI device, specified as a character vector of the form 'Ax' or 'Dx'. Here, x is the pin number, D is digital, and A is analog.

To identify the pins that can be used as chip select pins, see Chip Select Pins.

Example:

>> deviceObj.SPIChipSelectPin
ans = 
      'D10' 

Data Types: char

SCLPin — Serial clock pin

Read-only: character vector

This property is read-only.

A serial clock pin for the serial clock signal that the SPI controller generates.

Example:

>> deviceObj.SCLPin

ans =

     'D13'

Data Types: char

SDIPin — Serial Data In pin

Read-only: character vector

This property is read-only.

The pin that connects the peripheral output to the controller input.

Example:

>> deviceObj.SDIPin

ans =

     'D12'

Data Types: char

SDOPin — Serial Data Out pin

Read-only: character vector

This property is read-only.

The pin that connects the controller output to the peripheral input.

Example:

>> deviceObj.SDOPin

ans =

     'D11'

Data Types: char

SPIMode — SPI communication mode

0 (default) | 1 | 2 | 3

SPI communication mode, specified as a number between 0 and 3. Specify the clock polarity and phase by setting the mode.

SPI Mode	Clock Polarity	Clock Phase
0	0	0
1	0	1
2	1	0
3	1	1

Example:

>> deviceObj.SPIMode

ans =

     2

Data Types: double

ActiveLevel — Logic level

Read-only: 'low' (default) | 'high'

This property is read-only.

The logic levels of the SPI pins.

Example:

>> deviceObj.ActiveLevel

ans =
    ActiveLevelEnum enumeration 
    low

BitOrder — SPI communication bit order

'msbfirst' (default) | 'lsbfirst'

SPI communication bit order, specified as msbfirst or lsbfirst. If it is msbfirst, the most significant bit is transmitted first to the writeRead output. If it is lsbfirst, the least significant bit is transmitted first.

Example:

>> deviceObj.BitOrder

ans = 

    'msbfirst'

BitRate — Speed at which bus is set for SPI communication

Read-only: 4000000 (default) | positive integer in range [1,4000000]

This property is read-only.

The speed at which bus is set for SPI communication in bits/s, specified as a positive integer.

Example:

>> deviceObj.BitRate

ans = 

    4000000

Data Types: double

Object Functions

writeRead

Write and read data from SPI device

Examples

Create SPI Device Connection

Create an arduino object with the SPI library.

arduinoObj = arduino('COM5','Uno',Libraries='SPI')

arduinoObj = 
  arduino with properties:

                  Port: 'COM5'
                 Board: 'Uno'
         AvailablePins: {'D2-D13', 'A0-A5'}
  AvailableDigitalPins: {'D2-D13', 'A0-A5'}
      AvailablePWMPins: {'D3', 'D5-D6', 'D9-D11'}
   AvailableAnalogPins: {'A0-A5'}
    AvailableI2CBusIDs: [0]
             Libraries: {'SPI'}
Show all properties

Create a device object for the SPI device connected to pin D10.

deviceObj = device(arduinoObj,SPIChipSelectPin=D10)

deviceObj = 
  device with properties:

             Interface: 'SPI'
      SPIChipSelectPin: 'D10'
                SCLPin: 'D13'
                SDIPin: 'D12'
                SDOPin: 'D11'

Show all properties, functions

More About

Code Generation Using MATLAB Function Block

• Use device in a MATLAB^® Function block with the Simulink^® Support Package for Arduino Hardware to generate code that can be deployed on Arduino Hardware.

• Specifying SPIMode,BitRate, and BitOrder as name-value arguments is not supported in the MATLAB Function block. You can set SPIMode,BitRate, and BitOrder from the Configuration Parameters dialog box. To set the values:

  • On the Simulink Toolstrip, in the Hardware tab, click Hardware Settings to open the Configuration Parameters dialog box.

  • In the Configuration Parameters dialog box, select Hardware Implementation. Verify that the Hardware board parameter is set to the appropriate Arduino board.

  • Go to Hardware board settings > Target hardware resources > SPI properties. 

  • Enter the value to set BitRate in SPI clock out frequency(kHz), SPIMode, and BitOrder.

• The properties Interface,SPIMode, BitRate,BitOrder,SCLPin,SDIPin, and SDOPin are not accessible from the device object.

• The property ActiveLevel is always 'low'.

Alternative Functionality

App

Use Arduino Explorer to configure the SPI device to read and write data. You can use the app in the installed version of MATLAB and MATLAB Online™. For more information, see Connect to SPI Device Using Arduino Explorer App.

Version History

Introduced in R2019a