ESP32 Mutex Example: Fix FreeRTOS Race Conditions and Watchdog Crashes

When you run multiple concurrent tasks on the ESP32's dual-core Xtensa LX6 processor, sharing hardware resources like the I2C bus, SPI, or the Serial port without protection is a guaranteed way to corrupt data or crash the system. A mutex (mutual exclusion) acts as a digital padlock. Only the task holding the mutex token can access the shared resource; all other tasks must wait until the token is returned.

If you are seeing garbled OLED output, intermittent sensor readings, or sudden reboots, you likely have a race condition. Below is a production-ready ESP32 mutex example targeting the Arduino IDE environment, complete with timeout error handling and a debugging matrix for when things go wrong.

Project Spec Sheet & Hardware Requirements

This build demonstrates two concurrent FreeRTOS tasks attempting to write to a shared I2C OLED display and the Serial monitor simultaneously. We use a timeout-based mutex approach rather than infinite blocking, which is critical for preventing watchdog resets in embedded systems.

Bill of Materials

• Microcontroller: ESP32-WROOM-32 DevKit V1 (e.g., NodeMCU-32S)
• Display: 0.96" I2C OLED (SSD1306 driver, 0x3C address)
• Wiring: 4x silicone jumper wires (breadboard compatible)
• Debugging Tool (Optional): 24MHz Logic Analyzer (to visually confirm I2C bus contention and mutex release timing)

Pin Mapping Table

The Complete ESP32 Mutex Example Code

The following code is fully compilable in the Arduino IDE (ensure you have the ESP32 board manager installed and the Adafruit_SSD1306 and Adafruit_GFX libraries added via the Library Manager). It creates two tasks pinned to different cores. Both tasks require the I2C bus to update the display and print to Serial.

Instead of using portMAX_DELAY (which blocks forever and can trigger the Task Watchdog if a task crashes while holding the lock), we use a 100-millisecond timeout. If the mutex cannot be acquired, the task logs an error and yields, keeping the system alive.

#include <Arduino.h>
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

// --- Pin Definitions & Hardware Config ---
#define SDA_PIN 21
#define SCL_PIN 22
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET   -1
#define OLED_I2C_ADDR 0x3C

// --- Mutex Timeout Config ---
#define MUTEX_TIMEOUT_MS 100

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
SemaphoreHandle_t i2c_mutex;

// Forward declarations
void task1_SensorRead(void *pvParameters);
void task2_NetworkLog(void *pvParameters);

void setup() {
  Serial.begin(115200);
  delay(500); // Allow serial monitor to connect
  
  Wire.begin(SDA_PIN, SCL_PIN);
  
  if(!display.begin(SSD1306_SWITCHCAPVCC, OLED_I2C_ADDR)) {
    Serial.println(F("[FATAL] SSD1306 allocation failed. Check I2C wiring."));
    for(;;); // Halt
  }
  display.clearDisplay();
  display.display();

  // Create the Mutex
  i2c_mutex = xSemaphoreCreateMutex();
  if (i2c_mutex == NULL) {
    Serial.println("[FATAL] Mutex creation failed! Insufficient heap.");
    while(1);
  }

  // Create Tasks pinned to specific cores to force cross-core contention
  xTaskCreatePinnedToCore(task1_SensorRead, "SensorTask", 2048, NULL, 1, NULL, 0); // Core 0
  xTaskCreatePinnedToCore(task2_NetworkLog, "NetworkTask", 2048, NULL, 1, NULL, 1); // Core 1
}

void loop() {
  // Loop is left empty; FreeRTOS tasks handle execution
  vTaskDelay(portMAX_DELAY);
}

void task1_SensorRead(void *pvParameters) {
  int simulated_sensor_val = 0;
  while(1) {
    simulated_sensor_val = analogRead(34); // Read GPIO 34
    
    // Attempt to take the mutex with a timeout
    if (xSemaphoreTake(i2c_mutex, pdMS_TO_TICKS(MUTEX_TIMEOUT_MS)) == pdTRUE) {
      // --- CRITICAL SECTION START ---
      display.clearDisplay();
      display.setTextSize(1);
      display.setTextColor(SSD1306_WHITE);
      display.setCursor(0,0);
      display.print("Sensor: ");
      display.println(simulated_sensor_val);
      display.display();
      
      Serial.print("[Task1] Sensor: ");
      Serial.println(simulated_sensor_val);
      // --- CRITICAL SECTION END ---
      
      xSemaphoreGive(i2c_mutex); // Release mutex
    } else {
      Serial.println("[Task1 ERROR] Mutex timeout! Bus busy.");
    }
    vTaskDelay(pdMS_TO_TICKS(200));
  }
}

