Chapter 131: I2C Advanced Error Handling

Chapter Objectives

After completing this chapter, you will be able to:

• Identify common types of errors that can occur during I2C communication.
• Understand how the ESP-IDF I2C driver reports errors.
• Implement robust error checking for I2C transactions.
• Effectively use and configure timeouts for I2C operations.
• Implement basic retry mechanisms for transient I2C errors.
• Understand the principles of I2C bus recovery techniques.
• Recognize situations where software recovery might be insufficient.

Introduction

In the previous chapters, we learned how to configure the I2C bus and communicate with single and multiple I2C slave devices. While those examples covered basic success and failure logging, real-world embedded systems often operate in noisy environments or interact with devices that might occasionally behave unpredictably. Simply detecting a failure is often not enough; a robust system should attempt to handle errors gracefully, potentially recover from them, and maintain stability.

This chapter focuses on advanced error handling techniques for I2C communication with ESP32. We will explore the types of errors you might encounter, how the ESP-IDF reports them, and strategies to build more resilient I2C interactions. This includes proper timeout management, implementing retry logic, and understanding basic bus recovery concepts. Robust error handling is critical for applications demanding high reliability, such as industrial controllers, medical devices, or long-running sensor networks.

Theory

Common I2C Communication Errors

Several types of errors can disrupt I2C communication. Understanding these is the first step to handling them:

1. No Acknowledge (NACK) on Address:
   • Cause: The master sends a slave address, but no slave device on the bus responds with an Acknowledge (ACK) bit. This usually means:
     • The slave device is not connected or not powered.
     • The slave address used by the master is incorrect.
     • The slave device is faulty or stuck.
     • Wiring issues (SDA/SCL lines broken or disconnected).
   • Indication: The master detects that the SDA line was not pulled low by any slave during the 9th clock pulse after the address byte.
2. No Acknowledge (NACK) on Data:
   • Cause: During a write operation, the master sends a data byte, and the addressed slave fails to ACK it. This might indicate:
     • The slave received the data but cannot process it (e.g., internal buffer full, invalid command/register).
     • The slave is busy.
     • The slave has encountered an internal error.
   • During a read operation, the master is expected to NACK the last byte it intends to read from the slave to signal the end of the read. If the master ACKs when the slave expects a NACK (or vice-versa in some specific protocol extensions), it can lead to issues. However, typically, a NACK from a slave on data written by the master is the primary concern here.
3. Arbitration Lost (ESP_ERR_INVALID_STATE or similar, context-dependent):
   • Cause: In a multi-master I2C bus (less common in typical ESP32 applications which usually act as the sole master), if two masters try to transmit on the bus simultaneously, one will lose arbitration. The master that detects its SDA level doesn’t match what it transmitted loses arbitration and must stop its current transaction.
   • Indication: The ESP-IDF I2C driver handles arbitration internally. If the ESP32 is the only master, this error is unlikely unless there’s significant noise or a misbehaving slave device trying to drive the bus incorrectly.
4. Timeout Errors (ESP_ERR_TIMEOUT):
   • Cause: An I2C operation (like waiting for an ACK, or for a slave to release SCL during clock stretching) does not complete within a specified timeout period. This can happen if:
     • A slave device is holding SCL or SDA low indefinitely (stuck bus).
     • The slave is extremely slow and exceeds the master’s patience.
     • Hardware issues (e.g., missing pull-ups leading to lines not returning high).
   • Indication: The i2c_master_cmd_begin() function in ESP-IDF returns ESP_ERR_TIMEOUT.
5. Bus Busy (ESP_ERR_INVALID_STATE or specific busy error):
   • Cause: The I2C bus lines (SCL or SDA) are detected as being held low before a new transaction is initiated, indicating the bus is not idle. This can be a symptom of a previous transaction not completing correctly or a stuck slave.
   • Indication: The driver might refuse to start a new transaction.
6. SCL or SDA Line Stuck Low/High:
   • Cause: A device on the bus (master or slave) or a short circuit is holding one of the lines permanently low or high. Missing pull-ups can cause lines to float or appear stuck low if a device tries to pull them low.
   • Indication: Leads to timeouts or inability to initiate START/STOP conditions. A logic analyzer is invaluable here.

