Finalized 0.0.9 documentation.

1 files changed, 152 insertions, 0 deletions

diff --git a/source/lang/api/hardwarespi.rst b/source/lang/api/hardwarespi.rst
new file mode 100644
index 0000000..c71b2c3
--- /dev/null
+++ b/source/lang/api/hardwarespi.rst
@@ -0,0 +1,152 @@
+.. 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
+---------------------
+
+HardwareSPI Class Reference
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can use the SPI interface by including a declaration ``HardwareSPI
+Spi(number);`` at the start of the sketch or program.  The ``number``
+must be either 1 or 2 and specifies which port to use.  Once this is
+done, you can call any of the methods documented here using
+``Spi.method(arguments)``; for example, ``Spi.send(0x13)`` would send
+the value ``0x13`` into the port buffer to be transmitted as soon as
+possible.
+
+.. 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)
+
+