docs/library/machine.SPI.rst: Add example SPI usage.

Signed-off-by: Michael Buesch <m@bues.ch>

1 files changed, 36 insertions, 0 deletions

diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst
index 46ac2ec74c..1116f0e8a3 100644
--- a/docs/library/machine.SPI.rst
+++ b/docs/library/machine.SPI.rst
@@ -19,6 +19,42 @@ Software SPI is implemented by bit-banging and can be used on any pin but
 is not as efficient.  These classes have the same methods available and
 differ primarily in the way they are constructed.
 
+Example usage::
+
+    from machine import SPI, Pin
+
+    spi = SPI(0, baudrate=400000)           # Create SPI peripheral 0 at frequency of 400kHz.
+                                            # Depending on the use case, extra parameters may be required
+                                            # to select the bus characteristics and/or pins to use.
+    cs = Pin(4, mode=Pin.OUT, value=1)      # Create chip-select on pin 4.
+
+    try:
+        cs(0)                               # Select peripheral.
+        spi.write(b"12345678")              # Write 8 bytes, and don't care about received data.
+    finally:
+        cs(1)                               # Deselect peripheral.
+
+    try:
+        cs(0)                               # Select peripheral.
+        rxdata = spi.read(8, 0x42)          # Read 8 bytes while writing 0x42 for each byte.
+    finally:
+        cs(1)                               # Deselect peripheral.
+
+    rxdata = bytearray(8)
+    try:
+        cs(0)                               # Select peripheral.
+        spi.readinto(rxdata, 0x42)          # Read 8 bytes inplace while writing 0x42 for each byte.
+    finally:
+        cs(1)                               # Deselect peripheral.
+
+    txdata = b"12345678"
+    rxdata = bytearray(len(txdata))
+    try:
+        cs(0)                               # Select peripheral.
+        spi.write_readinto(txdata, rxdata)  # Simultaneously write and read bytes.
+    finally:
+        cs(1)                               # Deselect peripheral.
+
 Constructors
 ------------