Implementing Timeouts for Blocking Serial Communication

1. The Problem: Blocking Calls

Many functions, especially those dealing with I/O, are blocking. This means the function will not return until its operation is complete. For example, a function to read 10 bytes from a serial port might wait indefinitely if the data never arrives. While waiting, your program is completely stuck at that line of code, unable to do anything else.

To get an intuitive feel for this problem, we'll watch a video that demonstrates it using a simple, common example: blinking LEDs with Arduino's delay() function. The principle is exactly the same for an ESP32 waiting on a sensor.

As you saw, the delay() function prevents any other part of the loop from running until it has finished. A serial read function waiting for data from an unpowered or disconnected sensor behaves in the exact same way—it can block your program forever.

From your mechanical engineering background, you can think of this like a critical control loop that gets stuck waiting for a sensor update. If the sensor fails and the code blocks, the loop can no longer send updated commands to actuators, potentially leading to system instability or failure.

2. Timeouts: The Solution to Blocking

The solution is to put a limit on how long a blocking function is allowed to wait. This is a timeout. If the operation doesn't complete within the specified time, the function gives up and returns an error, allowing your program to continue.

Many ESP-IDF functions that perform I/O operations have a built-in timeout parameter for this very reason. Let's look at how to use them for our serial protocols.

3. Implementing UART Timeouts

For UART communication, the primary function for reading data is uart_read_bytes(). As we'll see in the documentation, it includes a parameter specifically for setting a timeout.

The ticks_to_wait parameter specifies the maximum number of FreeRTOS "ticks" (the smallest unit of time for the scheduler) that the function should wait. Waiting forever can be specified with portMAX_DELAY.

Conveniently, FreeRTOS provides a macro pdMS_TO_TICKS() to convert milliseconds into ticks, which is much more intuitive.

The following video demonstrates the practical effect of this timeout parameter.

Here is how you would implement a UART read with a 100ms timeout:

#include "driver/uart.h"
#include "esp_log.h"

#define BUF_SIZE 1024
static const char* TAG = "UART_TIMEOUT_EXAMPLE";

void read_from_uart() {
    uint8_t* data = (uint8_t*) malloc(BUF_SIZE);
    const uart_port_t uart_num = UART_NUM_2;
    
    // Set a timeout of 100 milliseconds
    const TickType_t timeout_ticks = pdMS_TO_TICKS(100);

    // Try to read up to BUF_SIZE bytes, waiting a maximum of 100ms.
    int length = uart_read_bytes(uart_num, data, BUF_SIZE, timeout_ticks);

    if (length > 0) {
        ESP_LOGI(TAG, "Read %d bytes", length);
        // Process the received data here...
    } else {
        // If length is 0, it means the timeout expired before any data arrived.
        // If length is -1, it indicates a driver error.
        ESP_LOGW(TAG, "UART read timed out or failed.");
    }

    free(data);
}

In the UART driver, a timeout is not considered an esp_err_t error; the function simply returns with the number of bytes it managed to read before the time ran out (which can be 0).

4. Implementing I2C Timeouts

The I2C driver handles timeouts in a way that aligns more closely with our previous lesson. Most I2C transaction functions return an esp_err_t and accept a timeout value in milliseconds.

As the documentation shows, functions like i2c_master_transmit, i2c_master_receive, and i2c_master_transmit_receive all accept a timeout in milliseconds. If the bus is busy or the slave device doesn't respond within that time, the function will return ESP_ERR_TIMEOUT.

This makes handling the timeout straightforward, building on what you learned in the last lesson.

#include "driver/i2c.h"
#include "esp_log.h"
#include "esp_err.h"

static const char* TAG = "I2C_TIMEOUT_EXAMPLE";

esp_err_t read_i2c_sensor(i2c_master_dev_handle_t dev_handle, uint8_t* data_buf, size_t data_len) {
    // Set a timeout of 50 milliseconds for this transaction.
    int timeout_ms = 50;

    esp_err_t ret = i2c_master_receive(dev_handle, data_buf, data_len, timeout_ms);

    if (ret == ESP_OK) {
        ESP_LOGI(TAG, "I2C read successful.");
    } else if (ret == ESP_ERR_TIMEOUT) {
        ESP_LOGE(TAG, "I2C read timed out after %d ms.", timeout_ms);
        // This is where you might implement retry logic from the previous lesson.
    } else {
        ESP_LOGE(TAG, "I2C read failed: %s", esp_err_to_name(ret));
    }

    return ret;
}

Setting the timeout to -1 tells the function to wait forever, which is generally not recommended unless you have a specific reason to do so.

5. Choosing the Right Timeout Value

Selecting a timeout value is a balancing act:

• Too Short: You risk ESP_ERR_TIMEOUT errors even when the device is working correctly but is just a bit slow to respond. This can be caused by sensor processing time or a busy communication bus.
• Too Long: If a device fails, your application will be blocked for the full duration of the timeout, reducing its responsiveness. A 5-second timeout means your task is frozen for 5 seconds every time it tries to communicate with a dead sensor.

The ideal value depends on the specific device (check its datasheet for response times), the I2C bus speed, and your application's real-time requirements. A good starting point is often between 20ms and 100ms.

Conclusion

You have now learned how to tame blocking calls and build more predictable, resilient embedded applications. By setting explicit timeouts, you ensure that a single unresponsive peripheral won't bring your entire system to a halt.

Key Takeaways:

• Blocking calls halt program execution until they are complete, which can be dangerous if they wait indefinitely.
• Timeouts provide an exit strategy, limiting the maximum time a function will block.
• In ESP-IDF UART, use the ticks_to_wait parameter in uart_read_bytes(). A timeout here results in reading 0 bytes.
• In ESP-IDF I2C, use the xfer_timeout_ms parameter in transaction functions. A timeout here returns the ESP_ERR_TIMEOUT error code, which you can handle explicitly.
• Choosing a timeout value requires balancing device response time against system responsiveness.

This lesson concludes our module on Serial Communication Protocols. We've covered configuration, data parsing, error checking, and now, timeout handling for UART and I2C.

In our next lesson, we will begin a new module on a powerful feature of the ESP32: FreeRTOS. While timeouts prevent a task from blocking forever, they still cause it to block for a short period. With FreeRTOS, we will learn how to run multiple tasks concurrently, so that one task waiting on a sensor doesn't stop other tasks, like updating a display or controlling a motor, from running. This will be a major step forward in building complex applications.