I2C devices¶

On the program side, machine.I2C makes the microcontroller the master of a real electrical I2C bus: it generates the clock on SCL and exchanges data on SDA (API). Peripherals provides three slave devices to connect to this bus. Their behaviour is always described by a Python script. Another MCU can also be the slave, with machine.I2CTarget (API, examples MultiMcu.I2c and MultiMcu.I2cIrq).

SCL and SDA lines of the I2c.Echo example: START, address byte, slave acknowledge, then first data byte. Figure labels are in French: « temps » = time, « adresse 0x42 + écriture » = address 0x42 + write.

Wiring¶

Two wires shared by every bus member, plus ground:

from machine import Pin, I2C

i2c = I2C(0, scl=Pin(4), sda=Pin(5), freq=100000)
print(i2c.scan())                    # addresses present, e.g. [66]
i2c.writeto(0x42, b'Hello')
print(i2c.readfrom(0x42, 5))

The bus is open-drain: each member can only pull a line low or release it, and pull-up resistors bring the lines back up. At least one device on the bus must carry these resistors (usePullUp = true). I2C() does switch on the internal pull-ups of the microcontroller on SCL and SDA, as on the Pico, but 50 kΩ against the input capacitances of the devices is far too slow: a released line has no time to rise, and every transaction raises OSError(ETIMEDOUT), as on a board where the resistors were forgotten (I2c.NoPullUp example). The Grove display carries them by default, like the real module.

Any number of devices can share the two wires; each one only answers its own addresses (I2c.MultiDevice example).

Supplied devices¶

Default scripts live in Resources/Scripts/Device/.

The Grove LCD RGB display¶

The real module carries two chips, hence two addresses for a single component; the script emulates them from their datasheets:

• JHD1313 (0x3E, HD44780-compatible display controller): clear, home, write position, display on or off, shift. The display is off at power-up, like the real one: the driver must switch it on.
• PCA9633 (0x62, backlight driver): red, green, blue intensities.

The icon shows both lines and takes the backlight colour while replaying the result. valueOut returns (red, green, blue, display on), intensities from 0 to 255.

The I2c.GroveLcd example drives this display with an off-the-shelf MicroPython driver, run unmodified: driver_grove_lcd_rgb.py, placed next to the program that imports it.

Connectors¶

On the program side, the bus is written with machine.I2C (controller) or machine.I2CTarget (target): see the API and the official MicroPython documentation (machine.I2C, machine.I2CTarget, rp2 port).

Parameters¶

Bus and behaviour (General tab)¶

Inputs / outputs (Inputs / outputs tab)¶

Electrical (Electrical tab)¶

Writing a device script¶

The script only sees transactions: no bits, no START/STOP, no acknowledges. Four functions, all optional:

registers = bytearray(16)
pointer = 0

def on_write(addr, data, t, v):     # the master has just written data (bytes, never empty)
    global pointer
    pointer = data[0] % 16
    for byte in data[1:]:
        registers[pointer] = byte
        pointer = (pointer + 1) % 16

def on_read(addr, t, v):            # the master starts reading
    return bytes(registers[pointer:])    # bytes, str, list of ints or int

def outputs():                      # read after each call -> valueOut
    return registers[0]

def lines():                        # read after each call -> two lines of text (displays)
    return ('line 1', 'line 2')

addr lets a component with several addresses know which chip is being addressed. Same rules as for serial devices: a script loaded once per component, variables that persist from one call to the next, no waiting nor access to machine, print() in the log, simulation stopped on exception.

To create a new device: copy Resources/Scripts/Device/i2c_generic.py and select it in an I2cGenericDevice.

Variables to plot¶

Examples¶