# I3C API

This page aggregates all I3C-related functions for the C API.

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 CosmicSDK_I3cSetBusVoltage(CosmicSDK_Handle *handle, 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:

      - handle – Handle to the CosmicSDK instance.

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

    Return values:

      - SUCCESS – The bus voltage was successfully configured.

      - FW_VOLTAGE_OUT_OF_RANGE – The requested voltage value is outside the supported range.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cControllerInit(CosmicSDK_Handle *handle, I3cPushPullRate pushPullFrequency, I3cOpenDrainTransferRate openDrainFrequency, I2cTransferRate i2cOpenDrainFrequency, I3cDriveStrength driveStrength)

    Initializes the I3C controller.

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

    Note

    - This function must be called exactly once.

    - Calling any I3C API before initialization will result in `FW_INTERFACE_NOT_INITIALIZED`.

    - Calling this function more than once will result in `FW_INTERFACE_ALREADY_INITIALIZED`.

    - To modify the I3C configuration after initialization, use CosmicSDK_I3cSetParameters instead of reinitializing the interface.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - pushPullFrequency – The I3C SCL frequency in the push-pull phase. See I3cPushPullRate for supported values.

      - openDrainFrequency – The I3C SCL frequency in the open-drain phase. See I3cOpenDrainTransferRate for supported values.

      - i2cOpenDrainFrequency – The I2C SCL open drain frequency. See I2cTransferRate for supported values.

      - driveStrength – The drive strength configuration for the I3C pads. See I3cDriveStrength for supported values.

    Return values:

      - SUCCESS – I3C interphase was successfully initialized.

      - FW_INTERFACE_ALREADY_INITIALIZED – The I3C interface has already been initialized.

      - FW_INVALID_PARAMETER – One or more configuration parameters are invalid or unsupported.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cSetParameters(CosmicSDK_Handle *handle, I3cPushPullRate pushPullFrequency, I3cOpenDrainTransferRate openDrainFrequency, I2cTransferRate i2cOpenDrainFrequency, I3cDriveStrength driveStrength)

    Sets the I3C bus parameters.

    This function updates the I3C bus parameters after the I3C interface has been successfully initialized using CosmicSDK_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 CosmicSDK_I3cControllerInit.

    - Calling this function before UART initialization will result in `FW_INTERFACE_NOT_INITIALIZED`.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - pushPullFrequency – The I3C SCL frequency in the push-pull phase. See I3cPushPullRate for supported values.

      - openDrainFrequency – The I3C SCL frequency in the open-drain phase. See I3cOpenDrainTransferRate for supported values.

      - i2cOpenDrainFrequency – The I2C SCL open drain frequency. See I2cTransferRate for supported values.

      - driveStrength – The drive strength configuration for the I3C pads. See I3cDriveStrength for supported values.

    Return values:

      - SUCCESS – I3C parameters were successfully updated.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_INVALID_PARAMETER – One or more configuration parameters are invalid or unsupported.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cInitBus(CosmicSDK_Handle *handle, I3cTargetInfo *targets, uint8_t numberOfTargets)

    Initializes the I3C bus.

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

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

    - Assign a specific dynamic address to a known I3C target.

    - Register legacy I2C devices on the bus, which do not respond to the ENTDAA CCC.

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

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

    Note

    - This function must be called exactly once.

    - Calling any I3C API before initialization will result in `FW_INTERFACE_NOT_INITIALIZED`.

    - Calling this function more than once will result in `FW_INTERFACE_ALREADY_INITIALIZED`.

    - To modify the I3C configuration after initialization, use CosmicSDK_I3cSetParameters instead of reinitializing the interface.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

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

      - numberOfTargets – The quantity of devices on the targets array.

    Return values:

      - SUCCESS – I3C bus was successfully initialized.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_NOT_ENOUGH_SPACE_IN_TARGET_DEVICES_TABLE – The number of targets to be initialized surpassed the maximum allowed number of targets (11).

      - FW_INVALID_TARGET_ADDRESS – The address of one of the target devices is a reserved address.

      - FW_I3C_BUS_INIT_NACK_RSTDAA – One or more targets did not acknowledge the RSTDAA CCC during bus initialization.

      - FW_I3C_BUS_INIT_NACK_SETDASA – A target did not acknowledge the SETDASA CCC when assigning a dynamic address.

      - FW_I3C_BUS_INIT_NACK_SETAASA – A target did not acknowledge the SETAASA CCC when assigning a dynamic address.

      - FW_I3C_BUS_INIT_NACK_ENTDAA – One or more targets did not acknowledge or complete the ENTDAA CCC.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus during initialization.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cResetBus(CosmicSDK_Handle *handle)

    Resets the I3C bus.

    Issue the RSTDAA CCC and clear the target device table.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

    Return values:

      - SUCCESS – I3C bus was successfully resetted.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus during the reset.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cGetDeviceTable(CosmicSDK_Handle *handle, I3cTargetInfo *targets, uint8_t maxTargets, uint8_t *targetsQuantity)

    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:

      - handle – Handle to the CosmicSDK instance.

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

      - maxTargets – Maximum number of target entries that can be stored in the targets array.

      - targetsQuantity – The effective number of target on the bus, copied into the targets array argument.

    Return values:

      - SUCCESS – I3C device table successfully returned.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - SDK_ERROR_WRONG_REQUEST – `target` and/or `targetsQuantity` are NULL pointers.

  uint16_t CosmicSDK_I3cSetTargetDeviceConfiguration(CosmicSDK_Handle *handle, 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:

      - handle – Handle to the CosmicSDK instance.

      - address – Target address whose configuration will be set.

      - targetConfiguration – A dictionary containing the new configuration.

    Return values:

      - SUCCESS – I3C target device configuration updated.

      - FW_TARGET_ADDRESS_NOT_FOUND_IN_THE_TABLE – The Supernova’s stored target device table does not have the requested target address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cLegacyI2CWrite(CosmicSDK_Handle *handle, uint8_t address, const uint8_t *subAddress, uint8_t subAddressLength, const uint8_t *inData, uint16_t dataLength, I3cTransferFlags flags)

    Performs an I3C write using Legacy I2C mode.

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

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - address – The static address of the I2C target.

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

      - subAddressLength – The sub-address length.

      - inData – The data to be written to the device.

      - dataLength – The data length.

      - flags – Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can be combined using bitwise OR. See I3cTransferFlags for supported values.

    Return values:

      - SUCCESS – I3C data was successfully sent.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_I2C_NACK_BYTE – The I2C target NACKed the write data, terminating the message.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - SDK_ERROR_WRONG_REQUEST –

        - The `subAddressLength` parameter is greater than four or

        - the `subAddressLength` parameter is greater than zero but `subAddress` is NULL pointer or

        - the `dataLength` parameter is greater than zero but `subAddress` is NULL pointer.

  uint16_t CosmicSDK_I3cLegacyI2CRead(CosmicSDK_Handle *handle, uint8_t address, const uint8_t *subAddress, uint8_t subAddressLength, uint16_t readLength, uint8_t *outData, I3cTransferFlags flags)

    Performs an I3C read using Legacy I2C mode.

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

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - address – The static address of the I2C target.

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

      - subAddressLength – The sub-address length.

      - readLength – The length of data to be read.

      - outData – The buffer to store the read data.

      - flags – Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can be combined using bitwise OR. See I3cTransferFlags for supported values.

    Return values:

      - SUCCESS – I3C data was successfully read.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_I2C_NACK_BYTE – The I2C target NACKed the data.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - SDK_ERROR_WRONG_REQUEST –

        - The `subAddressLength` parameter is greater than four or

        - the `subAddressLength` parameter is greater than zero but `subAddress` is NULL pointer or

        - the `outData` parameter is NULL pointer.

  uint16_t CosmicSDK_I3cSdrWrite(CosmicSDK_Handle *handle, uint8_t address, const uint8_t *subAddress, uint8_t subAddressLength, const uint8_t *inData, uint16_t dataLength, I3cTransferFlags flags)

    Performs an I3C write in SDR mode.

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

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

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

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

      - subAddressLength – The sub-address length.

      - inData – The data to be written to the device.

      - dataLength – The data length

      - flags – Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can be combined using bitwise OR. See I3cTransferFlags for supported values.

    Return values:

      - SUCCESS – I3C data was successfully sent.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - SDK_ERROR_WRONG_REQUEST –

        - The `subAddressLength` is greater than four or

        - the `subAddressLength` is greater than zero but `subAddress` is NULL pointer or

        - the `dataLength` is greater than zero but `inData` is NULL pointer.

  uint16_t CosmicSDK_I3cSdrRead(CosmicSDK_Handle *handle, uint8_t address, const uint8_t *subAddress, uint8_t subAddressLength, uint16_t readLength, uint8_t *outData, uint16_t *outDataLength, I3cTransferFlags flags)

    Performs an I3C read in SDR mode.

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

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - address – The dynamic address of the I3C target.

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

      - subAddressLength – The sub-address length.

      - readLength – The length of data to be read.

      - outData – The buffer to store the read data.

      - outDataLength – The actual length of the data read.

      - flags – Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can be combined using bitwise OR. See I3cTransferFlags for supported values.

    Return values:

      - SUCCESS – I3C data was successfully read.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - SDK_ERROR_WRONG_REQUEST –

        - The `subAddressLength` parameter is greater than four or

        - the `subAddressLength` parameter is greater than zero but `subAddress` is NULL pointer or

        - the `outData` parameter and/or `outDataLength` parameter are NULL pointers.

  uint16_t CosmicSDK_I3cHdrDdrWrite(CosmicSDK_Handle *handle, uint8_t address, uint8_t command, const uint8_t *inData, uint16_t dataLength)

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

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

      - dataLength – Length of the data buffer.

    Return values:

      - SUCCESS – I3C data was successfully sent.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - SDK_ERROR_WRONG_REQUEST – The `dataLength` parameter is greater than zero but `subAddress` is NULL pointer.

  uint16_t CosmicSDK_I3cHdrDdrRead(CosmicSDK_Handle *handle, uint8_t address, uint8_t command, uint16_t readLength, uint16_t *outDataLength, uint8_t *outData)

    Performs an I3C read in HDR-DDR mode.

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

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - address – The dynamic address of the I3C target.

      - command – The HDR-DDR command byte. Must be in the range [0x80, 0xFF].

      - readLength – The length of the data to read. Must be a multiple of 2.

      - outData – The buffer where the received data will be stored.

      - outDataLength – The actual length of the data read.

    Return values:

      - SUCCESS – I3C data was successfully read.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - SDK_ERROR_WRONG_REQUEST – The `outData` parameter and/or `outDataLength` parameter are NULL pointers.

  uint16_t CosmicSDK_I3cTargetResetPattern(CosmicSDK_Handle *handle)

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

    - The reset action executed depends on the most recent RSTACT configuration, or the default reset behavior if none was configured.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

    Return values:

      - SUCCESS – I3C Target Reset Pattern emmitted successfully.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cHdrExitPattern(CosmicSDK_Handle *handle)

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

    - It must be issued while the bus is operating in HDR mode.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

    Return values:

      - SUCCESS – I3C Exit Pattern issued successfully.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cCccRSTDAA(CosmicSDK_Handle *handle)

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

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

    Unlike the CosmicSDK_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 CosmicSDK_I3cControllerInit.

    - After issuing RSTDAA, a new Dynamic Address Assignment (DAA) procedure must be executed before communicating with targets using dynamic addresses.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

    Return values:

      - SUCCESS – RSTDAA was successfully sent.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cCccENTDAA(CosmicSDK_Handle *handle)

    Enter Dynamic Address Assignment procedure (ENTDAA).

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

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

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

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

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

    Return values:

      - SUCCESS – The Dynamic Address Assignment procedure completed successfully.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_TARGET_DEVICES_TABLE_OVERFLOW – The number of targets answered to the ENTDAA is greater than the maximum allowed number of targets (11).

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cCccSETDASA(CosmicSDK_Handle *handle, uint8_t staticAddress, uint8_t dynamicAddress)

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

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

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

    Prior to issuing the CCC, the SDK validates that:

    - The requested dynamic address is not reserved.

    - The dynamic address is not already in use by another target.

    - There is available space in the internal target device table.

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - staticAddress – Static address of the target device.

      - dynamicAddress – Dynamic address to assign to the target.

    Return values:

      - SUCCESS – The dynamic address was successfully assigned and the device was added to the target device table.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_NOT_ENOUGH_SPACE_IN_TARGET_DEVICES_TABLE – The number of targets on the table is already the maximum allowed number of targets (11).

      - FW_INVALID_TARGET_ADDRESS – The dynamic address to be assigned is a reserved address.

      - FW_REPEATED_TARGET_ADDRESS – The dynamic address to be set is already used by a target on the bus.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cCccSETAASA(CosmicSDK_Handle *handle, const uint8_t *staticAddresses, size_t count)

    Set static address as dynamic address (SETAASA CCC).

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

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

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

    Prior to issuing the CCC, the SDK validates that:

    - None of the provided addresses are reserved.

    - There is sufficient space in the internal target device table to accommodate all new devices.

    Note

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

    - Only targets that support the SETAASA CCC will respond and adopt their static address as dynamic.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

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

      - count – Number of static addresses in the array.

    Return values:

      - SUCCESS – The CCC was successfully sent and the responding targets were added to the device table using their static address as dynamic address.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_NOT_ENOUGH_SPACE_IN_TARGET_DEVICES_TABLE – The number of targets on the table plus the number of targets on `staticAddresses` is greater than the maximum allowed number of targets (11).

      - FW_INVALID_TARGET_ADDRESS – One or more addresses are reserved addresses.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cCccSETNEWDA(CosmicSDK_Handle *handle, uint8_t oldDynamicAddress, uint8_t newDynamicAddress)

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

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

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

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

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

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - oldDynamicAddress – The dynamic address of the target.

      - newDynamicAddress – The new dynamic address for the target.

    Return values:

      - SUCCESS – The dynamic address was successfully updated on the target and in the device table.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_INVALID_TARGET_ADDRESS – The dynamic address to be assigned is a reserved address.

      - FW_REPEATED_TARGET_ADDRESS – The dynamic address to be set is already used by a target on the bus.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cCccGETPID(CosmicSDK_Handle *handle, uint8_t address, uint8_t *pid)

    Gets the PID of one target.

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

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

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - address – The dynamic address of the target device.

      - pid – Vector where the retrieved Provisional ID will be stored.

    Return values:

      - SUCCESS – Target PID was successfully gotten.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - SDK_ERROR_WRONG_REQUEST – The `pid` parameter is NULL pointer.

  uint16_t CosmicSDK_I3cCccGETBCR(CosmicSDK_Handle *handle, uint8_t address, uint8_t *bcr)

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

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

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

    Note

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

    - The output parameter `bcr` is updated only if the function returns SUCCESS.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - address – The dynamic address of the target device.

      - bcr – The Bus Characteristic Register of the target.

    Return values:

      - SUCCESS – Target BCR was successfully gotten.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - SDK_ERROR_WRONG_REQUEST – The `dcr` parameter is NULL pointer.

  uint16_t CosmicSDK_I3cCccGETDCR(CosmicSDK_Handle *handle, uint8_t address, uint8_t *dcr)

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

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

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

    Note

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

    - The output parameter `dcr` is updated only if the function returns SUCCESS.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - address – The dynamic address of the target device.

      - dcr – The Device Characteristic Register of the target.

    Return values:

      - SUCCESS – Target DCR was successfully gotten.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - SDK_ERROR_WRONG_REQUEST – The `dcr` parameter is NULL pointer.

  uint16_t CosmicSDK_I3cCccGETSTATUS(CosmicSDK_Handle *handle, uint8_t targetAddress, uint8_t *status, uint8_t *lenOut, bool hasDefByte, uint8_t defByte)

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

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

    Two formats of the GETSTATUS CCC are supported:

    - Format 1: If `defByte` is not provided, the command is issued without a defining byte and the target returns its default STATUS data.

    - Format 2: If `defByte` is provided, it is transmitted as the defining byte, and the target returns the STATUS data corresponding to that definition.

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - targetAddress – The dynamic address of the target device from which to get the STATUS.

      - status – Vector where the retrieved STATUS will be stored.

      - lenOut – Number of bytes returned.

      - hasDefByte – If true, defByte is used and Format 2 of the CCC is sent.

      - defByte – The defining byte for the GETSTATUS Format 2 version of the CCC. If not provided, the default value is None and it is assumed the Format 1 of the CCC.

    Return values:

      - SUCCESS – Target STATUS was successfully gotten.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - SDK_ERROR_WRONG_REQUEST – The `status` parameter and/or the `lenOut` parameter are NULL pointers.

  uint16_t CosmicSDK_I3cCccGETCAPS(CosmicSDK_Handle *handle, uint8_t targetAddress, uint8_t *caps, uint8_t *lenOut, bool hasDefByte, uint8_t defByte)

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

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

    Two formats of the GETCAPS CCC are supported:

    - Format 1: If `defByte` is not provided, the command is issued without a defining byte and the target returns its default CAPS data.

    - Format 2: If `defByte` is provided, it is transmitted as the defining byte, and the target returns the CAPS data corresponding to that definition.

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - targetAddress – The address of the target device from which to get the CAPS.

      - caps – Vector where the retrieved Optional Feature Capabilities (CAPS) will be stored.

      - lenOut – Number of bytes returned.

      - hasDefByte – If true, defByte is used and Format 2 of the CCC is sent.

      - defByte – The defining byte for the GETCAPS Format 2 version of the CCC. If not provided, the default value is None and it is assumed the Format 1 of the CCC.

    Return values:

      - SUCCESS – Target CAPS was successfully gotten.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - SDK_ERROR_WRONG_REQUEST – The `caps` parameter and/or the `lenOut` parameter are NULL pointers.

  uint16_t CosmicSDK_I3cCccRSTACTBroadcast(CosmicSDK_Handle *handle, I3cTargetResetDefByte defByte)

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

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

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

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

    Note

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

    - Devices that do not support the specified reset action may ignore the command.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

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

    Return values:

      - SUCCESS – RSTACT Broadcast was successfully sent.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cCccRSTACTDirect(CosmicSDK_Handle *handle, uint8_t targetAddress, I3cTargetResetDefByte defByte, I3cTransferDirection direction, uint8_t *outValue)

    Sends the Direct Write or Direct Read RSTACT CCC.

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

    The behavior depends on the selected `direction:`

    - Write transfer: The `defByte` specifies the reset action to be configured for the addressed target. The Target Reset Pattern is emitted within the same frame, causing the target to execute the specified reset action.

    - Read transfer: The command retrieves the reset recovery timing information from the addressed target, as defined by the I3C specification. The retrieved value is stored in `outValue` if provided.

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

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - targetAddress – The dynamic address of the target device.

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

      - direction – Indicates whether the command is a read or write transfer. See I3cTransferDirection for supported values.

      - outValue – Pointer where the retrieved reset recovery timing value will be stored when `direction` is read. Ignored for write transfers.

    Return values:

      - SUCCESS – RSTACT Direct was successfully sent and acknowledged by the addressed target.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - SDK_ERROR_WRONG_REQUEST – The `direction` is `READ` but `outValue` is NULL pointer.

  uint16_t CosmicSDK_I3cCccENECBroadcast(CosmicSDK_Handle *handle, const uint8_t events)

    Enable events for all targets (broadcast).

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

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

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

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

    Return values:

      - SUCCESS – ENEC Broadcast was successfully sent.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cCccENECDirect(CosmicSDK_Handle *handle, uint8_t address, const uint8_t events)

    Enable specific events on a single target (direct).

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

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

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - address – The dynamic address of the target device.

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

    Return values:

      - SUCCESS – ENEC Direct was successfully sent and acknowledged by the addressed target.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cCccDISECBroadcast(CosmicSDK_Handle *handle, const uint8_t events)

    Disable events for all targets (broadcast).

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

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

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

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

    Return values:

      - SUCCESS – DISEC Broadcast was successfully sent.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cCccDISECDirect(CosmicSDK_Handle *handle, uint8_t address, const uint8_t events)

    Disable specific events on a single target (direct).

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

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

    Note

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

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - address – The dynamic address of the target device.

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

    Return values:

      - SUCCESS – DISEC Direct was successfully sent and acknowledged by the addressed target.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cCccGETMWL(CosmicSDK_Handle *handle, uint8_t address, uint16_t *maxWriteLength)

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

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

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

    Note

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

    - The output parameter `maxWriteLength` is updated only if the function returns SUCCESS.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - address – The dynamic address of the target device.

      - maxWriteLength – The Maximum Write Length of the target.

    Return values:

      - SUCCESS – Target MWL was successfully gotten.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - CosmicSDK_I3cCccGETMWL – The `maxWriteLength` parameter is NULL pointer.

  uint16_t CosmicSDK_I3cCccSETMWLBroadcast(CosmicSDK_Handle *handle, uint16_t mwl)

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

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

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

    Note

    - This function is valid only when the host is initialized as an I3C controller with CosmicSDK_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:

      - handle – Handle to the CosmicSDK instance.

      - mwl – The Maximum Write Length.

    Return values:

      - SUCCESS – MLW Broadcast was successfully sent.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cCccSETMWLDirect(CosmicSDK_Handle *handle, uint8_t address, uint16_t mwl)

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

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

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

    Note

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

    - A return value of SUCCESS indicates that the CCC was transmitted successfully and acknowledged by the addressed target.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - address – The dynamic address of the target device.

      - mwl – The Maximum Write Length for the target.

    Return values:

      - SUCCESS – MWL Direct was successfully sent and acknowledged by the addressed target.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cCccGETMRL(CosmicSDK_Handle *handle, uint8_t address, uint16_t *maxReadLength, uint8_t *ibiLength, bool *ibiLengthReturned)

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

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

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

    Note

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

    - The output parameters `maxReadLength` and `ibiLength` are updated only if the function returns SUCCESS.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - address – The dynamic address of the target device.

      - maxReadLength – The Maximum Read Length of the target.

      - ibiLength – (optional) Set to the maximum IBI payload length if supported by the target, or reset if the target does not support IBI payloads.

      - ibiLengthReturned – Flag indicating if the target responded with IBI Length information. If the target does not support IBI, a NULL pointer could be passed.

    Return values:

      - SUCCESS – Target MRL was successfully gotten.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

      - CosmicSDK_I3cCccGETMWL – The `maxReadLength` parameter is NULL pointer.

  uint16_t CosmicSDK_I3cCccSETMRLBroadcast(CosmicSDK_Handle *handle, uint16_t mrl, bool hasIbiLength, uint8_t ibiLength)

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

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

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

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

    Note

    - This function is valid only when the host is initialized as an I3C controller with CosmicSDK_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:

      - handle – Handle to the CosmicSDK instance.

      - mrl – The Maximum Read Length.

      - hasIbiLength – If true, send the CCC with an IBI payload length.

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

    Return values:

      - SUCCESS – MRL Broadcast was successfully sent.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – None target acknowledged the broadcast address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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

  uint16_t CosmicSDK_I3cCccSETMRLDirect(CosmicSDK_Handle *handle, uint8_t address, uint16_t mrl, bool hasIbiLength, uint8_t ibiLength)

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

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

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

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

    Note

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

    - The IBI payload length field is included in the CCC only when `ibiLength` contains a value.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - address – The dynamic address of the target device.

      - mrl – The Maximum Read Length for the target.

      - hasIbiLength – If true, send the CCC with an IBI payload length.

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

    Return values:

      - SUCCESS – MRL Direct was successfully sent and acknowledged by the addressed target.

      - FW_INTERFACE_NOT_INITIALIZED – The I3C interface has not been initialized.

      - FW_INVALID_COMMAND – The host device was initialized as a target device instead of a controller device.

      - FW_BUS_TIMEOUT – A timeout occurred while waiting for a response on the I3C bus.

      - FW_I3C_NACK_ADDRESS – The target NACKed the address.

      - SDK_ERROR_TIMEOUT – The operation timed out.

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