I3C API

This page aggregates all C++ I3C-related public methods of the class CosmicSDK.

Note

I3C protocol support, and therefore this I3C API, is available only on the Binho Supernova. The Binho Pulsar does not support I3C.

group CosmicSDK I3C API

Constants and APIs related to I3C operations.

Functions

uint16_t i3cSetBusVoltage(uint16_t voltage_mV)

Set the I3C bus supply voltage (VTARG).

Configures the output voltage applied to the I3C bus through the Supernova VTARG pin.

Setting the voltage to 0 mV disables the VTARG output and powers off the downstream devices connected to the I3C bus.

This function controls the physical bus supply and does not perform any I3C protocol transaction.

Note

Ensure the selected voltage is compatible with all connected devices.
Disabling VTARG (0 mV) may reset or power down all downstream targets.

Parameters:

voltage_mV – Voltage in millivolts to set the I3C bus to. Valid values are 0 mV or any value between 800 mV and 3300 mV.

Return values:

SUCCESS – The bus voltage was successfully configured.
FW_VOLTAGE_OUT_OF_RANGE – The requested voltage value is outside the supported range.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cControllerInit(I3cPushPullRate pushPullFrequency, I3cOpenDrainTransferRate openDrainFrequency, I2cTransferRate i2cOpenDrainFrequency, I3cDriveStrength driveStrength)

Initializes the I3C controller.

This function initializes the I3C peripheral and must be called successfully before any other I3C-related API is used.

Note

This function must be called exactly once.
Calling any I3C API before initialization will result in FW_INTERFACE_NOT_INITIALIZED.
Calling this function more than once will result in FW_INTERFACE_ALREADY_INITIALIZED.
To modify the I3C configuration after initialization, use i3cSetParameters instead of reinitializing the interface.

Parameters:

pushPullFrequency – The I3C SCL frequency in the push-pull phase. See I3cPushPullRate for supported values.
openDrainFrequency – The I3C SCL frequency in the open-drain phase. See I3cOpenDrainTransferRate for supported values.
i2cOpenDrainFrequency – The I2C SCL open drain frequency. See I2cTransferRate for supported values.
driveStrength – The drive strength configuration for the I3C pads. See I3cDriveStrength for supported values.

Return values:

SUCCESS – I3C interphase was successfully initialized.
FW_INTERFACE_ALREADY_INITIALIZED – The I3C interface has already been initialized.
FW_INVALID_PARAMETER – One or more configuration parameters are invalid or unsupported.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cSetParameters(I3cPushPullRate pushPullFrequency, I3cOpenDrainTransferRate openDrainFrequency, I2cTransferRate i2cOpenDrainFrequency, I3cDriveStrength driveStrength)

Sets the I3C bus parameters.

This function updates the I3C bus parameters after the I3C interface has been successfully initialized using i3cControllerInit. It allows runtime reconfiguration of the I3C without requiring a full deinitialization or reinitialization of the peripheral.

Note

This function must only be called after a successful call to i3cControllerInit.
Calling this function before UART initialization will result in FW_INTERFACE_NOT_INITIALIZED.

Parameters:

pushPullFrequency – The I3C SCL frequency in the push-pull phase. See I3cPushPullRate for supported values.
openDrainFrequency – The I3C SCL frequency in the open-drain phase. See I3cOpenDrainTransferRate for supported values.
i2cOpenDrainFrequency – The I2C SCL open drain frequency. See I2cTransferRate for supported values.
driveStrength – The drive strength configuration for the I3C pads. See I3cDriveStrength for supported values.

Return values:

SUCCESS – I3C parameters were successfully updated.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_INVALID_PARAMETER – One or more configuration parameters are invalid or unsupported.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cInitBus(std::vector<I3cTargetInfo> targets = {})

Initializes the I3C bus.

By default, the Supernova acting as the controller issues the RSTDAA followed by the ENTDAA CCCs to discover I3C targets on the bus and automatically assign dynamic addresses.

Optionally, a table of target devices can be provided to control the bus initialization process. When the targets parameter is provided, the controller uses this information to:

Assign a specific dynamic address to a known I3C target.
Register legacy I2C devices on the bus, which do not respond to the ENTDAA CCC.

This allows mixed I3C/I2C buses to be initialized correctly and enables deterministic dynamic address assignment for selected targets.

