LED Control

1. GPIO Overview

GPIO (General Purpose Input/Output) is the most fundamental peripheral interface of MCUs. Through software configuration, chip pins can be set to Input mode (reading external signals) or Output mode (driving external circuits).

This experiment controls two onboard LEDs to blink synchronously at 1Hz, demonstrating the basic workflow of GPIO output control. The code uses a component-based layered design, encapsulating hardware operations into semantic macros, so upper-layer applications don't need to worry about pin numbers or polarity.

Typical GPIO application scenarios:

2. Core Concepts

2.1 Common-Anode LED Connection

This board uses Common-Anode LED connection:

xxxxxxxxxx
VDD (3.3V) ──→ LED Anode ──→ LED Cathode ──→ Current-Limiting Resistor ──→ GPIO Pin

Core Understanding: In common-anode connection, GPIO output low = LED ON. This is opposite to the intuition "1=on", so semantic macros are crucial—LED0(0) means "turn on LED0", and the macro internally translates to gpio_set_level(GPIO43, 0).

2.2 Layered Architecture

This project follows the hardware abstraction layering principle:

xxxxxxxxxx
┌────────────────────────────────┐
│  app_main()                    │  ← Application layer: only cares about LED0_TOGGLE() semantics
│  Doesn't care about pin numbers, polarity, or driver details     │
├────────────────────────────────┤
│  components/LED/led.h / led.c  │  ← LED driver layer: semantic macros + initialization
│  LED0(0)=ON, LED0(1)=OFF      │     Encapsulates polarity, pins, and configuration flow
├────────────────────────────────┤
│  driver/gpio.h                 │  ← Driver layer: gpio_set_level / gpio_config
│  gpio_config() / set/get       │     IDF abstracts GPIO hardware operations
├────────────────────────────────┤
│  ESP32-S3 GPIO Hardware        │  ← Physical layer: IO MUX + Matrix + Pad
└────────────────────────────────┘

Benefits of Layering:

1. Changing pins only requires modifying macros in led.h, zero changes to application code

2. Semantic macro LED0(0) is more intuitive than gpio_set_level(43, 0), eliminating confusion about "why is 0 ON"

3. LED driver component is reusable—all example routines needing LED operations can reference components/LED/

3. ESP32-S3 GPIO Hardware Characteristics

Special Pin Reminders:

4. Project Architecture and Flow

xxxxxxxxxx
app_main()
  ├─ nvs_flash_init()      ← Initialize NVS (erase and rebuild if failed)
  │
  ├─ led_init()            ← Initialize GPIO43 / GPIO44 one by one
  │   ├─ gpio_config(GPIO43)  Push-pull bidirectional, no pull-up/down, no interrupt
  │   ├─ gpio_config(GPIO44)  Push-pull bidirectional, no pull-up/down, no interrupt
  │   ├─ LED0(1)               Initial: output high = OFF
  │   └─ LED1(1)               Initial: output high = OFF
  │
  └─ while(1) Main Loop
      ├─ LED0_TOGGLE()     Read level → invert → write
      ├─ LED1_TOGGLE()     Read level → invert → write
      └─ vTaskDelay(500ms) Delay 500ms (release CPU)

Source File Structure:

xxxxxxxxxx
1.LED/
├── CMakeLists.txt               # Top-level build file
├── main/
│   ├── CMakeLists.txt           # main component (depends on esp_driver_gpio / nvs_flash / LED)
│   └── main.c                   # Application entry app_main()
└── components/
    └── LED/
        ├── CMakeLists.txt       # LED component (depends on esp_driver_gpio)
        ├── led.h                # Pin macros + control macros + function declarations
        └── led.c                # GPIO initialization implementation

5. Hardware Dependencies

Hardware Connection:

Dependencies: esp_driver_gpio, nvs_flash, freertos, LED

6. Source Code Analysis

6.1 LED Driver Layer — led.h: Macro Encapsulation

The header file defines pin numbers and semantic control macros, which is the core abstraction of the entire driver:

xxxxxxxxxx
// ============ Pin definitions ============
#define LED0_GPIO_PIN   GPIO_NUM_43
#define LED1_GPIO_PIN   GPIO_NUM_44

// ============ Output control macros (1=OFF, 0=ON) ============
#define LED0(x) do { \
    x ? gpio_set_level(LED0_GPIO_PIN, 1) : \
        gpio_set_level(LED0_GPIO_PIN, 0); \
} while (0)

// ============ Toggle macros ============
#define LED0_TOGGLE() do { \
    gpio_set_level(LED0_GPIO_PIN, !gpio_get_level(LED0_GPIO_PIN)); \
} while (0)

Why wrap macros with do { ... } while(0)? This is the standard safe写法 for multi-statement C macros. Without wrapping, if (cond) LED0(0); else ... would cause compilation errors due to semicolon parsing. do-while(0) ensures the macro is a complete syntactic unit in any control flow context.

LED0_TOGGLE() three-step process:

1. gpio_get_level() — Read current level (HIGH=1 / LOW=0)

2. ! — Invert

3. gpio_set_level() — Write inverted level

6.2 LED Driver Layer — led.c: Initialization

led_init() is the most core function of this experiment—configuring GPIO hardware registers, determining the pin's working mode. Let's break it down line by line and also explain ESP32-S3 GPIO configuration options.

