I2C Controller¶

The PxI2CController class implements the functionality of an I2C Controller. It provides methods to write and read data to/from I2C devices.

PxI2CController ¶

PxI2CController(
    exerciser: AqProtocolExerciser,
    *args,
    config: PxI2CControllerConfig | None = None,
    **kwargs
)

An I2C controller device class.

This class provides a high-level interface to an I2C controller with base I2C fuctionality. It does not automatically create an actual instance on the Protocol Exerciser until user call the attach_to_bus method.

Typical usage example:

i2c_bus = PxI2CBus(exerciser_session)
i2c_controller = PxI2CController(exerciser_session)
i2c_controller.attach_to_bus(i2c_bus)

... # Do any operation from this controller

i2c_controller.detach_from_bus()

METHOD	DESCRIPTION
`i2c_write`	Perform a write operation to an I2C device.
`i2c_write_addr`	Perform a write operation to an I2C device with sub-address.
`i2c_read`	Perform a read operation from an I2C device.
`i2c_read_addr`	Perform a read operation from an I2C device with sub-address.
`writeto`	Write buffer contents to an I2C device (CircuitPython/MicroPython compat).
`readfrom`	Read bytes from an I2C device (CircuitPython/MicroPython compat).
`readfrom_into`	Read bytes from an I2C device into a buffer (CircuitPython/MicroPython compat).
`writevto`	Write concatenated buffers to an I2C device (MicroPython compat).
`writeto_then_readfrom`	Combine write-then-read (CircuitPython/MicroPython compat).
`readfrom_mem`	Read from device memory/register (MicroPython compat).
`readfrom_mem_into`	Read from device memory/register into a buffer (MicroPython compat).
`writeto_mem`	Write to device memory/register (MicroPython compat).
`add_event_handler`	Add an event handler to the current device instance, by event class or event name.
`remove_event_handler`	Remove an event handler from the current device instance, by event class or event name.
`get_event_handlers`	Retreive handlers registerd on this device.
`on_event`	Add an event handler to the instance by decorator, by event class or event name.
`match`	Return whether a device config describes a device of this class.
`update_additional_data`	Atomically update additional_data with revision-aware retry.
`update_config`	Set the config of the controller.
`set_config`	Set the config of the controller.
`attach_to_bus`	Attach the controller to a bus.
`detach_from_bus`	Detach the device from the bus.
`perform_operation`	Send an operation.
`send_i2c_transactions`	Send a sequence of I2C transactions.
`send_transactions`	Send a sequence of I2C transactions.
`scan`	Scan the I2C peripherals, returning a list of 7-bit addresses.
`i2c_scan_all`	Perform scan operation that scanning all available targets.

ATTRIBUTE	DESCRIPTION
`available_events_map`	Map each available event name to its id in event topics. TYPE: `dict[str, str]`
`is_attached`	Check if the device is attached to a bus. TYPE: `bool`
`state`	Get the state of the device. TYPE: `DeviceStateT \| None`
`name`	Get the name of the device. TYPE: `str`
`cts_op_name`	Get the name of CTS operation. TYPE: `str \| None`
`additional_data`	Get the opaque additional data blob associated with this device. TYPE: `bytes`
`config`	Get the config of the device. TYPE: `DeviceConfigT \| None`

available_events_map ¶

available_events_map: dict[str, str]

Map each available event name to its id in event topics.

is_attached ¶

is_attached: bool

Check if the device is attached to a bus.

state ¶

state: DeviceStateT | None

Get the state of the device.

name ¶

name: str

Get the name of the device.

cts_op_name ¶

cts_op_name: str | None

Get the name of CTS operation.

additional_data ¶

additional_data: bytes

Get the opaque additional data blob associated with this device.

config ¶

config: DeviceConfigT | None

Get the config of the device.

i2c_write ¶

i2c_write(address: int, data: list[int]) -> int | None

Perform a write operation to an I2C device.

This method sends data to an I2C device with a given address.

PARAMETER	DESCRIPTION
`address` ¶	The address of the I2C device to write to. TYPE: `int`
`data` ¶	The data to be written to the I2C device. TYPE: `list[int]`

RETURNS	DESCRIPTION
`int \| None`	The number of bytes written. Returns None if the target NACKs.

RAISES	DESCRIPTION
`ValueError`	`data` must be a list of integers within (0, 256).

i2c_write_addr ¶

i2c_write_addr(
    address: int, sub_address: int | list[int], data: list[int]
) -> int | None

Perform a write operation to an I2C device with sub-address.

This method sends data to an I2C device with a given address and sub_address.

PARAMETER	DESCRIPTION
`address` ¶	The address of the I2C device to write to. TYPE: `int`
`sub_address` ¶	The sub-address of the I2C device to write to. May be a single byte value or a list of bytes for multi-byte address phases. TYPE: `int \| list[int]`
`data` ¶	The data to be written to the I2C device. TYPE: `list[int]`

