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
parent
8c35f3979c
commit
c816b89353
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user