diff options
| -rw-r--r-- | docs/library/machine.I2C.rst | 154 |
1 files changed, 121 insertions, 33 deletions
diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index d04ef5eef5..a7e90ca39b 100644 --- a/docs/library/machine.I2C.rst +++ b/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. |