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: I2CControllerConfig | 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
add_event_handler	Add an event handler to the current device instance.
attach_to_bus	Attach the controller to a bus.
config	Set the config of the controller.
detach_from_bus	Detach the device from the bus.
get_event_handlers	Retreive handlers registerd on this device.
i2c_read	Perform a read operation from an I2C device.
i2c_read_addr	Perform a read operation from an I2C device with sub-address.
i2c_scan_all	Perform scan operation that scanning all available targets.
i2c_write	Perform a write opteration to an I2C device.
i2c_write_addr	Perform a write operation to an I2C device with sub-address.
on_event	Add an event handler to the instance by decorator.
perform_operation	Send an operation.
remove_event_handler	Remove an event handler.
send_transactions	Send a sequence of I2C transactions.

ATTRIBUTE	DESCRIPTION
available_events_map	A reverse mapping of field_name_by_number, which uses field name as key. TYPE: dict[str, str]
is_attached	Check if the device is attached to a bus. TYPE: bool
name	Get the name of the device. TYPE: str
state	Get the state of the device. TYPE: Message | None

available_events_map

available_events_map: dict[str, str]

A reverse mapping of field_name_by_number, which uses field name as key.

is_attached

is_attached: bool

Check if the device is attached to a bus.

name

name: str

Get the name of the device.

state

state: Message | None

Get the state of the device.

add_event_handler

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

Add an event handler to the current device instance.

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

config

config(config: Message) -> None

Set the config of the controller.

detach_from_bus

detach_from_bus() -> None

Detach the device from the bus.

The opposite of the attach_to_bus method.

get_event_handlers

get_event_handlers() -> dict[str, Callable]

Retreive handlers registerd on this device.

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 abort 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 0.

i2c_read_addr

i2c_read_addr(address: int, sub_address: 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. TYPE: int
count	The numebr of bytes to read from the I2C device. TYPE: int

Retunrs

The data read from I2C device. Returns None if the target NACKs.

RAISES	DESCRIPTION
OverflowError	If the sub_address is not within (0, 256).

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_write

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

Perform a write opteration 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, 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. 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
OverflowError	If the sub_address is not within (0, 256).
ValueError	bytes must be in range(0, 256)

on_event

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

Add an event handler to the instance by decorator.

perform_operation

perform_operation(operation: PxDeviceOperation) -> PxDeviceOperation

Send an operation.

remove_event_handler

remove_event_handler(event: str) -> None

Remove an event handler.

send_transactions

send_transactions(transactions: list[I2CTransaction]) -> 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]

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