ESP-IDF Error Reporting

The primary function for executing I2C master transactions in ESP-IDF is i2c_master_cmd_begin(i2c_port_t i2c_num, i2c_cmd_handle_t cmd_handle, TickType_t ticks_to_wait). Its return value (esp_err_t) is crucial for error detection:

• ESP_OK: The entire command link (sequence of I2C operations) executed successfully, and all expected ACKs were received.
• ESP_ERR_TIMEOUT: The operation timed out. This is a common error if a slave is unresponsive or the bus is stuck. The ticks_to_wait parameter determines how long the function will block.
• ESP_FAIL: A general failure. This often indicates a NACK was received from the slave when an ACK was expected (e.g., after sending the slave address or a data byte during a write).
• ESP_ERR_INVALID_ARG: Invalid arguments were passed to the function.
• ESP_ERR_INVALID_STATE: The I2C driver was not in a valid state to perform the operation (e.g., not installed, or bus busy).

The simpler helper functions like i2c_master_transmit(), i2c_master_receive(), and i2c_master_transmit_receive() (ESP-IDF v5.1+) also return esp_err_t and internally use i2c_master_cmd_begin, so they can return similar error codes.

Timeout Configuration

The ticks_to_wait parameter in i2c_master_cmd_begin() is critical for error handling. It specifies the maximum time the function will wait for the transaction to complete.

• Setting it too low: May cause legitimate (but slow) transactions to time out.
• Setting it too high (or portMAX_DELAY): May cause the task to block for an unacceptably long time if the bus is stuck or a slave is unresponsive, potentially impacting system responsiveness.
• Recommended practice: Choose a reasonable timeout based on the expected transaction time for your specific slave devices and bus speed (e.g., a few milliseconds to tens of milliseconds). For 100kHz I2C, transferring a byte takes about 0.1ms. A transaction of a few bytes might take 1-2ms. A timeout of 50-100ms (pdMS_TO_TICKS(50)) is often a good starting point for many devices.

graph TD
    A["Start I2C Transaction<br>i2c_master_cmd_begin(port, cmd, ticks_to_wait)"] --> B{Transaction Complete?};
    B -- Yes --> C[Return ESP_OK];
    B -- No --> D{ticks_to_wait Expired?};
    D -- Yes --> E["Return ESP_ERR_TIMEOUT<br>(Slave unresponsive / Bus stuck)"];
    D -- No --> F{Other Error Occurred?};
    F -- Yes (e.g., NACK) --> G[Return ESP_FAIL / Other Error Code];
    F -- No --> B; 
    %% Loop back to check completion if not timed out and no other error yet

    %% Styling
    classDef primary fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6;
    classDef success fill:#D1FAE5,stroke:#059669,stroke-width:2px,color:#065F46;
    classDef decision fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E;
    classDef process fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF;
    classDef error fill:#FEE2E2,stroke:#DC2626,stroke-width:1px,color:#991B1B;

    class A primary;
    class B decision;
    class C success;
    class D decision;
    class E error;
    class F decision;
    class G error;

Retry Mechanisms

For transient errors (e.g., a temporary NACK due to a slave being momentarily busy, or a noise glitch), a simple retry mechanism can significantly improve robustness.

1. Identify Retryable Errors: Not all errors are suitable for retrying.
   • Good candidates for retry: ESP_ERR_TIMEOUT, ESP_FAIL (NACK).
   • Poor candidates for retry (or require more complex handling): ESP_ERR_INVALID_ARG (programming error), persistent ESP_ERR_TIMEOUT after multiple retries (likely a hard fault).
2. Implement a Retry Loop:
   • Wrap the I2C transaction call in a loop.
   • Limit the number of retries to prevent indefinite blocking.
   • Introduce a small delay between retries to give the slave or bus time to recover.