If targets is empty, the controller relies solely on the standard I3C discovery mechanism (RSTDAA + ENTDAA) and only I3C targets responding to ENTDAA will be detected.

Note

This function must be called exactly once.
Calling any I3C API before initialization will result in FW_INTERFACE_NOT_INITIALIZED.
Calling this function more than once will result in FW_INTERFACE_ALREADY_INITIALIZED.
To modify the I3C configuration after initialization, use i3cSetParameters instead of reinitializing the interface.

Parameters:

targets – A vector containing information about the target devices connected to the I3C bus. See I3cTargetInfo for valid table entry format.

Return values:

SUCCESS – I3C bus was successfully initialized.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_NOT_ENOUGH_SPACE_IN_TARGET_DEVICES_TABLE – The number of targets to be initialized surpassed the maximum allowed number of targets (11).
FW_INVALID_TARGET_ADDRESS – The address of one of the target devices is a reserved address.
FW_I3C_BUS_INIT_NACK_RSTDAA – One or more targets did not acknowledge the RSTDAA CCC during bus initialization.
FW_I3C_BUS_INIT_NACK_SETDASA – A target did not acknowledge the SETDASA CCC when assigning a dynamic address.
FW_I3C_BUS_INIT_NACK_SETAASA – A target did not acknowledge the SETAASA CCC when assigning a dynamic address.
FW_I3C_BUS_INIT_NACK_ENTDAA – One or more targets did not acknowledge or complete the ENTDAA CCC.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus during initialization.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cResetBus()

Resets the I3C bus.

Issue the RSTDAA CCC and clear the target device table.

Return values:

SUCCESS – I3C bus was successfully resetted.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus during the reset.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cGetDeviceTable(std::vector<I3cTargetInfo> &targets)

Get the target device table stored internally in the Supernova.

Retrieves the current I3C target device table maintained internally by the Supernova firmware.

The table contains information about the targets discovered or configured on the I3C bus, such as dynamic address, static address (if available), PID (if retrieved), and other relevant attributes.

This function does not perform any bus transaction. It only queries the internal device table maintained by the firmware.

Note

The returned table reflects the current internal state of the Supernova.
The content of the table depends on previous operations such as ENTDAA, SETDASA, SETAASA, GETPID, etc.

Parameters:

targets – The list of targets on the I3C bus See I3cTargetInfo for table entry format.

Return values:

SUCCESS – I3C device table successfully returned.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cSetTargetDeviceConfiguration(uint8_t address, I3cTargetConfiguration targetConfiguration)

Changes de configuration of an I3C target given by a dictionary containing the new target configuration.

Updates the configuration of a target device stored in the Supernova’s internal I3C device table.

Note

The target must exist in the internal device table prior to calling this function.

Parameters:

address – Target address whose configuration will be set.
targetConfiguration – A dictionary containing the new configuration.

Return values:

SUCCESS – I3C target device configuration updated.
FW_TARGET_ADDRESS_NOT_FOUND_IN_THE_TABLE – The Supernova’s stored target device table does not have the requested target address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cLegacyI2cWrite(uint8_t address, const std::vector<uint8_t> &subAddress, const std::vector<uint8_t> &inData, I3cTransferFlags flags)

Performs a write transfer in Legacy I2C mode.

Writes data to an I2C target in Legacy I2C mode over the I3C bus. This function issues a standard I2C write transaction (Legacy I2C mode), optionally including an internal subaddress on the target device. The transfer may also begin with a broadcast address (0x7E) if required by the higher-level protocol being implemented.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

address – The static address of the I2C target.
subAddress – The optional sub-address to write to. The maximum size is 4 bytes.
inData – The data to be written to the device.
flags – Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can be combined using bitwise OR. See I3cTransferFlags for supported values.

Return values:

SUCCESS – I3C data was successfully sent.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_I2C_NACK_BYTE – The I2C target NACKed the write data, terminating the message.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cLegacyI2cRead(uint8_t address, const std::vector<uint8_t> &subAddress, uint16_t readLength, std::vector<uint8_t> &outData, I3cTransferFlags flags)

Performs a read transfer in Legacy I2C mode.

Reads data from an I2C target in Legacy I2C mode over the I3C bus. This function performs a standard I2C read operation (Legacy I2C mode). Optionally, a subaddress may be written first to select a register or memory location prior to performing the read.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

