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

Signed-off-by: Damien George <[email protected]>

Author: dpgeorge

docs/esp32/quickref.rst

@@ -249,16 +249,15 @@ ESP32 specific ADC class method reference:
 Software SPI bus
 ----------------
 
-There are two SPI drivers. One is implemented in software (bit-banging)
-and works on all pins, and is accessed via the :ref:`machine.SPI <machine.SPI>`
-class::
+Software SPI (using bit-banging) works on all pins, and is accessed via the
+:ref:`machine.SoftSPI <machine.SoftSPI>` class::
 
-    from machine import Pin, SPI
+    from machine import Pin, SoftSPI
 
-    # construct an SPI bus on the given pins
+    # construct a SoftSPI bus on the given pins
     # polarity is the idle state of SCK
     # phase=0 means sample on the first edge of SCK, phase=1 means the second
-    spi = SPI(baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
+    spi = SoftSPI(baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
 
     spi.init(baudrate=200000) # set the baudrate
 
@@ -298,39 +297,54 @@ mosi   13           23
 miso   12           19
 =====  ===========  ============
 
-Hardware SPI has the same methods as Software SPI above::
+Hardware SPI is accessed via the :ref:`machine.SPI <machine.SPI>` class and
+has the same methods as software SPI above::
 
     from machine import Pin, SPI
 
     hspi = SPI(1, 10000000, sck=Pin(14), mosi=Pin(13), miso=Pin(12))
     vspi = SPI(2, baudrate=80000000, polarity=0, phase=0, bits=8, firstbit=0, sck=Pin(18), mosi=Pin(23), miso=Pin(19))
 
+Software I2C bus
+----------------
 
-I2C bus
--------
-
-The I2C driver has both software and hardware implementations, and the two
-hardware peripherals have identifiers 0 and 1.  Any available output-capable
-pins can be used for SCL and SDA.  The driver is accessed via the
-:ref:`machine.I2C <machine.I2C>` class::
-
-    from machine import Pin, I2C
+Software I2C (using bit-banging) works on all output-capable pins, and is
+accessed via the :ref:`machine.SoftI2C <machine.SoftI2C>` class::
 
-    # construct a software I2C bus
-    i2c = I2C(scl=Pin(5), sda=Pin(4), freq=100000)
+    from machine import Pin, SoftI2C
 
-    # construct a hardware I2C bus
-    i2c = I2C(0)
-    i2c = I2C(1, scl=Pin(5), sda=Pin(4), freq=400000)
+    i2c = SoftI2C(scl=Pin(5), sda=Pin(4), freq=100000)
 
-    i2c.scan()              # scan for slave devices
+    i2c.scan()              # scan for devices
 
-    i2c.readfrom(0x3a, 4)   # read 4 bytes from slave device with address 0x3a
-    i2c.writeto(0x3a, '12') # write '12' to slave device with address 0x3a
+    i2c.readfrom(0x3a, 4)   # read 4 bytes from device with address 0x3a
+    i2c.writeto(0x3a, '12') # write '12' to device with address 0x3a
 
     buf = bytearray(10)     # create a buffer with 10 bytes
     i2c.writeto(0x3a, buf)  # write the given buffer to the slave
 
+Hardware I2C bus
+----------------
+
+There are two hardware I2C peripherals with identifiers 0 and 1.  Any available
+output-capable pins can be used for SCL and SDA but the defaults are given
+below.
+
+=====  ===========  ============
+\      I2C(0)       I2C(1)
+=====  ===========  ============
+scl    18           25
+sda    19           26
+=====  ===========  ============
+
+The driver is accessed via the :ref:`machine.I2C <machine.I2C>` class and
+has the same methods as software I2C above::
+
+    from machine import Pin, I2C
+
+    i2c = I2C(0)
+    i2c = I2C(1, scl=Pin(5), sda=Pin(4), freq=400000)
+
 Real time clock (RTC)
 ---------------------
 

docs/esp8266/quickref.rst

@@ -214,15 +214,15 @@ Software SPI bus
 ----------------
 
 There are two SPI drivers. One is implemented in software (bit-banging)
-and works on all pins, and is accessed via the :ref:`machine.SPI <machine.SPI>`
+and works on all pins, and is accessed via the :ref:`machine.SoftSPI <machine.SoftSPI>`
 class::
 
-    from machine import Pin, SPI
+    from machine import Pin, SoftSPI
 
     # construct an SPI bus on the given pins
     # polarity is the idle state of SCK
     # phase=0 means sample on the first edge of SCK, phase=1 means the second
-    spi = SPI(-1, baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
+    spi = SoftSPI(baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
 
     spi.init(baudrate=200000) # set the baudrate
 
@@ -258,7 +258,8 @@ I2C bus
 -------
 
 The I2C driver is implemented in software and works on all pins,
-and is accessed via the :ref:`machine.I2C <machine.I2C>` class::
+and is accessed via the :ref:`machine.I2C <machine.I2C>` class (which is an
+alias of :ref:`machine.SoftI2C <machine.SoftI2C>`)::
 
     from machine import Pin, I2C
 

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()
 

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
 -------