aboutsummaryrefslogtreecommitdiffstats
path: root/source/lang/api/hardwarespi.rst
blob: 53a225d7c65a1196de7201ceefd9a4889d64eb1f (plain)
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
.. highlight:: cpp

.. _lang-hardwarespi:

HardwareSPI
===========

This class is used for creating objects to manage the Maple's built-in
SPI ports.  The Maple has two SPI ports.  The relevant pins
corresponding to each port's logic signals are documented in the
following table (and on the Maple silkscreen):

.. _lang-hardwarespi-pinout:

.. list-table::
   :header-rows: 1

   * - Port number
     - NSS
     - MOSI
     - MISO
     - SCK

   * - 1
     - 10
     - 11
     - 12
     - 13

   * - 2
     - 31
     - 32
     - 33
     - 34

If you use a SPI port, you cannot simultaneously use its associated
pins for other purposes.

Library Documentation
---------------------

Using the SPI Class
^^^^^^^^^^^^^^^^^^^

You can declare that you want to use SPI in your sketch by putting
``HardwareSPI Spi(number);`` with your variables, where ``number`` is
1 or 2, depending on which SPI you want to use.  Then you can use the
functions described in the next section.  For example::

   // Use SPI 1
   HardwareSpi Spi(1);

   void setup() {
       Spi.begin(SPI_18MHZ);
   }

   void loop() {
       // Get the next byte from the peripheral
       uint8 byte = Spi.recv();
   }

HardwareSPI Class Reference
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cpp:class:: HardwareSPI

   Class for interacting with SPI.

.. cpp:function:: HardwareSPI::HardwareSPI(uint32 spi_num)

   Construct an object for managing a SPI peripheral.  ``spi_num``
   must be 1 or 2; see the :ref:`table above
   <lang-hardwarespi-pinout>` for pinout information.

.. cpp:function:: void HardwareSPI::begin(SPIFrequency freq, uint32 endianness, uint32 mode)

   Configure the baudrate of the given SPI port and set up the header
   pins appropriately.

   Parameters:

   - ``freq``: one of the ``SPIFrequency`` values, given :ref:`below
     <lang-hardwarespi-spifrequency>`.

   - ``endianness``: either ``LSBFIRST`` (little-endian) or
     ``MSBFIRST`` (big-endian).

   - ``mode``: one of 0, 1, 2, or 3, and specifies which SPI mode is
     used.  The mode number determines a combination of polarity and
     phase according to the following table:

     .. list-table::
        :header-rows: 1

        * - Mode
          - Polarity
          - Phase

        * - 0
          - 0
          - 0

        * - 1
          - 0
          - 1

        * - 2
          - 1
          - 0

        * - 3
          - 1
          - 1

     For more information on polarity and phase, see the
     :ref:`external references, below <lang-hardwarespi-seealso>`.

.. cpp:function:: void HardwareSPI::begin()

   A convenience ``begin()``, equivalent to ``begin(SPI_1_125MHZ,
   MSBFIRST, 0)``.

.. 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.

SPI Speeds
^^^^^^^^^^

.. _lang-hardwarespi-spifrequency:

The possible SPI speeds are configured using the ``SPIFrequency`` enum:

.. doxygenenum:: SPIFrequency

.. _lang-hardwarespi-seealso:

See Also
--------

* `Wikipedia Article on Serial Peripheral Interface Bus (SPI)
  <http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus>`_
* `Arduino reference on SPI
  <http://www.arduino.cc/playground/Code/Spi>`_
* `Hardcore SPI on Arduino <http://klk64.com/arduino-spi/>`_ by kik64
* STMicro documentation for STM32F103RB microcontroller:

  * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf)
  * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf)