Mutex

1. Mutex Overview

1.1 What is a Mutex

Mutex is FreeRTOS's core mechanism for protecting shared resources. When multiple tasks need to access the same global variable, peripheral, or data structure, mutex ensures that only one task can enter the critical section at any given time, preventing data races.

1.2 Importance and Application Scenarios

Mutex is one of the most commonly used, most fundamental synchronization mechanisms in RTOS multi-tasking programming, and almost any scenario involving multi-task shared resources relies on it:

Core Value: Mutex is not only a tool for protecting data, but also the cornerstone of ensuring system stability and predictability. Unlocked shared resource access is one of the hardest to reproduce, hardest to debug bugs in embedded systems.

1.3 This Project Demonstrates

This project demonstrates mutex through a "Grab Goods Game" (Human vs AI): Producer produces goods every second, human holds BOOT button to grab lock→releases to grab goods, AI automatically grabs lock→grabs goods→cools down for 1s. First to grab 10 goods wins. Human wins → rainbow LED cycling, AI wins → solid red LED.

Through this game, you will intuitively understand: lock exclusivity (human keeps holding → AI can never get lock), critical section protection (all stock/score operations are inside the lock), and deadlock prevention (each task strictly follows Take → Operation → Give order).

2. Core Concepts

2.1 How Mutex Works

  Task A                Task B
    │                     │
    │ xSemaphoreTake()    │ xSemaphoreTake()
    ▼ (got lock)          ▼ (blocked, waiting)
  ┌────────────┐         ╔══════════════╗
  │  Critical  │         ║ Waiting for   ║
  │  Section   │         ║ lock release...║
  │  Access    │         ╚══════════════╝
  │  shared    │
  │  variables │
  └────────────┘              │
    │                         │
    │ xSemaphoreGive()        ▼ (got lock)
    ▼ (release lock)      ┌────────────┐
                           │  Critical  │
                           │  Section   │
                           └────────────┘

2.2 Mutex API

​x
// Create mutex
SemaphoreHandle_t xSemaphoreCreateMutex(void);

// Take lock (enter critical section)
xSemaphoreTake(xMutex, portMAX_DELAY);

// Give lock (exit critical section)
xSemaphoreGive(xMutex);

2.3 Mutex vs Binary Semaphore

Mutex priority inheritance mechanism is key to solving priority inversion. When a high-priority task waits for a lock, the low-priority task holding the lock is temporarily elevated to high priority to ensure quick lock release.

2.4 Shared Resource Protection Principles

xxxxxxxxxx
All code accessing g_goods must:
  1. xSemaphoreTake(xMutex, ...)  ← Take lock
  2. Read/modify g_goods          ← Critical section
  3. xSemaphoreGive(xMutex)       ← Give lock

Missing any step = data race = bug

3. Project Architecture and Flow

xxxxxxxxxx
app_main()
  ├─ rgb_init() + key_init()          ← WS2812 (GPIO48) + Button (GPIO0)
  ├─ xSemaphoreCreateMutex()          ← Create mutex (protects: g_goods, g_human_score, g_ai_score)
  ├─ xTaskCreate(vProducer)           ← Producer (Prio 2)
  ├─ xTaskCreate(vConsumer1_Human)    ← Human (Prio 3)
  └─ xTaskCreate(vConsumer2_AI)       ← AI (Prio 2)

  Producer ──(take→produce n→give)──► g_goods    ← Shared resource
  Human    ──(hold→take...release→grab→give)──► g_human_score
  AI       ──(take→grab→give→cool 1s)──► g_ai_score

  Human holds button continuously → Lock always held by Human → AI blocks permanently at xSemaphoreTake
                                        → Demonstrates mutex exclusivity

Game Rules:

4. Hardware Dependencies

Required Components: freertos/FreeRTOS, freertos/task, freertos/semphr, driver/gpio, led_strip, esp_log, esp_random

This project uses a third-party library again: For details, review (Third-party library installation process: 2.Basic Peripherals → 10.RGB LED Effects)

