I2C API

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

group CosmicSDK I2C API

Constants and APIs related to I2C operations.

Functions

uint16_t CosmicSDK_I2cSetBusVoltage(CosmicSDK_Handle *handle, uint16_t voltage_mV, bool persist)

Sets the I2C bus voltage.

Warning

On Supernova and Pulsar host adapters, the I2C interface shares the same voltage domain as SPI, UART and GPIOs. As a result, calling this method to set the I2C voltage will also affect the voltage of SPI, UART and GPIO interfaces. This must be taken into account when more than one interfaces are used simultaneously.

Parameters:

• handle – Handle to the CosmicSDK instance.

• voltage_mV – Voltage in millivolts to set the I2C bus to. The valid values are 0 mV, and any value in the range 1200 to 3300 mV. The value 0mV deactivates the VTARG pin and turn offs the downstream devices.

• persist – If true, the voltage setting will be persistent across power cycles. This ensures that any DUT connected to the I2C bus (e.g. via Pulsar or Supernova) will receive power immediately upon startup, without waiting for the host to issue the voltage set command. If false, the setting will only apply to the current session.

Return values:

• SUCCESS – Voltage successfully configured.

• FW_VOLTAGE_OUT_OF_RANGE – If the requested voltage is outside the valid range.

• FW_VOLTAGE_ADJUSTMENT_FAILURE – If the voltage could not be applied.

• SDK_ERROR_TIMEOUT – The operation timed out.

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

uint16_t CosmicSDK_I2cControllerInit(CosmicSDK_Handle *handle, uint8_t bus, uint32_t frequency_Hz, uint8_t pullUpResistor)

Initializes the I2C controller.

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

Note

• This function must be called exactly once.

• Calling any I2C 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 I2C configuration after initialization, use CosmicSDK_I2cSetParameters instead of reinitializing the interface.

Parameters:

• handle – Handle to the CosmicSDK instance.

• bus – I2C bus number (e.g., 0 for I2C_BUS_A). Valid values are defined in definitions.h (e.g., I2C_BUS_A, I2C_BUS_B).

• frequency_Hz – The I2C bus frequency in Hz (e.g., 400000 for 400kHz).

• pullUpResistor – The pull-up resistor value. Valid values are defined in definitions.h (e.g., I2C_PULLUP_330Ohm).

Return values:

• SUCCESS – I2C interphase was successfully initialized.

• FW_INTERFACE_ALREADY_INITIALIZED – The I2C interface has already been initialized.

• FW_BUS_NOT_SUPPORTED – The bus value is not valid.

• FW_INVALID_PARAMETER – The pullUpResistor value is not valid.

• SDK_ERROR_TIMEOUT – The operation timed out.

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

uint16_t CosmicSDK_I2cSetParameters(CosmicSDK_Handle *handle, uint8_t bus, uint32_t frequency_Hz, uint8_t pullUpResistor)

Sets the I2C bus parameters.

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

Note

• This function must only be called after a successful call to CosmicSDK_I2cControllerInit.

• Calling this function before UART initialization will result in FW_INTERFACE_NOT_INITIALIZED.

Parameters:

• handle – Handle to the CosmicSDK instance.

• bus – I2C bus number (e.g., 0 for I2C_BUS_A). Valid values are defined in definitions.h (e.g., I2C_BUS_A, I2C_BUS_B).

• frequency_Hz – The I2C bus frequency in Hz (e.g., 400000 for 400kHz).

• pullUpResistor – The pull-up resistor value. Valid values are defined in definitions.h (e.g., I2C_PULLUP_330Ohm).

Return values:

• SUCCESS – I2C parameters were successfully updated.

• FW_FEATURE_NOT_SUPPORTED_BY_HARDWARE – The device is Supernova and the hardware revision is previous to ‘C’.

• FW_I2C_PULLUP_RESISTOR_SETTING_FAILURE – The firmware failed to set the Pull Up Resistor.

• FW_INVALID_PARAMETER – The pullUpResistor value is not valid.

