SPI bus interface class. More...

#include <frc/SPI.h>

Public Types
enum	Port { kOnboardCS0 = 0 , kOnboardCS1 , kOnboardCS2 , kOnboardCS3 , kMXP }
	SPI port. More...

enum	Mode { kMode0 = HAL_SPI_kMode0 , kMode1 = HAL_SPI_kMode1 , kMode2 = HAL_SPI_kMode2 , kMode3 = HAL_SPI_kMode3 }
	SPI mode. More...

Public Member Functions
	SPI (Port port)
	Constructor. More...

virtual	~SPI ()

	SPI (SPI &&)=default

SPI &	operator= (SPI &&)=default

Port	GetPort () const
	Returns the SPI port. More...

void	SetClockRate (int hz)
	Configure the rate of the generated clock signal. More...

void	SetMode (Mode mode)
	Sets the mode for the SPI device. More...

void	SetChipSelectActiveHigh ()
	Configure the chip select line to be active high. More...

void	SetChipSelectActiveLow ()
	Configure the chip select line to be active low. More...

virtual int	Write (uint8_t *data, int size)
	Write data to the peripheral device. More...

virtual int	Read (bool initiate, uint8_t *dataReceived, int size)
	Read a word from the receive FIFO. More...

virtual int	Transaction (uint8_t dataToSend, uint8_t dataReceived, int size)
	Perform a simultaneous read/write transaction with the device. More...

void	InitAuto (int bufferSize)
	Initialize automatic SPI transfer engine. More...

void	FreeAuto ()
	Frees the automatic SPI transfer engine. More...

void	SetAutoTransmitData (std::span< const uint8_t > dataToSend, int zeroSize)
	Set the data to be transmitted by the engine. More...

void	StartAutoRate (units::second_t period)
	Start running the automatic SPI transfer engine at a periodic rate. More...

void	StartAutoTrigger (DigitalSource &source, bool rising, bool falling)
	Start running the automatic SPI transfer engine when a trigger occurs. More...

void	StopAuto ()
	Stop running the automatic SPI transfer engine. More...

void	ForceAutoRead ()
	Force the engine to make a single transfer. More...

int	ReadAutoReceivedData (uint32_t *buffer, int numToRead, units::second_t timeout)
	Read data that has been transferred by the automatic SPI transfer engine. More...

int	GetAutoDroppedCount ()
	Get the number of bytes dropped by the automatic SPI transfer engine due to the receive buffer being full. More...

void	ConfigureAutoStall (HAL_SPIPort port, int csToSclkTicks, int stallTicks, int pow2BytesPerRead)
	Configure the Auto SPI Stall time between reads. More...

void	InitAccumulator (units::second_t period, int cmd, int xferSize, int validMask, int validValue, int dataShift, int dataSize, bool isSigned, bool bigEndian)
	Initialize the accumulator. More...

void	FreeAccumulator ()
	Frees the accumulator. More...

void	ResetAccumulator ()
	Resets the accumulator to zero. More...

void	SetAccumulatorCenter (int center)
	Set the center value of the accumulator. More...

void	SetAccumulatorDeadband (int deadband)
	Set the accumulator's deadband. More...

int	GetAccumulatorLastValue () const
	Read the last value read by the accumulator engine. More...

int64_t	GetAccumulatorValue () const
	Read the accumulated value. More...

int64_t	GetAccumulatorCount () const
	Read the number of accumulated values. More...

double	GetAccumulatorAverage () const
	Read the average of the accumulated value. More...

void	GetAccumulatorOutput (int64_t &value, int64_t &count) const
	Read the accumulated value and the number of accumulated values atomically. More...

void	SetAccumulatorIntegratedCenter (double center)
	Set the center value of the accumulator integrator. More...

double	GetAccumulatorIntegratedValue () const
	Read the integrated value. More...

double	GetAccumulatorIntegratedAverage () const
	Read the average of the integrated value. More...

Protected Attributes
hal::SPIPort	m_port

