I3C API

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

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 id, 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:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • 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 command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cControllerInit(uint16_t id, uint8_t pushPullFrequency, uint8_t openDrainFrequency, uint8_t i2cOpenDrainFrequency, uint8_t 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.

  • To modify the I3C configuration after initialization, use i3cSetParameters instead of reinitializing the interface.

Parameters:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • 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 – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cSetParameters(uint16_t id, uint8_t pushPullFrequency, uint8_t openDrainFrequency, uint8_t i2cOpenDrainFrequency, uint8_t 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

Parameters:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • 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 – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cInitBus(uint16_t id, 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.

  • To modify the I3C configuration after initialization, use i3cSetParameters instead of reinitializing the interface.

Parameters:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

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

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cResetBus(uint16_t id)

Resets the I3C bus.

Issue the RSTDAA CCC and clear the target device table.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cGetDeviceTable(uint16_t id)

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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cSetTargetDeviceConfiguration(uint16_t id, 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:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • address – Target address whose configuration will be set.

  • targetConfiguration – A dictionary containing the new configuration.

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

Performs an I3C write using Legacy I2C mode.

Writes data to an I2C target using a Legacy I2C Private Transfer 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:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • address – The static address of the I2C target.

  • subAddress – The optional sub-address to write to.

  • 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 – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

Performs an I3C read using Legacy I2C mode.

Reads data from an I2C target using a Legacy I2C Private Transfer 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:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • address – The static address of the I2C target.

  • subAddress – The optional sub-address to write to.

  • readLength – The length of data to be read.

  • 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 – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cSdrWrite(uint16_t id, 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:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • address – The dynamic address of the I3C target, or the group address.

  • subAddress – The optional sub-address to write to.

  • 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 – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cSdrRead(uint16_t id, uint8_t address, const std::vector<uint8_t> &subAddress, uint16_t readLength, 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:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • address – The dynamic address of the I3C target.

  • subAddress – The optional sub-address to write to.

  • readLength – The length of data to be read.

  • 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 – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cHdrDdrWrite(uint16_t id, 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:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • 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 – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cHdrDdrRead(uint16_t id, uint8_t address, uint8_t command, uint16_t readLength)

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:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • 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.

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cTargetResetPattern(uint16_t id)

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.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cHdrExitPattern(uint16_t id)

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.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccTransfer(uint16_t id, uint8_t address, I3cTransferDirection direction, I3cTransferMode mode, bool nonStop, I3cCccType type, uint8_t payloadLength, CCC ccc, uint8_t definingByte, const std::vector<uint8_t> &inData = std::vector<uint8_t>{})

Perform a CCC transfer.

Sends a Common Command Code (CCC) to one or more I3C targets.

Parameters:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • address – Target dynamic address on the I3C bus.

  • direction – Data transfer direction (read or write). See I3cTransferDirection for supported values.

  • mode – I3C transfer mode used for the transaction. See I3cTransferMode for supported values.

  • nonStop – If true, the transfer will not issue a STOP condition after completion.

  • type – Type of CCC command, indicating whether a defining byte is used. See I3cCccType for supported values.

  • payloadLength – Length in bytes of the CCC payload.

  • ccc – The specific CCC to send to the target. See CCC for supported values.

  • definingByte – Optional defining byte associated with the CCC, if required by the command type.

  • inData – The data to be transferred for write transfers.

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.