// Conceptual retry loop
int max_retries = 3;
esp_err_t ret;
for (int i = 0; i < max_retries; i++) {
    ret = i2c_master_cmd_begin(i2c_num, cmd, pdMS_TO_TICKS(50)); // 50ms timeout
    if (ret == ESP_OK) {
        break; // Success
    }
    ESP_LOGW(TAG, "I2C transaction failed (attempt %d/%d): %s. Retrying...", 
             i + 1, max_retries, esp_err_to_name(ret));
    vTaskDelay(pdMS_TO_TICKS(20)); // Wait 20ms before retrying
}
if (ret != ESP_OK) {
    ESP_LOGE(TAG, "I2C transaction failed after %d retries: %s", max_retries, esp_err_to_name(ret));
    // Handle persistent failure
}

graph TD
    A[Start: Initiate I2C Transaction Attempt] --> B{Attempt < Max Retries?};
    B -- Yes --> C["Execute I2C Command<br>e.g., i2c_master_cmd_begin()"];
    C --> D{"Transaction Successful?<br>(ret == ESP_OK)"};
    D -- Yes --> E[End: Success!];
    D -- No --> F{"Error Retryable?<br>(e.g., ESP_FAIL, ESP_ERR_TIMEOUT)"};
    F -- Yes --> G[Log Warning & Increment Attempt Counter];
    G --> H["Wait for<br>Retry Delay<br>(vTaskDelay)"];
    H --> B;
    F -- No --> I[End: Persistent Failure<br>Log Error, Handle Non-retryable Error];
    B -- No --> J[End: Max Retries Reached<br>Log Error, Handle Persistent Failure];

    %% Styling
    classDef primary fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6;
    classDef success fill:#D1FAE5,stroke:#059669,stroke-width:2px,color:#065F46;
    classDef decision fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E;
    classDef process fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF;
    classDef error fill:#FEE2E2,stroke:#DC2626,stroke-width:1px,color:#991B1B;
    classDef check fill:#FEE2E2,stroke:#DC2626,stroke-width:1px,color:#991B1B; %% Using error style for check for now

    class A primary;
    class B decision;
    class C process;
    class D decision;
    class E success;
    class F decision;
    class G process;
    class H process;
    class I error;
    class J error;

I2C Bus Recovery

If the I2C bus becomes stuck (e.g., SDA or SCL held low by a misbehaving slave), new transactions cannot start. Software-based bus recovery techniques can sometimes resolve these situations.

1. SCL Stuck Low (Clock Stretching Gone Wrong): If a slave is holding SCL low indefinitely, the master cannot proceed. The ESP32’s I2C peripheral has hardware timeout mechanisms for clock stretching. If i2c_master_cmd_begin times out, this could be a cause.
2. SDA Stuck Low: If a slave holds SDA low outside of a valid data transmission (e.g., after it was supposed to release it for an ACK from the master, or after a STOP condition), the bus is stuck.
3. “Bus Clear” or “Bus Reset” Procedure:
   • The I2C specification doesn’t define a formal reset signal. However, a common procedure to attempt to free a stuck bus involves the master manually toggling the SCL line.
   • Procedure:
     1. The master sends up to 9 clock pulses on SCL.
     2. During each clock pulse, the slave device that might be holding SDA low should check if SDA is still low. If it was in the middle of sending a data bit, it should continue and then release SDA.
     3. After these clock pulses, the master attempts to generate a START condition followed by a STOP condition. This sequence should reset the bus state for most compliant slave devices.
   • Implementation on ESP32: This typically requires bit-banging the SCL/SDA lines using GPIO functions if the I2C peripheral itself is stuck or cannot perform this. This means temporarily uninstalling/disabling the I2C driver, taking control of the pins as GPIOs, performing the clocking sequence, and then re-initializing the I2C driver.

