📚 课程目录第1章点亮板载LED

1. 点亮板载LED

任务目标

编写并烧录一个ESP-IDF工程，将开发板上的板载LED点亮，以此验证ESP-IDF开发环境已正确搭建、编译烧录链路通畅，并掌握最基本的GPIO输出操作。

硬件与前置条件

一块ESP32系列开发板（如ESP32-DevKitC、ESP32-S3-DevKitC等），板载LED通常连接在GPIO2（ESP32）或GPIO48（ESP32-S3）等特定引脚。
已安装ESP-IDF开发环境（建议v5.x版本），并配置好目标芯片（idf.py set-target esp32或对应型号）。
开发板通过USB线连接电脑，确认串口驱动已识别。

确定板载LED引脚

不同开发板的板载LED引脚不同，请先查阅开发板原理图或丝印。常见对应关系如下：

ESP32-DevKitC：GPIO2（蓝色LED，低电平点亮）
ESP32-S3-DevKitC-1：GPIO48（RGB LED中的绿色通道，高电平点亮）
ESP32-C3-DevKitM-1：GPIO8（RGB LED，高电平点亮）

若不确定，可先查阅开发板官方文档确认引脚号与有效电平。本案例代码以高电平点亮为例，若你的板载LED为低电平点亮，将代码中的电平值取反即可。

工程结构与完整代码

在ESP-IDF中新建工程后，核心代码集中在main目录下。以下为最小可复现实现：

// main/led_blink.c
#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/gpio.h"
#include "esp_log.h"

// 根据实际开发板修改：ESP32 DevKitC 为 GPIO_NUM_2，ESP32-S3 DevKitC 为 GPIO_NUM_48
#define LED_GPIO   GPIO_NUM_2
#define LED_ON_LEVEL  1   // 高电平点亮；若为低电平点亮则改为0

static const char *TAG = "LED";

void app_main(void)
{
    gpio_config_t io_conf = {
        .pin_bit_mask = (1ULL << LED_GPIO),
        .mode = GPIO_MODE_OUTPUT,
        .pull_up_en = GPIO_PULLUP_DISABLE,
        .pull_down_en = GPIO_PULLDOWN_DISABLE,
        .intr_type = GPIO_INTR_DISABLE,
    };
    gpio_config(&io_conf);

    ESP_LOGI(TAG, "GPIO initialized, turning LED ON...");
    gpio_set_level(LED_GPIO, LED_ON_LEVEL);

    // 保持程序运行，LED持续点亮
    while (1) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

编译与烧录

在工程根目录下打开终端，依次执行以下命令（假设目标芯片为ESP32，其他芯片请先执行idf.py set-target <chip>）：

idf.py build
idf.py -p /dev/ttyUSB0 flash monitor   # Linux/macOS；Windows下串口为 COMx

烧录成功后，monitor窗口会持续输出日志。按Ctrl+]退出monitor。

验证方法与判定标准

现象验证：程序烧录并复位后，板载LED应持续点亮（不闪烁）。若LED不亮，检查GPIO引脚号是否与开发板匹配，以及有效电平是否取反。
日志验证：monitor窗口应输出GPIO initialized, turning LED ON...，且无错误信息（如panic、assert失败等）。
环境验证：编译无报错、烧录成功即说明ESP-IDF工具链、目标芯片配置和串口驱动均正常。

常见问题

编译报错“unknown type name 'gpio_config_t'”：检查是否已包含driver/gpio.h头文件。
烧录失败“Failed to connect”：确认开发板处于下载模式（多数开发板自动进入），或按住BOOT键再复位后重试烧录。
LED不亮但日志正常：大概率是引脚号或有效电平配置错误，对照开发板原理图修正LED_GPIO和LED_ON_LEVEL。