i2cioexpander – Support for I2C-based GPIO expanders

The i2cioexpander module contains classes to support I2C-based GPIO expanders that can be controlled via simple register reads and writes.

All classes change hardware state and should be deinitialized when they are no longer needed if the program continues after use. To do so, either call deinit() or use a context manager. See Lifetime and ContextManagers for more info.

Example:

import board
import busio
import i2cioexpander

i2c = busio.I2C(board.SCL, board.SDA)
expander = i2cioexpander.IOExpander(i2c, 0x20, 8, 0x01, 0x00, 0x03)
pin0 = expander.pins[0]
pin0.switch_to_output(value=True)

Available on these boards
  • Yoto Mini 2024
  • Yoto Player V3

class i2cioexpander.IOExpander(i2c: busio.I2C, address: int, num_pins: int, set_value_reg: int | None = None, get_value_reg: int | None = None, set_direction_reg: int | None = None)

Control a generic I2C-based GPIO expander

IOExpander provides a simple interface to I2C-based GPIO expanders that use basic register reads and writes for control. The expander provides individual pins through the pins attribute that implement the DigitalInOutProtocol.

Initialize an I2C GPIO expander

Parameters:
  • i2c (busio.I2C) – The I2C bus the expander is connected to

  • address (int) – The I2C device address

  • num_pins (int) – The number of GPIO pins (8 or 16)

  • set_value_reg (int) – Register address to write pin values (optional)

  • get_value_reg (int) – Register address to read pin values (optional)

  • set_direction_reg (int) – Register address to set pin directions (optional)

deinit() → None

Deinitialize the expander. No further operations are possible.

__enter__() → IOExpander

No-op used by Context Managers.

__exit__() → None

Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.

property input_value: int

Read the live value of all pins at once. Returns an integer where each bit represents a pin’s current state.

property output_value: int

Get or set the cached output value. Reading returns the last value written, not the live pin state. Writing updates the output pins.

property output_mask: int

Get or set which pins are configured as outputs. Each bit in the mask represents a pin: 1 for output, 0 for input.

property pins: Tuple[IOPin, ...]

A tuple of IOPin objects that implement the DigitalInOutProtocol. Each pin can be used like a digitalio.DigitalInOut object.

class i2cioexpander.IOPin

Control a single pin on an IOExpander in the same way as DigitalInOut.

Not constructed directly. Get from IOExpander.pins instead.

switch_to_output(value: bool = False, drive_mode: digitalio.DriveMode = digitalio.DriveMode.PUSH_PULL) → None

Set the drive mode and value and then switch to writing out digital values.

Parameters:
  • value (bool) – default value to set upon switching

  • drive_mode (digitalio.DriveMode) – drive mode for the output

switch_to_input(pull: digitalio.Pull | None = None) → None

Set the pull and then switch to read in digital values.

Parameters:

pull (digitalio.Pull) – pull configuration for the input

direction: digitalio.Direction

The direction of the pin.

value: bool

The digital logic level of the pin.

drive_mode: digitalio.DriveMode

The pin drive mode.

pull: digitalio.Pull | None

The pin pull direction.