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.
FW_EXTERNAL_VOLTAGE_DETECTED – Firmware 4.7.0 and later: the port already carries a voltage from another source, so the rail is left off. Call i3cUseExternalVoltage() to run from that supply.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cUseExternalVoltage(bool save = false)

Configures the I3C bus to use an externally supplied voltage.

Notify the host adapter that the I3C bus voltage comes from an external supply. The HV reading saturates at ~3299 mV, so an HV supply above 3.3 V is accepted, not refused with FW_VOLTAGE_OUT_OF_RANGE_ON_I3C_HV. Keep an external HV at or below 3.3 V.

Parameters:

save – Ignored by the firmware. The I3C rails come from DACs that store nothing, so this always applies only to the current session.

Return values:

SUCCESS – Voltage domain successfully switched to external supply.
FW_BOTH_I3C_PORTS_POWERED – The device has two I3C ports and both of them are currently powered. Please disconnect one of the two ports and try again.
FW_I3C_PORTS_NOT_POWERED – Both I3C ports are currently not powered. Please connect at least one of the two ports to a power supply and try again.
FW_VOLTAGE_OUT_OF_RANGE_ON_I3C_HV – The voltage detected on the I3C_HV pin is outside the valid range for external supply.
FW_VOLTAGE_OUT_OF_RANGE_ON_I3C_LV – The voltage detected on the I3C_LV pin is outside the valid range for external supply.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cGetBusVoltage(uint16_t &hvExternalVoltage_mV, uint16_t &lvExternalVoltage_mV)

Reads the measured I3C bus voltage from the host adapter.

The I3C interface has two independent voltage rails: a high-voltage rail (HV, 1200 mV to 3300 mV) and a low-voltage rail (LV, 800 mV to 1200 mV). The external (VTARG pin) voltage is returned for each rail.

Parameters:

hvExternalVoltage_mV – Receives the voltage (in millivolts) measured on the VTARG pin for the I3C high-voltage rail.
lvExternalVoltage_mV – Receives the voltage (in millivolts) measured on the VTARG pin for the I3C low-voltage rail.

Return values:

SUCCESS – Voltage measurements successfully retrieved.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.
SDK_ERROR_WRONG_RESPONSE – The host adapter answered with a response too short to hold the analog measurements, so no reading could be taken. Both out-parameters are left untouched. A firmware error reported in such a response is returned in its place.

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