RETURNS	DESCRIPTION
`int \| None`	The number of bytes written. Returns None if the target NACKs.

RAISES	DESCRIPTION
`OverflowError`	If `sub_address` is an int not within (0, 256).
`ValueError`	If `sub_address` is an empty list or bytes are out of range.

i2c_read ¶

i2c_read(address: int, count: int) -> list[int]

Perform a read operation from an I2C device.

This method tries to read data from an I2C device with a given address. It may return less than count bytes if the target aborts the read operation early.

PARAMETER	DESCRIPTION
`address` ¶	The address of the I2C device to read from. TYPE: `int`
`count` ¶	The number of bytes to read from the I2C device. TYPE: `int`

RETURNS	DESCRIPTION
`list[int]`	The data read from the I2C device. Returns an empty list if the target NACKs.

RAISES	DESCRIPTION
`ValueError`	Cannot perform read operation with count less or equal to 0.

i2c_read_addr ¶

i2c_read_addr(address: int, sub_address: int | list[int], count: int) -> list[int]

Perform a read operation from an I2C device with sub-address.

This method tries to read data from an I2C device with a given address and sub_address. It may return an amount of data which is less than count if the target aborts the read operation earlier.

PARAMETER	DESCRIPTION
`address` ¶	The address of the I2C device to read from. TYPE: `int`
`sub_address` ¶	The sub-address of the I2C device to read from. May be a single byte value or a list of bytes for multi-byte address phases. TYPE: `int \| list[int]`
`count` ¶	The number of bytes to read from the I2C device. TYPE: `int`

RETURNS	DESCRIPTION
`list[int]`	The data read from the I2C device. Returns an empty list if the target NACKs.

RAISES	DESCRIPTION
`OverflowError`	If `sub_address` is an int not within (0, 256).
`ValueError`	If `sub_address` is an empty list or count is less or equal to 0.

writeto ¶

writeto(
    address: int,
    buf: bytes | bytearray | memoryview,
    *,
    start: int = 0,
    end: int | None = None,
    stop: bool = True
) -> int

Write buffer contents to an I2C device (CircuitPython/MicroPython compat).

readfrom ¶

readfrom(address: int, nbytes: int, *, stop: bool = True) -> bytes

Read bytes from an I2C device (CircuitPython/MicroPython compat).

readfrom_into ¶

readfrom_into(
    address: int,
    buf: bytearray | memoryview,
    *,
    start: int = 0,
    end: int | None = None,
    stop: bool = True
) -> None

Read bytes from an I2C device into a buffer (CircuitPython/MicroPython compat).

writevto ¶

writevto(
    address: int, vector: list[bytes | bytearray | memoryview], *, stop: bool = True
) -> int

Write concatenated buffers to an I2C device (MicroPython compat).

writeto_then_readfrom ¶

writeto_then_readfrom(
    address: int,
    write_buf: bytes | bytearray | memoryview,
    read_buf: bytearray | memoryview,
    *,
    write_start: int = 0,
    write_end: int | None = None,
    read_start: int = 0,
    read_end: int | None = None,
    stop: bool = False
) -> None

Combine write-then-read (CircuitPython/MicroPython compat).

readfrom_mem ¶

readfrom_mem(address: int, memaddr: int, nbytes: int, *, addrsize: int = 8) -> bytes

Read from device memory/register (MicroPython compat).

readfrom_mem_into ¶

readfrom_mem_into(
    address: int, memaddr: int, buf: bytearray | memoryview, *, addrsize: int = 8
) -> None

Read from device memory/register into a buffer (MicroPython compat).

writeto_mem ¶

writeto_mem(
    address: int,
    memaddr: int,
    buf: bytes | bytearray | memoryview,
    *,
    addrsize: int = 8
) -> None

Write to device memory/register (MicroPython compat).

add_event_handler ¶

add_event_handler(event: str, handler: Callable[[Any], Any]) -> None

add_event_handler(event: type[EventT], handler: Callable[[EventT], Any]) -> None

add_event_handler(
    event: str | type[PxAbstractEvent], handler: Callable[[Any], Any]
) -> None

Add an event handler to the current device instance, by event class or event name.

remove_event_handler ¶

remove_event_handler(
    event: str | type[PxAbstractEvent], handler: Callable[[Any], Any] | None = None
) -> None

Remove an event handler from the current device instance, by event class or event name.

get_event_handlers ¶

get_event_handlers(
    filter_by: Callable[[str], bool] | None = None,
) -> dict[str, list[Callable[[Any], Any]]]

Retreive handlers registerd on this device.

Handlers are always scoped to this device; an optional filter_by is applied on friendly event names.

on_event ¶

on_event(event_type: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]

on_event(
    event_type: type[EventT],
) -> Callable[[Callable[[EventT], Any]], Callable[[EventT], Any]]