• FW_INTERFACE_NOT_INITIALIZED – The I2C interface has not been initialized.

• FW_BUS_NOT_SUPPORTED – The specified bus is not valid or not supported by the hardware.

• SDK_ERROR_TIMEOUT – The operation timed out.

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

uint16_t CosmicSDK_I2cSetPullUpResistors(CosmicSDK_Handle *handle, uint8_t bus, uint8_t value)

Sets the I2C pull-up resistors.

Configures the internal pull-up resistors connected to the selected I2C bus. The specified value determines the effective pull-up strength according to the hardware capabilities and predefined settings.

Note

• This function must only be called after a successful call to CosmicSDK_I2cControllerInit.

• On some hardware revisions, this feature may not be available.

Parameters:

• handle – Handle to the CosmicSDK instance.

• bus – I2C bus number (e.g., 0 for I2C_BUS_A). Valid values are defined in definitions.h (e.g., I2C_BUS_A, I2C_BUS_B).

• value – The value of the pull-up resistors to be set. Valid values are defined in definitions.h (e.g., I2C_PULLUP_NONE, I2C_PULLUP_330Ohm, I2C_PULLUP_1kOhm).

Return values:

• SUCCESS – I2C Pull Up Resistors were successfully updated.

• FW_BUS_NOT_SUPPORTED – The specified bus is not valid or not supported by the hardware.

• FW_INTERFACE_NOT_INITIALIZED – The I2C interface has not been initialized.

• FW_FEATURE_NOT_SUPPORTED_BY_HARDWARE – The device is Supernova and the hardware revision is previous to ‘C’.

• FW_I2C_PULLUP_RESISTOR_SETTING_FAILURE – The firmware failed to set the Pull Up Resistor.

• FW_INVALID_PARAMETER – The value is not valid.

• SDK_ERROR_TIMEOUT – The operation timed out.

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

uint16_t CosmicSDK_I2cWrite(CosmicSDK_Handle *handle, uint8_t bus, uint8_t address, const uint8_t *subAddress, uint8_t subAddressLength, const uint8_t *inData, uint32_t dataLength, bool nonStop)

Writes data to an I2C device at an optional subAddress.

Writes data to an I2C target , optionally including an internal subaddress on the target device.

Note

• This function is valid only when the host is initialized as an I2C controller with CosmicSDK_I2cControllerInit.

Parameters:

• handle – Handle to the CosmicSDK instance.

• bus – I2C bus number (e.g., 0 for I2C_BUS_A). Valid values are defined in definitions.h (e.g., I2C_BUS_A, I2C_BUS_B).

• address – The I2C address of the device.

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

• subAddressLength – Length of sub-address array (0-4 bytes).

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

• dataLength – Length of data to write.

• nonStop – If true, the operation will not stop after writing.

Return values:

• SUCCESS – The write transaction completed successfully.

• FW_INTERFACE_NOT_INITIALIZED – The I2C interface has not been initialized.

• FW_BUS_NOT_SUPPORTED – The specified bus is not valid or not supported by the hardware.

• FW_I2C_BUSY – The I2C bus is currently busy and the transfer could not be started.

• FW_I2C_NACK_ADDRESS – The target device did not acknowledge its address.

• FW_I2C_NACK_BYTE – A data byte was not acknowledged by the target device.

• FW_I2C_INVALID_PARAMETER – One or more input parameters are invalid (e.g., empty data buffer when required, invalid address, or unsupported configuration).

• FW_I2C_BIT_ERROR – A bit-level error occurred during the transfer (unexpected bus state).

• FW_I2C_ARBITRATION_LOST – Arbitration was lost during the transfer in multi-master mode.

• FW_I2C_NO_TRANSFER_IN_PROGRESS – An operation requiring an active transfer was requested but no transfer was in progress.

• FW_I2C_DMA_REQUEST_FAIL – The DMA request could not be serviced.

• FW_I2C_START_STOP_ERROR – An error occurred while generating a START or STOP condition.