graph TD
    subgraph Legend
        direction LR
        L1[Primary/Start]:::primary --- L2[Process]:::process
        L3[Decision]:::decision --- L4[Check/Validation]:::check
        L5[End/Success]:::success
    end

    A[Start: Bus Possibly Stuck] --> B{"Is SDA Line High?"};
    B -- Yes --> C["Attempt Normal STOP:<br>1. SCL High<br>2. SDA High to Low (Start-like)<br>3. SCL Low<br>4. SCL High<br>5. SDA Low to High (STOP)"];
    C --> D[Bus Potentially Cleared];

    B -- No (SDA is Low) --> E[SDA Stuck Low Detected];
    E --> F[Master Takes Control of SCL/SDA as GPIO];
    F --> G{"Generate up to 9 SCL Pulses<br>(Toggle SCL High/Low 9 times)"};
    G --> H{"During/After Pulses,<br>Did Slave Release SDA (SDA High)?"};
    H -- Yes --> I[SDA Released!];
    I --> J["Master Generates START Condition<br>(SDA Low while SCL High, then SCL Low)"];
    J --> K["Master Generates STOP Condition<br>(SCL High, then SDA High)"];
    K --> L[Bus Potentially Cleared];

    H -- No (SDA Still Low) --> M[SDA Remains Stuck];
    M --> N[Bus Clear Failed via SCL Toggling];
    
    D --> Z[End: Re-initialize I2C Driver];
    L --> Z;
    N --> Z;


    %% Styling
    classDef primary fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6;
    classDef success fill:#D1FAE5,stroke:#059669,stroke-width:2px,color:#065F46;
    classDef decision fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E;
    classDef process fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF;
    classDef check fill:#FEE2E2,stroke:#DC2626,stroke-width:1px,color:#991B1B;
    classDef endnode fill:#D1FAE5,stroke:#059669,stroke-width:2px,color:#065F46;


    class A primary;
    class B decision;
    class C process;
    class D success;
    class E check;
    class F process;
    class G process;
    class H decision;
    class I success;
    class J process;
    class K process;
    class L success;
    class M check;
    class N error; 
    %% Using check style for error for now as per request
    class Z endnode;

Warning: Bit-banging for bus recovery can be complex and might not work for all devices or situations. It should be used as a last resort before considering hardware resets.

Limitations of Software Recovery

Practical Examples

Let’s explore how to implement some of these error handling strategies.

Prerequisites:

• Same as previous chapters: ESP-IDF v5.x, ESP32 board, VS Code.
• An I2C slave device for testing. To reliably test error conditions like NACKs, you might temporarily disconnect the device or use an incorrect slave address.

Example 1: Detailed Error Checking and Retry Logic

This example expands on a simple I2C write operation to include detailed error checking and a retry loop.

#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c.h"
#include "esp_log.h"

static const char *TAG = "i2c_error_handling";

#define I2C_MASTER_SCL_IO           22      /*!< GPIO number used for I2C master clock */
#define I2C_MASTER_SDA_IO           21      /*!< GPIO number used for I2C master data  */
#define I2C_MASTER_NUM              I2C_NUM_0 /*!< I2C port number for master dev */
#define I2C_MASTER_FREQ_HZ          100000  /*!< I2C master clock frequency */
#define I2C_MASTER_TX_BUF_DISABLE   0       /*!< I2C master doesn't need buffer */
#define I2C_MASTER_RX_BUF_DISABLE   0       /*!< I2C master doesn't need buffer */

#define EXAMPLE_SLAVE_ADDR          0x28    /*!< Hypothetical slave address (change if needed) */
#define WRITE_BIT                   I2C_MASTER_WRITE
#define ACK_CHECK_EN                0x1

#define I2C_TRANSACTION_TIMEOUT_MS  100     // Timeout for the I2C transaction
#define I2C_RETRY_DELAY_MS          50      // Delay between retries
#define I2C_MAX_RETRIES             3       // Max number of retries