HAL_SPIMode	m_mode = HAL_SPIMode::HAL_SPI_kMode0

Detailed Description

SPI bus interface class.

This class is intended to be used by sensor (and other SPI device) drivers. It probably should not be used directly.

Member Enumeration Documentation

◆ Mode

enum frc::SPI::Mode

SPI mode.

Enumerator
kMode0	Clock idle low, data sampled on rising edge.
kMode1	Clock idle low, data sampled on falling edge.
kMode2	Clock idle high, data sampled on falling edge.
kMode3	Clock idle high, data sampled on rising edge.

◆ Port

enum frc::SPI::Port

SPI port.

Enumerator
kOnboardCS0	Onboard SPI bus port CS0.
kOnboardCS1	Onboard SPI bus port CS1.
kOnboardCS2	Onboard SPI bus port CS2.
kOnboardCS3	Onboard SPI bus port CS3.
kMXP	MXP (roboRIO MXP) SPI bus port.

Constructor & Destructor Documentation

◆ SPI() [1/2]

frc::SPI::SPI ( Port port )

explicit

Constructor.

Parameters

port	the physical SPI port

◆ ~SPI()

virtual frc::SPI::~SPI ( )

virtual

◆ SPI() [2/2]

frc::SPI::SPI ( SPI && )

default

Member Function Documentation

◆ ConfigureAutoStall()

void frc::SPI::ConfigureAutoStall	(	HAL_SPIPort	port,
		int	csToSclkTicks,
		int	stallTicks,
		int	pow2BytesPerRead
	)

Configure the Auto SPI Stall time between reads.

Parameters

port	The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP.
csToSclkTicks	the number of ticks to wait before asserting the cs pin
stallTicks	the number of ticks to stall for
pow2BytesPerRead	the number of bytes to read before stalling

◆ ForceAutoRead()

void frc::SPI::ForceAutoRead ( )

Force the engine to make a single transfer.

◆ FreeAccumulator()

void frc::SPI::FreeAccumulator ( )

Frees the accumulator.

◆ FreeAuto()

void frc::SPI::FreeAuto ( )

Frees the automatic SPI transfer engine.

◆ GetAccumulatorAverage()

double frc::SPI::GetAccumulatorAverage ( ) const

Read the average of the accumulated value.

Returns: The accumulated average value (value / count).

◆ GetAccumulatorCount()

int64_t frc::SPI::GetAccumulatorCount ( ) const

Read the number of accumulated values.

Read the count of the accumulated values since the accumulator was last Reset().

Returns: The number of times samples from the channel were accumulated.

◆ GetAccumulatorIntegratedAverage()

double frc::SPI::GetAccumulatorIntegratedAverage ( ) const

Read the average of the integrated value.

This is the sum of (each value times the time between values), divided by the count.

Returns: The average of the integrated value accumulated since the last Reset().

◆ GetAccumulatorIntegratedValue()

double frc::SPI::GetAccumulatorIntegratedValue ( ) const

Read the integrated value.

This is the sum of (each value * time between values).

Returns: The integrated value accumulated since the last Reset().

◆ GetAccumulatorLastValue()

int frc::SPI::GetAccumulatorLastValue ( ) const

Read the last value read by the accumulator engine.

◆ GetAccumulatorOutput()

void frc::SPI::GetAccumulatorOutput	(	int64_t &	value,
		int64_t &	count
	)		const

Read the accumulated value and the number of accumulated values atomically.

This function reads the value and count atomically. This can be used for averaging.

Parameters

value	Pointer to the 64-bit accumulated output.
count	Pointer to the number of accumulation cycles.

◆ GetAccumulatorValue()

int64_t frc::SPI::GetAccumulatorValue ( ) const

Read the accumulated value.

Returns: The 64-bit value accumulated since the last Reset().

◆ GetAutoDroppedCount()

int frc::SPI::GetAutoDroppedCount ( )

Get the number of bytes dropped by the automatic SPI transfer engine due to the receive buffer being full.