The I3C engine does not wait for a target that stretches SCL (fw-hostadapters#140): such a target loses bits and a read can return wrong data with SUCCESS. Enable I2C clock stretching first (firmware 4.6.0+), or put the target on the I2C port.
This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
A target that stretches SCL (SMBus, MCTP) needs i3cSetI2cClockStretching first: the I3C engine itself cannot wait for a stretched clock.

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. Supported values (see I3cTransferFlags):
- I3C_XFER_NONE: standard transfer (default).
- I3C_XFER_NONSTOP: no STOP condition is emitted at the end of the transfer.
- I3C_XFER_START_WITH_7E: the transfer starts with the broadcast address 0x7E before addressing the target.

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

The I3C engine does not wait for a target that stretches SCL (fw-hostadapters#140): such a target loses bits and a read can return wrong data with SUCCESS. Enable I2C clock stretching first (firmware 4.6.0+), or put the target on the I2C port.
This function is valid only when the host is initialized as an I3C controller with i3cControllerInit.
A target that stretches SCL (SMBus, MCTP) needs i3cSetI2cClockStretching first: the I3C engine itself cannot wait for a stretched clock.

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. Supported values (see I3cTransferFlags):
- I3C_XFER_NONE: standard transfer (default).
- I3C_XFER_NONSTOP: no STOP condition is emitted at the end of the transfer.
- I3C_XFER_START_WITH_7E: the transfer starts with the broadcast address 0x7E before addressing the target.

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 i3cSetI2cClockStretching(bool enable, uint32_t frequency_Hz, bool &enabled, uint32_t &actualFrequency_Hz)

Lets legacy I2C transfers on the I3C port wait for a target that stretches SCL.

The I3C engine keeps clocking SCL while a target holds it low, so a target that stretches the clock (SMBus and MCTP devices, for example) loses bits. With this mode on, the legacy I2C transfers on the I3C port – i3cLegacyI2cWrite, i3cLegacyI2cRead and their Bulk variants, and only those – run clocked in software and wait for the target to release SCL.

While the mode is on:

Commands that need the I3C engine are refused at once with FW_I3C_I2C_CLOCK_STRETCHING_ACTIVE: bus init/ENTDAA, bus reset, CCC transfers, trigger patterns and SDR/HDR private transfers. Turn the mode off first.
A stretch longer than the SMBus tTIMEOUT (35 ms) ends the legacy transfer with FW_BUS_TIMEOUT.

i3cControllerInit and i3cSetParameters turn the mode off. The SDA pull-up set by i3cSetSdaPullUp is not reset: it survives re-inits and applies again the next time the mode is turned on, until it is changed or the adapter is reset.

bool on = false; uint32_t sclHz = 0;
sdk.i3cSetI2cClockStretching(true, 100000, on, sclHz);   // on == true, sclHz <= 100000
sdk.i3cLegacyI2cWrite(0x50, {0x00}, {0xAB}, I3C_XFER_NONE);

Note

Firmware 4.5.x and older answer FW_UNSUPPORTED_COMMAND.

Parameters:

enable – true to turn clock stretching on, false to go back to the I3C engine.
frequency_Hz – SCL rate in Hz for the legacy transfers, 10000 to 1000000; FW_INVALID_PARAMETER outside that range. Ignored when enable is false. The rate actually used is the closest one the firmware can make at or below this. It is measured on the wire at each enable, so the ceiling depends on the wiring (746 kHz on one bench, 290-385 kHz on another for a 1 MHz request); read it from actualFrequency_Hz.
enabled – [out] Whether the mode is on after the call. Written whenever the response carries it; left untouched otherwise.
actualFrequency_Hz – [out] SCL rate the legacy transfers will run at, never above frequency_Hz; 0 when the mode is off. Written under the same condition as enabled.

Return values:

SUCCESS – The mode is now as requested.
FW_INVALID_PARAMETER – frequency_Hz is outside 10 kHz..1 MHz.
FW_INTERFACE_NOT_INITIALIZED – The I3C controller is not initialized; call i3cControllerInit first.
FW_UNSUPPORTED_COMMAND – The firmware predates this command (4.5.x and older).
FW_UNHANDLED_ERROR – The firmware failed to switch modes.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.
SDK_ERROR_WRONG_RESPONSE – The host adapter reported SUCCESS in a response too short to carry the mode and rate. The out-parameters are left untouched.

uint16_t i3cHoldSclLow(uint32_t duration_us, uint32_t &held_us)

Holds SCL low on the I3C port for a set time, then releases it.

SMBus interface reset (T2wrst in the PCI-SIG NVMe-MI out-of-band flow): SCL is driven low for duration_us, then released. SDA is released for the whole hold. Works with I2C clock stretching on or off; the mode is left as it was.

SCL has no on-board pull-up: an external one is needed for SCL to rise after the release.

The call waits for the hold: the response timeout is extended by duration_us plus 136 ms for this call only.

Note

Firmware that predates this command answers FW_UNSUPPORTED_COMMAND.

Parameters:

duration_us – How long to hold SCL low, in microseconds, 1 to 1000000; FW_INVALID_PARAMETER outside that range.
held_us – [out] How long SCL was held, measured by the firmware. Written whenever the response carries it (0 on a refusal); left untouched otherwise.

Return values:

SUCCESS – SCL was held and rose again after the release.
FW_INVALID_PARAMETER – duration_us is 0 or above 1000000.
FW_INTERFACE_NOT_INITIALIZED – The I3C controller is not initialized; call i3cControllerInit first.
FW_BUS_TIMEOUT – SCL was still low 35 ms after the release: a target is holding it, or there is no pull-up on SCL.
FW_UNSUPPORTED_COMMAND – The firmware predates this command.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.
SDK_ERROR_WRONG_RESPONSE – The host adapter reported SUCCESS in a response too short to carry held_us.

uint16_t i3cSetSdaPullUp(I3cSdaPullUp mode, I3cSdaPullUp &inEffect)

Sets the I3C port’s SDA pull-up.

Controls the 1 kOhm pull-up on the I3C port’s SDA line:

I3C_SDA_PULLUP_AUTO (default, the behaviour of every earlier firmware): the I3C engine drives it.
I3C_SDA_PULLUP_OFF: disconnected while the I2C clock-stretching mode is on.
I3C_SDA_PULLUP_ON: connected while the I2C clock-stretching mode is on.

With the I3C engine on the pins (stretching off) the engine drives the pull-up whatever the setting; ON/OFF apply to the clock-stretching (SMBus) mode.

SCL has no on-board pull-up; it needs an external one. The setting survives I3C re-inits until it is changed or the adapter is reset.

Note

Firmware that predates this command answers FW_UNSUPPORTED_COMMAND.

Parameters:

mode – I3C_SDA_PULLUP_AUTO, I3C_SDA_PULLUP_OFF or I3C_SDA_PULLUP_ON. Any other value is FW_INVALID_PARAMETER.
inEffect – [out] The stored setting after the call, also on FW_INVALID_PARAMETER: what the pull-up does while the clock-stretching mode is on, not while the I3C engine owns the pins. Written whenever the response carries it; left untouched otherwise.

Return values:

SUCCESS – The stored setting is now mode. It governs the pull-up only while the I2C clock-stretching mode is on; with the I3C engine on the pins the engine drives it.
FW_INVALID_PARAMETER – mode is not one of the three values; the setting is unchanged.
FW_UNSUPPORTED_COMMAND – The firmware predates this command.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.
SDK_ERROR_WRONG_RESPONSE – The host adapter reported SUCCESS in a response too short to carry the setting.

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

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. Supported values (see I3cTransferFlags):
- I3C_XFER_NONE: standard transfer.
- I3C_XFER_NONSTOP: no STOP condition is emitted at the end of the transfer.
- I3C_XFER_START_WITH_7E: the transfer starts with the broadcast address 0x7E before addressing the target (default).

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 = I3C_XFER_START_WITH_7E)

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. Supported values (see I3cTransferFlags):
- I3C_XFER_NONE: standard transfer.
- I3C_XFER_NONSTOP: no STOP condition is emitted at the end of the transfer.
- I3C_XFER_START_WITH_7E: the transfer starts with the broadcast address 0x7E before addressing the target (default).

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, I3cTransferFlags flags = I3C_XFER_NONE)

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.

Note

I3C_XFER_START_WITH_7E has no effect on HDR-DDR transfers.

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.
flags – Bitmask of transfer options for the HDR-DDR transaction (see I3cTransferFlags):
- I3C_XFER_NONE: standard transfer, the HDR Exit Pattern is emitted (default).
- I3C_XFER_SKIP_EXIT_PATTERN: the HDR Exit Pattern is not emitted after completion. This is an alias of I3C_XFER_NONSTOP (same bit); either name may be used.

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, I3cTransferFlags flags = I3C_XFER_NONE)

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.

