从单文件点灯到 BSP：用 idf.py 创建 DNESP32S3 工程

 1# 激活 EIM 安装的 ESP-IDF v5.5.5；每个新终端都要执行一次。
 2source "$HOME/.espressif/tools/activate_idf_v5.5.5.sh"
 3
 4# 确认当前终端使用的 ESP-IDF 版本。
 5idf.py --version
 6
 7# 新建并进入用于保存练习工程的目录。
 8mkdir -p "$HOME/esp"
 9cd "$HOME/esp"
10
11# 让 idf.py 生成最小工程骨架。
12idf.py create-project 02-01-main-led
13cd 02-01-main-led
14
15# 生成的源文件名带工程名；改为更常见的 main.c。
16mv main/02-01-main-led.c main/main.c

1# 将 main.c 注册为 main 组件的源文件。
2# GPIO 驱动只在本组件内部使用，所以声明为私有依赖。
3idf_component_register(SRCS "main.c"
4                    INCLUDE_DIRS "."
5                    PRIV_REQUIRES esp_driver_gpio)

1# DNESP32S3 使用 ESP32-S3 芯片。
2CONFIG_IDF_TARGET="esp32s3"
3# 开发板搭载 16 MB Flash。
4CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y

 1#include <stdbool.h>
 2#include "driver/gpio.h"
 3#include "esp_check.h"
 4#include "esp_log.h"
 5#include "freertos/FreeRTOS.h"
 6#include "freertos/task.h"
 7
 8// DNESP32S3 V1.2 板载红色用户 LED 连接到 GPIO1。
 9#define LED_GPIO GPIO_NUM_1
10
11// ESP_LOGI 会把这个字符串作为日志标签，便于区分日志来源。
12static const char *TAG = "led_demo";
13
14/**
15 * @brief 设置板载红色 LED 的亮灭状态。
16 *
17 * 原理图中的连接方式是：3.3 V -> 限流电阻 -> LED -> GPIO1。
18 * 因此 GPIO1 输出低电平时形成电流通路，LED 点亮；
19 * 输出高电平时 LED 熄灭。这叫“低电平有效”。
20 */
21static esp_err_t led_set(bool on)
22{
23    // on 为 true 时写 0，on 为 false 时写 1。
24    return gpio_set_level(LED_GPIO, on ? 0 : 1);
25}
26
27/**
28 * @brief 把 LED 引脚初始化为普通 GPIO 输出，并让 LED 默认熄灭。
29 */
30static esp_err_t led_init(void)
31{
32    const gpio_config_t config = {
33        // pin_bit_mask 的每一位对应一个 GPIO；左移 GPIO1 位就是选择 GPIO1。
34        .pin_bit_mask = 1ULL << LED_GPIO,
35        // LED 只需要输出高、低电平，不需要输入功能。
36        .mode = GPIO_MODE_OUTPUT,
37        // 板上已有完整的 LED 电路，不启用芯片内部上下拉电阻。
38        .pull_up_en = GPIO_PULLUP_DISABLE,
39        .pull_down_en = GPIO_PULLDOWN_DISABLE,
40        // 点灯不使用 GPIO 中断。
41        .intr_type = GPIO_INTR_DISABLE,
42    };
43
44    // gpio_config() 返回 ESP_OK 表示配置成功，否则把错误交给调用者。
45    esp_err_t err = gpio_config(&config);
46    if (err != ESP_OK) {
47        return err;
48    }
49
50    // 初始化结束后先灭灯，避免程序启动时 LED 状态不明确。
51    return led_set(false);
52}
53
54void app_main(void)
55{
56    // 初始化失败时打印错误位置并终止程序，便于入门阶段排错。
57    ESP_ERROR_CHECK(led_init());
58
59    // app_main 运行在 FreeRTOS 任务中；这个循环让 LED 持续闪烁。
60    while (1) {
61        ESP_ERROR_CHECK(led_set(true));
62        ESP_LOGI(TAG, "LED on");
63        // 把 500 毫秒换算成当前 FreeRTOS 配置对应的 tick 数。
64        vTaskDelay(pdMS_TO_TICKS(500));
65
66        ESP_ERROR_CHECK(led_set(false));
67        ESP_LOGI(TAG, "LED off");
68        vTaskDelay(pdMS_TO_TICKS(500));
69    }
70}

1tick 数 = 毫秒数 × configTICK_RATE_HZ ÷ 1000

1vTaskDelay(pdMS_TO_TICKS(500));

1# 查看 sdkconfig 中的 FreeRTOS tick 频率配置。
2grep '^CONFIG_FREERTOS_HZ=' sdkconfig

1# 首次配置工程时，明确选择 ESP32-S3。
2idf.py set-target esp32s3
3
4# 只编译，不连接开发板也可以完成这一步。
5idf.py build
6
7# 核对生成配置中的芯片型号和 Flash 容量。
8grep -E 'CONFIG_IDF_TARGET=|CONFIG_ESPTOOLPY_FLASHSIZE=' sdkconfig

1# Ubuntu：查找常见的 USB 转串口和 USB CDC 设备。
2find /dev -maxdepth 1 \( -name 'ttyUSB*' -o -name 'ttyACM*' \) -print | sort
3
4# macOS：烧录时通常选择 cu.*，插拔前后各运行一次更容易判断。
5find /dev -maxdepth 1 -name 'cu.*' -print | sort

