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 i2cUseExternalVoltage(uint16_t id, bool save = false)

Configures the I2C bus to use an externally supplied voltage.

Notify the host adapter that I2C/SPI/UART/GPIO bus voltage comes from an external supply.

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 will also affect the voltage domain of SPI, UART and GPIO interfaces.

Parameters:

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

  • save – If true, stores the measured external voltage as the rail’s power-on setpoint: after a power cycle the adapter drives the rail itself at that voltage. It does not store “external”. If false, 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 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). The controller runs at or below this value. With the default timing, firmware 4.6.2 picks the fastest SCL that does not exceed it (550 kHz runs at 500 kHz) and refuses a rate outside 11 Hz-3 MHz with FW_INVALID_PARAMETER; earlier firmware rounds up and accepts any rate. Once a duty cycle is set it runs at most about 0.3% under between 1 kHz and 1.2 MHz, and firmware refuses 0-36 Hz, 2400001-2404696 Hz and above 4.8 MHz.

  • 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). The controller runs at or below this value. With the default timing, firmware 4.6.2 picks the fastest SCL that does not exceed it (550 kHz runs at 500 kHz) and refuses a rate outside 11 Hz-3 MHz with FW_INVALID_PARAMETER; earlier firmware rounds up and accepts any rate. Once a duty cycle is set it runs at most about 0.3% under between 1 kHz and 1.2 MHz, and firmware refuses 0-36 Hz, 2400001-2404696 Hz and above 4.8 MHz.

  • 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 i2cSetDutyCycle(uint16_t id, uint8_t bus, uint8_t highPct)

Sets the share of each I2C SCL period that the clock is held high. Any ratio, 50 included, also moves the bus to an exact clock (550 kHz runs at 549.8, not the default timing’s 600); I2C_DUTY_CYCLE_DEFAULT and i2cControllerInit return to the default timing.

The frequency set with i2cControllerInit or i2cSetParameters stays; only the high:low split changes. The ratio survives later i2cSetParameters calls and i2cControllerInit restores the default timing (I2C_DUTY_CYCLE_DEFAULT).

highPct is passed through unchecked: the firmware decides what is valid. It is not clamped to the I2C specification’s tHIGH/tLOW minimums – 30 at 100 kHz gives a tHIGH of 3.0 us, under Standard-mode’s 4.0 us – so out-of-spec timing is available for margin testing.

Note

Firmware 4.5.1 and older predate the command and answer FW_UNSUPPORTED_COMMAND; firmware older than that may not answer at all (SDK_ERROR_TIMEOUT).

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

  • highPct – SCL high time as a percentage of the period: 20, 30, 40, 50, 60, 70 or 80, which also makes the frequency exact. I2C_DUTY_CYCLE_DEFAULT (0) returns to the default timing every earlier firmware 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 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 i2cDeinit(uint16_t id, uint8_t bus)

Deinitialize an I2C bus, releasing whichever role it holds.

Tears the bus down whether it was brought up as a controller or as a target, and leaves it with no role selected, so it can be initialized again as either one.

Note

  • The command reaches the firmware from v4.5.0 onwards; older firmware answers FW_UNSUPPORTED_COMMAND in the response.