Note

I3C_XFER_START_WITH_7E has no effect on HDR-DDR transfers.

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.
flags – Bitmask of transfer options for the HDR-DDR transaction (see I3cTransferFlags):
- I3C_XFER_NONE: standard transfer, the HDR Exit Pattern is emitted (default).
- I3C_XFER_SKIP_EXIT_PATTERN: the HDR Exit Pattern is not emitted after completion. This is an alias of I3C_XFER_NONSTOP (same bit); either name may be used.

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 i3cSdrWriteBulk(uint8_t address, const std::vector<uint8_t> &subAddress, const std::vector<uint8_t> &inData, I3cTransferFlags flags = I3C_XFER_START_WITH_7E)

Performs an I3C SDR write with the payload on the vendor bulk endpoint.

The large-payload counterpart of i3cSdrWrite, and the I3C mode with a real gain: i3cSdrWrite carries its bytes inside the request and so can never exceed MAX_I3C_PRIVATE_TRANSFER_LENGTH, while this one reaches whatever the device advertises for GROUP_I3C.

See also

The four checks every bulk call makes before it moves a byte.

Note

Valid only when the host is initialized as an I3C controller with i3cControllerInit.
Requires the vendor bulk transport to be usable; see isBulkTransportAvailable and getBulkCapabilities. Otherwise returns SDK_ERROR_BULK_UNAVAILABLE.
The register address shares the frame with the payload on a write, so the usable payload is the advertised ceiling minus subAddress.size(). A read has no such deduction.
There is no automatic chunking above the ceiling; splitting is the caller’s job.

Parameters:

address – The dynamic address of the I3C target.
subAddress – The optional register address to write to. At most 4 bytes.
inData – The data to be written; must be non-empty and within the advertised ceiling.
flags – Bitmask of transfer options (see I3cTransferFlags).

Return values:

SUCCESS – The transfer completed.
SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable, or the connected device does not advertise CMD_I3C_CONTROLLER_PRIVATE_TRANSFER_BULK.
SDK_ERROR_WRONG_REQUEST – subAddress is longer than 4 bytes, or inData is empty or over the ceiling.
SDK_ERROR_TIMEOUT – The operation timed out, or the payload could not be streamed over the bulk endpoint.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

Reads an I3C SDR block whose data phase returns on the vendor bulk endpoint.

The large-payload counterpart of i3cSdrRead. Only the data phase moves on the vendor bulk IN endpoint; this call collects it into outData once the reply has announced the length.

See also

The four checks every bulk call makes before it moves a byte.

Note

Valid only when the host is initialized as an I3C controller with i3cControllerInit.
Requires the vendor bulk transport to be usable; see isBulkTransportAvailable and getBulkCapabilities. Otherwise returns SDK_ERROR_BULK_UNAVAILABLE.
outData is sized to what the device actually announced, which may be shorter than readLength. It is left empty when nothing could be collected.

Parameters:

address – The dynamic address of the I3C target.
subAddress – The optional register address to read from. At most 4 bytes.
readLength – The length of data to be read; must be non-zero and within the advertised ceiling.
outData – Receives the data phase collected from the bulk endpoint.
flags – Bitmask of transfer options (see I3cTransferFlags).

Return values:

SUCCESS – The transfer completed and outData holds the payload.
SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable, or the command is not advertised.
SDK_ERROR_WRONG_REQUEST – subAddress is longer than 4 bytes, or readLength is zero or over the ceiling.
SDK_ERROR_WRONG_RESPONSE – The reply claimed success but was too short to carry its own announced length.
SDK_ERROR_TIMEOUT – The operation timed out, or the payload never arrived on the bulk endpoint.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cHdrDdrWriteBulk(uint8_t address, uint8_t command, const std::vector<uint8_t> &inData, I3cTransferFlags flags = I3C_XFER_NONE)

Performs an I3C HDR-DDR write with the payload on the vendor bulk endpoint.

The bulk-route counterpart of i3cHdrDdrWrite.

See also

The four checks every bulk call makes before it moves a byte.

Note

Valid only when the host is initialized as an I3C controller with i3cControllerInit.
DDR moves 16-bit words, so an odd-length write cannot be framed and is refused rather than truncated.

Warning

This buys nothing today, and that is deliberate. DDR is capped at I3C_HDR_DDR_MAX_PAYLOAD (1024) in both the firmware and this SDK, which i3cHdrDdrWrite already reaches over the ordinary route. The cap is not a buffer size: above roughly 2048 bytes the target stops answering its dynamic address and stays that way until re-enumeration, so an uncapped DDR transfer costs the caller their bus rather than returning an error. Note that getBulkCapabilities advertises the much larger GROUP_I3C ceiling, which does not apply to this mode — a host that asked for what it was told it could have would break its own bus, so this call refuses first. The entry point exists so the bulk route is complete and lifting the cap later is not a new API.

Parameters:

address – The dynamic address of the I3C target.
command – The HDR-DDR command byte. Must be in the range [0x80, 0xFF].
inData – The data to be written; must be non-empty, of even length, and within I3C_HDR_DDR_MAX_PAYLOAD.
flags – Bitmask of transfer options (see I3cTransferFlags).

Return values:

