I3C API

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

Note

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

group CosmicSDK I3C API

Constants and APIs related to I3C operations.

Functions

uint16_t i3cSetBusVoltage(uint16_t id, uint16_t voltage_mV)

Set the I3C bus supply voltage (VTARG).

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

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

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

Note

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

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
voltage_mV – Voltage in millivolts to set the I3C bus to. Valid values are 0 mV or any value between 800 mV and 3300 mV.

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cControllerInit(uint16_t id, uint8_t pushPullFrequency, uint8_t openDrainFrequency, uint8_t i2cOpenDrainFrequency, uint8_t driveStrength)

Initializes the I3C controller.

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

Note

This function must be called exactly once.
To modify the I3C configuration after initialization, use i3cSetParameters instead of reinitializing the interface.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
pushPullFrequency – The I3C SCL frequency in the push-pull phase. See I3cPushPullRate for supported values.
openDrainFrequency – The I3C SCL frequency in the open-drain phase. See I3cOpenDrainTransferRate for supported values.
i2cOpenDrainFrequency – The I2C SCL open drain frequency. See I2cTransferRate for supported values.
driveStrength – The drive strength configuration for the I3C pads. See I3cDriveStrength for supported values.

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cSetParameters(uint16_t id, uint8_t pushPullFrequency, uint8_t openDrainFrequency, uint8_t i2cOpenDrainFrequency, uint8_t driveStrength)

Sets the I3C bus parameters.

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

Note

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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
pushPullFrequency – The I3C SCL frequency in the push-pull phase. See I3cPushPullRate for supported values.
openDrainFrequency – The I3C SCL frequency in the open-drain phase. See I3cOpenDrainTransferRate for supported values.
i2cOpenDrainFrequency – The I2C SCL open drain frequency. See I2cTransferRate for supported values.
driveStrength – The drive strength configuration for the I3C pads. See I3cDriveStrength for supported values.

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

Initializes the I3C bus.

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

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

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

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

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

Note

This function must be called exactly once.
To modify the I3C configuration after initialization, use i3cSetParameters instead of reinitializing the interface.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
targets – A vector containing information about the target devices connected to the I3C bus. See I3cTargetInfo for valid table entry format.

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cResetBus(uint16_t id)

Resets the I3C bus.

Issue the RSTDAA CCC and clear the target device table.

Parameters:

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

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cGetDeviceTable(uint16_t id)

Get the target device table stored internally in the Supernova.

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

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

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

Note

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

Parameters:

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

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cSetTargetDeviceConfiguration(uint16_t id, uint8_t address, I3cTargetConfiguration targetConfiguration)

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

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

Note

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

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – Target address whose configuration will be set.
targetConfiguration – A dictionary containing the new configuration.

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

Performs an I3C write using Legacy I2C mode.

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

Note

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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The static address of the I2C target.
subAddress – The optional sub-address to write to.
inData – The data to be written to the device.
flags – Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can be combined using bitwise OR. 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

Performs an I3C read using Legacy I2C mode.

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