on_event(
    event_type: str | type[PxAbstractEvent],
) -> Callable[[Callable[..., Any]], Callable[..., Any]]

Add an event handler to the instance by decorator, by event class or event name.

match ¶

match(config: PxAbstractDeviceConfig) -> bool

Return whether a device config describes a device of this class.

update_additional_data ¶

update_additional_data(updater: Callable[[bytes], bytes]) -> None

Atomically update additional_data with revision-aware retry.

update_config ¶

update_config(updater: Callable[[Any], Any]) -> None

Set the config of the controller.

set_config ¶

set_config(config: DeviceConfigT) -> None

Set the config of the controller.

attach_to_bus ¶

attach_to_bus(bus: PxAbstractBus) -> None

Attach the controller to a bus.

This method is used to make the device aware of the bus it is connected to. It is used to set the bus attribute of the device.

Note

This method will not automatically create an actual instance on the Protocol Exerciser until user call the attach_to_bus method.

PARAMETER	DESCRIPTION
`bus` ¶	The bus to attach the device to TYPE: `PxAbstractBus`

RAISES	DESCRIPTION
`ValueError`	If the device is already attached to a bus

detach_from_bus ¶

detach_from_bus() -> None

Detach the device from the bus.

The opposite of the attach_to_bus method.

perform_operation ¶

perform_operation(
    operation: PxDeviceOperation, *, timeout: int | None = None
) -> PxDeviceOperation

Send an operation.

PARAMETER	DESCRIPTION
`operation` ¶	Device operation to perform. TYPE: `PxDeviceOperation`
`timeout` ¶	Optional base STOP-handshake wait in milliseconds. When omitted, the instrument uses subsystem defaults. TYPE: `int \| None` DEFAULT: `None`

send_i2c_transactions ¶

send_i2c_transactions(
    transactions: list[I2CTransaction], *, timeout: int | None = None
) -> list[I2CTransaction]

Send a sequence of I2C transactions.

This method enqueue a sequence of I2C transactions to be sent to the I2C bus, starting from a START pattern end with STOP. Each element in transactions is an pxmsg.I2CTransaction object, which contains one of the supported transaction type listed below:

pxmsg.I2CWriteTransaction
pxmsg.I2CReadTransaction

The transactions are sent in the order they are provided.

PARAMETER	DESCRIPTION
`transactions` ¶	A list of `pxmsg.I2CTransaction` objects to be sent. TYPE: `list[I2CTransaction]`
`timeout` ¶	Optional base STOP-handshake wait in milliseconds. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`PxError`	If the transaction fails. TYPE: `list[I2CTransaction]`

send_transactions ¶

send_transactions(
    transactions: list[I2CTransaction], *, timeout: int | None = None
) -> list[I2CTransaction]

Send a sequence of I2C transactions.

Alias for :meth:send_i2c_transactions.

scan ¶

scan() -> list[int]

Scan the I2C peripherals, returning a list of 7-bit addresses.

Compatible with CircuitPython/MicroPython methods.

RETURNS	DESCRIPTION
`list[int]`	Sorted list of 7-bit addresses that ACK an empty write.

i2c_scan_all ¶

i2c_scan_all() -> list[bool]

Perform scan operation that scanning all available targets.

This method scan all the available targets by sending write to all the targets. Then check each target return ACK or NACK, and set the corresponding element in returned list.

RETURNS	DESCRIPTION
`list[bool]`	The list contains the ACK or NACK. Can check whether the target was available by taking the address as index to access the list.

I2C Controller¶

PxI2CController ¶

available_events_map ¶

is_attached ¶

state ¶

name ¶

cts_op_name ¶

additional_data ¶

config ¶

i2c_write ¶

address ¶

data ¶

i2c_write_addr ¶

address ¶

sub_address ¶

data ¶

i2c_read ¶

address ¶

count ¶

i2c_read_addr ¶

address ¶

sub_address ¶

count ¶

writeto ¶

readfrom ¶

readfrom_into ¶

writevto ¶

writeto_then_readfrom ¶

readfrom_mem ¶

readfrom_mem_into ¶

writeto_mem ¶

add_event_handler ¶

remove_event_handler ¶

get_event_handlers ¶

on_event ¶

match ¶

update_additional_data ¶

update_config ¶

set_config ¶

attach_to_bus ¶

bus ¶

detach_from_bus ¶

perform_operation ¶

operation ¶

timeout ¶

send_i2c_transactions ¶

transactions ¶

timeout ¶

send_transactions ¶

scan ¶

i2c_scan_all ¶

`address` ¶

`data` ¶

`address` ¶

`sub_address` ¶

`data` ¶

`address` ¶

`count` ¶

`address` ¶

`sub_address` ¶

`count` ¶

`bus` ¶

`operation` ¶

`timeout` ¶

`transactions` ¶

`timeout` ¶