From bd20f15dfe5f86abf92a4dbe07a6f2eaf66b8e92 Mon Sep 17 00:00:00 2001
From: devsaurus <devsaurus@users.noreply.github.com>
Date: Sat, 9 Jan 2016 14:57:03 +0100
Subject: [PATCH] transferred spi module documentation

---
 docs/en/modules/spi.md | 173 +++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml             |   1 +
 2 files changed, 174 insertions(+)
 create mode 100644 docs/en/modules/spi.md

diff --git a/docs/en/modules/spi.md b/docs/en/modules/spi.md
new file mode 100644
index 00000000..014d83a5
--- /dev/null
+++ b/docs/en/modules/spi.md
@@ -0,0 +1,173 @@
+#spi module
+All transactions for sending and receiving are most-significant-bit first and least-significant last.
+For technical details of the underlying hardware refer to [metalphreak's ESP8266 HSPI articles](http://d.av.id.au/blog/tag/hspi/).
+
+## High Level Functions
+The high level functions provide a send & receive API for half- and
+full-duplex mode. Sent and received data items are restricted to 1 - 32 bit
+length and each data item is surrounded by (H)SPI CS inactive.
+
+## spi.recv()
+Receive data from SPI.
+
+#### Syntax
+`spi.recv(id, size[, default_data])`
+
+#### Parameters
+- `id` SPI ID number: 0 for SPI, 1 for HSPI
+- `size` number of data items to be read
+- `default_data` default data being sent on MOSI (all-1 if omitted)
+
+#### Returns
+String containing the bytes read from SPI.
+
+####See also
+[spi.send()](#spisend)
+
+## spi.send()
+Send data via SPI in half-duplex mode. Send & receive data in full-duplex mode.
+
+#### Syntax
+HALFDUPLEX:<br />
+`wrote = spi.send(id, data1[, data2[, ..., datan]])`
+
+FULLDUPLEX:<br />
+`wrote[, rdata1[, ..., rdatan]] = spi.send(id, data1[, data2[, ..., datan]])`
+
+#### Parameters
+- `id` SPI ID number: 0 for SPI, 1 for HSPI
+- `data` data can be either a string, a table or an integer number.<br/>Each data item is considered with `databits` number of bits.
+
+#### Returns
+- `wrote` number of written bytes
+- `rdata` received data when configured with `spi.FULLDUPLEX`<br />Same data type as corresponding data parameter.
+
+#### Example
+```lua
+=spi.send(1, 0, 255, 255, 255)
+4       255     192     32      0
+x = {spi.send(1, 0, 255, 255, 255)}
+=x[1]
+4
+=x[2]
+255
+=x[3]
+192
+=x[4]
+32
+=x[5]
+0
+=x[6]
+nil
+=#x
+5
+
+_, _, x = spi.send(1, 0, {255, 255, 255})
+=x[1]
+192
+=x[2]
+32
+=x[3]
+0
+```
+#### See also
+- [spi.setup()](#spisetup)
+- [spi.recv()](#spirecv)
+
+## spi.setup()
+Set up the SPI configuration.
+Refer to [Serial Peripheral Interface Bus](https://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus#Clock_polarity_and_phase) for details regarding the clock polarity and phase definition.
+
+#### Syntax
+`spi.setup(id, mode, cpol, cpha, databits, clock_div[, duplex_mode])`
+
+#### Parameters
+- `id` SPI ID number: 0 for SPI, 1 for HSPI
+- `mode` select master or slave mode
+	- `spi.MASTER`
+	- `spi.SLAVE` - **not supported currently**
+- `cpol` clock polarity selection
+	- `spi.CPOL_LOW` 
+	- `spi.CPOL_HIGH` - **not supported currently**
+- `cpha` clock phase selection
+	- `spi.CPHA_LOW`
+	- `spi.CPHA_HIGH`
+- `databits` number of bits per data item 1 - 32
+- `clock_div` SPI clock divider, f(SPI) = f(CPU) / `clock_div`
+- `duplex_mode` duplex mode
+	-  `spi.HALFDUPLEX` (default when omitted)
+	- `spi.FULLDUPLEX`
+
+#### Returns
+Number: 1
+
+## Low Level Hardware Functions
+The low level functions provide a hardware-centric API for application
+scenarios that need to excercise more complex SPI transactions. The
+programming model is built up around the HW send and receive buffers and SPI
+transactions are initiated with full control over the hardware features.
+
+## spi.get_miso()
+Extract data items from MISO buffer after `spi.transaction()`.
+
+#### Syntax
+`data1[, data2[, ..., datan]] = spi.get_miso(id, offset, bitlen, num)`
+
+#### Parameters
+- `id` SPI ID number: 0 for SPI, 1 for HSPI
+- `offset` bit offset into MISO buffer for first data item
+- `bitlen` bit length of a single data item
+- `num` number of data items to retrieve
+
+####Returns
+`num` data items
+
+#### See also
+[spi.transaction()](#spitransaction)
+
+## spi.set_mosi()
+Insert data items into MOSI buffer for `spi.transaction()`.
+
+#### Syntax
+`spi.set_mosi(id, offset, bitlen, data1[, data2[, ..., datan]])`
+
+####Parameters
+- `id` SPI ID number: 0 for SPI, 1 for HSPI
+- `offset` bit offset into MOSI buffer for inserting data1 and subsequent items
+- `bitlen` bit length of data1, data2, ...
+- `data` data items where `bitlen` number of bits are considered for the transaction.
+
+#### Returns
+`nil`
+
+#### See also
+[spi.transaction()](#spitransaction)
+
+## spi.transaction()
+Start an SPI transaction, consisting of up to 5 phases:
+
+1. Command
+2. Address
+3. MOSI
+4. Dummy
+5. MISO
+
+#### Syntax
+`spi.transaction(id, cmd_bitlen, cmd_data, addr_bitlen, addr_data, mosi_bitlen, dummy_bitlen, miso_bitlen)`
+
+#### Parameters
+- `id` SPI ID number: 0 for SPI, 1 for HSPI
+- `cmd_bitlen` bit length of the command phase (0 - 16)
+- `cmd_data` data for command phase
+- `addr_bitlen` bit length for address phase (0 - 32)
+- `addr_data` data for command phase
+- `mosi_bitlen` bit length of the MOSI phase (0 - 512)
+- `dummy_bitlen` bit length of the dummy phase (0 - 256)
+- `miso_bitlen` bit length of the MISO phase (0 - 512) for half-duplex.<br />Full-duplex mode is activated with a negative value.
+
+####Returns
+`nil`
+
+####See also
+- [spi.set_mosi()](#spisetmosi)
+- [spi.get_miso()](#spigetmiso)
diff --git a/mkdocs.yml b/mkdocs.yml
index f2ce5727..65467ff6 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -40,6 +40,7 @@ pages:
         - 'rtctime': 'en/modules/rtctime.md'
         - 'rtcfifo': 'en/modules/rtcfifo.md'
         - 'sntp': 'en/modules/sntp.md'
+        - 'spi': 'en/modules/spi.md'
         - 'tmr': 'en/modules/tmr.md'
         - 'u8g': 'en/modules/u8g.md'
         - 'uart': 'en/modules/uart.md'