1# flash 会自动触发编译，monitor 会在烧录后打开串口日志。
2idf.py -p '/dev/cu.替换为开发板端口' flash monitor

 1# 回到保存练习工程的目录，创建第二个独立工程。
 2cd "$HOME/esp"
 3idf.py create-project 02-02-bsp-led
 4cd 02-02-bsp-led
 5
 6# 统一主源文件名，并复制 2.1 的程序和板卡默认配置作为重构起点。
 7mv main/02-02-bsp-led.c main/main.c
 8cp ../02-01-main-led/main/main.c main/main.c
 9cp ../02-01-main-led/sdkconfig.defaults sdkconfig.defaults
10
11# 创建 BSP 组件及其中的 LED 模块目录。
12mkdir -p components/BSP/LED

 1#pragma once
 2
 3#include <stdbool.h>
 4#include "esp_err.h"
 5
 6/**
 7 * @brief 初始化 DNESP32S3 板载红色 LED。
 8 *
 9 * @return ESP_OK 表示成功，其他值表示 GPIO 配置失败。
10 */
11esp_err_t led_init(void);
12
13/**
14 * @brief 设置板载红色 LED 的状态。
15 *
16 * 调用者只表达“亮”或“灭”，无需知道 GPIO 编号和有效电平。
17 *
18 * @param on true 点亮，false 熄灭。
19 * @return ESP_OK 表示成功，其他值表示设置失败。
20 */
21esp_err_t led_set(bool on);

 1#include "led.h"
 2#include "driver/gpio.h"
 3
 4// GPIO 编号属于具体开发板的硬件知识，所以放在 BSP 实现中。
 5#define LED_GPIO GPIO_NUM_1
 6
 7esp_err_t led_init(void)
 8{
 9    const gpio_config_t config = {
10        // 位掩码的第 1 位对应 GPIO1。
11        .pin_bit_mask = 1ULL << LED_GPIO,
12        .mode = GPIO_MODE_OUTPUT,
13        // 板上已有完整的 LED 外部电路，不启用内部上下拉电阻。
14        .pull_up_en = GPIO_PULLUP_DISABLE,
15        .pull_down_en = GPIO_PULLDOWN_DISABLE,
16        .intr_type = GPIO_INTR_DISABLE,
17    };
18
19    esp_err_t err = gpio_config(&config);
20    if (err != ESP_OK) {
21        return err;
22    }
23
24    // GPIO 配置成功后先熄灭 LED，让初始化结果确定、可预期。
25    return led_set(false);
26}
27
28esp_err_t led_set(bool on)
29{
30    // 原理图为 3.3 V -> 电阻 -> LED -> GPIO1，因此低电平点亮。
31    // BSP 在这里完成“逻辑状态”到“硬件电平”的转换。
32    return gpio_set_level(LED_GPIO, on ? 0 : 1);
33}

1# LED/led.c 是 BSP 组件的实现文件。
2# 公开 LED 目录后，应用层才能直接包含 led.h。
3# GPIO 驱动只在 BSP 内部使用，所以声明为私有依赖。
4idf_component_register(SRCS "LED/led.c"
5                    INCLUDE_DIRS "LED"
6                    PRIV_REQUIRES esp_driver_gpio)

1components/BSP/LED/

1#include "led.h"

1# main 只调用 BSP 接口，不再直接依赖 GPIO 驱动。
2idf_component_register(SRCS "main.c"
3                    INCLUDE_DIRS "."
4                    PRIV_REQUIRES BSP)

1$IDF_PATH/components/       # ESP-IDF 自带组件
2项目根目录/components/     # 当前项目自己的组件
3EXTRA_COMPONENT_DIRS        # 工程额外指定的组件目录

1components/
2└── BSP/
3    └── CMakeLists.txt

 1#include "esp_check.h"
 2#include "esp_log.h"
 3#include "freertos/FreeRTOS.h"
 4#include "freertos/task.h"
 5#include "led.h"
 6
 7// 应用层只负责“何时亮、何时灭”，板卡接线细节由 BSP 负责。
 8static const char *TAG = "led_demo";
 9
10void app_main(void)
11{
12    // 通过 BSP 初始化 LED，无需在 main.c 中直接调用 gpio_config()。
13    ESP_ERROR_CHECK(led_init());
14
15    while (1) {
16        // true 表示“点亮”，BSP 会把它转换成这块板需要的低电平。
17        ESP_ERROR_CHECK(led_set(true));
18        ESP_LOGI(TAG, "LED on");
19        vTaskDelay(pdMS_TO_TICKS(500));
20
21        // false 表示“熄灭”，应用层不需要记忆高低电平的对应关系。
22        ESP_ERROR_CHECK(led_set(false));
23        ESP_LOGI(TAG, "LED off");
24        vTaskDelay(pdMS_TO_TICKS(500));
25    }
26}

 102-02-bsp-led/
 2├── CMakeLists.txt              # 工程入口
 3├── sdkconfig.defaults          # 芯片和 Flash 的默认配置
 4├── main/
 5│   ├── CMakeLists.txt          # 声明 main 对 BSP 的依赖
 6│   └── main.c                 # 应用逻辑：决定何时亮灭
 7└── components/
 8    └── BSP/
 9        ├── CMakeLists.txt      # 注册 BSP 组件
10        └── LED/
11            ├── led.h           # 对应用层公开的 LED 接口
12            └── led.c           # GPIO1 和低电平有效等板级细节

1# 第二个工程也要首次确认目标芯片，然后执行编译。
2idf.py set-target esp32s3
3idf.py build