address – The static address of the I2C target.
subAddress – The optional sub-address to write to. The maximum size is 4 bytes.
readLength – The length of data to be read.
outData – The buffer to store the read data.
flags – Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can be combined using bitwise OR. See I3cTransferFlags for supported values.

Return values:

SUCCESS – I3C data was successfully read.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_I2C_NACK_BYTE – The I2C target NACKed the data.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cSdrWrite(uint8_t address, const std::vector<uint8_t> &subAddress, const std::vector<uint8_t> &inData, I3cTransferFlags flags)

Performs an I3C write in SDR mode.

Writes data to an I3C device or to a group of I3C targets through an I3C Private Transfer in SDR mode. Optionally, the internal subaddress of the target memory where the data is written to can be set, especially when writing to a single target.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

address – The dynamic address of the I3C target, or the group address.
subAddress – The optional sub-address to write to. The maximum size is 4 bytes.
inData – The data to be written to the device.
flags – Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can be combined using bitwise OR. See I3cTransferFlags for supported values.

Return values:

SUCCESS – I3C data was successfully sent.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cSdrRead(uint8_t address, const std::vector<uint8_t> &subAddress, uint16_t readLength, std::vector<uint8_t> &outData, I3cTransferFlags flags)

Performs an I3C read in SDR mode.

Reads data from an I3C target through an I3C Private Read transfer in SDR mode. Optionally, the internal subaddress of the target where the data is read from can be also set.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

address – The dynamic address of the I3C target.
subAddress – The optional sub-address to write to. The maximum size is 4 bytes.
readLength – The length of data to be read.
outData – The buffer to store the read data.
flags – Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can be combined using bitwise OR. See I3cTransferFlags for supported values.

Return values:

SUCCESS – I3C data was successfully read.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cHdrDdrWrite(uint8_t address, uint8_t command, const std::vector<uint8_t> &inData)

Performs an I3C write in HDR-DDR mode.

Writes data to an I3C target using an HDR-DDR Private Transfer. If the bus is currently operating in SDR mode, this function will automatically issue the ENTHDR0 CCC before starting the HDR-DDR transfer.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

address – The dynamic address of the I3C target.
command – The HDR-DDR command byte. Must be in the range [0x00, 0x7F].
inData – The data payload to be written. The payload length must be a multiple of 2.

Return values:

SUCCESS – I3C data was successfully sent.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cHdrDdrRead(uint8_t address, uint8_t command, uint16_t readLength, std::vector<uint8_t> &outData)

Performs an I3C read in HDR-DDR mode.

Reads data from an I3C target using an HDR-DDR Private Read Transfer. If the bus is currently operating in SDR mode, this function will automatically issue the ENTHDR0 CCC before starting the HDR-DDR transfer.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

address – The dynamic address of the I3C target.
command – The HDR-DDR command byte. Must be in the range [0x80, 0xFF].
readLength – The length of the data to read. Must be a multiple of 2.
outData – The buffer where the received data will be stored.

Return values:

SUCCESS – I3C data was successfully read.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cTargetResetPattern()

Emit the Target Reset Pattern to trigger the default or configured reset action on the I3C targets.

Emits the I3C Target Reset Pattern on the bus.

All targets that recognize the Target Reset Pattern and support reset functionality will perform the corresponding reset action.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
The reset action executed depends on the most recent RSTACT configuration, or the default reset behavior if none was configured.

Return values:

SUCCESS – I3C Target Reset Pattern emmitted successfully.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cHdrExitPattern()

Issue the HDR Exit Pattern to leave the current HDR mode and exit back to SDR mode.

Emits the I3C HDR Exit Pattern on the bus.

This pattern terminates the current High Data Rate (HDR) mode and forces all participating devices to return to Standard Data Rate (SDR) mode, as defined by the I3C specification.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
It must be issued while the bus is operating in HDR mode.

Return values:

SUCCESS – I3C Exit Pattern issued successfully.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccRSTDAA()

Emit the RSTDAA CCC and reset all dynamic addresses assigned on the bus.

Sends the RSTDAA (Reset Dynamic Address Assignment) Common Command Code (CCC) in broadcast mode.

