Skip to content

pyb.I2C.rst

Latest commit

 

History

History
165 lines (109 loc) · 5.9 KB

pyb.I2C.rst

File metadata and controls

165 lines (109 loc) · 5.9 KB
.. currentmodule:: pyb

class I2C -- a two-wire serial protocol

I2C is a two-wire protocol for communicating between devices. At the physical level it consists of 2 wires: SCL and SDA, the clock and data lines respectively.

I2C objects are created attached to a specific bus. They can be initialised when created, or initialised later on.

Example:

from pyb import I2C

i2c = I2C(1)                             # create on bus 1
i2c = I2C(1, I2C.CONTROLLER)             # create and init as a controller
i2c.init(I2C.CONTROLLER, baudrate=20000) # init as a controller
i2c.init(I2C.PERIPHERAL, addr=0x42)      # init as a peripheral with given address
i2c.deinit()                             # turn off the I2C unit

Printing the i2c object gives you information about its configuration.

The basic methods are send and recv:

i2c.send('abc')      # send 3 bytes
i2c.send(0x42)       # send a single byte, given by the number
data = i2c.recv(3)   # receive 3 bytes

To receive inplace, first create a bytearray:

data = bytearray(3)  # create a buffer
i2c.recv(data)       # receive 3 bytes, writing them into data

You can specify a timeout (in ms):

i2c.send(b'123', timeout=2000)   # timeout after 2 seconds

A controller must specify the recipient's address:

i2c.init(I2C.CONTROLLER)
i2c.send('123', 0x42)        # send 3 bytes to peripheral with address 0x42
i2c.send(b'456', addr=0x42)  # keyword for address

Master also has other methods:

i2c.is_ready(0x42)           # check if peripheral 0x42 is ready
i2c.scan()                   # scan for peripherals on the bus, returning
                             #   a list of valid addresses
i2c.mem_read(3, 0x42, 2)     # read 3 bytes from memory of peripheral 0x42,
                             #   starting at address 2 in the peripheral
i2c.mem_write('abc', 0x42, 2, timeout=1000) # write 'abc' (3 bytes) to memory of peripheral 0x42
                                            # starting at address 2 in the peripheral, timeout after 1 second

Constructors

Methods

.. method:: I2C.deinit()

   Turn off the I2C bus.


.. method:: I2C.init(mode, *, addr=0x12, baudrate=400000, gencall=False, dma=False)

  Initialise the I2C bus with the given parameters:

     - ``mode`` must be either ``I2C.CONTROLLER`` or ``I2C.PERIPHERAL``
     - ``addr`` is the 7-bit address (only sensible for a peripheral)
     - ``baudrate`` is the SCL clock rate (only sensible for a controller)
     - ``gencall`` is whether to support general call mode
     - ``dma`` is whether to allow the use of DMA for the I2C transfers (note
       that DMA transfers have more precise timing but currently do not handle bus
       errors properly)


.. method:: I2C.is_ready(addr)

   Check if an I2C device responds to the given address.  Only valid when in controller mode.


.. method:: I2C.mem_read(data, addr, memaddr, *, timeout=5000, addr_size=8)

   Read from the memory of an I2C device:

     - ``data`` can be an integer (number of bytes to read) or a buffer to read into
     - ``addr`` is the I2C device address
     - ``memaddr`` is the memory location within the I2C device
     - ``timeout`` is the timeout in milliseconds to wait for the read
     - ``addr_size`` selects width of memaddr: 8 or 16 bits

   Returns the read data.
   This is only valid in controller mode.


.. method:: I2C.mem_write(data, addr, memaddr, *, timeout=5000, addr_size=8)

   Write to the memory of an I2C device:

     - ``data`` can be an integer or a buffer to write from
     - ``addr`` is the I2C device address
     - ``memaddr`` is the memory location within the I2C device
     - ``timeout`` is the timeout in milliseconds to wait for the write
     - ``addr_size`` selects width of memaddr: 8 or 16 bits

   Returns ``None``.
   This is only valid in controller mode.


.. method:: I2C.recv(recv, addr=0x00, *, timeout=5000)

   Receive data on the bus:

     - ``recv`` can be an integer, which is the number of bytes to receive,
       or a mutable buffer, which will be filled with received bytes
     - ``addr`` is the address to receive from (only required in controller mode)
     - ``timeout`` is the timeout in milliseconds to wait for the receive

   Return value: if ``recv`` is an integer then a new buffer of the bytes received,
   otherwise the same buffer that was passed in to ``recv``.


.. method:: I2C.send(send, addr=0x00, *, timeout=5000)

   Send data on the bus:

     - ``send`` is the data to send (an integer to send, or a buffer object)
     - ``addr`` is the address to send to (only required in controller mode)
     - ``timeout`` is the timeout in milliseconds to wait for the send

   Return value: ``None``.


.. method:: I2C.scan()

   Scan all I2C addresses from 0x01 to 0x7f and return a list of those that respond.
   Only valid when in controller mode.

Constants

.. data:: I2C.CONTROLLER

   for initialising the bus to controller mode


.. data:: I2C.PERIPHERAL

   for initialising the bus to peripheral mode