I2C API

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

group CosmicSDK I2C API

Constants and APIs related to I2C operations.

Functions

uint16_t i2cSetBusVoltage(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:

  • 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_EXTERNAL_VOLTAGE_DETECTED – Firmware 4.7.0 and later: the port already carries a voltage from another source, so the rail is left off. Call i2cUseExternalVoltage() to run from that supply. A persisted setpoint gets the same check at boot.

  • 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 i2cUseExternalVoltage(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:

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 – Voltage domain successfully switched to external supply.

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

  • FW_VOLTAGE_ADJUSTMENT_FAILURE – 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 i2cGetBusVoltage(uint16_t &externalVoltage_mV)

Reads the measured I2C bus voltage from the host adapter.

Warning

On Supernova and Pulsar host adapters, the I2C interface shares the same voltage domain as SPI, UART and GPIOs. As a result, this method returns the same voltage values as spiGetBusVoltage, uartGetBusVoltage, and gpioGetVoltage.

Parameters:

externalVoltage_mV – Receives the voltage (in millivolts) measured on the VTARG pin for the I2C/SPI/UART/GPIO voltage domain.

Return values:

  • SUCCESS – Voltage measurements successfully retrieved.

  • SDK_ERROR_TIMEOUT – The operation timed out.

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

  • SDK_ERROR_WRONG_RESPONSE – The host adapter answered with a response too short to hold the analog measurements, so no reading could be taken. externalVoltage_mV is left untouched. A firmware error reported in such a response is returned in its place.

uint16_t i2cControllerInit(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:

  • 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 – 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 i2cSetParameters(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:

  • 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. 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 i2cSetDutyCycle(uint8_t bus, uint8_t highPct, uint32_t &frequency_Hz, uint8_t &appliedHighPct)

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:

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

  • frequency_Hz – [out] SCL frequency in Hz on the wire. With highPct 0, firmware 4.6.2 reports the rate the default timing programmed; earlier firmware echoes the request. Written whenever the response carries it – which firmware does for any initialized controller bus, refusals included. Left untouched otherwise.

  • appliedHighPct – [out] High share in effect after the call, written under the same condition as frequency_Hz.

Return values:

  • SUCCESS – The duty cycle was applied.

  • FW_INVALID_PARAMETER – highPct is not 0 or one of 20..80 in steps of 10.

  • FW_INTERFACE_NOT_INITIALIZED – The bus is not initialized as an I2C controller.

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

  • FW_UNSUPPORTED_COMMAND – The firmware predates this command (4.5.1 and older).

  • SDK_ERROR_TIMEOUT – The operation timed out.

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

  • SDK_ERROR_WRONG_RESPONSE – The host adapter reported SUCCESS in a response too short to carry the applied settings. The out-parameters are left untouched.

uint16_t i2cSetPullUpResistors(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:

  • 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 i2cDeinit(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

  • This is the supported way out of I2C target mode. A bus that still holds a role refuses the other role’s init, so without this the only exit is a device reset.

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

Parameters:

bus – I2C bus to deinitialize.

Return values:

  • SUCCESS – The bus was successfully deinitialized.

  • FW_INTERFACE_NOT_INITIALIZED – The bus holds no role, so there was nothing to release.

  • FW_BUS_NOT_SUPPORTED – The hardware has no such bus.

  • FW_UNSUPPORTED_COMMAND – The firmware predates the command.

  • SDK_ERROR_TIMEOUT – The operation timed out.

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

uint16_t i2cWrite(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:

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

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

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

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

uint16_t i2cWriteBulk(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 over the vendor bulk endpoint.

The large-payload counterpart of i2cWrite. The addressing travels in the request as usual and inData is streamed on the vendor bulk OUT endpoint, which is what lifts the ceiling: i2cWrite carries its bytes inside the request and so can never exceed MAX_I2C_TRANSFER_LENGTH however large the device’s staging pool is.

See also

The four checks every bulk call makes before it moves a byte.

Note

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

  • Requires the vendor bulk transport to be usable; see isBulkTransportAvailable and getBulkCapabilities. Otherwise returns SDK_ERROR_BULK_UNAVAILABLE.

  • The real ceiling is the device’s advertised maximum for GROUP_I2C (see BulkCapabilities::maxPayloadFor), not the compile-time I2C_BULK_MAX_PAYLOAD, which is only an upper bound. There is no automatic chunking above it: splitting a larger transfer into several calls is the caller’s job.

  • I2C is bus-limited long before the transport is, so the gain here is smaller than for SPI — what it removes is the per-1024-byte command round trip, not the bus time.

Parameters:

  • bus – I2C bus number. 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. At most 4 bytes.

  • inData – The data to be written; must be non-empty and within the device’s advertised ceiling.

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

Return values:

  • SUCCESS – The transfer completed.

  • SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable, or the connected device does not advertise CMD_I2C_CONTROLLER_WRITE_BULK.

  • SDK_ERROR_WRONG_REQUEST – subAddress is longer than 4 bytes, or inData is empty or over the ceiling.

  • SDK_ERROR_TIMEOUT – The operation timed out, or the payload could not be streamed over the bulk endpoint. The reply wait is the SDK timeout plus the bus time at the last clock set for this bus.

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

uint16_t i2cReadBulk(uint8_t bus, uint8_t address, const std::vector<uint8_t> &subAddress, uint16_t readLength, std::vector<uint8_t> &outData, const bool nonStop)

Reads a block from an I2C device over the vendor bulk endpoint.

The large-payload counterpart of i2cRead. The request and reply travel as usual; only the data phase comes back on the vendor bulk IN endpoint, and this call collects it into outData once the reply has announced how many bytes to expect.

See also

The four checks every bulk call makes before it moves a byte.

Note

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

  • Requires the vendor bulk transport to be usable; see isBulkTransportAvailable and getBulkCapabilities. Otherwise returns SDK_ERROR_BULK_UNAVAILABLE.

  • The real ceiling is the device’s advertised maximum for GROUP_I2C, not the compile-time I2C_BULK_MAX_PAYLOAD.

  • outData is sized to what the device actually announced, which may be shorter than readLength on a NACKed or short transfer. It is left empty when nothing could be collected.

Parameters:

  • bus – I2C bus number. 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. At most 4 bytes.

  • readLength – The length of data to be read; must be non-zero and within the advertised ceiling.

  • outData – Receives the data phase collected from the bulk endpoint.

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

Return values:

  • SUCCESS – The transfer completed and outData holds the payload.

  • SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable, or the connected device does not advertise CMD_I2C_CONTROLLER_READ_BULK.

  • SDK_ERROR_WRONG_REQUEST – subAddress is longer than 4 bytes, or readLength is zero or over the ceiling.

  • SDK_ERROR_WRONG_RESPONSE – The reply claimed success but was too short to carry its own announced length.

  • SDK_ERROR_TIMEOUT – The operation timed out, or the payload never arrived on the bulk endpoint. The reply wait is the SDK timeout plus the bus time at the last clock set for this bus.

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

uint16_t i2cScanBus(std::vector<uint8_t> &deviceAddresses, uint8_t *count7BitAddresses, uint8_t *count10BitAddresses, uint8_t bus, bool include10BitAddresses = false)

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:

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

  • 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: it was too short to carry the address counts, or it declared more addresses than it carried. deviceAddresses, count7BitAddresses and count10BitAddresses are all left untouched. A firmware error reported in a response too short to carry the counts at all is returned in its place.

  • SDK_ERROR_TIMEOUT – The operation timed out.

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

uint16_t i2cTargetInit(uint8_t busId, uint16_t address, I2cTargetAddressMode addressMode, I2cTargetMemoryLayout memoryLayout, I2cTargetModel model, uint32_t &memorySize)

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. Preload defaults with i2cTargetWriteMemory and read back the controller’s writes with i2cTargetReadMemory.

Parameters:

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

  • memorySize – On success, receives the arena capacity in bytes (32 KB on Supernova, 16 KB on Pulsar). Set to 0 when the result is not SUCCESS.

Return values:

  • SUCCESS – The device entered target mode.

  • FW_INTERFACE_ALREADY_INITIALIZED – Already in target mode; use i2cTargetSetParameters instead. memorySize is left at 0.

  • FW_I2C_TARGET_STAGING_UNAVAILABLE – The bulk-staging pool could not be acquired for the arena.

  • SDK_ERROR_TIMEOUT – The operation timed out.

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

uint16_t i2cTargetSetParameters(uint8_t busId, uint16_t address, I2cTargetAddressMode addressMode, I2cTargetMemoryLayout memoryLayout, I2cTargetModel model, uint32_t &memorySize)

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. This is the idempotent way to re-run configuration (unlike i2cTargetInit, which returns FW_INTERFACE_ALREADY_INITIALIZED when already in target mode).

Parameters:

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

  • memorySize – On success, receives the arena capacity in bytes. Set to 0 when the result is not SUCCESS.

Return values:

  • SUCCESS – The target was reconfigured.

  • SDK_ERROR_TIMEOUT – The operation timed out.

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

uint16_t i2cTargetSetEepromConfig(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:

  • 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 configuration was applied.

  • FW_I2C_TARGET_WRONG_MODEL – The active model is not EEPROM.

  • FW_I2C_TARGET_INVALID_CONFIG – The configuration is invalid (e.g., pageSize is not a power of two).

  • SDK_ERROR_TIMEOUT – The operation timed out.

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

uint16_t i2cTargetErase(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:

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

  • FW_I2C_TARGET_WRONG_MODEL – The active model is not EEPROM.

  • SDK_ERROR_TIMEOUT – The operation timed out.

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

uint16_t i2cTargetSetRegisterRegion(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 i2cTargetWriteMemory). Bytes outside every defined region default to RW.

Parameters:

  • 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 region was added.

  • FW_I2C_TARGET_WRONG_MODEL – The active model is not REGISTER_MAP.

  • FW_I2C_TARGET_REGION_TABLE_FULL – The 16-region limit was reached.

  • FW_I2C_TARGET_INVALID_CONFIG – The region descriptor is invalid.

  • SDK_ERROR_TIMEOUT – The operation timed out.

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

uint16_t i2cTargetWriteMemory(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. Requires the vendor bulk transport to be claimed and the firmware to advertise the command; otherwise returns SDK_ERROR_BULK_UNAVAILABLE.

See also

The four checks every bulk call makes before it moves a byte.

Parameters:

  • memoryAddress – Arena offset to start writing at.

  • data – Bytes to store; 1 to I2C_BULK_MAX_PAYLOAD.

Return values:

  • SUCCESS – The arena was written.

  • 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 the bulk ceiling.

  • FW_I2C_TARGET_SURPASSED_MEMORY_SIZE – memoryAddress + data.size() exceeds the arena.

  • SDK_ERROR_TIMEOUT – The operation timed out.

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

uint16_t i2cTargetReadMemory(uint16_t memoryAddress, uint16_t length, std::vector<uint8_t> &outData)

Reads the I2C target arena back over the vendor bulk endpoint.

Sends the command, reads the reply (which echoes the length), resizes outData to the announced count, then collects the payload from the vendor IN endpoint. Requires the vendor bulk transport to be claimed and the firmware to advertise the command; otherwise returns SDK_ERROR_BULK_UNAVAILABLE.

See also

The four checks every bulk call makes before it moves a byte.

Parameters:

  • memoryAddress – Arena offset to start reading from.

  • length – Bytes to read; 1 to I2C_BULK_MAX_PAYLOAD.

  • outData – Receives the bytes read; resized to the announced length. Cleared on timeout.

Return values:

  • SUCCESS – The arena was read.

  • 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 the bulk ceiling.

  • FW_I2C_TARGET_SURPASSED_MEMORY_SIZE – memoryAddress + length exceeds the arena.

  • SDK_ERROR_TIMEOUT – The operation timed out.

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