Unlike the i3cResetBus method, the target device table is not cleared. After successful completion, the SDK updates the internal target device table by clearing only the stored dynamic addresses of all entries. The device information remains present in the table, allowing a new Dynamic Address Assignment (DAA) procedure to be performed without losing device metadata.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
After issuing RSTDAA, a new Dynamic Address Assignment (DAA) procedure must be executed before communicating with targets using dynamic addresses.

Return values:

SUCCESS – RSTDAA was successfully sent.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccENTDAA()

Enter Dynamic Address Assignment procedure (ENTDAA).

Sends the ENTDAA (Enter Dynamic Address Assignment) Common Command Code (CCC) in broadcast mode to initiate the Dynamic Address Assignment (DAA) procedure.

All unaddressed I3C targets participate in the arbitration process and are sequentially assigned a unique dynamic address by the controller.

During the procedure, each discovered target is identified and added to the internal target device table together with its assigned dynamic address and associated device information.

The procedure continues until no additional targets respond or the maximum number of supported targets is reached.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Return values:

SUCCESS – The Dynamic Address Assignment procedure completed successfully.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_TARGET_DEVICES_TABLE_OVERFLOW – The number of targets answered to the ENTDAA is greater than the maximum allowed number of targets (11).
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccSETDASA(uint8_t staticAddress, uint8_t dynamicAddress)

Assign a Dynamic Address to a target using its Static Address (SETDASA CCC).

Sends the SETDASA (Set Dynamic Address from Static Address) Common Command Code (CCC) in direct mode to the target identified by its static address.

The target device at staticAddress is instructed to adopt the specified dynamicAddress. Upon successful completion and acknowledgment by the target, the SDK adds a new entry to the internal target device table containing the assigned dynamic address and associated device information.

Prior to issuing the CCC, the SDK validates that:

The requested dynamic address is not reserved.
The dynamic address is not already in use by another target.
There is available space in the internal target device table.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

staticAddress – Static address of the target device.
dynamicAddress – Dynamic address to assign to the target.

Return values:

SUCCESS – The dynamic address was successfully assigned and the device was added to the target device table.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_NOT_ENOUGH_SPACE_IN_TARGET_DEVICES_TABLE – The number of targets on the table is already the maximum allowed number of targets (11).
FW_INVALID_TARGET_ADDRESS – The dynamic address to be assigned is a reserved address.
FW_REPEATED_TARGET_ADDRESS – The dynamic address to be set is already used by a target on the bus.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccSETAASA(const std::vector<uint8_t> &staticAddresses)

Set static address as dynamic address (SETAASA CCC).

Sends the SETAASA (Set All Addresses to Static Address) Common Command Code (CCC) in broadcast mode.

Targets that support the SETAASA CCC adopt their own static address as their dynamic address.

The staticAddresses parameter specifies the static addresses of the targets expected to process this command. After successful completion, the SDK adds a new entry to the internal target device table for each responding device, using its static address as its dynamic address.

Prior to issuing the CCC, the SDK validates that:

None of the provided addresses are reserved.
There is sufficient space in the internal target device table to accommodate all new devices.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
Only targets that support the SETAASA CCC will respond and adopt their static address as dynamic.

Parameters:

staticAddresses – Array of static addresses of those I3C targets that support SETAASA CCC. If the SETAASA CCC ends successfully, new devices are added to the target device table.

Return values:

SUCCESS – The CCC was successfully sent and the responding targets were added to the device table using their static address as dynamic address.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_NOT_ENOUGH_SPACE_IN_TARGET_DEVICES_TABLE – The number of targets on the table plus the number of targets on staticAddresses is greater than the maximum allowed number of targets (11).
FW_INVALID_TARGET_ADDRESS – One or more addresses are reserved addresses.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccSETNEWDA(uint8_t oldDynamicAddress, uint8_t newDynamicAddress)

Set a new Dynamic Address for a target by issuing the SETNEWDA CCC.

Sends the SETNEWDA (Set New Dynamic Address) Common Command Code (CCC) in direct mode to the specified target.

The target identified by oldDynamicAddress is instructed to change its dynamic address to newDynamicAddress.

If the command completes successfully and is acknowledged by the target, the SDK updates the internal target device table by replacing the stored dynamic address with the new value.

Validation of newDynamicAddress is performed before issuing the CCC to ensure that it is not a reserved address and that it is not already assigned to another target on the bus.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

