1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
.. 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.
|
