.. highlight:: cpp .. _lang-hardwarespi: 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 :ref:`SPI reference <spi>`. .. contents:: Contents :local: 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 :ref:`setup() <lang-setup>` and :ref:`loop() <lang-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). .. FIXME [Breathe] Output doesn't include the class; fix & submit pull req .. doxygenfunction:: HardwareSPI::begin .. note:: If you are using SPI port 3 (on a board that supports it; not all do); you'll need to call :ref:`lang-disabledebugports` before calling ``begin()``. The speed at which the SPI port communicates is configured using a ``SPIFrequency`` value: .. FIXME [0.1.0] Breathe's enum output is enormous; shrink & submit pull req .. doxygenenum:: SPIFrequency .. 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: .. doxygenenum:: spi_mode 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()``. .. cpp:function:: void HardwareSPI::write(byte data) Send a single byte of data. **Parameters**: - ``data``: Byte to send .. cpp:function:: byte HardwareSPI::read() Get the next available, unread byte. If there aren't any unread bytes, this function will wait until one is received. .. cpp:function:: 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 :ref:`lang-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. .. doxygenclass:: HardwareSPI :members: HardwareSPI, begin, beginSlave, end, read, write, transfer 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. .. cpp:function:: uint8 HardwareSPI::send(uint8 *data, uint32 length) Writes ``data`` into the port buffer to be transmitted as soon as possible, where ``length`` is the number of bytes to send from ``data``. Returns the last byte shifted back from slave. .. cpp:function:: uint8 HardwareSPI::send(uint8 data) Writes the single byte ``data`` into the port buffer to be transmitted as soon as possible. Returns the data byte shifted back from the slave. .. cpp:function:: uint8 HardwareSPI::recv() Reads a byte from the peripheral. Returns the next byte in the buffer.