oldDynamicAddress – The dynamic address of the target.
newDynamicAddress – The new dynamic address for the target.

Return values:

SUCCESS – The dynamic address was successfully updated on the target and in the device table.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_INVALID_TARGET_ADDRESS – The dynamic address to be assigned is a reserved address.
FW_REPEATED_TARGET_ADDRESS – The dynamic address to be set is already used by a target on the bus.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccGETPID(uint8_t address, std::vector<uint8_t> &pid)

Gets the PID of one target.

Sends the GETPID Common Command Code (CCC) in direct read mode to the specified I3C target.

If the transfer completes successfully, the the corresponding entry in the internal target device table is updated with the retrieved PID value.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

address – The dynamic address of the target device.
pid – Vector where the retrieved Provisional ID will be stored.

Return values:

SUCCESS – Target PID was successfully gotten.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccGETBCR(uint8_t address, uint8_t &bcr)

Get the Bus Characteristic Register (BCR) value of the target.

Sends the GETBCR (Get Bus Characteristic Register) Common Command Code (CCC) in direct mode to the specified I3C target.

The controller reads the BCR value from the addressed target and stores the result in bcr. If the operation completes successfully, the internal target device table is updated with the retrieved BCR value to keep the software representation synchronized with the device state.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
The output parameter bcr is updated only if the function returns SUCCESS.

Parameters:

address – The dynamic address of the target device.
bcr – The Bus Characteristic Register of the target.

Return values:

SUCCESS – Target BCR was successfully gotten.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccGETDCR(uint8_t address, uint8_t &dcr)

Get the Device Characteristic Register (DCR) value of the target.

Sends the GETDCR (Get Device Characteristic Register) Common Command Code (CCC) in direct mode to the specified I3C target.

The controller reads the DCR value from the addressed target and stores the result in dcr. If the operation completes successfully, the internal target device table is updated with the retrieved DCR value to keep the software representation synchronized with the device state.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
The output parameter dcr is updated only if the function returns SUCCESS.

Parameters:

address – The dynamic address of the target device.
dcr – The Device Characteristic Register of the target.

Return values:

SUCCESS – Target DCR was successfully gotten.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccGETSTATUS(uint8_t targetAddress, std::vector<uint8_t> &status, std::optional<uint8_t> defByte = std::nullopt)

Gets the STATUS from a target device on the I3C bus.

Sends the GETSTATUS Common Command Code (CCC) in direct read mode to the specified I3C target.

Two formats of the GETSTATUS CCC are supported:

Format 1: If defByte is not provided, the command is issued without a defining byte and the target returns its default STATUS data.
Format 2: If defByte is provided, it is transmitted as the defining byte, and the target returns the STATUS data corresponding to that definition.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

targetAddress – The dynamic address of the target device from which to get the STATUS.
status – Vector where the retrieved STATUS will be stored.
defByte – The defining byte for the GETSTATUS Format 2 version of the CCC. If not provided, the default value is None and it is assumed the Format 1 of the CCC.

Return values:

SUCCESS – Target STATUS was successfully gotten.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccGETCAPS(uint8_t targetAddress, std::vector<uint8_t> &caps, std::optional<uint8_t> defByte = std::nullopt)

Get the Optional Feature Capabilities (CAPS) from a target device on the I3C bus.

Sends the GETCAPS (Get Optional Feature Capabilities) Common Command Code (CCC) in direct read mode to the specified I3C target.

Two formats of the GETCAPS CCC are supported:

Format 1: If defByte is not provided, the command is issued without a defining byte and the target returns its default CAPS data.
Format 2: If defByte is provided, it is transmitted as the defining byte, and the target returns the CAPS data corresponding to that definition.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

targetAddress – The address of the target device from which to get the CAPS.
caps – Vector where the retrieved Optional Feature Capabilities (CAPS) will be stored.
defByte – The defining byte for the GETCAPS Format 2 version of the CCC. If not provided, the default value is None and it is assumed the Format 1 of the CCC.

Return values:

SUCCESS – Target CAPS was successfully gotten.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccRSTACTBroadcast(I3cTargetResetDefByte defByte)

Emits the RSTACT Broadcast CCC to configure the next Target Reset action on all I3C targets.

Sends the RSTACT (Reset Action) Common Command Code (CCC) in broadcast mode.