SUCCESS – The transfer completed.
SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable, or the command is not advertised.
SDK_ERROR_WRONG_REQUEST – inData is empty, odd-length, or over I3C_HDR_DDR_MAX_PAYLOAD.
SDK_ERROR_TIMEOUT – The operation timed out, or the payload could not be streamed over the bulk endpoint.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cHdrDdrReadBulk(uint8_t address, uint8_t command, uint16_t readLength, std::vector<uint8_t> &outData, I3cTransferFlags flags = I3C_XFER_NONE)

Reads an I3C HDR-DDR block whose data phase returns on the vendor bulk endpoint.

The bulk-route counterpart of i3cHdrDdrRead.

See also

The four checks every bulk call makes before it moves a byte.

Note

Valid only when the host is initialized as an I3C controller with i3cControllerInit.
outData is sized to what the device actually announced, and left empty when nothing could be collected.

Warning

Capped at I3C_HDR_DDR_MAX_PAYLOAD for the same reason as i3cHdrDdrWriteBulk — see that warning; the GROUP_I3C ceiling getBulkCapabilities advertises does not apply to this mode.

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 data to read. Must be a non-zero multiple of 2 and within I3C_HDR_DDR_MAX_PAYLOAD.
outData – Receives the data phase collected from the bulk endpoint.
flags – Bitmask of transfer options (see I3cTransferFlags).

Return values:

SUCCESS – The transfer completed and outData holds the payload.
SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable, or the command is not advertised.
SDK_ERROR_WRONG_REQUEST – readLength is zero, odd, or over I3C_HDR_DDR_MAX_PAYLOAD.
SDK_ERROR_WRONG_RESPONSE – The reply claimed success but was too short to carry its own announced length.
SDK_ERROR_TIMEOUT – The operation timed out, or the payload never arrived on the bulk endpoint.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

Performs a legacy I2C write on the I3C bus with the payload on the vendor bulk endpoint.

The bulk-route counterpart of i3cLegacyI2cWrite, provided so the route covers every mode the ordinary API offers. A legacy I2C target on an I3C bus is bounded by its own bus rate long before the transport matters, so expect a smaller gain here than from i3cSdrWriteBulk.

See also

The four checks every bulk call makes before it moves a byte.

Note