• FW_I2C_UNEXPECTED_STATE – The I2C peripheral entered an unexpected internal state.

• FW_I2C_TIMEOUT_CONTINUE_TRANSFER – Timeout occurred while attempting to continue an ongoing transfer.

• FW_I2C_TIMEOUT_WAITING_BUS_EVENT – Timeout while waiting for a bus event (e.g., TXE, RXNE, BTF).

• FW_I2C_TIMEOUT_SCL_LOW – Timeout detected due to SCL being held low (possible clock stretching or bus lock condition).

• 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_I2cRead(CosmicSDK_Handle *handle, uint8_t bus, uint8_t address, const uint8_t *subAddress, uint8_t subAddressLength, uint16_t readLength, uint8_t *outData, bool nonStop)

Reads data from an I2C device at an optional subAddress.

Reads data from an I2C target, 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 I2C controller with CosmicSDK_I2cControllerInit.

Parameters:

• handle – Handle to the CosmicSDK instance.

• bus – I2C bus number (e.g., 0 for I2C_BUS_A). Valid values are defined in definitions.h (e.g., I2C_BUS_A, I2C_BUS_B).

• address – The I2C address of the device.

• subAddress – The optional sub-address to read from.

• subAddressLength – Length of sub-address array (0-4 bytes).

• readLength – The length of data to be read.

• outData – The buffer to store the read data.

• nonStop – If true, the operation will not stop after reading.

Return values:

• SUCCESS – The read transaction completed successfully.

• FW_INTERFACE_NOT_INITIALIZED – The I2C interface has not been initialized.

• FW_BUS_NOT_SUPPORTED – The specified bus is not valid or not supported by the hardware.

• FW_I2C_BUSY – The I2C bus is currently busy and the transfer could not be started.

• FW_I2C_NACK_ADDRESS – The target device did not acknowledge its address.

• FW_I2C_NACK_BYTE – A data byte was not acknowledged by the target device.

• FW_I2C_INVALID_PARAMETER – One or more input parameters are invalid (e.g., empty data buffer when required, invalid address, or unsupported configuration).

• FW_I2C_BIT_ERROR – A bit-level error occurred during the transfer (unexpected bus state).

• FW_I2C_ARBITRATION_LOST – Arbitration was lost during the transfer in multi-master mode.

• FW_I2C_NO_TRANSFER_IN_PROGRESS – An operation requiring an active transfer was requested but no transfer was in progress.

• FW_I2C_DMA_REQUEST_FAIL – The DMA request could not be serviced.

• FW_I2C_START_STOP_ERROR – An error occurred while generating a START or STOP condition.

• FW_I2C_UNEXPECTED_STATE – The I2C peripheral entered an unexpected internal state.

• FW_I2C_TIMEOUT_CONTINUE_TRANSFER – Timeout occurred while attempting to continue an ongoing transfer.

• FW_I2C_TIMEOUT_WAITING_BUS_EVENT – Timeout while waiting for a bus event (e.g., TXE, RXNE, BTF).

• FW_I2C_TIMEOUT_SCL_LOW – Timeout detected due to SCL being held low (possible clock stretching or bus lock condition).

• 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_I2cScanBus(CosmicSDK_Handle *handle, uint8_t *deviceAddresses, uint8_t deviceAddressesLength, uint8_t *count7BitAddresses, uint8_t *count10BitAddresses, uint8_t bus, bool include10BitAddresses)

Request to the the host device to perform an I2C scan of the I2C bus and return the list of discovered static addresses.

Initiates an address scan on the selected I2C bus to detect connected target devices. The scan probes valid address ranges and collects the addresses of devices that acknowledge their address.

Discovered addresses are returned in deviceAddresses following this order:

• All detected 7-bit addresses first (1 byte per address).

• All detected 10-bit addresses afterwards (2 bytes per address, high byte first).

The total number of detected 7-bit and 10-bit devices is returned separately via count7BitAddresses and count10BitAddresses.

