HardwareSPI — Maple v0.0.12 Documentation

### Navigation

- next
- previous |
- LeafLabs |
- Index »
- Complete Language Index »

# 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
- Turning the SPI Port On
- Communicating Over SPI
- HardwareSPI Class Reference
- Deprecated Functions

## 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 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:

SPIFrequency enum

  Defines the possible SPI communication speeds.

  Values:

  - `SPI_18MHZ``= 0` -

    18 MHz

  - `SPI_9MHZ``= 1` -

    9 MHz

  - `SPI_4_5MHZ``= 2` -

    4.5 MHz

  - `SPI_2_25MHZ``= 3` -

    2.25 MHz

  - `SPI_1_125MHZ``= 4` -

    1.125 MHz

  - `SPI_562_500KHZ``= 5` -

    562.500 KHz

  - `SPI_281_250KHZ``= 6` -

    281.250 KHz

  - `SPI_140_625KHZ``= 7` -

    140.625 KHz

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:

spi_mode enum

  SPI mode configuration.

  Determines a combination of clock polarity (CPOL), which determines idle state of the clock line, and clock phase (CPHA), which determines which clock edge triggers data capture.

  Values:

  - `SPI_MODE_0` -

    Clock line idles low (0), data capture on first clock transition.

  - `SPI_MODE_1` -

    Clock line idles low (0), data capture on second clock transition.

  - `SPI_MODE_2` -

    Clock line idles high (1), data capture on first clock transition.

  - `SPI_MODE_3` -

    Clock line idles high (1), data capture on second clock transition.

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()`.

void `HardwareSPI::``write`(byte data)

  Send a single byte of data.

  Parameters:

  - `data`: Byte to send

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

> > HardwareSPI(uint32 spiPortNumber)

> >   Parameters: | `spiPortNumber` - Number of the SPI port to manage.

> > 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 write(uint8 data)

> >   Transmit a byte.

> >   Parameters: | `data` - Byte to transmit.

> > void write(const uint8 * buffer, uint32 length)

> >   Transmit multiple bytes.

> >   Parameters: | `buffer` - Bytes to transmit. `length` - Number of bytes in buffer to transmit.

> > uint8 transfer(uint8 data)

> >   Transmit a byte, then return the next unread byte.

> >   This function transmits before receiving.

> >   Parameters: | `data` - Byte to transmit.
> >   Return: | Next unread byte.

## 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, where `length` is the number of bytes to send from `data`. Returns the last byte shifted back from slave.

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.

uint8 `HardwareSPI::``recv`()

  Reads a byte from the peripheral. Returns the next byte in the buffer.

### Navigation

- next
- previous |
- LeafLabs |
- Index »
- Complete Language Index »