1 files changed, 85 insertions, 0 deletions
diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst
new file mode 100644
index 0000000000..eddd62dbdc
--- /dev/null
+++ b/docs/library/machine.SPI.rst
@@ -0,0 +1,85 @@
+.. _machine.SPI:
+
+class SPI -- a master-driven serial protocol
+============================================
+
+SPI is a serial protocol that is driven by a master.  At the physical level
+there are 3 lines: SCK, MOSI, MISO.
+
+.. only:: port_wipy
+
+    See usage model of I2C; SPI is very similar.  Main difference is
+    parameters to init the SPI bus::
+
+        from machine import SPI
+        spi = SPI(0, mode=SPI.MASTER, baudrate=1000000, polarity=0, phase=0, firstbit=SPI.MSB)
+
+    Only required parameter is mode, must be SPI.MASTER.  Polarity can be 0 or 
+    1, and is the level the idle clock line sits at.  Phase can be 0 or 1 to 
+    sample data on the first or second clock edge respectively.
+
+Constructors
+------------
+
+.. only:: port_wipy
+
+    .. class:: machine.SPI(id, ...)
+
+       Construct an SPI object on the given bus.  ``id`` can be only 0.
+       With no additional parameters, the SPI object is created but not
+       initialised (it has the settings from the last initialisation of
+       the bus, if any).  If extra arguments are given, the bus is initialised.
+       See ``init`` for parameters of initialisation.
+
+Methods
+-------
+
+.. method:: spi.init(mode, baudrate=1000000, \*, polarity=0, phase=0, bits=8, firstbit=SPI.MSB, pins=(CLK, MOSI, MISO))
+
+   Initialise the SPI bus with the given parameters:
+
+     - ``mode`` must be ``SPI.MASTER``.
+     - ``baudrate`` is the SCK clock rate.
+     - ``polarity`` can be 0 or 1, and is the level the idle clock line sits at.
+     - ``phase`` can be 0 or 1 to sample data on the first or second clock edge
+       respectively.
+     - ``bits`` is the width of each transfer, accepted values are 8, 16 and 32.
+     - ``firstbit`` can be ``SPI.MSB`` only.
+     - ``pins`` is an optional tupple with the pins to assign to the SPI bus.
+
+.. method:: spi.deinit()
+
+   Turn off the SPI bus.
+
+.. method:: spi.write(buf)
+
+    Write the data contained in ``buf``. 
+    Returns the number of bytes written.
+
+.. method:: spi.read(nbytes, *, write=0x00)
+
+    Read the ``nbytes`` while writing the data specified by ``write``.
+    Return the number of bytes read.
+
+.. method:: spi.readinto(buf, *, write=0x00)
+
+    Read into the buffer specified by ``buf`` while writing the data specified by
+    ``write``.
+    Return the number of bytes read.
+
+.. method:: spi.write_readinto(write_buf, read_buf)
+
+    Write from ``write_buf`` and read into ``read_buf``. Both buffers must have the
+    same length.
+    Returns the number of bytes written
+
+Constants
+---------
+
+.. data:: SPI.MASTER
+
+   for initialising the SPI bus to master
+
+.. data:: SPI.MSB
+
+   set the first bit to be the most significant bit