docs: Update I2C and SPI docs to add reference to SoftI2C and SoftSPI.

Signed-off-by: Damien George <damien@micropython.org>

2 files changed, 46 insertions, 12 deletions

diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst
index 743554bc7..f9b951564 100644
--- a/docs/library/machine.I2C.rst
+++ b/docs/library/machine.I2C.rst
@@ -12,6 +12,14 @@ when created, or initialised later on.
 
 Printing the I2C object gives you information about its configuration.
 
+Both hardware and software I2C implementations exist via the
+:ref:`machine.I2C <machine.I2C>` and `machine.SoftI2C` classes.  Hardware I2C uses
+underlying hardware support of the system to perform the reads/writes and is
+usually efficient and fast but may have restrictions on which pins can be used.
+Software I2C 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 I2C
@@ -33,21 +41,33 @@ Example usage::
 Constructors
 ------------
 
-.. class:: I2C(id=-1, *, scl, sda, freq=400000)
+.. class:: I2C(id, *, scl, sda, freq=400000)
 
    Construct and return a new I2C object using the following parameters:
 
-      - *id* identifies a particular I2C peripheral.  The default
-        value of -1 selects a software implementation of I2C which can
-        work (in most cases) with arbitrary pins for SCL and SDA.
-        If *id* is -1 then *scl* and *sda* must be specified.  Other
-        allowed values for *id* depend on the particular port/board,
-        and specifying *scl* and *sda* may or may not be required or
-        allowed in this case.
+      - *id* identifies a particular I2C peripheral.  Allowed values for
+        depend on the particular port/board
+      - *scl* should be a pin object specifying the pin to use for SCL.
+      - *sda* should be a pin object specifying the pin to use for SDA.
+      - *freq* should be an integer which sets the maximum frequency
+        for SCL.
+
+   Note that some ports/boards will have default values of *scl* and *sda*
+   that can be changed in this constructor.  Others will have fixed values
+   of *scl* and *sda* that cannot be changed.
+
+.. _machine.SoftI2C:
+.. class:: SoftI2C(scl, sda, *, freq=400000, timeout=255)
+
+   Construct a new software I2C object.  The parameters are:
+
       - *scl* should be a pin object specifying the pin to use for SCL.
       - *sda* should be a pin object specifying the pin to use for SDA.
       - *freq* should be an integer which sets the maximum frequency
         for SCL.
+      - *timeout* is the maximum time in microseconds to wait for clock
+        stretching (SCL held low by another device on the bus), after
+        which an ``OSError(ETIMEDOUT)`` exception is raised.
 
 General Methods
 ---------------
@@ -79,7 +99,7 @@ The following methods implement the primitive I2C master bus operations and can
 be combined to make any I2C transaction.  They are provided if you need more
 control over the bus, otherwise the standard methods (see below) can be used.
 
-These methods are available on software I2C only.
+These methods are only available on the `machine.SoftI2C` class.
 
 .. method:: I2C.start()
 
diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst
index ea460a7b8..7565241eb 100644
--- a/docs/library/machine.SPI.rst
+++ b/docs/library/machine.SPI.rst
@@ -11,21 +11,35 @@ SS (Slave Select), to select a particular device on a bus with which
 communication takes place. Management of an SS signal should happen in
 user code (via machine.Pin class).
 
+Both hardware and software SPI implementations exist via the
+:ref:`machine.SPI <machine.SPI>` and `machine.SoftSPI` classes.  Hardware SPI uses underlying
+hardware support of the system to perform the reads/writes and is usually
+efficient and fast but may have restrictions on which pins can be used.
+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.
+
 Constructors
 ------------
 
 .. class:: SPI(id, ...)
 
-   Construct an SPI object on the given bus, ``id``. Values of ``id`` depend
+   Construct an SPI object on the given bus, *id*. Values of *id* depend
    on a particular port and its hardware. Values 0, 1, etc. are commonly used
-   to select hardware SPI block #0, #1, etc. Value -1 can be used for
-   bitbanging (software) implementation of SPI (if supported by a port).
+   to select hardware SPI block #0, #1, etc.
 
    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.
 
+.. _machine.SoftSPI:
+.. class:: SoftSPI(baudrate=500000, *, polarity=0, phase=0, bits=8, firstbit=MSB, sck=None, mosi=None, miso=None)
+
+   Construct a new software SPI object.  Additional parameters must be
+   given, usually at least *sck*, *mosi* and *miso*, and these are used
+   to initialise the bus.  See `SPI.init` for a description of the parameters.
+
 Methods
 -------