The I3C engine does not wait for a target that stretches SCL (fw-hostadapters#140): such a target loses bits and a read can return wrong data with SUCCESS. Enable I2C clock stretching first (firmware 4.6.0+), or put the target on the I2C port.
Valid only when the host is initialized as an I3C controller with i3cControllerInit.
As with SDR, the register address shares the frame with the payload on a write.

Parameters:

address – The static address of the legacy I2C device.
subAddress – The optional register address to write to. At most 4 bytes.
inData – The data to be written; must be non-empty and within the advertised ceiling.
flags – Bitmask of transfer options (see I3cTransferFlags).

Return values:

SUCCESS – The transfer completed.
SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable, or the command is not advertised.
SDK_ERROR_WRONG_REQUEST – subAddress is longer than 4 bytes, or inData is empty or over the ceiling.
SDK_ERROR_TIMEOUT – The operation timed out, or the payload could not be streamed over the bulk endpoint.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

Reads a legacy I2C block on the I3C bus over the vendor bulk endpoint.

The bulk-route counterpart of i3cLegacyI2cRead. Only the data phase moves on the vendor bulk IN endpoint; this call collects it once the reply has announced the length.

See also

The four checks every bulk call makes before it moves a byte.

Note

The I3C engine does not wait for a target that stretches SCL (fw-hostadapters#140): such a target loses bits and a read can return wrong data with SUCCESS. Enable I2C clock stretching first (firmware 4.6.0+), or put the target on the I2C port.
Valid only when the host is initialized as an I3C controller with i3cControllerInit.
outData is sized to what the device actually announced, and left empty when nothing could be collected.

Parameters:

address – The static address of the legacy I2C device.
subAddress – The optional register address to read from. At most 4 bytes.
readLength – The length of data to be read; must be non-zero and within the advertised ceiling.
outData – Receives the data phase collected from the bulk endpoint.
flags – Bitmask of transfer options (see I3cTransferFlags).

Return values:

SUCCESS – The transfer completed and outData holds the payload.
SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable, or the command is not advertised.
SDK_ERROR_WRONG_REQUEST – subAddress is longer than 4 bytes, or readLength is zero or over the ceiling.
SDK_ERROR_WRONG_RESPONSE – The reply claimed success but was too short to carry its own announced length.
SDK_ERROR_TIMEOUT – The operation timed out, or the payload never arrived on the bulk endpoint.
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 i3cTargetInit(I3cTargetMemoryLayout memoryLayout, const std::vector<uint8_t> &pid, I3cBCR bcr, uint8_t dcr, uint8_t staticAddress, uint16_t mwl = 1024, uint16_t mrl = 1024)

Initializes the host adapter as an I3C target device.

Configures the I3C peripheral to act as a target device on the I3C bus. The host adapter exposes a memory of I3C_TARGET_MEMORY_SIZE bytes that any I3C controller on the bus can write and read using private transfers, and that the host application can access locally with i3cTargetWriteMemory and i3cTargetReadMemory.

The memoryLayout parameter selects how those bytes are grouped into addressable registers. See I3cTargetMemoryLayout for the supported layouts, the resulting register size and the range of valid register addresses.

Every transfer an I3C controller performs against this target is reported asynchronously through the NOTIF_I3C_TARGET_BUS_EVENT notification. See I3cTargetBusEvent and onNotification.

Note

This command is implemented by the firmware from FW4.1.1 onwards. Older firmware answers FW_UNSUPPORTED_COMMAND. Use getDeviceInfo to read the firmware version beforehand.
Unlike i3cControllerInit, this command re-initializes the I3C peripheral unconditionally, so it never reports FW_INTERFACE_ALREADY_INITIALIZED. It switches the role of the host adapter from controller to target when required.
Use i3cTargetSetParameters to modify the configuration of an already initialized target.
Target initiated In-Band Interrupts (IBI) are not implemented by the firmware yet, and therefore are not exposed by this API.

Note

The whole 0x00 to 0x7F range is deliberately permitted, which differs from the legacy Python SDK. That one rejects every reserved address, that is 0x00 to 0x07 and 0x78 to 0x7F, and therefore also rejects the 0x00 sentinel it would need to declare a target without static address. This SDK filters none of those ranges, consistently with the rest of the I3C API, which does not second-guess addresses either. It is the responsibility of the caller not to pick a reserved address other than the 0x00 sentinel, and of the firmware to reject it.

Parameters:

memoryLayout – The layout of the memory the target exposes to the I3C bus. See I3cTargetMemoryLayout for supported values.
pid – The 48-bit Provisional ID (PID) of the target, as exactly 6 bytes, MSB first. This is the same convention used by I3cTargetInfo::pid, that is, pid[0] holds the PID bits 47:40 and pid[5] holds the PID bits 7:0. The SDK splits it into the vendor id (PID bits 47:33), the random value flag (PID bit 32) and the part number (PID bits 31:0) expected on the wire.
bcr – The Bus Characteristics Register (BCR) the target reports on the bus. See I3cBCR for the meaning of every bit.
dcr – The Device Characteristics Register (DCR) the target reports on the bus. Any value between 0x00 and 0xFF is accepted. See I3cTargetDcr for a set of common presets.
staticAddress – The I2C static address of the target, from 0x00 to 0x7F. I3C_TARGET_UNASSIGNED_STATIC_ADDR (0x00) is accepted and means that the target does not expose a static address, which is the sentinel the firmware itself uses.
mwl – The Maximum Write Length (MWL) the target reports to the SETMWL and GETMWL CCCs, from 0 to I3C_TARGET_MAX_MWL bytes.
mrl – The Maximum Read Length (MRL) the target reports to the SETMRL and GETMRL CCCs, from 0 to I3C_TARGET_MAX_MRL bytes.

Return values:

SUCCESS – The host adapter was successfully initialized as an I3C target device.
FW_UNSUPPORTED_COMMAND – The firmware running on the host adapter does not implement I3C target mode. Update the firmware to FW4.1.1 or newer.
SDK_ERROR_WRONG_REQUEST – The request was malformed: pid is not exactly 6 bytes long, staticAddress is greater than 0x7F, or mwl / mrl surpass I3C_TARGET_MAX_MWL / I3C_TARGET_MAX_MRL.
SDK_ERROR_WRONG_RESPONSE – The host adapter answered with a malformed response, shorter than a command response header.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cTargetSetParameters(I3cTargetMemoryLayout memoryLayout, const std::vector<uint8_t> &pid, I3cBCR bcr, uint8_t dcr, uint8_t staticAddress, uint16_t mwl = 1024, uint16_t mrl = 1024)

Changes the configuration of the host adapter acting as an I3C target device.

Reapplies the complete I3C target configuration without re-initializing the I3C peripheral. The parameters are identical to the ones of i3cTargetInit, and all of them are applied, so the caller must always pass the full configuration and not only the fields to modify.

Note

This command is implemented by the firmware from FW4.1.1 onwards. Older firmware answers FW_UNSUPPORTED_COMMAND.
The host adapter must have been initialized as an I3C target device with i3cTargetInit beforehand.
Target initiated In-Band Interrupts (IBI) are not implemented by the firmware yet, and therefore are not exposed by this API.

Parameters:

memoryLayout – The layout of the memory the target exposes to the I3C bus. See I3cTargetMemoryLayout for supported values.
pid – The 48-bit Provisional ID (PID) of the target, as exactly 6 bytes, MSB first. Same convention as i3cTargetInit.
bcr – The Bus Characteristics Register (BCR) the target reports on the bus. See I3cBCR for the meaning of every bit.
dcr – The Device Characteristics Register (DCR) the target reports on the bus. Any value between 0x00 and 0xFF is accepted. See I3cTargetDcr for a set of common presets.
staticAddress – The I2C static address of the target, from 0x00 to 0x7F. I3C_TARGET_UNASSIGNED_STATIC_ADDR (0x00) is accepted and means that the target does not expose a static address.
mwl – The Maximum Write Length (MWL) the target reports to the SETMWL and GETMWL CCCs, from 0 to I3C_TARGET_MAX_MWL bytes.
mrl – The Maximum Read Length (MRL) the target reports to the SETMRL and GETMRL CCCs, from 0 to I3C_TARGET_MAX_MRL bytes.

Return values:

SUCCESS – The I3C target device configuration was successfully updated.
FW_INVALID_COMMAND – The host device was initialized as a controller device instead of a target device.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_UNSUPPORTED_COMMAND – The firmware running on the host adapter does not implement I3C target mode. Update the firmware to FW4.1.1 or newer.
SDK_ERROR_WRONG_REQUEST – The request was malformed: pid is not exactly 6 bytes long, staticAddress is greater than 0x7F, or mwl / mrl surpass I3C_TARGET_MAX_MWL / I3C_TARGET_MAX_MRL.
SDK_ERROR_WRONG_RESPONSE – The host adapter answered with a malformed response, shorter than a command response header.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cTargetWriteMemory(uint16_t memoryAddress, const std::vector<uint8_t> &data)

Writes data into the memory the host adapter exposes as an I3C target device.

Writes data into the target memory starting at the register given by memoryAddress. This is a local operation between the host application and the host adapter, it does not generate any traffic on the I3C bus. It is the way the host application publishes the values that an I3C controller on the bus reads afterwards.

Note

This command is implemented by the firmware from FW4.1.1 onwards. Older firmware answers FW_UNSUPPORTED_COMMAND.
The host adapter must have been initialized as an I3C target device with i3cTargetInit beforehand.
When the write surpasses the end of the target memory, the firmware clamps it to the space available and reports FW_SURPASSED_MEMORY_SIZE, so the write completes only partially.

Parameters:

memoryAddress – Address of the first register to write, expressed as a register index of the active memory layout and not as a byte offset. The firmware computes the byte offset inside the target memory as memoryAddress * registerSize, where registerSize is 1, 2 or 4 bytes for MEMORY_1_BYTE_X_1024_REGS, MEMORY_2_BYTES_X_512_REGS and MEMORY_4_BYTES_X_256_REGS respectively. The valid range therefore depends on the layout selected with i3cTargetInit or i3cTargetSetParameters: 0 to 1023 for 1-byte registers, 0 to 511 for 2-byte registers and 0 to 255 for 4-byte registers. The value is a plain byte offset only when the layout is MEMORY_1_BYTE_X_1024_REGS. These are the units the firmware uses, and they differ from the legacy Python SDK, which validates this field as a flat byte offset from 0 to 1023 whatever the layout in use. Since the SDK does not track the layout currently programmed in the device, only the layout independent upper bound (I3C_TARGET_MEMORY_SIZE) is checked locally. A register index that overflows the memory of the active layout is rejected by the firmware with FW_REGISTER_ADDRESS_OUT_OF_RANGE.
data – The data to be written into the target memory. The maximum size is I3C_TARGET_MEMORY_SIZE bytes.

Return values:

SUCCESS – The data was successfully written into the target memory.
FW_REGISTER_ADDRESS_OUT_OF_RANGE – The byte offset resulting from memoryAddress falls outside the target memory. No data was written.
FW_SURPASSED_MEMORY_SIZE – The write surpasses the end of the target memory. It was clamped to the space available and only partially completed.
FW_INVALID_COMMAND – The host device was initialized as a controller device instead of a target device.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_UNSUPPORTED_COMMAND – The firmware running on the host adapter does not implement I3C target mode. Update the firmware to FW4.1.1 or newer.
SDK_ERROR_WRONG_REQUEST – The request was malformed: memoryAddress is not lower than I3C_TARGET_MEMORY_SIZE, or data is longer than I3C_TARGET_MEMORY_SIZE bytes.
SDK_ERROR_WRONG_RESPONSE – The host adapter answered with a malformed response, shorter than a command response header.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cTargetReadMemory(uint16_t memoryAddress, uint16_t length, std::vector<uint8_t> &outData)

Reads data from the memory the host adapter exposes as an I3C target device.

Reads length bytes from the target memory starting at the register given by memoryAddress. This is a local operation between the host application and the host adapter, it does not generate any traffic on the I3C bus. It is the way the host application retrieves the values that an I3C controller on the bus wrote beforehand.

Note

This command is implemented by the firmware from FW4.1.1 onwards. Older firmware answers FW_UNSUPPORTED_COMMAND.
The host adapter must have been initialized as an I3C target device with i3cTargetInit beforehand.
When the read surpasses the end of the target memory, the firmware clamps it to the space available and reports FW_SURPASSED_MEMORY_SIZE, so outData holds fewer bytes than requested.

Parameters:

memoryAddress – Address of the first register to read, expressed as a register index of the active memory layout and not as a byte offset. The firmware computes the byte offset inside the target memory as memoryAddress * registerSize, where registerSize is 1, 2 or 4 bytes for MEMORY_1_BYTE_X_1024_REGS, MEMORY_2_BYTES_X_512_REGS and MEMORY_4_BYTES_X_256_REGS respectively. The valid range therefore depends on the layout selected with i3cTargetInit or i3cTargetSetParameters: 0 to 1023 for 1-byte registers, 0 to 511 for 2-byte registers and 0 to 255 for 4-byte registers. The value is a plain byte offset only when the layout is MEMORY_1_BYTE_X_1024_REGS. These are the units the firmware uses, and they differ from the legacy Python SDK, which validates this field as a flat byte offset from 0 to 1023 whatever the layout in use. Since the SDK does not track the layout currently programmed in the device, only the layout independent upper bound (I3C_TARGET_MEMORY_SIZE) is checked locally. A register index that overflows the memory of the active layout is rejected by the firmware with FW_REGISTER_ADDRESS_OUT_OF_RANGE.
length – Number of bytes to read from the target memory. The maximum value is I3C_TARGET_MEMORY_SIZE.
outData – The data read from the target memory. It holds the number of bytes the firmware actually read, which is lower than length when FW_SURPASSED_MEMORY_SIZE is reported, and empty when FW_REGISTER_ADDRESS_OUT_OF_RANGE is reported.

Return values:

SUCCESS – The data was successfully read from the target memory.
FW_REGISTER_ADDRESS_OUT_OF_RANGE – The byte offset resulting from memoryAddress falls outside the target memory. No data was read.
FW_SURPASSED_MEMORY_SIZE – The read surpasses the end of the target memory. It was clamped to the space available and only partially completed.
FW_INVALID_COMMAND – The host device was initialized as a controller device instead of a target device.
FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.
FW_UNSUPPORTED_COMMAND – The firmware running on the host adapter does not implement I3C target mode. Update the firmware to FW4.1.1 or newer.
SDK_ERROR_WRONG_REQUEST – The request was malformed: memoryAddress is not lower than I3C_TARGET_MEMORY_SIZE, or length is greater than I3C_TARGET_MEMORY_SIZE.
SDK_ERROR_WRONG_RESPONSE – The host adapter answered with a malformed response, shorter than a command response header.
SDK_ERROR_TIMEOUT – The operation timed out.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccRSTDAA(I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.

Parameters:

flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:

I3C_XFER_NONE: a STOP condition is issued after completion (default).
I3C_XFER_NONSTOP: no STOP condition is issued after completion.
I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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(std::vector<I3cTargetInfo> targets = {})

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.

Parameters:

targets – Optional table of I3cTargetInfo entries. When provided, the firmware assigns each entry’s dynamicAddress to the target matched by its pid, bcr and dcr, instead of auto-assigning. For each entry set its pid, bcr, dcr, the desired dynamicAddress, and configuration.bits.daaUseENTDAA = 1. Targets absent from the table are handled entirely by firmware logic. Defaults to an empty table, which sends the plain broadcast ENTDAA (every target is auto-assigned, matching legacy behavior).

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 or a target NACKed the assigned dynamic 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, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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 firmware adds a new entry to the internal target device table containing the assigned dynamic address and associated device information.

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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_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, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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 firmware adds a new entry to the internal target device table for each responding device, using its static address as its dynamic address.

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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_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, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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 firmware updates the internal target device table by replacing the stored dynamic address with the new value.

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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_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, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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.
SDK_ERROR_WRONG_RESPONSE – The host adapter answered with a response carrying no BCR byte. bcr is left untouched. A firmware error reported in such a response is returned in its place.

uint16_t i3cCccGETDCR(uint8_t address, uint8_t &dcr, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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.
SDK_ERROR_WRONG_RESPONSE – The host adapter answered with a response carrying no DCR byte. dcr is left untouched. A firmware error reported in such a response is returned in its place.

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

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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 i3cCccGETMXDS(uint8_t targetAddress, std::vector<uint8_t> &mxds, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Get the Maximum Data Speed (MXDS) from a target device on the I3C bus.

Sends the GETMXDS (Get Maximum Data Speed) Common Command Code (CCC) in direct read mode to the specified I3C target. Only format 1 is supported for this CCC (without defining byte).

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 MXDS.
mxds – Vector where the retrieved Maximum Data Speed (MXDS) bytes will be stored.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – Target MXDS 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 i3cCccGETXTIME(uint8_t targetAddress, std::vector<uint8_t> &xtime, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Get the Exchange Timing Support (XTIME) from a target device on the I3C bus.

Sends the GETXTIME (Get Exchange Timing Support) Common Command Code (CCC) in direct read mode to the specified I3C target.

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 XTIME data.
xtime – Vector where the retrieved Exchange Timing data (4 bytes) will be stored.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – Target XTIME was successfully retrieved.
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, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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 i3cCccRSTGRPABroadcast(I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Sends the Broadcast RSTGRPA CCC.

Sends the RSTGRPA (Reset Group Address) Common Command Code (CCC) in broadcast mode to all I3C targets on the bus. This command instructs all targets to clear their group address assignments.

Note

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

Parameters:

flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:

I3C_XFER_NONE: a STOP condition is issued after completion (default).
I3C_XFER_NONSTOP: no STOP condition is issued after completion.
I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – RSTGRPA 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 i3cCccENTAS0Broadcast(I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Sends the Broadcast ENTAS0 CCC.

Sends the ENTAS0 (Enter Activity State 0) Common Command Code (CCC) in broadcast mode to all I3C targets on the bus. This command instructs all targets to enter Activity State 0 (normal operating mode).

Note

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

Parameters:

flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:

I3C_XFER_NONE: a STOP condition is issued after completion (default).
I3C_XFER_NONSTOP: no STOP condition is issued after completion.
I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – ENTAS0 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 i3cCccENTAS1Broadcast(I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Sends the Broadcast ENTAS1 CCC.

Sends the ENTAS1 (Enter Activity State 1) Common Command Code (CCC) in broadcast mode to all I3C targets on the bus. This command instructs all targets to enter Activity State 1 (limited operating mode).

Note

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

Parameters:

flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:

I3C_XFER_NONE: a STOP condition is issued after completion (default).
I3C_XFER_NONSTOP: no STOP condition is issued after completion.
I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – ENTAS1 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 i3cCccENTAS2Broadcast(I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Sends the Broadcast ENTAS2 CCC.

Sends the ENTAS2 (Enter Activity State 2) Common Command Code (CCC) in broadcast mode to all I3C targets on the bus. This command instructs all targets to enter Activity State 2 (slower operating mode).

Note

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

Parameters:

flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:

I3C_XFER_NONE: a STOP condition is issued after completion (default).
I3C_XFER_NONSTOP: no STOP condition is issued after completion.
I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – ENTAS2 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 i3cCccENTAS3Broadcast(I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Sends the Broadcast ENTAS3 CCC.

Sends the ENTAS3 (Enter Activity State 3) Common Command Code (CCC) in broadcast mode to all I3C targets on the bus. This command instructs all targets to enter Activity State 3 (lowest activity / sleep mode).

Note

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

Parameters:

flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:

I3C_XFER_NONE: a STOP condition is issued after completion (default).
I3C_XFER_NONSTOP: no STOP condition is issued after completion.
I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – ENTAS3 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 i3cCccENTAS3Direct(uint8_t address, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Sends the Direct Write ENTAS3 CCC.

Sends the ENTAS3 (Enter Activity State 3) Common Command Code (CCC) in direct mode to the specified target. This command instructs the addressed target to enter Activity State 3 (lowest activity / sleep mode).

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:

address – The dynamic address of the target device.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – ENTAS3 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 i3cCccENTAS2Direct(uint8_t address, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Sends the Direct Write ENTAS2 CCC.

Sends the ENTAS2 (Enter Activity State 2) Common Command Code (CCC) in direct mode to the specified target. This command instructs the addressed target to enter Activity State 2 (slower operating mode).

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:

address – The dynamic address of the target device.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – ENTAS2 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 i3cCccENTAS1Direct(uint8_t address, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Sends the Direct Write ENTAS1 CCC.

Sends the ENTAS1 (Enter Activity State 1) Common Command Code (CCC) in direct mode to the specified target. This command instructs the addressed target to enter Activity State 1 (limited operating mode).

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:

address – The dynamic address of the target device.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – ENTAS1 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 i3cCccENTAS0Direct(uint8_t address, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Sends the Direct Write ENTAS0 CCC.

Sends the ENTAS0 (Enter Activity State 0) Common Command Code (CCC) in direct mode to the specified target. This command instructs the addressed target to enter Activity State 0 (normal operating mode).

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:

address – The dynamic address of the target device.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – ENTAS0 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 i3cCccRSTGRPADirect(uint8_t address, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Sends the Direct Write RSTGRPA CCC.

Sends the RSTGRPA (Reset Group Address) Common Command Code (CCC) in direct mode to the specified target. This command instructs the addressed target to clear its group address assignment.

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:

address – The dynamic address of the target device.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – RSTGRPA 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 i3cCccRSTACTDirect(uint8_t targetAddress, I3cTargetResetDefByte defByte, I3cTransferDirection direction, uint8_t *outValue = nullptr, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC 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.
SDK_ERROR_WRONG_RESPONSE – On a read transfer, the host adapter answered with a response carrying no payload byte. outValue is left untouched. A firmware error reported in such a response is returned in its place.

uint16_t i3cCccSETGRPADirect(uint8_t targetAddress, uint8_t grpa, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Sends the Direct Write SETGRPA CCC.

Sends the SETGRPA (Set Group Address) Common Command Code (CCC) in direct mode to the specified target. This command assigns a group address to the addressed 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 configured as an I3C controller.

Parameters:

targetAddress – The dynamic address of the target device.
grpa – The group address assignment byte to send to the target.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – SETGRPA 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, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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.
SDK_ERROR_WRONG_RESPONSE – The host adapter answered with a response too short to carry the Maximum Write Length. maxWriteLength is left untouched. A firmware error reported in such a response is returned in its place.

uint16_t i3cCccSETMWLBroadcast(uint16_t mwl, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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 i3cCccSETXTIMEBroadcast(uint8_t subCmdByte, const std::optional<std::vector<uint8_t>> &data = std::nullopt, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Set the exchange timing information for all targets (broadcast CCC).

Sends the SETXTIME (Set Exchange Timing Information) 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 SETXTIME CCC.
Devices that do not support this CCC may ignore the command.

Parameters:

subCmdByte – The sub-command byte for the SETXTIME command.
data – Additional data for the SETXTIME command, default is an empty list.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – SETXTIME 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 i3cCccSETBUSCONBroadcast(uint8_t context, const std::optional<std::vector<uint8_t>> &data = std::nullopt, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Set the bus context for all targets (broadcast CCC).

Sends the SETBUSCON (Set Bus Context) 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 SETBUSCON CCC.
Devices that do not support this CCC may ignore the command.

Parameters:

context – The bus context value to set for the targets.
data – Additional data for the SETBUSCON command.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – SETBUSCON 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 i3cCccSETXTIMEDirect(uint8_t targetAddress, uint8_t subCmdByte, const std::optional<std::vector<uint8_t>> &data = std::nullopt, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Set the exchange timing information for a specific target (direct CCC).

Sends the SETXTIME (Set Exchange Timing Information) 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:

targetAddress – The dynamic address of the target device.
subCmdByte – The sub-command byte for the SETXTIME command.
data – Additional data byte for the SETXTIME command, default is empty.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

Return values:

SUCCESS – SETXTIME 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 i3cCccSETMWLDirect(uint8_t address, uint16_t mwl, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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.
SDK_ERROR_WRONG_RESPONSE – The host adapter answered with a response too short to carry the Maximum Read Length, or one that declared an IBI payload length it did not carry. Both maxReadLength and ibiLength are left untouched. A firmware error reported in such a response is returned in its place.

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

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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.
flags – Bitmask of transfer options controlling the behavior of the CCC transaction. Only the following values from I3cTransferFlags are supported for CCC transfers:
- I3C_XFER_NONE: a STOP condition is issued after completion (default).
- I3C_XFER_NONSTOP: no STOP condition is issued after completion.
- I3C_XFER_START_WITH_7E is not valid for CCC transfers.

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.