docs/library/machine.I2C: Update to reflect ESP8266 implementation.

This machine.I2C documentation is now closer to a more port-neutral
description, although there are still differences between WiPy and
ESP8266.

docs/library/machine.I2C.rst

@@ -49,12 +49,15 @@ Constructors
        Construct an I2C object on the given bus.  `bus` can only be 0.
        If the bus is not given, the default one will be selected (0).
 
-Methods
--------
+.. only:: port_esp8266
 
-.. method:: i2c.deinit()
+    .. class:: machine.I2C(scl, sda, \*, freq=400000)
 
-   Turn off the I2C bus.
+       Construct and return a new I2C object.
+       See the init method below for a description of the arguments.
+
+General Methods
+---------------
 
 .. only:: port_wipy
 
@@ -66,48 +69,131 @@ Methods
          - ``baudrate`` is the SCL clock rate
          - ``pins`` is an optional tuple with the pins to assign to the I2C bus.
 
-    .. method:: i2c.readfrom(addr, nbytes)
+.. only:: port_esp8266
+
+    .. method:: i2c.init(scl, sda, \*, freq=400000)
+
+      Initialise the I2C bus with the given arguments:
 
-        Read ``nbytes`` from the slave specified by ``addr``.
-        Returns a ``bytes`` object with the data read.
+         - `scl` is a pin object for the SCL line
+         - `sda` is a pin object for the SDA line
+         - `freq` is the SCL clock rate
 
-    .. method:: i2c.readfrom_into(addr, buf)
+.. method:: i2c.deinit()
 
-        Read into ``buf`` from the slave specified by ``addr``.
-        Returns the number of bytes read.
+   Turn off the I2C bus.
 
-    .. method:: i2c.writeto(addr, buf, \*, stop=True)
+   Availability: WiPy.
 
-        Write ``buf`` to the slave specified by ``addr``. Set ``stop`` to ``False``
-        if the transfer should be continued.
-        Returns the number of bytes written.
+.. method:: i2c.scan()
 
-    .. method:: i2c.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8)
+   Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of
+   those that respond.  A device responds if it pulls the SDA line low after
+   its address (including a read bit) is sent on the bus.
 
-        Read ``nbytes`` from the slave specified by ``addr`` starting from the memory
-        address specified by ``memaddr``.
-        Param ``addrsize`` specifies the address size in bits.
-        Returns a ``bytes`` object with the data read.
+   Note: on WiPy the I2C object must be in master mode for this method to be valid.
 
-    .. method:: i2c.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8)
+Primitive I2C operations
+------------------------
 
-        Read into ``buf`` from the slave specified by ``addr`` starting from the memory
-        address specified by ``memaddr``.
-        Param ``addrsize`` specifies the address size in bits.
-        Returns the number of bytes read.
+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.
 
-    .. method:: i2c.writeto_mem(addr, memaddr, buf, \*, addrsize=8)
+.. method:: i2c.start()
 
-        Write ``buf`` to the slave specified by ``addr`` starting from the
-        memory address specified by ``memaddr``. Param ``addrsize`` specifies the 
-        address size in bits.
-        Set ``stop`` to ``False`` if the transfer should be continued.
-        Returns the number of bytes written.
+   Send a start bit on the bus (SDA transitions to low while SCL is high).
 
-.. method:: i2c.scan()
+   Availability: ESP8266.
+
+.. method:: i2c.stop()
+
+   Send a stop bit on the bus (SDA transitions to high while SCL is high).
+
+   Availability: ESP8266.
+
+.. method:: i2c.readinto(buf)
+
+   Reads bytes from the bus and stores them into `buf`.  The number of bytes
+   read is the length of `buf`.  An ACK will be sent on the bus after
+   receiving all but the last byte, and a NACK will be sent following the last
+   byte.
+
+   Availability: ESP8266.
+
+.. method:: i2c.write(buf)
+
+   Write all the bytes from `buf` to the bus.  Checks that an ACK is received
+   after each byte and raises an OSError if not.
+
+   Availability: ESP8266.
+
+Standard bus operations
+-----------------------
+
+The following methods implement the standard I2C master read and write
+operations that target a given slave device.
 
-   Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of those that respond.
-   Only valid when in master mode.
+.. method:: i2c.readfrom(addr, nbytes)
+
+   Read `nbytes` from the slave specified by `addr`.
+   Returns a `bytes` object with the data read.
+
+.. method:: i2c.readfrom_into(addr, buf)
+
+   Read into `buf` from the slave specified by `addr`.
+   The number of bytes read will be the length of `buf`.
+
+   On WiPy the return value is the number of bytes read.  Otherwise the
+   return value is `None`.
+
+.. method:: i2c.writeto(addr, buf, \*, stop=True)
+
+   Write the bytes from `buf` to the slave specified by `addr`.
+
+   The `stop` argument (only available on WiPy) tells if a stop bit should be
+   sent at the end of the transfer.  If `False` the transfer should be
+   continued later on.
+
+   On WiPy the return value is the number of bytes written.  Otherwise the
+   return value is `None`.
+
+Memory operations
+-----------------
+
+Some I2C devices act as a memory device (or set of registers) that can be read
+from and written to.  In this case there are two addresses associated with an
+I2C transaction: the slave address and the memory address.  The following
+methods are convenience functions to communicate with such devices.
+
+.. method:: i2c.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8)
+
+   Read `nbytes` from the slave specified by `addr` starting from the memory
+   address specified by `memaddr`.
+   The argument `addrsize` specifies the address size in bits (on ESP8266
+   this argument is not recognised and the address size is always 8 bits).
+   Returns a `bytes` object with the data read.
+
+.. method:: i2c.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8)
+
+   Read into `buf` from the slave specified by `addr` starting from the
+   memory address specified by `memaddr`.  The number of bytes read is the
+   length of `buf`.
+   The argument `addrsize` specifies the address size in bits (on ESP8266
+   this argument is not recognised and the address size is always 8 bits).
+
+   On WiPy the return value is the number of bytes read.  Otherwise the
+   return value is `None`.
+
+.. method:: i2c.writeto_mem(addr, memaddr, buf, \*, addrsize=8)
+
+   Write `buf` to the slave specified by `addr` starting from the
+   memory address specified by `memaddr`.
+   The argument `addrsize` specifies the address size in bits (on ESP8266
+   this argument is not recognised and the address size is always 8 bits).
+
+   On WiPy the return value is the number of bytes written.  Otherwise the
+   return value is `None`.
 
 Constants
 ---------
@@ -115,3 +201,5 @@ Constants
 .. data:: I2C.MASTER
 
    for initialising the bus to master mode
+
+   Availability: WiPy.