I2C Communication Crash Prevention Strategies With ESP32 And ESP-IDF

Hey everyone,

I wanted to dive into a critical topic regarding I2C communication failures, particularly when using ESP_ERROR_CHECK in ESP32 projects. This is especially relevant for those of us working with the I2Cdevlib library and the ESP-IDF framework. We'll explore the potential pitfalls and discuss more robust error-handling strategies to ensure our applications are production-ready.

The Issue: ESP_ERROR_CHECK and I2C Communication

The core of the discussion revolves around the use of ESP_ERROR_CHECK with I2C functions like i2c_master_cmd_begin. While ESP_ERROR_CHECK is a handy tool for debugging, it can lead to unexpected behavior in production environments. Let's break down why.

Understanding ESP_ERROR_CHECK

In debug builds, ESP_ERROR_CHECK acts as a safety net. If a function call returns an error (i.e., a value other than ESP_OK), ESP_ERROR_CHECK triggers abort(), effectively halting the program. This is fantastic for catching errors during development, as it immediately flags issues and prevents the program from running with potentially corrupted data.

The Problem in Production

Here's where things get tricky. In production builds, ESP_ERROR_CHECK is often disabled (it becomes an empty macro). This means that if a function like i2c_master_cmd_begin fails—for example, due to the I2C bus being busy (ESP_ERR_TIMEOUT)—the error is essentially ignored. Consider this scenario with the writeBytes function from I2Cdevlib:

