class I2C – a two-wire serial protocol

I2C is a two-wire protocol for communicating between devices. At the physical level it consists of two lines, SCL (clock) and SDA (data). The OpenMV Cam does not provide on-board pull-ups on either line – external pull-ups are required on both SCL and SDA for the bus to function.

I2C objects are attached to a specific bus and may be initialised at construction time or later via init().

Example:

from pyb import I2C

i2c = I2C(2)                              # create on bus 2 (uninitialised)
i2c = I2C(2, 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 the given address
i2c.deinit()                              # turn off the peripheral

Printing the I2C object shows 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 in place, 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

A controller also has these methods:

# Check if peripheral 0x42 is ready.
i2c.is_ready(0x42)

# Scan the bus and return a list of responding addresses.
i2c.scan()

# Read 3 bytes from peripheral 0x42 starting at memaddr 2.
i2c.mem_read(3, 0x42, 2)

# Write 3 bytes to peripheral 0x42 at memaddr 2.
i2c.mem_write("abc", 0x42, 2, timeout=1000)

Constructors

class pyb.I2C(bus: int | str, *args, **kwargs)

Construct an I2C object on the given bus (an integer peripheral index, e.g. 2 for I2C2). With no additional parameters the object is created but not initialised (it retains the previous bus settings, if any); if extra arguments are given the bus is initialised. See init() for the available parameters.

I2C(2) is wired to the same header pins on every OpenMV Cam that exposes pyb.I2C (M4 / M7 / H7 / H7 Plus / Pure Thermal):

Signal

Header pin

Notes

SCL

P4

SDA

P5

I2C(4) is additionally available on the OpenMV Cam M7, H7, H7 Plus and Pure Thermal with SCL on header pin P7 and SDA on header pin P8.

The OpenMV Cam N6 does not expose pyb.I2C; use machine.I2C instead.

Methods

deinit() → None

Turn off the I2C bus.

init(mode: int, *, addr: int = 0x12, baudrate: int = 400000, gencall: bool = False, dma: bool = False) → None

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).

The actual clock frequency may be lower than the requested frequency. This is dependent on the platform hardware. The actual rate may be determined by printing the I2C object.

is_ready(addr: int) → bool

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

mem_read(data: int | bytearray, addr: int, memaddr: int, *, timeout: int = 5000, addr_size: int = 8) → bytes

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.

mem_write(data: int | bytes | bytearray, addr: int, memaddr: int, *, timeout: int = 5000, addr_size: int = 8) → None

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.

Only valid in controller mode.

recv(recv: int | bytearray, addr: int = 0x00, *, timeout: int = 5000) → bytes

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.

send(send: int | bytes | bytearray, addr: int = 0x00, *, timeout: int = 5000) → None

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.

scan() → List[int]

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

Constants

CONTROLLER: int

Initialises the bus as the master (controller) – it drives SCL and initiates transactions.

PERIPHERAL: int

Initialises the bus as a slave (peripheral) that listens on the addr set in init() and responds to transactions started by a controller on the same bus.