static esp_err_t i2c_master_bus_init(void) {
    i2c_config_t conf = {
        .mode = I2C_MODE_MASTER,
        .sda_io_num = I2C_MASTER_SDA_IO,
        .scl_io_num = I2C_MASTER_SCL_IO,
        .sda_pullup_en = GPIO_PULLUP_ENABLE,
        .scl_pullup_en = GPIO_PULLUP_ENABLE,
        .master.clk_speed = I2C_MASTER_FREQ_HZ,
    };
    esp_err_t err = i2c_param_config(I2C_MASTER_NUM, &conf);
    if (err != ESP_OK) {
        ESP_LOGE(TAG, "I2C param config failed: %s", esp_err_to_name(err));
        return err;
    }
    err = i2c_driver_install(I2C_MASTER_NUM, conf.mode, I2C_MASTER_RX_BUF_DISABLE, I2C_MASTER_TX_BUF_DISABLE, 0);
    if (err != ESP_OK) {
        ESP_LOGE(TAG, "I2C driver install failed: %s", esp_err_to_name(err));
        return err;
    }
    ESP_LOGI(TAG, "I2C master bus initialized successfully on port %d", I2C_MASTER_NUM);
    return ESP_OK;
}

static esp_err_t robust_i2c_write(uint8_t slave_addr, uint8_t *data, size_t data_len) {
    esp_err_t ret = ESP_FAIL; // Initialize with a failure state

    for (int attempt = 0; attempt < I2C_MAX_RETRIES; attempt++) {
        i2c_cmd_handle_t cmd = i2c_cmd_link_create();
        if (cmd == NULL) {
            ESP_LOGE(TAG, "Failed to create I2C command link (attempt %d)", attempt + 1);
            // No point retrying if cmd link creation fails, likely out of memory
            return ESP_ERR_NO_MEM; 
        }

        i2c_master_start(cmd);
        i2c_master_write_byte(cmd, (slave_addr << 1) | WRITE_BIT, ACK_CHECK_EN);
        if (data_len > 0) {
            i2c_master_write(cmd, data, data_len, ACK_CHECK_EN);
        }
        i2c_master_stop(cmd);

        ret = i2c_master_cmd_begin(I2C_MASTER_NUM, cmd, pdMS_TO_TICKS(I2C_TRANSACTION_TIMEOUT_MS));
        i2c_cmd_link_delete(cmd);

        if (ret == ESP_OK) {
            ESP_LOGI(TAG, "I2C write to 0x%02X successful (attempt %d)", slave_addr, attempt + 1);
            break; // Success, exit loop
        } else {
            ESP_LOGW(TAG, "I2C write to 0x%02X failed (attempt %d/%d): %s (%d)", 
                     slave_addr, attempt + 1, I2C_MAX_RETRIES, esp_err_to_name(ret), ret);
            
            if (attempt < I2C_MAX_RETRIES - 1) {
                ESP_LOGI(TAG, "Retrying in %d ms...", I2C_RETRY_DELAY_MS);
                vTaskDelay(pdMS_TO_TICKS(I2C_RETRY_DELAY_MS));
            }
        }
    }

    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "I2C write to 0x%02X ultimately FAILED after %d attempts.", slave_addr, I2C_MAX_RETRIES);
        // Further actions could be taken here, e.g., log persistent error, try bus recovery, etc.
    }
    return ret;
}

void app_main(void) {
    ESP_ERROR_CHECK(i2c_master_bus_init());

    uint8_t sample_data[] = {0xDE, 0xAD, 0xBE, 0xEF};

    ESP_LOGI(TAG, "Attempting robust I2C write...");
    esp_err_t status = robust_i2c_write(EXAMPLE_SLAVE_ADDR, sample_data, sizeof(sample_data));

    if (status == ESP_OK) {
        ESP_LOGI(TAG, "Main: Robust write completed successfully.");
    } else {
        ESP_LOGE(TAG, "Main: Robust write failed with error: %s", esp_err_to_name(status));
        // Consider what to do if the operation ultimately fails.
        // Maybe try a bus clear, or signal a higher-level error.
    }

    // To test NACK: use an address that has no device, e.g., 0x01
    ESP_LOGI(TAG, "Attempting robust I2C write to a non-existent device (expecting NACK/failure)...");
    status = robust_i2c_write(0x01, sample_data, sizeof(sample_data));
     if (status == ESP_OK) {
        ESP_LOGW(TAG, "Main: Write to 0x01 unexpectedly succeeded? Check setup.");
    } else {
        ESP_LOGI(TAG, "Main: Robust write to 0x01 correctly failed as expected.");
    }

    // Optional: Delete driver
    // i2c_driver_delete(I2C_MASTER_NUM);
}