The RSTACT CCC and the Target Reset Pattern are emitted within the same frame. All targets that support the specified reset action execute it upon receiving the command and the associated reset pattern.

This operation affects all I3C targets on the bus that support RSTACT.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
Devices that do not support the specified reset action may ignore the command.

Parameters:

defByte – The defining byte specifying the reset action to be performed. See I3cTargetResetDefByte for supported values.

Return values:

SUCCESS – RSTACT Broadcast was successfully sent.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccRSTACTDirect(uint8_t targetAddress, I3cTargetResetDefByte defByte, I3cTransferDirection direction, uint8_t *outValue = nullptr)

Sends the Direct Write or Direct Read RSTACT CCC.

Sends the RSTACT (Reset Action) Common Command Code (CCC) in direct mode to the specified target.

The behavior depends on the selected direction:

Write transfer: The defByte specifies the reset action to be configured for the addressed target. The Target Reset Pattern is emitted within the same frame, causing the target to execute the specified reset action.
Read transfer: The command retrieves the reset recovery timing information from the addressed target, as defined by the I3C specification. The retrieved value is stored in outValue if provided.

Only the addressed target processes this command. Other devices on the bus are not affected.

Note

This function is valid only when the host is configured as an I3C controller.

Parameters:

targetAddress – The dynamic address of the target device.
defByte – The defining byte specifying the reset action to be performed. See I3cTargetResetDefByte for supported values.
direction – Indicates whether the command is a read or write transfer. See I3cTransferDirection for supported values.
outValue – Pointer where the retrieved reset recovery timing value will be stored when direction is read. Ignored for write transfers.

Return values:

SUCCESS – RSTACT Direct was successfully sent and acknowledged by the addressed target.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccENECBroadcast(const uint8_t events)

Enable events for all targets (broadcast).

Sends the ENEC (Enable Events Command) Common Command Code (CCC) in broadcast mode to all I3C targets on the bus.

Targets that do not support a specific event or the ENEC CCC may ignore the corresponding bits.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

events – Bitmask of I3C events to be enabled. Possible events are defined on I3CEvent. Multiple events may be combined using bitwise OR.

Return values:

SUCCESS – ENEC Broadcast was successfully sent.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccENECDirect(uint8_t address, const uint8_t events)

Enable specific events on a single target (direct).

Sends the ENEC (Enable Events Command) Common Command Code (CCC) in direct mode to the specified I3C target.

Only the addressed target processes this command. Other devices on the bus are not affected.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

address – The dynamic address of the target device.
events – Bitmask of I3C events to be enabled. Possible events are defined on I3CEvent. Multiple events may be combined using bitwise OR.

Return values:

SUCCESS – ENEC Direct was successfully sent and acknowledged by the addressed target.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccDISECBroadcast(const uint8_t events)

Disable events for all targets (broadcast).

Sends the DISEC (Disable Events) Common Command Code (CCC) in broadcast mode to all I3C targets on the bus.

All targets capable of processing broadcast CCCs will receive and apply the command. Devices that do not support a given event may ignore the corresponding bit.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

events – Bitmask of I3C events to be disabled. Possible events are defined on I3CEvent. Multiple events may be combined using bitwise OR.

Return values:

SUCCESS – DISEC Broadcast was successfully sent.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccDISECDirect(uint8_t address, const uint8_t events)

Disable specific events on a single target (direct).

Sends the DISEC (Disable Events) Common Command Code (CCC) in direct mode to a single I3C target identified by its dynamic address.

Only the addressed target processes this command. Unlike the broadcast variant, other devices on the bus are not affected.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.

Parameters:

address – The dynamic address of the target device.
events – Bitmask of I3C events to be disabled. Possible events are defined on I3CEvent. Multiple events may be combined using bitwise OR.

Return values:

SUCCESS – DISEC Direct was successfully sent and acknowledged by the addressed target.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccGETMWL(uint8_t address, uint16_t &maxWriteLength)

Get the Maximum Write Length (MWL) supported by the target.

Sends the GETMWL (Get Maximum Write Length) Common Command Code (CCC) in direct mode to the specified I3C target.

The controller reads the Maximum Write Length value supported by the addressed target and stores the result in maxWriteLength.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
The output parameter maxWriteLength is updated only if the function returns SUCCESS.

Parameters:

address – The dynamic address of the target device.
maxWriteLength – The Maximum Write Length of the target.