Note

• This function is valid only when the host is initialized as an I2C controller with CosmicSDK_I2cControllerInit.

Warning

Depending on the bus characteristics, such as frequency, voltage, number of targets connected, and the length of the wires used in the hardware setup, the performance of the I2C SCAN BUS may be affected, and as a result, it might return a wrong list of detected addresses, an SDK_ERROR_TIMEOUT error, and the firmware might indeed get stuck, especially in the Pulsar. In order to avoid this scenario, consider the following recommendations to run a smooth scan bus procedure:

• Set the clock frequency to low values, such as 100KHz and 400 KHz.

• Disable the pull-up resistors, or set their value to high values - weak pull-ups.

  • In the case of the Pulsar, suggested values are: I2C_PULLUP_DISABLE , I2C_PULLUP_4kOhm, or I2C_PULLUP_2_2kOhm

  • In the case of the Supernova, suggested values are: I2C_PULLUP_DISABLE , I2C_PULLUP_10kOhm, or I2C_PULLUP_4_7kOhm

Parameters:

• handle – Handle to the CosmicSDK instance.

• deviceAddresses – Buffer to store all the device addresses found by the scan bus. The addresses are stored in the following way:

  • 7-bit addresses first.

  • 10-bit addresses at the end.

  • Each 10-bit address uses two bytes of the buffer (high byte first).

• deviceAddressesLength – Capacity of deviceAddresses.

• count7BitAddresses – Variable to store the number of 7-bit addresses discovered.

• count10BitAddresses – Variable to store the number of 10-bit addresses discovered.

• bus – I2C bus number (e.g., 0 for I2C_BUS_A). Valid values are defined in definitions.h (e.g., I2C_BUS_A, I2C_BUS_B).

• include10BitAddresses – Indicates if the scan must include 10-bit addresses.

Return values:

• SUCCESS – The Scan Bus completed successfully.

• FW_INTERFACE_NOT_INITIALIZED – The I2C interface has not been initialized.

• FW_BUS_NOT_SUPPORTED – The specified bus is not valid or not supported by the hardware.

• FW_I2C_BUS_WITH_NO_TARGETS_CONNECTED – No target device detected.

• FW_I2C_BUSY – The I2C bus is currently busy and the transfer could not be started.

• FW_I2C_NACK_ADDRESS – The target device did not acknowledge its address.

• FW_I2C_NACK_BYTE – A data byte was not acknowledged by the target device.

• FW_I2C_INVALID_PARAMETER – One or more input parameters are invalid (e.g., empty data buffer when required, invalid address, or unsupported configuration).

• FW_I2C_BIT_ERROR – A bit-level error occurred during the transfer (unexpected bus state).

• FW_I2C_ARBITRATION_LOST – Arbitration was lost during the transfer in multi-master mode.

• FW_I2C_NO_TRANSFER_IN_PROGRESS – An operation requiring an active transfer was requested but no transfer was in progress.

• FW_I2C_DMA_REQUEST_FAIL – The DMA request could not be serviced.

• FW_I2C_START_STOP_ERROR – An error occurred while generating a START or STOP condition.

• FW_I2C_UNEXPECTED_STATE – The I2C peripheral entered an unexpected internal state.

• FW_I2C_TIMEOUT_CONTINUE_TRANSFER – Timeout occurred while attempting to continue an ongoing transfer.

• FW_I2C_TIMEOUT_WAITING_BUS_EVENT – Timeout while waiting for a bus event (e.g., TXE, RXNE, BTF).

• FW_I2C_TIMEOUT_SCL_LOW – Timeout detected due to SCL being held low (possible clock stretching or bus lock condition).

• SDK_ERROR_WRONG_RESPONSE – The response received from the device does not match the expected format or size.

• 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 bus is different form I2C_BUS_A or I2C_BUS_B or

  • the deviceAddresses parameter and/or the count7BitAddresses parameter and/or count10BitAddresses parameter are NULL pointers.