Code Explanation:

• Constants: I2C_TRANSACTION_TIMEOUT_MS, I2C_RETRY_DELAY_MS, I2C_MAX_RETRIES are defined for better control over the retry behavior.
• i2c_master_bus_init(): Standard I2C initialization.
• robust_i2c_write() function:
  • Takes slave address, data pointer, and data length as input.
  • Implements a for loop for retries.
  • Inside the loop, it creates and executes an I2C command link.
  • i2c_master_cmd_begin() is called with the defined I2C_TRANSACTION_TIMEOUT_MS.
  • If ESP_OK is returned, the loop breaks.
  • If an error occurs, it’s logged, and a delay (I2C_RETRY_DELAY_MS) is introduced before the next attempt.
  • If all retries fail, a final error message is logged.
• app_main():
  • Initializes the I2C bus.
  • Calls robust_i2c_write() to send data to EXAMPLE_SLAVE_ADDR.
  • Calls robust_i2c_write() again, but to an unlikely slave address (e.g., 0x01) to simulate and test the NACK error handling and retry logic.

Build and Run/Flash/Observe Steps:

1. Save, build, flash, and monitor as usual.
2. Scenario 1 (Device Present): If an I2C device is connected at EXAMPLE_SLAVE_ADDR, the first call to robust_i2c_write should succeed, possibly on the first attempt.
3. Scenario 2 (Device Absent or Wrong Address): The second call to robust_i2c_write (to address 0x01) should fail. Observe the log output: you should see it attempt the write I2C_MAX_RETRIES times, logging the failure (likely ESP_FAIL due to NACK, or ESP_ERR_TIMEOUT if pull-ups are missing and lines don’t go high) for each attempt, with delays in between.

Example 2: Conceptual I2C Bus Clear (Bit-Banging)

This is a conceptual example of how one might attempt an I2C bus clear by bit-banging GPIOs. This is advanced and should be used cautiously.

Warning: Directly manipulating pins used by a peripheral driver requires careful coordination. The I2C driver should be uninstalled or the peripheral reset before attempting this, and reinitialized afterwards. This example is simplified and might need adjustments for specific hardware or more robust error checking.

#include "driver/gpio.h"
// ... other includes from Example 1

// Assume I2C_MASTER_SDA_IO and I2C_MASTER_SCL_IO are defined

