Component: SPI Master (Comms: Interface)

Author	Matrix Ltd
Version	2.1
Category	Comms: Interface

SPI Master component

Low level routines for controlling or interacting with an SPI interface. SPI or Serial Peripheral Interface is a bus used for board level communications between devices. A target microcontroller will usually have at least one hardware SPI peripheral built in. If the hardware SPI pins are in use or more SPI channels are required then there is also a software mode available.

Detailed description

Overview

The SPI bus is a high speed communications bus which is usually best suited for talking between devices situated on the same circuit board. Due to the high frequency digital nature of the bus care should be taken to keep tracks as short as possible and as far away as possible from other sources of noise. A typical SPI bus consists of four signals, chip select, data out, data in and clock. The SPI bus usually consists of a single master device and then one or more slave devices.

As the data out and data in signals are subjective in terms of who is sending and receiving the data there are alternate names to help clarify the connection.

Data out (SDO) is also known as MOSI which stands for Master Out Slave In.

Data in (SDI) is also known as MISO which stands for Master In Slave Out.

Each SPI transaction consists of a byte made up of 8 clock cycles allowing the 8-bits of the byte to be transferred.

Chip Select CS / Slave Select SS

Each device connected to the SPI bus connects in parallel to the main three SPI pins: data out, data in and clock. The fourth pin the CS pin must be unique for every SPI device present on the bus allowing only one device to be addressed at any one time. As every slave device on the SPI bus requires a individual CS signal from the SPI Master a good way of adding more devices without consuming more of the pins of the SPI master is to use things like 3 to 8 pin multiplexer ICs. The CS signal activates the slave device when pulled low and disables the slave device when pulled high.

Adding a pull up resistor of around 10K - 100K between the CS signal and VCC allows the SPI slave device to be disabled whenever the Microcontroller is not ready to perform the functionality of the SPI master e.g. during reprogramming or when the device is held in reset.

Three Wire SPI

Three wire SPI is a version of SPI where the master can send data to the slave device but cannot read any data back for example a DAC or graphical LCD.

Four Wire SPI

Four wire SPI is the complete version of SPI where the master can sent data to the device and receive data back from the device. A single SPI operation simultaneously transfers a byte from the master to the slave via the MOSI signal and also a byte from the slave to the master via the MISO signal. Normally only one of these bytes is meaningful so it's down to the protocol of the slave device as to how to perform writes and reads.

Examples

More information on SPI can be found here,

Matrix Flowcode Blog: Simplified communications I2C and SPI

Downloadable macro reference

	SendString
Sends a string of bytes to the SPI bus. Not compatible with NULL values.
- STRING	Str
Data string to send out.
- VOID	Return

	TransactionArray
Allows simultaneous two way communications, send and receive multiple times. DataOut is used to store data to be transmitted. DataIn is used to store received data.
- BYTE	DataOut
Data Bytes to send out
- BYTE	DataIn
Data Bytes received
- BYTE	NumBytes
Number of bytes to send and receive
- VOID	Return

	GetString
Attempts to read a string of bytes from the SPI bus. Not compatible with NULL values. String variable needs to be at least (NumBytes + 1) in length to store NULL terminator.
- BYTE	NumBytes
Number of bytes to read into the string, string array length must be at least +1
- STRING	Return

	SendChar
General purpose SPI send byte macro
- BYTE	Char
Data byte to send
- VOID	Return

	Transaction
Allows simultaneous two way communications, send and receive,
- BYTE	DataOut
Data Byte to send out
- BYTE	Return

	SendByteArray
Sends a an array of bytes to the SPI bus. Similar to the SendString component macro but allows the value 0.
- BYTE	NumBytes
Number of bytes to write
- BYTE	Data
Byte Array to Send Data from.
- VOID	Return

	Disable_CS
Outputs a high signal to the chip select pin to deselect the remote slave device.
- VOID	Return

	GetByteArray
