HardwareSPI¶
This page describes how to use the built-in SPI ports. It does not describe the SPI protocol itself. For more information about SPI, see the SPI reference.
Contents
Getting Started¶
In order to get started, you’ll first need to define a HardwareSPI
variable, which you’ll use to control the SPI port. Do this by
putting the line “HardwareSPI spi(number);
” with your variables,
where number
is the SPI port’s number.
Here’s an example (we’ll fill in setup() and loop() later):
// Use SPI port number 1
HardwareSPI spi(1);
void setup() {
// Your setup code
}
void loop() {
// Do stuff with SPI
}
Turning the SPI Port On¶
Now it’s time to turn your SPI port on. Do this with the begin()
function (an example is given below).
-
void
HardwareSPI::
begin
(void)¶ Equivalent to begin(SPI_1_125MHZ, MSBFIRST, 0).
-
void
HardwareSPI::
begin
(SPIFrequency frequency, uint32 bitOrder, uint32 mode)¶ Turn on a SPI port and set its GPIO pin modes for use as master.
SPI port is enabled in full duplex mode, with software slave management.
- Parameters
frequency
-Communication frequency
bitOrder
-Either LSBFIRST (little-endian) or MSBFIRST (big-endian)
mode
-SPI mode to use, one of SPI_MODE_0, SPI_MODE_1, SPI_MODE_2, and SPI_MODE_3.
Note
If you are using SPI port 3 (on a board that supports it;
not all do); you’ll need to call disableDebugPorts()
before calling begin()
.
The speed at which the SPI port communicates is configured using a
SPIFrequency
value:
-
enum
SPIFrequency
¶ Defines the possible SPI communication speeds.
Values:
-
SPI_PCLK_DIV_2
= 0¶
-
SPI_PCLK_DIV_4
= 1¶
-
SPI_PCLK_DIV_8
= 2¶
-
SPI_PCLK_DIV_16
= 3¶
-
SPI_PCLK_DIV_32
= 4¶
-
SPI_PCLK_DIV_64
= 5¶
-
SPI_PCLK_DIV_128
= 6¶
-
SPI_PCLK_DIV_256
= 7¶
-
Note
Due to hardware issues, you can’t use the frequency
SPI_140_625KHz
with SPI port 1.
The “mode” value determines the clock phase and polarity, like so:
-
enum
spi_mode
¶ SPI mode configuration.
A SPI mode determines a combination of the idle state of the clock line (the clock polarity, or “CPOL”), and which clock edge triggers data capture (the clock phase, or “CPHA”).
Values:
-
SPI_MODE_LOW_RISING
= 0¶ Clock idles low, data captured on rising edge (first transition)
-
SPI_MODE_LOW_FALLING
= 1¶ Clock idles low, data captured on falling edge (second transition)
-
SPI_MODE_HIGH_FALLING
= 2¶ Clock idles high, data captured on falling edge (first transition)
-
SPI_MODE_HIGH_RISING
= 3¶ Clock idles high, data captured on rising edge (second transition)
-
SPI_MODE_0
= SPI_MODE_LOW_RISING¶ Same as SPI_MODE_LOW_RISING.
-
SPI_MODE_1
= SPI_MODE_LOW_FALLING¶ Same as SPI_MODE_LOW_FALLING.
-
SPI_MODE_2
= SPI_MODE_HIGH_FALLING¶ Same as SPI_MODE_HIGH_FALLING.
-
SPI_MODE_3
= SPI_MODE_HIGH_RISING¶ Same as SPI_MODE_HIGH_RISING.
-
You’ll need to determine the correct values for frequency
,
bitOrder
, and mode
yourself, by consulting the datasheet for
the device you’re communicating with. Continuing our example from
before, we’ll add a call to begin()
to our setup()
:
// Use SPI port number 1
HardwareSPI spi(1);
void setup() {
// Turn on the SPI port
spi.begin(SPI_18MHZ, MSBFIRST, 0);
}
void loop() {
// Do stuff with SPI
}
If you call begin()
with no arguments (as in “spi.begin();
”),
it’s the same as if you wrote “spi.begin(SPI_1_125MHZ, MSBFIRST,
0);
”.
Communicating Over SPI¶
Now that you’ve got your SPI port set up, it’s time to start
communicating. You can send data using HardwareSPI::write()
,
receive data using HardwareSPI::read()
, and do both using
HardwareSPI::transfer()
.
-
byte
HardwareSPI::
read
()¶ Get the next available, unread byte. If there aren’t any unread bytes, this function will wait until one is received.
-
byte
HardwareSPI::
transfer
(byte data)¶ Send a byte, then return the next byte received.
Parameters:
data
: Byte to send
Returns: Next unread byte
Continuing our example from before, let’s send a number over SPI and print out whatever we get back over SerialUSB:
// Use SPI port number 1
HardwareSPI spi(1);
void setup() {
// Turn on the SPI port
spi.begin(SPI_18MHZ, MSBFIRST, 0);
}
void loop() {
// Send 245 over SPI, and wait for a response.
spi.write(245);
byte response = spi.read();
// Print out the response received.
SerialUSB.print("response: ");
SerialUSB.println(response, DEC);
}
HardwareSPI Class Reference¶
There are a number of other things you can accomplish with your
spi
object. A full function listing follows.
-
class
HardwareSPI
¶ Wirish SPI interface.
This implementation uses software slave management, so the caller is responsible for controlling the slave select line.
Public Functions
-
void
begin
(SPIFrequency frequency, uint32 bitOrder, uint32 mode)¶ Turn on a SPI port and set its GPIO pin modes for use as master.
SPI port is enabled in full duplex mode, with software slave management.
- Parameters
frequency
-Communication frequency
bitOrder
-Either LSBFIRST (little-endian) or MSBFIRST (big-endian)
mode
-SPI mode to use, one of SPI_MODE_0, SPI_MODE_1, SPI_MODE_2, and SPI_MODE_3.
-
void
begin
(void)¶ Equivalent to begin(SPI_1_125MHZ, MSBFIRST, 0).
-
void
beginSlave
(uint32 bitOrder, uint32 mode)¶ Turn on a SPI port and set its GPIO pin modes for use as a slave.
SPI port is enabled in full duplex mode, with software slave management.
- Parameters
bitOrder
-Either LSBFIRST (little-endian) or MSBFIRST(big-endian)
mode
-SPI mode to use
-
void
beginSlave
(void)¶ Equivalent to beginSlave(MSBFIRST, 0).
-
void
end
(void)¶ Disables the SPI port, but leaves its GPIO pin modes unchanged.
-
uint8
read
(void)¶ Return the next unread byte.
If there is no unread byte waiting, this function will block until one is received.
-
void
read
(uint8 *buffer, uint32 length)¶ Read length bytes, storing them into buffer.
- Parameters
buffer
-Buffer to store received bytes into.
length
-Number of bytes to store in buffer. This function will block until the desired number of bytes have been read.
-
void
Deprecated Functions¶
The following functions are defined for now, but they have been deprecated, and will be removed in a future Maple IDE release. You shouldn’t use them in new programs, and you should change any of your programs which do use them to the up-to-date functions discussed above.
-
uint8
HardwareSPI::
send
(uint8 *data, uint32 length)¶ Writes
data
into the port buffer to be transmitted as soon as possible, wherelength
is the number of bytes to send fromdata
. Returns the last byte shifted back from slave.