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

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`
`state`	Get the state of the device. TYPE: `Message \| None`
`name`	Get the name of the device. TYPE: `str`
`cts_op_name`	Get the name of CTS operation. TYPE: `str \| 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.

state ¶

state: Message | 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.

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.

add_event_handler ¶

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

Add an event handler to the current device instance.

remove_event_handler ¶

remove_event_handler(event: str) -> None

Remove an event handler.

get_event_handlers ¶

get_event_handlers() -> dict[str, Callable]

Retreive handlers registerd on this device.

on_event ¶

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

Add an event handler to the instance by decorator.

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.

perform_operation ¶

perform_operation(operation: PxDeviceOperation) -> PxDeviceOperation

Send an operation.

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

send_i2c_transactions ¶

send_i2c_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]`

send_transactions ¶

send_transactions(transactions: list[I2CTransaction]) -> list[I2CTransaction]

Send a sequence of I2C transactions.

Alias for :meth:send_i2c_transactions.

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 ¶

i2c_write ¶

`address` ¶

`data` ¶

i2c_write_addr ¶

`address` ¶

`sub_address` ¶

`data` ¶

i2c_read ¶

`address` ¶

`count` ¶

i2c_read_addr ¶

`address` ¶

`sub_address` ¶

`count` ¶

add_event_handler ¶

remove_event_handler ¶

get_event_handlers ¶

on_event ¶

config ¶

detach_from_bus ¶

perform_operation ¶

attach_to_bus ¶

`bus` ¶

send_i2c_transactions ¶

`transactions` ¶

send_transactions ¶

i2c_scan_all ¶

I2C Controller¶

PxI2CController ¶

available_events_map ¶

is_attached ¶

state ¶

name ¶

cts_op_name ¶

i2c_write ¶

address ¶

data ¶

i2c_write_addr ¶

address ¶

sub_address ¶

data ¶

i2c_read ¶

address ¶

count ¶

i2c_read_addr ¶

address ¶

sub_address ¶

count ¶

add_event_handler ¶

remove_event_handler ¶

get_event_handlers ¶

on_event ¶

config ¶

detach_from_bus ¶

perform_operation ¶

attach_to_bus ¶

bus ¶

send_i2c_transactions ¶

transactions ¶

send_transactions ¶

i2c_scan_all ¶

`address` ¶

`data` ¶

`address` ¶

`sub_address` ¶

`data` ¶

`address` ¶

`count` ¶

`address` ¶

`sub_address` ¶

`count` ¶

`bus` ¶

`transactions` ¶