Note

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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The static address of the I2C target.
subAddress – The optional sub-address to write to.
readLength – The length of data to be read.
flags – Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can be combined using bitwise OR. 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cSetI2cClockStretching(uint16_t id, bool enable, uint32_t frequency_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.

Note

Firmware 4.5.x and older answer FW_UNSUPPORTED_COMMAND.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 the reply.

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cHoldSclLow(uint16_t id, uint32_t duration_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 response arrives after the hold plus up to 35 ms; it carries the result (SUCCESS, FW_INVALID_PARAMETER for 0 or above 1000000 us, FW_INTERFACE_NOT_INITIALIZED, FW_BUS_TIMEOUT when SCL is still low 35 ms after the release) and a uint32_t with the measured hold in microseconds. Firmware that predates this command answers FW_UNSUPPORTED_COMMAND with no parameters.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
duration_us – How long to hold SCL low, in microseconds, 1 to 1000000.

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cSetSdaPullUp(uint16_t id, I3cSdaPullUp mode)

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.

The response carries the result (SUCCESS, or FW_INVALID_PARAMETER for a value above 2) and one byte with the stored setting (it governs the pull-up only while clock stretching is on). Firmware that predates this command answers FW_UNSUPPORTED_COMMAND with no parameters.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
mode – I3C_SDA_PULLUP_AUTO, I3C_SDA_PULLUP_OFF or I3C_SDA_PULLUP_ON.

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cSdrWrite(uint16_t id, uint8_t address, const std::vector<uint8_t> &subAddress, const std::vector<uint8_t> &inData, I3cTransferFlags flags = 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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the I3C target, or the group address.
subAddress – The optional sub-address to write to.
inData – The data to be written to the device.
flags – Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can be combined using bitwise OR. 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the I3C target.
subAddress – The optional sub-address to write to.
readLength – The length of data to be read.
flags – Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can be combined using bitwise OR. 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cHdrDdrWrite(uint16_t id, uint8_t address, uint8_t command, const std::vector<uint8_t> &inData, 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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the I3C target.
command – The HDR-DDR command byte. Must be in the range [0x00, 0x7F].
inData – The data payload to be written. The payload length must be a multiple of 2.
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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cHdrDdrRead(uint16_t id, uint8_t address, uint8_t command, uint16_t readLength, 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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the I3C target.
command – The HDR-DDR command byte. Must be in the range [0x80, 0xFF].
readLength – The length of the data to read. Must be a multiple of 2.
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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

Identical to i3cSdrWrite except for the command code and where inData travels: the request carries only the addressing, and the payload is streamed on the vendor OUT endpoint immediately afterwards — before waiting for the reply, because the firmware is already blocked receiving on the endpoint by then.

This is the 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.

Note

Valid only when the host is initialized as an I3C controller with i3cControllerInit.
Requires the vendor bulk transport; see isBulkAvailable. This is the low-level entry point and does not consult the device’s capability record — CosmicSDK::i3cSdrWriteBulk does.
The register address shares the frame with the payload on a write, so the usable payload is the device’s ceiling minus subAddress.size().

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the I3C target.
subAddress – The optional register address to write to. At most 4 bytes.
inData – The data to be written; must be non-empty and within I3C_BULK_MAX_PAYLOAD.
flags – Bitmask of transfer options (see I3cTransferFlags).

Return values:

SUCCESS – The command was sent and the payload was accepted by the endpoint.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.
SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable (not claimed, or unsupported by the firmware).
SDK_ERROR_WRONG_REQUEST – subAddress is longer than 4 bytes, or inData is empty or over the bulk ceiling.
SDK_ERROR_TIMEOUT – Streaming inData over the bulk endpoint timed out.

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

Starts an I3C SDR read whose data phase returns on the vendor bulk endpoint.

Identical to i3cSdrRead except for the command code and where the data comes back: the reply announces the length and the bytes arrive on the vendor IN endpoint. Collect them with receivePayload after the reply — only the reply says how many bytes are coming.

Unlike a write, the register address goes out in its own frame before the read, so it does not count against the payload ceiling.

Note

Valid only when the host is initialized as an I3C controller with i3cControllerInit.
Requires the vendor bulk transport; see isBulkAvailable. This is the low-level entry point and does not consult the device’s capability record — CosmicSDK::i3cSdrReadBulk does.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the I3C target.
subAddress – The optional register address to read from. At most 4 bytes.
readLength – The length of data to be read; must be non-zero and within I3C_BULK_MAX_PAYLOAD.
flags – Bitmask of transfer options (see I3cTransferFlags).

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.
SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable (not claimed, or unsupported by the firmware).
SDK_ERROR_WRONG_REQUEST – subAddress is longer than 4 bytes, or readLength is zero or over the bulk ceiling.

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

Identical to i3cHdrDdrWrite except for the command code and the payload route.

Note

Valid only when the host is initialized as an I3C controller with i3cControllerInit.
Requires the vendor bulk transport; see isBulkAvailable.
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 HID. 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 the capability record advertises the much larger GROUP_I3C ceiling, which does not apply to this mode. The entry point exists so the route is complete and so lifting the cap later is a one-line change rather than a new API.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the I3C target.
command – The HDR-DDR command byte. Must be in the range [0x80, 0xFF].
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 command was sent and the payload was accepted by the endpoint.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.
SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable (not claimed, or unsupported by the firmware).
SDK_ERROR_WRONG_REQUEST – inData is empty, odd-length, or over I3C_HDR_DDR_MAX_PAYLOAD.
SDK_ERROR_TIMEOUT – Streaming inData over the bulk endpoint timed out.

uint16_t i3cHdrDdrReadBulk(uint16_t id, uint8_t address, uint8_t command, uint16_t readLength, I3cTransferFlags flags = I3C_XFER_NONE)

Starts an I3C HDR-DDR read whose data phase returns on the vendor bulk endpoint.

Identical to i3cHdrDdrRead except for the command code and the data route.

Note

Valid only when the host is initialized as an I3C controller with i3cControllerInit.
Requires the vendor bulk transport; see isBulkAvailable.

Warning

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

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the I3C target.
command – The HDR-DDR command byte. Must be in the range [0x80, 0xFF].
readLength – The length of the data to read. Must be a non-zero multiple of 2 and within I3C_HDR_DDR_MAX_PAYLOAD.
flags – Bitmask of transfer options (see I3cTransferFlags).

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.
SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable (not claimed, or unsupported by the firmware).
SDK_ERROR_WRONG_REQUEST – readLength is zero, odd, or over I3C_HDR_DDR_MAX_PAYLOAD.

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

Identical to i3cLegacyI2cWrite except for the command code and the payload route. Provided so the bulk route covers every mode the non-bulk API offers; a legacy I2C target on an I3C bus is bounded by its own bus rate long before the transport matters, so expect the gain to be smaller here than for i3cSdrWriteBulk.

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.
Requires the vendor bulk transport; see isBulkAvailable.
As with SDR, the register address shares the frame with the payload on a write.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The static address of the 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 I3C_BULK_MAX_PAYLOAD.
flags – Bitmask of transfer options (see I3cTransferFlags).

Return values:

SUCCESS – The command was sent and the payload was accepted by the endpoint.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.
SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable (not claimed, or unsupported by the firmware).
SDK_ERROR_WRONG_REQUEST – subAddress is longer than 4 bytes, or inData is empty or over the bulk ceiling.
SDK_ERROR_TIMEOUT – Streaming inData over the bulk endpoint timed out.

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

Starts a legacy I2C read on the I3C bus whose data phase returns on the vendor bulk endpoint.

Identical to i3cLegacyI2cRead except for the command code and the data route. Collect the payload with receivePayload after the reply announces its length.

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.
Requires the vendor bulk transport; see isBulkAvailable.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The static address of the 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 I3C_BULK_MAX_PAYLOAD.
flags – Bitmask of transfer options (see I3cTransferFlags).

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.
SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable (not claimed, or unsupported by the firmware).
SDK_ERROR_WRONG_REQUEST – subAddress is longer than 4 bytes, or readLength is zero or over the bulk ceiling.

uint16_t i3cTargetResetPattern(uint16_t id)

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

Emits the I3C Target Reset Pattern on the bus.

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

Note

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

Parameters:

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

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cHdrExitPattern(uint16_t id)

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

Emits the I3C HDR Exit Pattern on the bus.

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

Note

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

Parameters:

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

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cTargetInit(uint16_t id, 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 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.
Unlike i3cControllerInit, this command re-initializes the I3C peripheral unconditionally. 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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 command was successfully sent to the host adapter.
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_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 command was successfully sent to the host adapter.
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_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cTargetWriteMemory(uint16_t id, 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.
The host adapter must have been initialized as an I3C target device with i3cTargetInit beforehand.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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. 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.
data – The data to be written into the target memory. The maximum size is I3C_TARGET_MEMORY_SIZE bytes.

Return values:

SUCCESS – The command was successfully sent to the host adapter.
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_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cTargetReadMemory(uint16_t id, uint16_t memoryAddress, uint16_t length)

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.

The data read is delivered in the payload of the command response, see I3cTargetTransferMemoryResponse.

Note

This command is implemented by the firmware from FW4.1.1 onwards.
The host adapter must have been initialized as an I3C target device with i3cTargetInit beforehand.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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. 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.
length – Number of bytes to read from the target memory. The maximum value is I3C_TARGET_MEMORY_SIZE.

Return values:

SUCCESS – The command was successfully sent to the host adapter.
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_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

Perform a CCC transfer.

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

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – Target dynamic address on the I3C bus.
direction – Data transfer direction (read or write). See I3cTransferDirection for supported values.
mode – I3C transfer mode used for the transaction. See I3cTransferMode for supported values.
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.
- I3C_XFER_NONSTOP: no STOP condition is issued after completion. I3C_XFER_START_WITH_7E is not valid for CCC transfers.
type – Type of CCC command, indicating whether a defining byte is used. See I3cCccType for supported values.
payloadLength – Length in bytes of the CCC payload.
ccc – The specific CCC to send to the target. See CCC for supported values.
definingByte – Optional defining byte associated with the CCC, if required by the command type.
inData – The data to be transferred for write transfers.

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

Reset Dynamic Address Assignment (RSTDAA CCC).

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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccENTDAA(uint16_t id, std::vector<I3cTargetInfo> targets = {})

Enter Dynamic Address Assignment procedure (ENTDAA CCC).

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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccSETNEWDA(uint16_t id, uint8_t oldDynamicAddress, uint8_t newDynamicAddress, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Set a new Dynamic Address for a target (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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccENECBroadcast(uint16_t id, uint8_t events, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Enable events for all targets (ENEC broadcast CCC).

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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccENECDirect(uint16_t id, uint8_t address, uint8_t events, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Enable specific events on a single target (ENEC direct CCC).

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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccDISECBroadcast(uint16_t id, uint8_t events, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Disable events for all targets (DISEC broadcast CCC).

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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccDISECDirect(uint16_t id, uint8_t address, uint8_t events, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Disable specific events on a single target (DISEC direct CCC).

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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

Set the Maximum Write Length (MWL) for all targets (SETMWL 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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccSETMWLDirect(uint16_t id, uint8_t address, uint16_t mwl, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Set the Maximum Write Length (MWL) for a specific target (SETMWL 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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccGETMWL(uint16_t id, uint8_t address, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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

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

The retrieved Maximum Write Length value is delivered via the response callback.

Note

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

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccGETMRL(uint16_t id, uint8_t address, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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

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.

The retrieved Maximum Read Length (and optional IBI payload length) is delivered via the response callback.

Note

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

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccGETPID(uint16_t id, uint8_t address, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Gets the PID of one target (GETPID CCC).

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

The retrieved Provisional ID is delivered via the response callback.

Note

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

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccGETBCR(uint16_t id, uint8_t address, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

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

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

The retrieved BCR value is delivered via the response callback.

Note

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

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

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

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

The retrieved DCR value is delivered via the response callback.

Note

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

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccGETMXDS(uint16_t id, uint8_t targetAddress, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Get the Maximum Data Speed (MXDS) from a target (GETMXDS CCC).

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

The retrieved Maximum Data Speed data is delivered via the response callback.

Note

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

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
targetAddress – The address of the target device from which to get the MXDS.
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 command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccGETXTIME(uint16_t id, uint8_t targetAddress, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Get the Exchange Timing Support (XTIME) from a target (GETXTIME CCC).

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

The retrieved Exchange Timing data is delivered via the response callback.

Note

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

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
targetAddress – The address of the target device from which to get the XTIME data.
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 command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccGETCAPS(uint16_t id, uint8_t targetAddress, std::optional<uint8_t> defByte = std::nullopt, I3cTransferFlags flags = I3cTransferFlags::I3C_XFER_NONE)

Get the Optional Feature Capabilities (CAPS) from a target (GETCAPS CCC).

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.

The retrieved Optional Feature Capabilities data is delivered via the response callback.

Note

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

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
targetAddress – The address of the target device from which to get the CAPS.
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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

Gets the STATUS from a target device on the I3C bus (GETSTATUS CCC).

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.

The retrieved STATUS data is delivered via the response callback.

Note

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

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
targetAddress – The dynamic address of the target device from which to get the STATUS.
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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t i3cCccRSTACTDirect(uint16_t id, uint8_t targetAddress, I3cTargetResetDefByte defByte, I3cTransferDirection direction, 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 delivered via the response callback.

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:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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.
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 command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
address – The dynamic address of the 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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

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

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
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 – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.