Returns: Number of bytes dropped

◆ GetPort()

Port frc::SPI::GetPort ( ) const

Returns the SPI port.

Returns: The SPI port.

◆ InitAccumulator()

void frc::SPI::InitAccumulator	(	units::second_t	period,
		int	cmd,
		int	xferSize,
		int	validMask,
		int	validValue,
		int	dataShift,
		int	dataSize,
		bool	isSigned,
		bool	bigEndian
	)

Initialize the accumulator.

Parameters

period	Time between reads
cmd	SPI command to send to request data
xferSize	SPI transfer size, in bytes
validMask	Mask to apply to received data for validity checking
validValue	After valid_mask is applied, required matching value for validity checking
dataShift	Bit shift to apply to received data to get actual data value
dataSize	Size (in bits) of data field
isSigned	Is data field signed?
bigEndian	Is device big endian?

◆ InitAuto()

void frc::SPI::InitAuto ( int bufferSize )

Initialize automatic SPI transfer engine.

Only a single engine is available, and use of it blocks use of all other chip select usage on the same physical SPI port while it is running.

Parameters

bufferSize buffer size in bytes

◆ operator=()

SPI & frc::SPI::operator= ( SPI && )

default

◆ Read()

virtual int frc::SPI::Read	(	bool	initiate,
		uint8_t *	dataReceived,
		int	size
	)

virtual

Read a word from the receive FIFO.

Waits for the current transfer to complete if the receive FIFO is empty.

If the receive FIFO is empty, there is no active transfer, and initiate is false, errors.

Parameters

initiate	If true, this function pushes "0" into the transmit buffer and initiates a transfer. If false, this function assumes that data is already in the receive FIFO from a previous write.
dataReceived	Buffer to receive data from the device
size	The length of the transaction, in bytes

◆ ReadAutoReceivedData()

int frc::SPI::ReadAutoReceivedData	(	uint32_t *	buffer,
		int	numToRead,
		units::second_t	timeout
	)

Read data that has been transferred by the automatic SPI transfer engine.

Transfers may be made a byte at a time, so it's necessary for the caller to handle cases where an entire transfer has not been completed.

Each received data sequence consists of a timestamp followed by the received data bytes, one byte per word (in the least significant byte). The length of each received data sequence is the same as the combined size of the data and zeroSize set in SetAutoTransmitData().

Blocks until numToRead words have been read or timeout expires. May be called with numToRead=0 to retrieve how many words are available.

Parameters

buffer	buffer where read words are stored
numToRead	number of words to read
timeout	timeout (ms resolution)

Returns: Number of words remaining to be read

◆ ResetAccumulator()

void frc::SPI::ResetAccumulator ( )

Resets the accumulator to zero.

◆ SetAccumulatorCenter()

void frc::SPI::SetAccumulatorCenter ( int center )

Set the center value of the accumulator.

The center value is subtracted from each value before it is added to the accumulator. This is used for the center value of devices like gyros and accelerometers to make integration work and to take the device offset into account when integrating.

◆ SetAccumulatorDeadband()

void frc::SPI::SetAccumulatorDeadband ( int deadband )

Set the accumulator's deadband.

◆ SetAccumulatorIntegratedCenter()

void frc::SPI::SetAccumulatorIntegratedCenter ( double center )

Set the center value of the accumulator integrator.

The center value is subtracted from each value*dt before it is added to the integrated value. This is used for the center value of devices like gyros and accelerometers to take the device offset into account when integrating.

◆ SetAutoTransmitData()

void frc::SPI::SetAutoTransmitData	(	std::span< const uint8_t >	dataToSend,
		int	zeroSize
	)

Set the data to be transmitted by the engine.

Up to 16 bytes are configurable, and may be followed by up to 127 zero bytes.

Parameters

dataToSend	data to send (maximum 16 bytes)
zeroSize	number of zeros to send after the data

◆ SetChipSelectActiveHigh()