void task2_NetworkLog(void *pvParameters) {
  int packet_count = 0;
  while(1) {
    packet_count++;
    
    if (xSemaphoreTake(i2c_mutex, pdMS_TO_TICKS(MUTEX_TIMEOUT_MS)) == pdTRUE) {
      // --- CRITICAL SECTION START ---
      display.setCursor(0,20);
      display.print("Packets: ");
      display.println(packet_count);
      display.display();
      
      Serial.print("[Task2] Packets: ");
      Serial.println(packet_count);
      // --- CRITICAL SECTION END ---
      
      xSemaphoreGive(i2c_mutex);
    } else {
      Serial.println("[Task2 ERROR] Mutex timeout! Bus busy.");
    }
    vTaskDelay(pdMS_TO_TICKS(350));
  }
}

Debugging: When Your Mutex Fails

Even with a mutex in place, improper implementation will crash the ESP32. If your board enters a bootloop or freezes, check these first three things:

1. Did you release the mutex on every code path? If you have an early return or a break statement inside the critical section, the mutex is never given back. All subsequent tasks will time out or block forever.
2. Are you calling the mutex from an ISR? Interrupt Service Routines cannot block. Calling xSemaphoreTake inside an ISR will instantly trigger an assertion failure.
3. Is a higher-priority task starving the holder? If Task A (low priority) holds the mutex, and Task B (high priority) is waiting for it, but Task C (high priority) keeps preempting Task A, Task A never gets the CPU time to finish its work and release the mutex. This is called priority inversion.

Exact Error Strings and Ranked Causes

When the ESP32 crashes, it dumps a core trace to the Serial monitor. Here is how to decode the most common mutex-related failures.

For deeper architectural reference on how FreeRTOS handles these queues under the hood, consult the official FreeRTOS Semaphore and Mutex documentation. For ESP32-specific hardware interrupt constraints, refer to the Espressif FreeRTOS API Reference.

Extending and Simplifying the Build

Depending on your project scope, you may need to scale this architecture up or strip it down.

How to Extend the Build

• Recursive Mutexes: If your critical section calls a function that also tries to take the same mutex, a standard mutex will deadlock. Replace xSemaphoreCreateMutex() with xSemaphoreCreateRecursiveMutex(). You must then use xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive(), and ensure you give it back the exact number of times you took it.
• SPI Bus Sharing: The exact same mutex logic applies to SPI. If you have an SD card and an SPI display on the same bus, wrap the SD.open() and display.write() calls in the same mutex critical section.
• Priority Inheritance: To solve the priority inversion mentioned in the debugging section, FreeRTOS standard mutexes actually implement priority inheritance by default. When a high-priority task blocks on a mutex held by a low-priority task, the RTOS temporarily boosts the low-priority task to the higher level until it releases the lock.

How to Simplify the Build

• Single-Core Execution: If you don't strictly need true parallel processing, pin all hardware-interfacing tasks to Core 0, and leave Core 1 for Wi-Fi/Bluetooth stack operations. If only one task ever touches the I2C bus, you can delete the mutex entirely.
• C++ std::lock_guard: If you are writing modern C++ on the ESP32, you can wrap the FreeRTOS mutex in a custom class and use std::lock_guard to guarantee the mutex is released when the variable goes out of scope, eliminating the risk of forgotten xSemaphoreGive() calls during early returns.

Frequently Asked Questions

What is the difference between a mutex and a semaphore in ESP32?

A mutex is designed for resource protection; it has the concept of an "owner." Only the task that takes the mutex can give it back. A binary semaphore is designed for task synchronization (signaling); a task can take it, and an entirely different task (or an ISR) can give it back. For protecting an I2C bus or global variable, always use a mutex.

Can I use an ESP32 mutex example inside an interrupt (ISR)?

No. Standard mutexes require the RTOS scheduler to potentially put a task to sleep while it waits for the lock. Context switching inside an ISR is forbidden on the ESP32. If you must signal a task from an ISR, use a Binary Semaphore or a FreeRTOS Queue, and use the FromISR variants of the API (e.g., xSemaphoreGiveFromISR).

Why does my ESP32 mutex example cause a watchdog timeout?

The ESP32 has a Task Watchdog Timer (TWDT) that defaults to 5 seconds. If a high-priority task enters a critical section and gets stuck (e.g., waiting for an I2C ACK that never arrives due to a disconnected wire), it will hold the mutex indefinitely. Other tasks waiting on that mutex will block, eventually starving the Idle tasks. When the Idle tasks on either core are starved for 5 seconds, the TWDT triggers a Guru Meditation Error and reboots the chip. Always use hardware timeouts (like Wire.setWireTimeout()) alongside your mutex timeouts.

How do I check if a mutex is locked without blocking?

Pass a timeout of 0 ticks to the take function: xSemaphoreTake(i2c_mutex, 0). If it returns pdTRUE, you successfully acquired the lock (meaning it was unlocked). If it returns pdFALSE, the mutex is currently held by another task, and your code can immediately execute a fallback routine instead of waiting.