Note: led_strip is a third-party component provided by ESP-IDF Component Registry, not built into IDF. Before use, declare dependency in main/idf_component.yml:

xxxxxxxxxx
## IDF Component Manager Manifest File
dependencies:
idf:
 version: '>=4.1.0'
espressif/led_strip: ^3.0.3

After declaration, execute idf.py build, and component manager will automatically download component to managed_components/ directory.

5. Source Code Analysis

Full source code: Source Code → ESP-IDF → 4.FreeRTOS → 2. RTOS_Inter-task_communication → RTOS-MUTEX

5.1 Header Files and Macro Configuration

This section defines GPIO pins, game parameters, and all shared resource variables protected by mutex.

xxxxxxxxxx
#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/semphr.h"
#include "esp_log.h"
#include "esp_random.h"
#include "driver/gpio.h"
#include "led_strip.h"

static const char *TAG = "MUTEX_GAME";

// ---- GPIO Pin Definitions ----
#define KEY_GPIO        0
#define BLINK_GPIO      48
#define LED_NUM         1
#define DEBOUNCE_MS     50

// ---- Game Parameters ----
#define WIN_COUNT       10
#define PRODUCE_MIN     2
#define PRODUCE_MAX     5
#define AI_COOLDOWN_MS  1000

// ---- Rainbow Colors (WS2812 GRB Order) ----
typedef struct {
    uint8_t green;
    uint8_t red;
    uint8_t blue;
} led_color_t;

static const led_color_t rainbow_colors[] = {
    {0,   150, 0  },   // Red
    {60,  150, 0  },   // Orange
    {150, 150, 0  },   // Yellow
    {150, 0,   0  },   // Green
    {150, 0,   150},   // Cyan
    {0,   0,   150},   // Blue
    {0,   120, 150},   // Purple
};
#define COLOR_COUNT  7

// ---- Shared Resources (all protected by mutex) ----
static SemaphoreHandle_t xMutex = NULL;
static int  g_goods       = 0;
static int  g_human_score = 0;
static int  g_ai_score    = 0;
static bool g_game_over   = false;
static int  g_winner      = 0;

static led_strip_handle_t led_strip;

5.2 key_init() — Button GPIO Initialization

Configure BOOT button (GPIO0) as internal pull-up input mode, low level when pressed.

xxxxxxxxxx
static void key_init(void)
{
    gpio_config_t cfg = {
        .pin_bit_mask = 1ULL << KEY_GPIO,
        .mode         = GPIO_MODE_INPUT,
        .pull_up_en   = GPIO_PULLUP_ENABLE,
        .pull_down_en = GPIO_PULLDOWN_DISABLE,
        .intr_type    = GPIO_INTR_DISABLE,
    };
    gpio_config(&cfg);
}

5.3 rgb_init() — WS2812 LED Initialization

Initialize WS2812 strip on GPIO48 via RMT peripheral.

xxxxxxxxxx
static void rgb_init(void)
{
    led_strip_config_t strip_cfg = {
        .strip_gpio_num          = BLINK_GPIO,
        .max_leds                = LED_NUM,
        .led_model               = LED_MODEL_WS2812,
        .color_component_format  = LED_STRIP_COLOR_COMPONENT_FMT_GRB,
        .flags.invert_out        = false,
    };
    led_strip_rmt_config_t rmt_cfg = {
        .resolution_hz = 10 * 1000 * 1000,
        .flags.with_dma = false,
    };
    ESP_ERROR_CHECK(led_strip_new_rmt_device(&strip_cfg, &rmt_cfg, &led_strip));
    led_strip_clear(led_strip);
}

5.4 rgb_set() / rgb_rainbow_loop() / rgb_red_loop() — LED Display Functions

Three LED control functions: set solid color, rainbow cycle, solid red.

xxxxxxxxxx
static void rgb_set(uint8_t r, uint8_t g, uint8_t b)
{
    led_strip_set_pixel(led_strip, 0, r, g, b);
    led_strip_refresh(led_strip);
}

static void rgb_rainbow_loop(void)
{
 Binary Semaphore
Event Groups