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.
This commit is contained in:
Damien George 2016-05-02 12:31:17 +01:00
parent 8c35f3979c
commit c816b89353
1 changed files with 125 additions and 37 deletions

View File

@ -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
Read ``nbytes`` from the slave specified by ``addr``.
Returns a ``bytes`` object with the data read.
.. method:: i2c.init(scl, sda, \*, freq=400000)
.. method:: i2c.readfrom_into(addr, buf)
Initialise the I2C bus with the given arguments:
Read into ``buf`` from the slave specified by ``addr``.
Returns the number of bytes 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.writeto(addr, buf, \*, stop=True)
.. method:: i2c.deinit()
Write ``buf`` to the slave specified by ``addr``. Set ``stop`` to ``False``
if the transfer should be continued.
Returns the number of bytes written.
Turn off the I2C bus.
.. 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``.
Param ``addrsize`` specifies the address size in 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``.
Param ``addrsize`` specifies the address size in bits.
Returns the number of bytes read.
.. 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``. Param ``addrsize`` specifies the
address size in bits.
Set ``stop`` to ``False`` if the transfer should be continued.
Returns the number of bytes written.
Availability: WiPy.
.. method:: i2c.scan()
Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of those that respond.
Only valid when in master mode.
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.
Note: on WiPy the I2C object must be in master mode for this method to be valid.
Primitive I2C operations
------------------------
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.start()
Send a start bit on the bus (SDA transitions to low while SCL is high).
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.
.. 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.