bool I2Cdev::writeBytes(uint8_t devAddr, uint8_t regAddr, uint8_t length, uint8_t *data) {
    i2c_cmd_handle_t cmd = i2c_cmd_link_create();
    I2C_DEV_CHECK(i2c_master_start(cmd));
    I2C_DEV_CHECK(i2c_master_write_byte(cmd, (devAddr << 1) | I2C_MASTER_WRITE, I2C_MASTER_ACK));
    I2C_DEV_CHECK(i2c_master_write_byte(cmd, regAddr, I2C_MASTER_ACK));
    I2C_DEV_CHECK(i2c_master_write(cmd, data, length, I2C_MASTER_ACK));
    I2C_DEV_CHECK(i2c_master_stop(cmd));
    esp_err_t ret = i2c_master_cmd_begin(I2C_NUM, cmd, 1000 / portTICK_RATE_MS);
    i2c_cmd_link_delete(cmd);

If i2c_master_cmd_begin fails and ESP_ERROR_CHECK is disabled, the ret variable will hold the error code, but the function will continue executing. The writeBytes function, unaware of the failure, will return true, indicating a successful write even though it wasn't. This can lead to unpredictable behavior and data corruption in your application.

I2C: A Sensitive Protocol

It’s crucial to remember that I2C is a sensitive communication protocol. It relies on precise timing and acknowledgment signals. Ignoring errors can lead to the device going out of sync, resulting in further communication failures and potentially a system crash. We need a more robust way to handle these situations.

The Solution: Robust Error Handling for Production

So, what's the alternative? Instead of relying solely on ESP_ERROR_CHECK, we need to implement more explicit and nuanced error handling. This involves checking the return values of I2C functions and taking appropriate actions based on the specific error encountered.

Embracing if/else Statements

The most straightforward approach is to use if/else statements to check the return values of I2C functions. This allows us to handle different error scenarios in a controlled manner. For example:

esp_err_t ret = i2c_master_cmd_begin(I2C_NUM, cmd, 1000 / portTICK_RATE_MS);
if (ret != ESP_OK) {
    // Handle the error
    ESP_LOGE(TAG, "I2C master command failed: %s", esp_err_to_name(ret));
    // Retry the operation, return an error, or take other appropriate action
    return false; // Indicate failure
} else {
    // Operation was successful
    return true; // Indicate success
}

In this example, we explicitly check the return value of i2c_master_cmd_begin. If it's not ESP_OK, we log an error message and can choose to retry the operation, return an error to the calling function, or take other corrective actions. This gives us much finer-grained control over error handling.

Returning esp_err_t

Another effective strategy is to return the esp_err_t value from your I2C functions. This allows the calling function to handle the error as it sees fit. For example:

esp_err_t writeBytes(uint8_t devAddr, uint8_t regAddr, uint8_t length, uint8_t *data) {
    i2c_cmd_handle_t cmd = i2c_cmd_link_create();
    esp_err_t ret;

    ret = i2c_master_start(cmd);
    if (ret != ESP_OK) goto error;

    ret = i2c_master_write_byte(cmd, (devAddr << 1) | I2C_MASTER_WRITE, I2C_MASTER_ACK);
    if (ret != ESP_OK) goto error;

    ret = i2c_master_write_byte(cmd, regAddr, I2C_MASTER_ACK);
    if (ret != ESP_OK) goto error;

    ret = i2c_master_write(cmd, data, length, I2C_MASTER_ACK);
    if (ret != ESP_OK) goto error;

    ret = i2c_master_stop(cmd);
    if (ret != ESP_OK) goto error;

    ret = i2c_master_cmd_begin(I2C_NUM, cmd, 1000 / portTICK_RATE_MS);
    if (ret != ESP_OK) goto error;

    i2c_cmd_link_delete(cmd);
    return ESP_OK; // Indicate success

error:
    i2c_cmd_link_delete(cmd);
    return ret; // Return the error code
}

In this revised writeBytes function, we check the return value of each I2C function call. If an error occurs, we jump to an error label, delete the command link, and return the error code. This allows the caller to handle the error appropriately.

Implementing Retry Mechanisms

In many cases, I2C communication failures are transient. The bus might be temporarily busy, or there might be a minor glitch. In such scenarios, implementing a retry mechanism can significantly improve the robustness of your application. Here’s an example:

esp_err_t writeBytesWithRetry(uint8_t devAddr, uint8_t regAddr, uint8_t length, uint8_t *data, int retries) {
    esp_err_t ret;
    for (int i = 0; i < retries; i++) {
        ret = writeBytes(devAddr, regAddr, length, data);
        if (ret == ESP_OK) {
            return ESP_OK; // Success!
        }
        ESP_LOGW(TAG, "I2C write failed, retrying (%d/%d): %s", i + 1, retries, esp_err_to_name(ret));
        vTaskDelay(pdMS_TO_TICKS(10)); // Wait a bit before retrying
    }
    ESP_LOGE(TAG, "I2C write failed after %d retries: %s", retries, esp_err_to_name(ret));
    return ret; // Return the last error
}

This writeBytesWithRetry function attempts to write the data multiple times. If a write fails, it logs a warning, waits for a short period, and retries. After a certain number of retries, it gives up and returns the error. This approach can handle transient errors effectively.

The Importance of Logging

Regardless of the error-handling strategy you choose, logging is crucial. When an I2C error occurs, it's essential to log the error code, the function in which the error occurred, and any other relevant information. This helps in diagnosing issues and understanding the behavior of your system.

Use ESP_LOGE (error), ESP_LOGW (warning), and ESP_LOGI (info) macros to log messages at different severity levels. Include the error code (obtained using esp_err_to_name) in your log messages to provide clear information about the failure.

Applying These Strategies to I2Cdevlib

Now, let’s bring it back to I2Cdevlib. The original poster highlighted the writeBytes function as a potential area of concern. We can apply the principles we’ve discussed to make this function more robust.

Here’s how we might modify the writeBytes function in I2Cdevlib to include proper error handling:

bool I2Cdev::writeBytes(uint8_t devAddr, uint8_t regAddr, uint8_t length, uint8_t *data) {
    i2c_cmd_handle_t cmd = i2c_cmd_link_create();
    esp_err_t ret = ESP_OK;

    ret = i2c_master_start(cmd);
    if (ret != ESP_OK) goto cleanup;

    ret = i2c_master_write_byte(cmd, (devAddr << 1) | I2C_MASTER_WRITE, I2C_MASTER_ACK);
    if (ret != ESP_OK) goto cleanup;

    ret = i2c_master_write_byte(cmd, regAddr, I2C_MASTER_ACK);
    if (ret != ESP_OK) goto cleanup;

    ret = i2c_master_write(cmd, data, length, I2C_MASTER_ACK);
    if (ret != ESP_OK) goto cleanup;

    ret = i2c_master_stop(cmd);
    if (ret != ESP_OK) goto cleanup;

    ret = i2c_master_cmd_begin(I2C_NUM, cmd, 1000 / portTICK_RATE_MS);
    if (ret != ESP_OK) goto cleanup;

    i2c_cmd_link_delete(cmd);
    return true; // Indicate success

cleanup:
    i2c_cmd_link_delete(cmd);
    ESP_LOGE(TAG, "I2C writeBytes failed: %s", esp_err_to_name(ret));
    return false; // Indicate failure
}

In this modified version, we’ve replaced I2C_DEV_CHECK with explicit error checking using if statements. If any of the I2C functions return an error, we jump to the cleanup label, delete the command link, log the error, and return false. This ensures that the calling function is aware of the failure.

Conclusion: Prioritizing Robustness

In conclusion, while ESP_ERROR_CHECK is a valuable tool during development, it's not sufficient for robust error handling in production environments. We need to embrace more explicit error checking, using if/else statements, returning esp_err_t values, and implementing retry mechanisms where appropriate. By prioritizing robust error handling, we can build more reliable and stable ESP32 applications that utilize I2C communication.

By implementing these strategies, we can ensure our I2C communication is more resilient and our applications are better prepared for the challenges of a production environment. Let's continue to share our experiences and best practices to build even more robust and reliable systems! Happy coding, everyone!