xxxxxxxxxx
void led_init(void)
{
    gpio_config_t gpio_init_struct = {0};

    gpio_init_struct.intr_type    = GPIO_INTR_DISABLE;
    gpio_init_struct.mode         = GPIO_MODE_INPUT_OUTPUT;
    gpio_init_struct.pull_up_en   = GPIO_PULLUP_DISABLE;
    gpio_init_struct.pull_down_en = GPIO_PULLDOWN_DISABLE;

    gpio_init_struct.pin_bit_mask = 1ull << LED0_GPIO_PIN;
    ESP_ERROR_CHECK(gpio_config(&gpio_init_struct));

    gpio_init_struct.pin_bit_mask = 1ull << LED1_GPIO_PIN;
    ESP_ERROR_CHECK(gpio_config(&gpio_init_struct));

        LED0(1);   // Initial OFF
        LED1(1);   // Initial OFF
}

6.2.1 gpio_config_t Structure

ESP32-S3 GPIO configuration uses independent struct fields: mode, pull-up/down, interrupt, and pin are four independent dimensions. Fill in → call gpio_config() to write to hardware registers at once. This is more flexible than STM32's traditional approach of encoding 8 modes + pull-up/down into enum combinations.

xxxxxxxxxx
typedef struct {
    uint64_t      pin_bit_mask;   // Pin bitmask, bit N=1 means GPIO_N is selected
    gpio_mode_t   mode;           // GPIO mode, 6 choices
    gpio_pullup_t pull_up_en;     // Internal pull-up (0=OFF, 1=ON)
    gpio_pulldown_t pull_down_en; // Internal pull-down (0=OFF, 1=ON)
    gpio_int_type_t intr_type;    // Interrupt type
} gpio_config_t;

6.2.2 mode — Six GPIO Operating Modes

ESP-IDF defines 6 modes. For LED blinking, we only need two, the rest are for reference:

Push-Pull Output — Internally uses PMOS + NMOS complementary pair, high and low levels are actively driven by the chip, fast transition and strong drive capability:

xxxxxxxxxx
        VDD
         │      Output 1 → PMOS conducts, NMOS turns off → pin pulled to VDD
       PMOS     Output 0 → PMOS turns off, NMOS conducts → pin pulled to GND
         ├── PAD
       NMOS     Not suitable for multiple output pins in parallel (one pulls high + one pulls low = short circuit)
         │
        GND

Open-Drain Output — Only NMOS, high level relies on external pull-up resistor, multiple devices can share bus (wire-AND):

xxxxxxxxxx
   External pull-up resistor ── VDD
         │        Output 0 → NMOS conducts → pull low
       PAD        Output 1 → NMOS turns off → external resistor pulls high
         │
       NMOS       Suitable for I2C, single-wire multi-device sharing scenarios
         │
        GND

This project selects GPIO_MODE_INPUT_OUTPUT (push-pull bidirectional): Compared to GPIO_MODE_OUTPUT, it adds input enable, ensuring LED0_TOGGLE() calling gpio_get_level() reliably reads back the current level.

6.2.3 pull_up_en / pull_down_en — Internal Pull-up/Pull-down

ESP32-S3 has built-in ~ 45kΩ weak pull-up/pull-down resistors:

Typical combinations:

This project sets PU=0, PD=0: LEDs are actively driven by GPIO push-pull output, level is always defined, pull-up/down only adds unnecessary static power consumption.

6.3 Application Layer — main.c: Program Entry

xxxxxxxxxx
void app_main(void)
{
    // ===== NVS Initialization =====
    esp_err_t ret = nvs_flash_init();
    if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
        ESP_ERROR_CHECK(nvs_flash_erase());
        ESP_ERROR_CHECK(nvs_flash_init());
    }

    // ===== LED Initialization =====
    led_init();

    // ===== Main Loop =====
    while (1) {
        LED0_TOGGLE();
        LED1_TOGGLE();
        vTaskDelay(pdMS_TO_TICKS(500));
    }
}

NVS Initialization: nvs_flash_init() initializes ESP-IDF's key-value storage system. Wi-Fi configuration, PHY calibration data, etc. are stored in NVS partition. Even if not using Wi-Fi, initialization is recommended (many IDF subsystems depend on it).

Why use vTaskDelay() instead of bare-metal delay()? vTaskDelay() suspends the current task to Blocked state for 500ms, during which the CPU can execute other tasks. Bare-metal delay is busy-waiting, which should always be avoided under RTOS. pdMS_TO_TICKS(500) converts 500ms to FreeRTOS tick count.

6.4 Build Files — CMakeLists.txt

LED Component (components/LED/CMakeLists.txt):

xxxxxxxxxx
idf_component_register(
    SRCS "led.c"
    INCLUDE_DIRS "."
    REQUIRES esp_driver_gpio)

• SRCS — Component source files

• INCLUDE_DIRS — Header file search path (. = current directory)

• REQUIRES — Depends on esp_driver_gpio

main Component (main/CMakeLists.txt):

xxxxxxxxxx
idf_component_register(
    SRCS "main.c"
    INCLUDE_DIRS "."
    REQUIRES esp_driver_gpio nvs_flash LED)

After declaring dependency on LED, CMake automatically finds components/LED/ and links it.

7. Operation Flow

7.1 Build and Flash

For detailed flashing process, see: 1. Before Development → 3. Build and Flash

7.2 Expected Behavior

• Both LEDs blink synchronously at 1Hz

• ON 500ms → OFF 500ms → repeat

• No serial log output (this experiment has no printf / ESP_LOGI calls)

  

  

7.3 Verification Methods

8. Common Issues