static void i2c_bus_clear_attempt(void) {
    ESP_LOGW(TAG, "Attempting I2C bus clear sequence...");

    // Temporarily configure pins as open-drain output GPIOs
    // It's crucial that the I2C driver for this port is NOT active or installed here.
    // Or, one might reconfigure the peripheral to GPIO matrix temporarily.
    // This is a simplified illustration.

    gpio_config_t io_conf = {
        .pin_bit_mask = (1ULL << I2C_MASTER_SDA_IO) | (1ULL << I2C_MASTER_SCL_IO),
        .mode = GPIO_MODE_OUTPUT_OD, // Open Drain
        .pull_up_en = GPIO_PULLUP_ENABLE, // Enable pull-ups
        .pull_down_en = GPIO_PULLDOWN_DISABLE,
        .intr_type = GPIO_INTR_DISABLE
    };
    gpio_config(&io_conf);

    // Ensure SDA and SCL are high initially (due to pull-ups)
    gpio_set_level(I2C_MASTER_SDA_IO, 1);
    gpio_set_level(I2C_MASTER_SCL_IO, 1);
    vTaskDelay(pdMS_TO_TICKS(1)); // Short delay

    // Check if SDA is stuck low by a slave. If so, master cannot generate START.
    // If SDA is high, try to generate a STOP to reset slaves that missed a previous STOP.
    if (gpio_get_level(I2C_MASTER_SDA_IO) == 1) {
        gpio_set_level(I2C_MASTER_SCL_IO, 1); // SCL high
        vTaskDelay(pdMS_TO_TICKS(1));
        gpio_set_level(I2C_MASTER_SDA_IO, 0); // SDA low (part of START)
        vTaskDelay(pdMS_TO_TICKS(1));
        gpio_set_level(I2C_MASTER_SCL_IO, 0); // SCL low
        vTaskDelay(pdMS_TO_TICKS(1));
        
        // Generate STOP: SCL high, then SDA high
        gpio_set_level(I2C_MASTER_SCL_IO, 1);
        vTaskDelay(pdMS_TO_TICKS(1));
        gpio_set_level(I2C_MASTER_SDA_IO, 1);
        vTaskDelay(pdMS_TO_TICKS(1));
        ESP_LOGI(TAG, "Generated a STOP condition via bit-bang.");
    } else {
         ESP_LOGW(TAG, "SDA is low, attempting to clock it out...");
        // SDA is stuck low. Try to clock it out.
        for (int i = 0; i < 9; i++) { // Send 9 clock pulses
            gpio_set_level(I2C_MASTER_SCL_IO, 0);
            vTaskDelay(pdMS_TO_TICKS(1)); // SCL low period
            gpio_set_level(I2C_MASTER_SCL_IO, 1);
            vTaskDelay(pdMS_TO_TICKS(1)); // SCL high period
            if (gpio_get_level(I2C_MASTER_SDA_IO) == 1) {
                ESP_LOGI(TAG, "SDA released after %d clocks.", i + 1);
                break; // SDA released
            }
        }
        // After clocking, try to issue a STOP condition
        if (gpio_get_level(I2C_MASTER_SDA_IO) == 1) {
            gpio_set_level(I2C_MASTER_SCL_IO, 1); // SCL high
            vTaskDelay(pdMS_TO_TICKS(1));
            // SDA is already high
            ESP_LOGI(TAG, "Generated STOP after clocking out SDA.");
        } else {
            ESP_LOGE(TAG, "SDA still stuck low after 9 clocks. Bus clear failed.");
        }
    }
    
    // IMPORTANT: After this, pins should be reconfigured back for I2C peripheral use,
    // and the I2C driver should be re-initialized if it was uninstalled.
    // For example: i2c_driver_delete(I2C_MASTER_NUM); followed by i2c_master_bus_init();
    ESP_LOGI(TAG, "Bus clear attempt finished. Re-initialize I2C driver now.");
}

// In app_main, if robust_i2c_write ultimately fails:
// if (status != ESP_OK) {
//     ESP_LOGE(TAG, "Main: Robust write failed. Attempting bus clear.");
//     i2c_driver_delete(I2C_MASTER_NUM); // Uninstall driver before bit-banging
//     vTaskDelay(pdMS_TO_TICKS(10));    // Give some time
//     i2c_bus_clear_attempt();
//     vTaskDelay(pdMS_TO_TICKS(10));
//     ESP_ERROR_CHECK(i2c_master_bus_init()); // Re-initialize driver
//     ESP_LOGI(TAG, "Attempting write again after bus clear...");
//     status = robust_i2c_write(EXAMPLE_SLAVE_ADDR, sample_data, sizeof(sample_data));
//     // ... check status again
// }

Code Explanation:

• This function i2c_bus_clear_attempt is highly simplified and illustrative.
• It first reconfigures the I2C pins as open-drain GPIO outputs. This requires the I2C peripheral driver to be uninstalled or disabled for these pins first.
• It checks if SDA is already high. If so, it attempts to send a STOP condition.
• If SDA is low, it attempts to send 9 clock pulses on SCL, checking if SDA gets released.
• After the clock pulses, it tries to generate a STOP condition if SDA is high.
• Crucially, after attempting a bus clear, the I2C driver must be re-initialized for the port before normal I2C operations can resume. The commented-out section in app_main shows this sequence.

Tip: The ESP-IDF I2C driver itself has some internal mechanisms to handle bus recovery and timeouts. Before implementing complex manual bit-banging, ensure you’re using appropriate timeouts with i2c_master_cmd_begin and handling its error codes. Manual bus clear is a more drastic step.