Parameters:

  • id – Transaction id, echoed in the response.

  • bus – I2C bus to deinitialize.

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 i2cWriteBulk(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 a block to an I2C device with the payload on the vendor bulk endpoint.

Identical to i2cWrite on the wire except for the command code and where the payload travels: the request carries only the addressing, and inData is streamed on the vendor OUT endpoint immediately afterwards. That is what lifts the ceiling — i2cWrite carries its bytes inside the request, so it can never exceed MAX_I2C_TRANSFER_LENGTH however large the device’s staging pool is.

Note

  • Valid only when the host is initialized as an I2C controller with i2cControllerInit.

  • The payload is pushed straight after the request, before waiting for the reply. The firmware is already blocked receiving on the endpoint by the time the request lands, so waiting for the reply first would deadlock.

  • Requires the vendor bulk transport; see isBulkAvailable. This is the low-level entry point and does not consult the device’s capability record — CosmicSDK::i2cWriteBulk does.

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; must be non-empty and within I2C_BULK_MAX_PAYLOAD.

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

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 i2cReadBulk(uint16_t id, uint8_t bus, uint8_t address, const std::vector<uint8_t> &subAddress, uint16_t readLength, const bool nonStop)

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

Identical to i2cRead on the wire except for the command code and where the data comes back: the reply announces the length, and the bytes themselves arrive on the vendor IN endpoint. Collect them with receivePayload after the reply — only the reply says how many bytes are coming, so reading first would deadlock anything larger than the endpoint FIFO.

Note

  • Valid only when the host is initialized as an I2C controller with i2cControllerInit.

  • Requires the vendor bulk transport; see isBulkAvailable. This is the low-level entry point and does not consult the device’s capability record — CosmicSDK::i2cReadBulk does.

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; must be non-zero and within I2C_BULK_MAX_PAYLOAD.

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

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

uint16_t i2cTargetInit(uint16_t id, uint8_t busId, uint16_t address, I2cTargetAddressMode addressMode, I2cTargetMemoryLayout memoryLayout, I2cTargetModel model)

Enters I2C target (slave) mode.

Arms the device as an I2C target backed by an arena drawn from the shared bulk-staging pool. An external controller reads and writes that arena over the bus while the firmware services the transactions autonomously. The model selects how the arena behaves on the bus.

Note

Parameters:

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

  • busId – I2C bus number (e.g., I2C_BUS_A).

  • address – Target address the device answers to (7-bit: 0x08..0x77; 10-bit: 0x000..0x3FF).

  • addressMode – 7-bit or 10-bit addressing. See I2cTargetAddressMode.

  • memoryLayout – 8-bit or 16-bit register addressing. See I2cTargetMemoryLayout.

  • model – Emulation model presented on the bus. See I2cTargetModel.

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 i2cTargetSetParameters(uint16_t id, uint8_t busId, uint16_t address, I2cTargetAddressMode addressMode, I2cTargetMemoryLayout memoryLayout, I2cTargetModel model)

Reconfigures the active I2C target in place.

Re-arms the target with a new address, layout, or model without discarding the arena contents. It resets the register-map table and the address pointer. Shares the exact request/response shape as i2cTargetInit and is the idempotent way to re-run configuration.

Parameters:

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

  • busId – I2C bus number (e.g., I2C_BUS_A).

  • address – Target address the device answers to (7-bit: 0x08..0x77; 10-bit: 0x000..0x3FF).

  • addressMode – 7-bit or 10-bit addressing. See I2cTargetAddressMode.

  • memoryLayout – 8-bit or 16-bit register addressing. See I2cTargetMemoryLayout.

  • model – Emulation model presented on the bus. See I2cTargetModel.

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 i2cTargetSetEepromConfig(uint16_t id, uint16_t totalSize, uint16_t pageSize, uint32_t writeCycle_us, uint32_t eraseCycle_us, I2cTargetEepromBusyBehavior busyBehavior, uint8_t erasedValue, uint16_t wpStart, uint16_t wpEnd)

Configures the EEPROM emulation model (I2C target).

Valid only while the active model is I2C_TARGET_MODEL_EEPROM. Sets the page-wrap granularity, program/erase busy timing, and the write-protect window.

Parameters:

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

  • totalSize – Addressable size (must be <= arena). Reads/writes wrap here.

  • pageSize – Page-write wrap granularity. Must be a power of two.

  • writeCycle_us – Program time in microseconds. A data write is busy for eraseCycle + writeCycle.

  • eraseCycle_us – Erase time in microseconds. An explicit erase is busy for eraseCycle.

  • busyBehavior – How the device signals busy. See I2cTargetEepromBusyBehavior.

  • erasedValue – Value of an erased byte (typically 0xFF). Also the fill value for WO/RESERVED regions.

  • wpStart – Write-protect region start (inclusive).

  • wpEnd – Write-protect region end (exclusive). wpStart == wpEnd disables it.

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 i2cTargetErase(uint16_t id, I2cTargetEraseScope scope, uint16_t address)

Host-triggered EEPROM erase (I2C target).

Valid only in the EEPROM model. Fills the target region with the configured erased value and enters the busy window for eraseCycle_us.

Parameters:

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

  • scope – Erase scope (single page or whole chip). See I2cTargetEraseScope.

  • address – For PAGE scope, an address selecting the page to erase. Ignored for CHIP scope.

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 i2cTargetSetRegisterRegion(uint16_t id, uint16_t startAddr, uint16_t endAddr, I2cTargetRegisterAccess access, uint8_t width, uint8_t flags)

Adds one region descriptor to the REGISTER_MAP model (I2C target).

Valid only in the REGISTER_MAP model. Send once per region (up to 16) to set the access policy and width of an address span; register values themselves live in the arena (preload defaults with CosmicSDK::i2cTargetWriteMemory). Bytes outside every defined region default to RW.

Parameters:

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

  • startAddr – Region start address (inclusive).

  • endAddr – Region end address (exclusive). Must be > startAddr and <= arena.

  • access – Access policy for the span. See I2cTargetRegisterAccess.

  • width – Register width in bytes: 1 or 2.

  • flags – Region flags. Bit 1 = no-auto-increment; other bits reserved (send 0).

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 i2cTargetWriteMemory(uint16_t id, uint16_t memoryAddress, const std::vector<uint8_t> &data)

Preloads the I2C target arena over the vendor bulk endpoint.

Sends the command, then streams data on the vendor OUT endpoint immediately afterwards, because the firmware holds that endpoint open for it from the moment the command is dispatched. This call blocks the calling thread only for the duration of the bulk transfer itself (not for the firmware’s reply); the firmware’s actual result code for the write arrives later through the registered onResponse callback.

Parameters:

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

  • memoryAddress – Arena offset to start writing at.

  • data – Bytes to store; must be non-empty and within I2C_BULK_MAX_PAYLOAD.

Return values:

  • SUCCESS – The command and payload were successfully sent to the host adapter.

  • SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable (not claimed, or unsupported by the firmware).

  • SDK_ERROR_WRONG_REQUEST – data is empty or larger than I2C_BULK_MAX_PAYLOAD.

  • SDK_ERROR_TIMEOUT – Streaming data over the bulk endpoint timed out.

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

uint16_t i2cTargetReadMemory(uint16_t id, uint16_t memoryAddress, uint16_t length)

Starts an I2C target arena read over the vendor bulk endpoint.

Only the data phase comes back on the vendor bulk endpoint; the reply announces the length first, so the caller must wait for the onResponse callback and then collect the payload with receivePayload once the announced length is known.

Parameters:

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

  • memoryAddress – Arena offset to start reading from.

  • length – Bytes to read; must be non-zero and within I2C_BULK_MAX_PAYLOAD.

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

  • SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable (not claimed, or unsupported by the firmware).

  • SDK_ERROR_WRONG_REQUEST – length is zero or larger than I2C_BULK_MAX_PAYLOAD.

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