Common mistakes

Informative

Pitfalls when using the I2C driver, and how to avoid them. Each maps to a rule in I2c — Requirements or an error in Errors.

  • Passing a real pointer to I2c_Init. configPtr MUST be NULL_PTR — a non-null pointer raises I2C_DEVERR_PARAM_POINTER (CHI-I2C-MUST-09). The configuration is selected at build time.

  • Staging the wrong direction in a target. In I2c_Callout_OnAddress you must call I2c_StartTxTransaction for I2C_DIR_CONTROLLER_READ and I2c_StartRxTransaction for I2C_DIR_CONTROLLER_WRITE; the opposite raises I2C_DEVERR_INVALID_DIRECTION (CHI-I2C-MUST-20).

  • Freeing the buffer too early. txDataPtr / rxDataPtr must stay valid until I2c_Callout_OnTransmission / I2c_Callout_OnReception fires (CHI-I2C-MUST-13).

  • Treating NACK as a fatal driver fault. A device that does not acknowledge is reported as I2C_ERR_NACK_RECEIVED via I2c_Callout_OnError — decide whether to retry, STOP, or abort. Bus and arbitration failures are separate runtime errors (Errors).

  • Using a 10-bit or general-call address. Only 7-bit addressing is supported (device_address and deviceAddr in [0, 127]); the general call address 0x00 is out of scope.

  • Forgetting to service polled events. If a channel is configured for Polling you must call I2c_PollFunction cyclically, or no transfer progresses and no callout fires.

  • Expecting a repeated START without one. To keep the bus, start the next transaction inside the completion callout; otherwise the driver issues STOP.