Attempts to read an array of bytes from the SPI bus. Similar to the GetString component macro but allows the value 0.
- BYTE	NumBytes
Number of bytes to read
- BYTE	Data
Byte Array to Assign Data to.
- VOID	Return

	GetChar
General purpose SPI get byte macro
- BYTE	Return

	UnInitialise
Deactivates the SPI peripheral leaving the I/O pins in a state where they can be used for general purpose I/O.
- VOID	Return

	Enable_CS
Outputs a low signal to the chip select pin to select the remote slave device.
- VOID	Return

	Initialise
Activates the SPI peripheral and claims control over the I/O pins.
- VOID	Return

	I2CStop
Put the I2C Module into Stop mode
- BYTE	Channel
- VOID	Return

	SPIPrescaler
Modify the speed of the SPI bus
- BYTE	Channel
Channel Index: Range 0 - SPI Bus Count - 1
- BYTE	Prescaler
Range: 0-2
- VOID	Return

	PWMSetDuty
Sets the duty for the PWM output
- BYTE	Channel
Range: 0-5
- BYTE	Duty
- VOID	Return

	ADCSample10
Reads the voltage present on an Alanog pin as an 10-bit value range 0-1023
- BYTE	ADCChannel
Range: 0-12
- UINT	Return

	I2CTransSend
Sends an I2C Transaction on the selected I2C channel. Returns the number of bytes sent.
- BYTE	Channel
Channel Index: Range 0 - I2C Bus Count - 1
- BYTE	Data
Data to send
- UINT	Count
Number of bytes to send out, MS bit 0x8000 signifies no Stop if set
- UINT	Return

	I2CTransInit
Initialises the I2C Transaction mode with the 7-bit device address
- BYTE	Channel
Channel Index: Range 0 - I2C Bus Count - 1
- BYTE	DeviceAddress
7-bit Device Address
- BYTE	Baud
0=100KHz, 1=400KHz, 2=1MHz
- VOID	Return

	IOSetOutputPin
Sets the selected digital pin to an output and assigns the output state.
- BYTE	Pin
Range: 0-29
[[File:]] -	State
Range: 0-1
- VOID	Return

	UARTReceive
Receives a data byte from the UART. Recommend calling the UARTCheckRx function first to ensure data is available.
- BYTE	Channel
Channel Index: Range 0 - UART Bus Count - 1
- BYTE	Return

	SPIInitialise
Initialsie the SPI module ready for communications
- BYTE	Channel
Channel Index: Range 0 - SPI Bus Count - 1
- VOID	Return

	I2CSend
Transmit a byte using the I2C bus
- BYTE	Channel
Channel Index: Range 0 - I2C Bus Count - 1
- BYTE	DataOut
[[File:]] -	Return

	UARTSend
Send a byte via the UART module
- BYTE	Channel
Channel Index: Range 0 - UART Bus Count - 1
- BYTE	Data
Data Byte to send. Range: 0-255
- VOID	Return

	PWMSetPrescaler
Sets the prescaler for the PWM output
- BYTE	Channel
- BYTE	Prescaler
- BYTE	Period
- VOID	Return

	PWMEnable
Enable a PWM output
- BYTE	Channel
Range: 0-1
- VOID	Return

	Initialise
Initialise the comms to the Arduino board ready for commands to be sent.
- VOID	Return

	IOSetOutputPin
Sets the selected digital pin to an output and assigns the output state.
- BYTE	Pin
Range: 0-29
[[File:]] -	State
Range: 0-1
- VOID	Return

	UARTReceive
Receives a data byte from the UART. Recommend calling the UARTCheckRx function first to ensure data is available.
- BYTE	Channel
Channel Index: Range 0 - UART Bus Count - 1
- BYTE	Return

	ADCSampleAverage10
Reads the voltage present on an Analog pin as an 10-bit value range 0-1023. Performs the selected number of samples with the selected time in microseconds in between samples
- BYTE	ADCChannel
Range: 0, 3-7
- BYTE	SampleCount
Range: 1- 100
- BYTE	SampleDelay
Delay in us between each sample
- UINT	Return

	OneWireScanBus