void frc::SPI::SetChipSelectActiveHigh ( )

Configure the chip select line to be active high.

◆ SetChipSelectActiveLow()

void frc::SPI::SetChipSelectActiveLow ( )

Configure the chip select line to be active low.

◆ SetClockRate()

void frc::SPI::SetClockRate ( int hz )

Configure the rate of the generated clock signal.

The default value is 500,000Hz. The maximum value is 4,000,000Hz.

Parameters

hz	The clock rate in Hertz.

◆ SetMode()

void frc::SPI::SetMode ( Mode mode )

Sets the mode for the SPI device.

Mode 0 is Clock idle low, data sampled on rising edge

Mode 1 is Clock idle low, data sampled on falling edge

Mode 2 is Clock idle high, data sampled on falling edge

Mode 3 is Clock idle high, data sampled on rising edge

Parameters

mode	The mode to set.

◆ StartAutoRate()

void frc::SPI::StartAutoRate ( units::second_t period )

Start running the automatic SPI transfer engine at a periodic rate.

InitAuto() and SetAutoTransmitData() must be called before calling this function.

Parameters

period period between transfers (us resolution)

◆ StartAutoTrigger()

void frc::SPI::StartAutoTrigger	(	DigitalSource &	source,
		bool	rising,
		bool	falling
	)

Start running the automatic SPI transfer engine when a trigger occurs.

InitAuto() and SetAutoTransmitData() must be called before calling this function.

Parameters

source	digital source for the trigger (may be an analog trigger)
rising	trigger on the rising edge
falling	trigger on the falling edge

◆ StopAuto()

void frc::SPI::StopAuto ( )

Stop running the automatic SPI transfer engine.

◆ Transaction()

virtual int frc::SPI::Transaction	(	uint8_t *	dataToSend,
		uint8_t *	dataReceived,
		int	size
	)

virtual

Perform a simultaneous read/write transaction with the device.

Parameters

dataToSend	The data to be written out to the device
dataReceived	Buffer to receive data from the device
size	The length of the transaction, in bytes

◆ Write()

virtual int frc::SPI::Write	(	uint8_t *	data,
		int	size
	)

virtual

Write data to the peripheral device.

Blocks until there is space in the output FIFO.

If not running in output only mode, also saves the data received on the CIPO input during the transfer into the receive FIFO.

Member Data Documentation

◆ m_mode

HAL_SPIMode frc::SPI::m_mode = HAL_SPIMode::HAL_SPI_kMode0

protected

◆ m_port

hal::SPIPort frc::SPI::m_port

protected

The documentation for this class was generated from the following file:

frc/SPI.h

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Mode

◆ Port

Constructor & Destructor Documentation

◆ SPI() [1/2]

◆ ~SPI()

◆ SPI() [2/2]

Member Function Documentation

◆ ConfigureAutoStall()

◆ ForceAutoRead()

◆ FreeAccumulator()

◆ FreeAuto()

◆ GetAccumulatorAverage()

◆ GetAccumulatorCount()

◆ GetAccumulatorIntegratedAverage()

◆ GetAccumulatorIntegratedValue()

◆ GetAccumulatorLastValue()

◆ GetAccumulatorOutput()

◆ GetAccumulatorValue()

◆ GetAutoDroppedCount()

◆ GetPort()

◆ InitAccumulator()

◆ InitAuto()

◆ operator=()

◆ Read()

◆ ReadAutoReceivedData()

◆ ResetAccumulator()

◆ SetAccumulatorCenter()

◆ SetAccumulatorDeadband()

◆ SetAccumulatorIntegratedCenter()

◆ SetAutoTransmitData()

◆ SetChipSelectActiveHigh()

◆ SetChipSelectActiveLow()

◆ SetClockRate()

◆ SetMode()

◆ StartAutoRate()

◆ StartAutoTrigger()

◆ StopAuto()

◆ Transaction()

◆ Write()

Member Data Documentation

◆ m_mode

◆ m_port