I2C API

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

group CosmicSDK I2C API

Constants and APIs related to I2C operations.

Functions

uint16_t i2cSetBusVoltage(uint16_t id, uint16_t voltage_mV, bool persist = false)

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:

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

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

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

Parameters:

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

  • 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 (e.g., I2C_PULLUP_330Ohm).

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 i2cSetParameters(uint16_t id, 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 i2cControllerInit. It allows runtime reconfiguration of the I2C without requiring a full deinitialization or reinitialization of the peripheral.

Note

Parameters:

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

  • 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 (e.g., I2C_PULLUP_330Ohm).

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

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

Parameters:

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

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

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 i2cWrite(uint16_t id, uint8_t bus, uint8_t address, const std::vector<uint8_t> &subAddress, const std::vector<uint8_t> &inData, const 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 i2cControllerInit.

Parameters:

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

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

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

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

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

Parameters:

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

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

  • readLength – The length of data to be read.

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

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

Parameters:

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

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

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