Scans the one wire bus to detect all connected devices. Returns the number of one wire devices found.
- BYTE	Channel
Channel Index: Range 0 - I2C Bus Count - 1
- BYTE	Return

	SPIInitialise
Initialsie the SPI module ready for communications
- BYTE	Channel
Channel Index: Range 0 - SPI Bus Count - 1
- VOID	Return

	OneWireReceiveByte
Receives a byte from the one wire bus a bit at a time
- BYTE	Channel
Channel Index: Range 0 - I2C Bus Count - 1
- BYTE	Return

	I2CSend
Transmit a byte using the I2C bus
- BYTE	Channel
Channel Index: Range 0 - I2C Bus Count - 1
- BYTE	DataOut
[[File:]] -	Return

	UARTSend
Send a byte via the UART module
- BYTE	Channel
Channel Index: Range 0 - UART Bus Count - 1
- BYTE	Data
Data Byte to send. Range: 0-255
- VOID	Return

	OneWireGetDeviceCount
Returns the number of devices found by the last ScanBus operation.
- BYTE	Channel
Channel Index: Range 0 - I2C Bus Count - 1
- BYTE	Return

	PWMSetPrescaler
Sets the prescaler for the PWM output
- BYTE	Channel
Range: 0 - 11
- BYTE	Prescaler
- BYTE	Period
- VOID	Return

	PWMEnable
Enable a PWM output
- BYTE	Channel
Range: 0-11
- VOID	Return

	ADCSampleArray10
Reads the voltage present on an Analog pin as an 10-bit value range 0-1023 Performs the selected number of samples with the selected time in microseconds in between samples and returns each sample in a single packet
- BYTE	ADCChannel
Range: 0, 3-7
- BYTE	SampleCount
Range: 1- 32
- UINT	SampleDelay
Delay in us between each sample
- UINT	Samples
10-bit samples returned from the function
- VOID	Return

	ADCSampleAverage8
Reads the voltage present on an Analog pin as an 8-bit value range 0-255 Performs the selected number of samples with the selected time in microseconds in between samples
- BYTE	ADCChannel
Range: 0, 3-7
- BYTE	SampleCount
Range: 1- 100
- BYTE	SampleDelay
Delay in us between each sample
- BYTE	Return

	Initialise
Initialise the comms to the Arduino board ready for commands to be sent.
- VOID	Return

	PWMEnable
Allows pulse width modulated transistor outputs to be switched on or off. Bit 0 = Enable AB Bit 1 = A / Bit 2 = B Bit 3 = C / Bit 4 = D Bit 5 = Enable CD
- BYTE	EnableMask
Range 0-63 or 0b00000 to 0b111111
- VOID	Return

	Initialise
- VOID	Return

Property reference

	Properties
	Prescale
Prescale option selector
	Clock Phase
Clock Phase (data change edge) selection
	Clock Polarity
Clock Polarity setting, inactive (idle) state
	Sample Point
Data bit read sample point
	Connections
	Channel
SPI Channel selector
	MOSI
SPI Data Out Pin SDO - Also Known as Master Out Slave In (MOSI) when used in Master mode.
	MISO
SPI Data In Pin SDI - Also Known as Master In Slave Out (MISO) when used in Master mode.
	CLK
SPI Clock Pin CLK - The Clock signal is driven by the SPI master.
	Use Auto CS
Allow the SPI component to manage the CS pin for us in Master mode. On initialise the CS pin is automatically set high to disable the remote SPI device.
	CS / SS
Chip Select / Slave Select Pin Master Mode: General purpose output pin used to select the remote SPI device. Slave Mode: Hardware chip select pin input used to select the SPI device.
	Simulations
	Label
Label used to identify the component on the panel.
	Scope Traces
Selects if the scope traces are automatically generated or not
	Console Data
Selects if the console data is automatically generated or not
	API