Variant Notes

The core I2C error reporting mechanisms (esp_err_t return codes from i2c_master_cmd_begin and helper functions) are consistent across ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, and ESP32-H2 variants when using the ESP-IDF driver.

• Hardware Timeouts: The underlying I2C hardware peripherals on these chips have configurable timeout registers for SCL clock stretching and bus busy conditions. The ESP-IDF I2C driver configures these based on the master.clk_speed and internal logic. The ticks_to_wait in i2c_master_cmd_begin acts as an overall software timeout for the entire command sequence.
• Number of I2C Ports: As mentioned in Chapter 130, variants like ESP32, S2, S3, and H2 have two I2C controllers, while C3 and C6 have one. This doesn’t directly affect error handling mechanisms for a given port but offers flexibility in isolating problematic devices onto separate buses if one bus becomes persistently unreliable.
• GPIO Matrix: All these variants use the GPIO matrix, allowing I2C signals to be routed to most GPIO pins. The electrical characteristics of the pins and the board layout (trace length, pull-up placement) can influence susceptibility to noise and thus the frequency of certain errors. Robust hardware design is the first line of defense.

No significant differences exist in the ESP-IDF software API for error handling itself across these variants for a given I2C port. The strategies discussed (timeout, retry, checking return codes) apply universally.

Common Mistakes & Troubleshooting Tips

Exercises

1. Selective Retry Implementation:Modify the robust_i2c_write function from Example 1. Instead of retrying on any error, make it retry only if ret == ESP_FAIL (typically NACK). If ret == ESP_ERR_TIMEOUT, it should log a specific timeout error and perhaps only retry once or not at all, suggesting a more severe issue. For other errors like ESP_ERR_INVALID_ARG, it should not retry.
2. Error Counter and Degraded Mode Simulation:Create a global or static error counter for a specific I2C device. Each time a transaction with this device fails (even after retries), increment the counter. If the counter exceeds a threshold (e.g., 5 consecutive failures), your application should log a “Device X presumed offline, entering degraded mode” message and stop trying to communicate with that specific device for a while (e.g., 1 minute) before trying again. This simulates handling a persistently failing peripheral.
3. Research: I2C Hardware Watchdog/Reset ICs:Some systems use external ICs that can monitor I2C bus activity or provide a hardware reset to I2C slaves. Research such an IC (e.g., a simple I/O expander controlling power to an I2C slave, or a dedicated I2C bus supervisor).
   • Describe its functionality.
   • How could it be integrated with an ESP32 to improve I2C robustness beyond what software-only techniques can achieve? (Conceptual, no coding).

Summary

• Robust I2C communication relies on diligent error checking, primarily by inspecting the esp_err_t return value from ESP-IDF I2C functions.
• ESP_ERR_TIMEOUT (often from a stuck bus or unresponsive slave) and ESP_FAIL (often from NACKs) are common I2C errors.
• Configuring an appropriate ticks_to_wait timeout for i2c_master_cmd_begin is crucial to prevent indefinite blocking while still allowing legitimate transactions.
• Implementing retry logic with delays and a maximum attempt count can handle transient I2C errors.
• For severely stuck I2C buses, a “bus clear” procedure (manually clocking SCL and attempting a STOP via GPIO bit-banging) can be attempted, but requires careful driver management.
• Not all errors are recoverable by software; persistent issues may require hardware intervention (reset, power cycle) or a system-level strategy for graceful degradation.
• The ESP-IDF I2C error handling APIs are consistent across ESP32 variants.

Further Reading

• ESP-IDF I2C Driver Documentation: (Same as previous chapters)
  • ESP-IDF I2C API Reference (Check for your specific ESP32 variant if needed).
• NXP I2C Bus Specification (UM10204): Contains details on bus states, error conditions, and some recovery notes.
• Application Notes on I2C Robustness: Search for “I2C bus robustness,” “I2C error recovery,” or “I2C fault tolerance” from semiconductor manufacturers like NXP, Texas Instruments, Analog Devices, etc. They often provide insights into common failure modes and hardware/software solutions.