Return values:

SUCCESS – Target MWL was successfully gotten.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccSETMWLBroadcast(uint16_t mwl)

Set the Maximum Write Length (MWL) for all targets (broadcast CCC).

Sends the SETMWL (Set Maximum Write Length) Common Command Code (CCC) in broadcast mode to all I3C targets on the bus.

All targets capable of processing broadcast CCCs will receive and apply the command.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
The configured value applies to all targets that support the SETMWL CCC.
Devices that do not support this CCC may ignore the command.

Parameters:

mwl – The Maximum Write Length.

Return values:

SUCCESS – MLW Broadcast was successfully sent.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccSETMWLDirect(uint8_t address, uint16_t mwl)

Set the Maximum Write Length (MWL) for a specific target (direct CCC).

Sends the SETMWL (Set Maximum Write Length) Common Command Code (CCC) in direct mode to the specified I3C target.

Only the addressed target processes this command. Other devices on the bus are not affected.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
A return value of SUCCESS indicates that the CCC was transmitted successfully and acknowledged by the addressed target.

Parameters:

address – The dynamic address of the target device.
mwl – The Maximum Write Length for the target.

Return values:

SUCCESS – MWL Direct was successfully sent and acknowledged by the addressed target.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccGETMRL(uint8_t address, uint16_t &maxReadLength, std::optional<uint8_t> &ibiLength)

Get the Maximum Read Length (MRL) supported by the target.

Sends the GETMRL (Get Maximum Read Length) Common Command Code (CCC) in direct mode to the specified I3C target.

If the target supports In-Band Interrupt (IBI) payloads, it appends an additional byte to the response indicating the maximum supported IBI payload length. In that case, ibiLength is set with the returned value. If the response contains only two bytes, the target does not support IBI payloads and ibiLength is reset.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
The output parameters maxReadLength and ibiLength are updated only if the function returns SUCCESS.

Parameters:

address – The dynamic address of the target device.
maxReadLength – The Maximum Read Length of the target.
ibiLength – (optional) Set to the maximum IBI payload length if supported by the target, or reset if the target does not support IBI payloads.

Return values:

SUCCESS – Target MRL was successfully gotten.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccSETMRLBroadcast(uint16_t mrl, std::optional<uint8_t> ibiLength = std::nullopt)

Set the Maximum Read Length (MRL) for all targets (broadcast CCC).

Sends the SETMRL (Set Maximum Read Length) Common Command Code (CCC) in broadcast mode to all I3C targets on the bus.

If ibiLength is provided, the CCC includes the optional IBI payload length field and configures the maximum IBI payload size supported by the targets. If ibiLength is not set, the CCC is sent without the IBI payload length field and the existing IBI payload configuration remains unchanged.

All targets capable of processing broadcast CCCs will receive and apply the command according to the I3C specification.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
The IBI payload length field is included in the CCC only when ibiLength contains a value.
Devices that do not support the optional IBI length field may ignore it.

Parameters:

mrl – The Maximum Read Length.
ibiLength – (optional) When set, configures the maximum IBI payload size for the target; when not set, no IBI payload length is configured.

Return values:

SUCCESS – MRL Broadcast was successfully sent.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccSETMRLDirect(uint8_t address, uint16_t mrl, std::optional<uint8_t> ibiLength = std::nullopt)

Set the Maximum Read Length (MRL) for a specific target (direct CCC).

Sends the SETMRL (Set Maximum Read Length) Common Command Code (CCC) in direct mode to the specified I3C target.

If ibiLength is provided, the CCC includes the optional IBI payload length field and configures the maximum IBI payload size supported by the target. If ibiLength is not set, the CCC is sent without the IBI payload length field and the target IBI payload configuration remains unchanged.

Only the addressed target processes this command. Other devices on the bus are not affected.

Note

This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
The IBI payload length field is included in the CCC only when ibiLength contains a value.

Parameters:

address – The dynamic address of the target device.
mrl – The Maximum Read Length for the target.
ibiLength – (optional) When set, configures the maximum IBI payload size for the target; when not set, no IBI payload length is configured.

Return values:

SUCCESS – MRL Direct was successfully sent and acknowledged by the addressed target.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.
FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.
FW_I3C_NACK_ADDRESS – The target NACKed the address.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.