SDU棋界精灵——ESP32点亮一颗LED

ESP32 点亮 LED 的实现主要通过 SingleLed 类完成，该类用于控制单个 WS2812 类型的 LED（通常为板载 LED）。实现了 ESP32 对单颗 LED 的控制，支持颜色设置、状态驱动点亮及闪烁等功能。

类 / 方法	功能描述
`SingleLed`	封装单颗 WS2812 LED 的控制逻辑，支持颜色设置、开关、闪烁等功能。
`TurnOn()`	点亮 LED，根据 `r_`, `g_`, `b_` 的值设置颜色并刷新显示。
`SetColor(r, g, b)`	设置 LED 的 RGB 颜色值（0-255）。
`led_strip_set_pixel`	底层函数，设置指定 LED 像素的颜色（用于 WS2812 等灯带驱动）。
`led_strip_refresh`	刷新 LED 显示，使颜色设置生效。

一、LED 硬件配置与驱动初始化

LED 硬件配置与驱动初始化的核心是根据 LED 类型选择合适的外设（RMT 或 LEDC），并正确配置引脚、时序、颜色格式等参数。SingleLed 和 GpioLed 类分别封装了数字灯带和普通 LED 的驱动逻辑，通过继承 Led 基类实现统一的状态控制接口，确保硬件无关性和代码可复用性。

1.WS2812 类型 LED（数字灯带，如板载 RGB 灯）

（1）硬件配置

GPIO 选择：使用 BUILTIN_LED_GPIO（通常为 GPIO5 或自定义引脚）作为数据引脚，仅需一根 GPIO 即可控制单颗或多颗 WS2812 灯珠。
电路连接：

VCC：连接 5V 或 3.3V 电源（根据 LED 型号）。
GND：接地。
DATA：连接 ESP32 的指定 GPIO（如 DISPLAY_MOSI_PIN 或自定义引脚）。

（2）驱动初始化（`SingleLed` 类）

核心通过 RMT（Remote Control）外设驱动 WS2812，利用 led_strip 库实现：

// single_led.cc 构造函数
SingleLed::SingleLed(gpio_num_t gpio) {
    assert(gpio != GPIO_NUM_NC);

    // 1. LED 灯带基础配置
    led_strip_config_t strip_config = {};
    strip_config.strip_gpio_num = gpio;           // 数据引脚 GPIO
    strip_config.max_leds = 1;                    // 单颗 LED
    strip_config.led_pixel_format = LED_PIXEL_FORMAT_GRB; // GRB 颜色格式（WS2812 常用）
    strip_config.led_model = LED_MODEL_WS2812;     // 指定 LED 型号

    // 2. RMT 驱动配置（控制信号时序）
    led_strip_rmt_config_t rmt_config = {};
    rmt_config.resolution_hz = 10 * 1000 * 1000;  // 10MHz 分辨率，确保信号精度

    // 3. 创建 LED 设备
    ESP_ERROR_CHECK(led_strip_new_rmt_device(&strip_config, &rmt_config, &led_strip_));
    led_strip_clear(led_strip_);  // 初始化时关闭 LED

    // 4. 初始化闪烁定时器（可选，用于状态提示）
    esp_timer_create_args_t blink_timer_args = {
        .callback = [](void *arg) { static_cast<SingleLed*>(arg)->OnBlinkTimer(); },
        .arg = this,
        .dispatch_method = ESP_TIMER_TASK,
        .name = "blink_timer",
    };
    ESP_ERROR_CHECK(esp_timer_create(&blink_timer_args, &blink_timer_));
}

LED_PIXEL_FORMAT_GRB：WS2812 通常使用 GRB 顺序，需与实际硬件一致。
LED_MODEL_WS2812：指定驱动模型，确保时序匹配。
rmt_config.resolution_hz：高分辨率保证信号准确，避免颜色显示异常。

2.普通 GPIO 控制 LED（通过 PWM 调节亮度）

（1）硬件配置

GPIO 选择：任意 GPIO（如 DISPLAY_BACKLIGHT_PIN），需连接一个限流电阻（约 220Ω）到 LED 阳极，阴极接地。
电路连接：

VCC：连接 3.3V 电源。
GND：接地。
GPIO：通过 PWM 输出控制亮度（需支持 LEDC 外设）。

（2）驱动初始化（`GpioLed` 类）

使用 LEDC（LED 控制器）外设实现 PWM 控制，支持亮度调节和闪烁：

// gpio_led.cc 构造函数
GpioLed::GpioLed(gpio_num_t gpio, int output_invert) {
    // 1. 配置 LEDC 定时器
    ledc_timer_config_t timer_config = {
        .speed_mode = LEDC_LOW_SPEED_MODE,  // 低速模式（适合背光等非高频场景）
        .duty_resolution = LEDC_TIMER_10_BIT, // 10 位分辨率（0-1023 亮度等级）
        .timer_num = LEDC_TIMER_0,          // 选择定时器 0
        .freq_hz = 20000,                   // 20kHz 频率（避免人眼可见闪烁）
        .clk_cfg = LEDC_AUTO_CLK,           // 自动选择时钟源
    };
    ESP_ERROR_CHECK(ledc_timer_config(&timer_config));

    // 2. 配置 LEDC 通道
    ledc_channel_config_t channel_config = {
        .gpio_num = gpio,                   // LED 连接的 GPIO
        .speed_mode = LEDC_LOW_SPEED_MODE,
        .channel = LEDC_CHANNEL_0,          // 通道 0
        .intr_type = LEDC_INTR_DISABLE,      // 禁用中断
        .timer_sel = LEDC_TIMER_0,
        .duty = 0,                          // 初始占空比（0% 关闭）
        .hpoint = 0,
        .flags = {
            .output_invert = output_invert  // 是否反转输出（根据电路设计）
        }
    };
    ESP_ERROR_CHECK(ledc_channel_config(&channel_config));

    ledc_initialized_ = true;
    duty_ = 0;
}

duty_resolution：分辨率越高，亮度调节越细腻（10 位对应 1024 级）。
freq_hz：20kHz 以上避免人眼感知到闪烁，适合背光等场景。
output_invert：若 LED 阳极接 GPIO，阴极接地，通常无需反转；反之需设置为 1。

3.核心驱动差异对比

特性	WS2812（数字灯带，`SingleLed`）	普通 LED（PWM 控制，`GpioLed`）
控制方式	单总线数字信号（RMT 驱动）	PWM 模拟电压（LEDC 驱动）
颜色支持	真彩色（RGB 独立控制）	单色（亮度调节）
硬件复杂度	单引脚控制多灯珠，需匹配时序	简单 GPIO + 电阻，适合单色场景
典型场景	状态指示灯（如红蓝绿提示）	背光、单色提示灯
驱动核心函数	`led_strip_new_rmt_device`	`ledc_timer_config` + `ledc_channel_config`

4.关键设计

（1）线程安全：

两者均使用 std::mutex 确保多线程环境下的操作安全（如 SingleLed 的 TurnOn() 和 GpioLed 的 StartBlinkTask()）。

std::lock_guard<std::mutex> lock(mutex_); // 互斥锁防止竞态条件

（2）状态驱动：

通过 OnStateChanged() 方法根据设备状态（如连接、断开）自动切换 LED 行为（点亮、闪烁、关闭）。

// SingleLed 示例：设备连接时设为蓝色
case kDeviceStateConnected:
    SetColor(0, 0, DEFAULT_BRIGHTNESS);
    TurnOn();
    break;

（3）闪烁与渐变：

GpioLed 支持通过定时器实现闪烁（StartContinuousBlink）和亮度渐变（StartFadeTask），利用 esp_timer 实现精准定时。

// 启动连续闪烁（每 500ms 切换状态）
void GpioLed::StartContinuousBlink(int interval_ms) {
    StartBlinkTask(BLINK_INFINITE, interval_ms); // BLINK_INFINITE 表示无限次
}

5.硬件配置最佳实践

（1）引脚定义：使用 gpio_num_t 类型定义引脚（如 BUILTIN_LED_GPIO），确保与实际硬件匹配。- 避免使用 GPIO_NUM_NC，初始化时通过 assert 检查有效性。

（2）电源管理： WS2812 多灯珠场景需外接电源，避免 ESP32 供电不足；单灯珠可直接由板载 3.3V 供电。 – 普通 LED 需串联限流电阻，阻值根据 LED 电压和电流计算（如 (3.3V – LED电压)/LED电流）。

（3）驱动兼容性： led_strip 库支持多种数字灯带（如 WS2811、SK6812），仅需修改 led_model 参数。 LEDC 外设支持所有支持 PWM 的 GPIO，可通过 ledc_channel_config 灵活配置。

二、核心方法

核心方法围绕颜色 / 亮度设置、状态驱动和外设控制展开，根据 LED 类型（数字灯带 WS2812、普通 GPIO 控制 LED、背光 LED）分为不同实现，核心逻辑集中在 SingleLed、GpioLed 和 PwmBacklight 类中

所有方法均遵循线程安全和资源管理原则，通过状态机驱动实现设备状态与 LED 行为的解耦，确保代码的可维护性和鲁棒性。

1.WS2812 数字灯带

`（1）SetColor(uint8_t r, uint8_t g, uint8_t b)`

功能：设置 LED 颜色（GRB 格式，亮度通过分量值控制，范围 0-255，0 为关闭，255 为最大亮度）。

void SingleLed::SetColor(uint8_t r, uint8_t g, uint8_t b) {
    r_ = r;
    g_ = g;
    b_ = b;
}

关键：颜色顺序为 GRB（WS2812 硬件特性），需与实际灯珠一致。

`（2）TurnOn()`

功能：开启 LED 并显示当前颜色。

void SingleLed::TurnOn() {
    if (led_strip_ == nullptr) return;
    std::lock_guard<std::mutex> lock(mutex_);
    esp_timer_stop(blink_timer_); // 停止闪烁定时器
    led_strip_set_pixel(led_strip_, 0, r_, g_, b_); // 设置第 0 颗灯珠颜色
    led_strip_refresh(led_strip_); // 刷新输出，使颜色生效
}

互斥锁：保证线程安全，避免多线程同时操作。
停止闪烁：关闭定时器，避免闪烁干扰。
设置像素：通过 led_strip_set_pixel 写入颜色数据。
刷新输出：调用 led_strip_refresh 触发 RMT 外设发送时序信号。

`（3）TurnOff()`

功能：关闭 LED（设置为黑色）。

void SingleLed::TurnOff() {
    if (led_strip_ == nullptr) return;
    std::lock_guard<std::mutex> lock(mutex_);
    esp_timer_stop(blink_timer_);
    led_strip_clear(led_strip_); // 清除所有像素数据（置黑）
}

（4）闪烁与状态驱动`StartContinuousBlink(int interval_ms)`

功能：启动连续闪烁（无限次），间隔 interval_ms 毫秒。

void SingleLed::StartContinuousBlink(int interval_ms) {
    StartBlinkTask(BLINK_INFINITE, interval_ms); // BLINK_INFINITE 表示无限次
}

通过 esp_timer 周期性触发 OnBlinkTimer，交替调用 led_strip_set_pixel 和 led_strip_clear，实现闪烁效果。
blink_counter_ 记录闪烁次数，奇数为点亮，偶数为关闭：

void SingleLed::OnBlinkTimer() {
    blink_counter_--;
    if (blink_counter_ & 1) { // 奇数，点亮
        led_strip_set_pixel(led_strip_, 0, r_, g_, b_);
        led_strip_refresh(led_strip_);
    } else { // 偶数，关闭
        led_strip_clear(led_strip_);
        if (blink_counter_ == 0) esp_timer_stop(blink_timer_); // 停止定时器
    }
}

2.普通 GPIO 控制 LED（`GpioLed` 类）

`（1）SetBrightness(uint8_t brightness)`

功能：设置 LED 亮度（通过 PWM 占空比，范围 0-100，对应 0%-100% 亮度）。

void GpioLed::SetBrightness(uint8_t brightness) {
    duty_ = brightness * LEDC_DUTY / 100; // LEDC_DUTY 为最大占空比（如 1023 对应 100%）
}

`（2）TurnOn()`

功能：以当前亮度开启 LED。

void GpioLed::TurnOn() {
    if (!ledc_initialized_) return;
    std::lock_guard<std::mutex> lock(mutex_);
    esp_timer_stop(blink_timer_); // 停止闪烁定时器
    ledc_fade_stop(ledc_channel_.speed_mode, ledc_channel_.channel); // 停止渐变
    ledc_set_duty(ledc_channel_.speed_mode, ledc_channel_.channel, duty_); // 设置占空比
    ledc_update_duty(ledc_channel_.speed_mode, ledc_channel_.channel); // 应用占空比
}

停止闪烁 / 渐变：确保无其他任务干扰。
设置占空比：通过 ledc_set_duty 设置 PWM 占空比，控制亮度。
更新输出：调用 ledc_update_duty 使配置生效。

（3）StartContinuousBlink(int interval_ms)

功能：启动连续闪烁，间隔 interval_ms 毫秒，亮度在当前值和 0 之间切换。

void GpioLed::StartContinuousBlink(int interval_ms) {
    StartBlinkTask(BLINK_INFINITE, interval_ms);
}

定时器触发 OnBlinkTimer，交替设置占空比为 duty_（点亮）和 0（关闭）：

void GpioLed::OnBlinkTimer() {
    blink_counter_--;
    if (blink_counter_ & 1) { // 奇数，点亮
        ledc_set_duty(ledc_channel_.speed_mode, ledc_channel_.channel, duty_);
    } else { // 偶数，关闭
        ledc_set_duty(ledc_channel_.speed_mode, ledc_channel_.channel, 0);
        if (blink_counter_ == 0) esp_timer_stop(blink_timer_);
    }
    ledc_update_duty(ledc_channel_.speed_mode, ledc_channel_.channel); // 刷新 PWM
}

`（4）StartFadeTask()`

功能：启动亮度渐变（在当前亮度和目标亮度之间平滑过渡）。

void GpioLed::StartFadeTask() {
    ledc_set_fade_with_time(ledc_channel_.speed_mode, ledc_channel_.channel, 
                           fade_up_ ? LEDC_DUTY : 0, LEDC_FADE_TIME); // 设置渐变参数
    ledc_fade_start(ledc_channel_.speed_mode, ledc_channel_.channel, LEDC_FADE_NO_WAIT); // 启动渐变
}

关键：利用 LEDC 外设的渐变功能，通过 ledc_set_fade_with_time 指定目标占空比和渐变时间，实现平滑亮度变化。

3.背光 LED（`PwmBacklight` 类，用于屏幕背光）

SetBrightness(uint8_t brightness, bool permanent = false)

功能：设置背光亮度（范围 0-100），支持持久化存储（写入配置）。

void Backlight::SetBrightness(uint8_t brightness, bool permanent) {
    if (brightness > 100) brightness = 100;
    if (brightness_ == brightness) return;
    target_brightness_ = brightness;
    step_ = (target_brightness_ > brightness_) ? 1 : -1;
    esp_timer_start_periodic(transition_timer_, 5 * 1000); // 每 5ms 调整一次亮度
}

通过定时器 transition_timer_ 逐步调整亮度（每次变化 step_），避免亮度突变。
调用 SetBrightnessImpl 实际设置 PWM 占空比：

void PwmBacklight::SetBrightnessImpl(uint8_t brightness) {
    uint32_t duty_cycle = (1023 * brightness) / 100; // 10 位分辨率，1023 对应 100%
    ledc_set_duty(LEDC_LOW_SPEED_MODE, LEDC_CHANNEL_0, duty_cycle);
    ledc_update_duty(LEDC_LOW_SPEED_MODE, LEDC_CHANNEL_0);
}

4.状态驱动点亮逻辑（`OnStateChanged` 方法）

所有 LED 类均继承 Led 接口，通过 OnStateChanged 根据设备状态自动切换点亮行为

（1）WS2812 数字灯带（`SingleLed`）

void SingleLed::OnStateChanged() {
    auto device_state = Application::GetInstance().GetDeviceState();
    switch (device_state) {
        case kDeviceStateStarting:   // 启动中：蓝色闪烁（100ms 间隔）
            SetColor(0, 0, DEFAULT_BRIGHTNESS);
            StartContinuousBlink(100);
            break;
        case kDeviceStateConnecting: // 连接中：常亮蓝色
            SetColor(0, 0, DEFAULT_BRIGHTNESS);
            TurnOn();
            break;
        case kDeviceStateListening:  // 监听中：检测到语音时亮红色（高亮度），否则低亮度红色
            if (app.IsVoiceDetected()) {
                SetColor(HIGH_BRIGHTNESS, 0, 0);
            } else {
                SetColor(LOW_BRIGHTNESS, 0, 0);
            }
            TurnOn();
            break;
    }
}

（2）普通 GPIO 控制 LED（`GpioLed`）

void GpioLed::OnStateChanged() {
    switch (device_state) {
        case kDeviceStateIdle:       // 空闲状态：低亮度常亮
            SetBrightness(IDLE_BRIGHTNESS);
            TurnOn();
            break;
        case kDeviceStateSpeaking:   // 说话时：高亮度常亮
            SetBrightness(SPEAKING_BRIGHTNESS);
            TurnOn();
            break;
        case kDeviceStateUpgrading:  // 升级中：黄色闪烁（100ms 间隔）
            SetBrightness(UPGRADING_BRIGHTNESS);
            StartContinuousBlink(100);
            break;
    }
}

（3）背光 LED（`PwmBacklight` 类）

主要根据用户操作或设备状态调节亮度（无闪烁逻辑）

// 在设备进入低功耗时降低背光亮度
void PwmBacklight::OnStateChanged() {
    auto device_state = Application::GetInstance().GetDeviceState();
    if (device_state == kDeviceStateLowPower) {
        SetBrightness(LOW_POWER_BRIGHTNESS); // 低功耗亮度（10%）
    } else {
        // 恢复默认亮度或用户设置亮度
    }
}

5.线程安全与资源管理

（1）互斥锁：

所有修改 LED 状态的方法（如 TurnOn、StartBlinkTask）均使用 std::lock_guard<std::mutex> 保证线程安全，避免竞态条件：

std::lock_guard<std::mutex> lock(mutex_); // 自动加锁/解锁

（2）定时器管理：

通过 esp_timer 实现精准定时，闪烁或渐变任务结束后自动停止定时器，释放资源：

esp_timer_stop(blink_timer_); // 停止闪烁定时器

（3）驱动资源释放：

析构函数中释放 LED 驱动资源（如 WS2812 的 led_strip_del、LEDC 的 ledc_fade_stop）：

SingleLed::~SingleLed() {
    esp_timer_stop(blink_timer_);
    if (led_strip_ != nullptr) led_strip_del(led_strip_); // 释放 RMT 驱动资源
}

三、在设备状态中控制 LED

控制 LED 的核心逻辑通过状态驱动模型实现，所有 LED 类（SingleLed、GpioLed、PwmBacklight）均继承 Led 接口，通过 OnStateChanged 方法响应设备状态变化，实现不同状态下 LED 行为的自动化控制。

1.设备状态枚举与核心触发逻辑

（1）设备状态定义

通过 DeviceState 枚举定义设备状态，常见状态包括：

enum class DeviceState {
    kDeviceStateUnknown,
    kDeviceStateStarting,    // 启动中
    kDeviceStateConnecting,  // 网络连接中
    kDeviceStateIdle,        // 空闲状态
    kDeviceStateListening,   // 语音监听中
    kDeviceStateSpeaking,    // 语音回复中
    kDeviceStateUpgrading,   // 固件升级中
    // 其他状态...
};

（2）状态切换触发

主动调用：通过 Application::SetDeviceState 方法主动切换状态，例如启动时调用 SetDeviceState(kDeviceStateStarting)。
事件驱动：由网络连接、用户交互、语音检测等事件触发状态变化，如检测到唤醒词后从 kDeviceStateIdle 切换为 kDeviceStateListening。

（3）LED 状态更新

设备状态变化时，通过 Board::GetLed()->OnStateChanged() 触发 LED 行为更新，核心逻辑在 Application::SetDeviceState 中：

void Application::SetDeviceState(DeviceState state) {
    // ... 状态切换逻辑 ...
    auto led = Board::GetInstance().GetLed();
    led->OnStateChanged(); // 触发 LED 状态更新
}

2.状态驱动的关键机制

（1）状态与 LED 行为的解耦

通过 OnStateChanged 统一处理：所有 LED 行为（颜色、亮度、闪烁）均在状态切换时触发，避免代码冗余。
参数化配置：亮度、颜色、闪烁间隔等通过宏定义（如 DEFAULT_BRIGHTNESS、IDLE_BRIGHTNESS）管理，方便维护：

#define DEFAULT_BRIGHTNESS 80    // 最大亮度的 80%
#define LOW_BRIGHTNESS 30        // 低亮度阈值
#define BLINK_INTERVAL_MS 100    // 闪烁间隔

（2）动态亮度调节与渐变

普通 LED 与背光：利用 LEDC 外设的渐变功能（ledc_set_fade_with_time），在状态切换时平滑调整亮度，避免视觉突变：

void GpioLed::StartFadeTask() {
    // 从当前亮度渐变到目标亮度，耗时 200ms
    ledc_set_fade_with_time(ledc_channel_.speed_mode, ledc_channel_.channel, 
                           fade_up_ ? LEDC_DUTY : 0, 200);
    ledc_fade_start(ledc_channel_.speed_mode, ledc_channel_.channel, LEDC_FADE_NO_WAIT);
}

（3）闪烁逻辑的统一管理

定时器控制：通过 esp_timer 实现精准闪烁间隔，状态切换时自动停止上一状态的闪烁任务：

void SingleLed::StartContinuousBlink(int interval_ms) {
    esp_timer_stop(blink_timer_); // 停止旧定时器
    esp_timer_start_periodic(blink_timer_, interval_ms * 1000); // 启动新定时器
}

四、手动点亮LED

手动点亮 LED 是指不依赖设备状态驱动（如 OnStateChanged），而是通过直接调用 SingleLed、GpioLed、PwmBacklight 类的方法控制 LED 行为，适用于测试、调试、用户交互触发等场景。关键步骤包括实例化 LED 类、设置颜色 / 亮度参数、调用 TurnOn() 或相关控制方法，并注意硬件引脚配置和线程安全。通过与状态驱动的结合，可实现从简单单次控制到复杂状态反馈的全场景 LED 控制。

1.WS2812 数字灯带（`SingleLed` 类）

接线：将 WS2812 灯珠的 DATA 引脚连接到 ESP32 的指定 GPIO（如 GPIO5，宏定义为 BUILTIN_LED_GPIO），VCC 接 3.3V 或 5V，GND 接地。
头文件：包含 single_led.h 和 ESP-IDF 相关头文件。

#include <iostream>
#include "single_led.h"
#include "esp_log.h"

// 定义 LED 连接的 GPIO（假设板载 LED 为 GPIO5）
#define BUILTIN_LED_GPIO GPIO_NUM_5

void ManualControlSingleLed() {
    // 1. 创建 SingleLed 实例（指定 GPIO）
    SingleLed led(BUILTIN_LED_GPIO);

    // 2. 设置颜色（GRB 格式，红色：R=255, G=0, B=0）
    led.SetColor(255, 0, 0);

    // 3. 手动点亮 LED
    led.TurnOn();
    ESP_LOGI("LED", "LED turned on (red)");

    // 4. 保持一段时间（示例：5 秒）
    vTaskDelay(pdMS_TO_TICKS(5000));

    // 5. 关闭 LED（可选）
    led.TurnOff();
    ESP_LOGI("LED", "LED turned off");
}

// 在主函数或任务中调用
void app_main() {
    ManualControlSingleLed();
}

实例化：SingleLed led(gpio) 初始化时自动完成 RMT 驱动配置和 LED 设备创建。
颜色设置：SetColor(r, g, b) 直接设置 RGB 分量（0-255），注意 WS2812 为 GRB 顺序（与常规 RGB 不同）。
立即点亮：TurnOn() 触发 led_strip_set_pixel 和 led_strip_refresh，实时更新 LED 显示。
线程安全：内部通过 std::mutex 保证多线程下的安全调用，无需额外加锁。

2.普通 GPIO 控制 LED（`GpioLed` 类）

接线：LED 阳极通过 220Ω 电阻连接 ESP32 GPIO（如 GPIO4），阴极接地。
头文件：包含 gpio_led.h。

#include "gpio_led.h"
#include "esp_timer.h"

// 定义 LED 连接的 GPIO（自定义引脚，如 GPIO4）
#define CUSTOM_LED_GPIO GPIO_NUM_4

void ManualControlGpioLed() {
    // 1. 创建 GpioLed 实例（指定 GPIO，输出不反转）
    GpioLed led(CUSTOM_LED_GPIO, 0); // output_invert=0 表示正极接 GPIO

    // 2. 设置亮度（0-100，50 表示 50% 亮度）
    led.SetBrightness(50);

    // 3. 手动点亮 LED
    led.TurnOn();
    printf("LED turned on (50%% brightness)
");

    // 4. 闪烁示例：手动控制闪烁（非状态驱动）
    for (int i = 0; i < 3; i++) {
        led.TurnOn();    // 点亮
        vTaskDelay(pdMS_TO_TICKS(500));
        led.TurnOff();   // 关闭
        vTaskDelay(pdMS_TO_TICKS(500));
    }

    // 5. 渐变亮度（从 50% 到 100%，耗时 1 秒）
    led.SetBrightness(100);
    led.StartFadeTask(); // 启动渐变
    vTaskDelay(pdMS_TO_TICKS(1000));
}

亮度设置：SetBrightness(0-100) 映射到 LEDC 外设的占空比（如 100 对应最大占空比 LEDC_DUTY，通常为 1023）。
直接控制：TurnOn() 立即应用当前亮度，TurnOff() 设为 0 亮度（关闭）。
渐变效果：StartFadeTask() 利用 LEDC 外设的渐变功能，实现亮度平滑过渡，需提前通过 ledc_set_fade_with_time 配置渐变参数。

3.背光 LED（`PwmBacklight` 类，用于屏幕背光）

接线：背光 LED 通常集成在屏幕模块中，通过指定 GPIO（如 DISPLAY_BACKLIGHT_PIN）控制，无需额外接线。
头文件：包含 backlight.h。

#include "backlight.h"
#include "pwm_backlight.h"

// 定义背光控制的 GPIO（假设为 GPIO15）
#define BACKLIGHT_GPIO GPIO_NUM_15

void ManualControlBacklight() {
    // 1. 创建 PwmBacklight 实例（指定 GPIO）
    PwmBacklight backlight(BACKLIGHT_GPIO);

    // 2. 设置亮度（0-100，立即生效）
    backlight.SetBrightness(70); // 70% 亮度
    printf("Backlight brightness set to 70%%
");

    // 3. 临时高亮（如用户操作时，100% 亮度保持 2 秒）
    backlight.SetBrightness(100);
    vTaskDelay(pdMS_TO_TICKS(2000));
    backlight.SetBrightness(70); // 恢复默认亮度

    // 4. 渐变到最低亮度（关闭背光）
    backlight.SetBrightness(0);
    backlight.StartFadeTask(); // 启动渐变（耗时默认 200ms）
}

亮度范围：SetBrightness(0) 关闭背光，100 为最大亮度，支持非整数输入（内部自动取整）。
渐变控制：StartFadeTask() 自动根据当前亮度和目标亮度计算渐变方向，实现平滑过渡，避免屏幕亮度突变。
持久化存储：若需要保存亮度设置（如断电记忆），可调用 SaveBrightnessToFlash() 方法，结合 NVS 存储实现。

4.适用场景

测试与调试：

验证 LED 硬件连接是否正常（如通过 TurnOn() 快速测试单个灯珠）。
调试驱动初始化逻辑（检查 led_strip_new_rmt_device 是否返回正确错误码）。

用户交互触发：

按钮按下时点亮特定颜色 LED（如确认按钮触发绿色常亮）。
触摸事件响应（触摸时高亮，松开后恢复）。

临时状态指示：

文件读写时闪烁蓝色 LED，提示操作进行中。
传感器数据异常时点亮红色 LED，触发用户注意。

5.与状态驱动的对比

特性	手动点亮	状态驱动点亮
触发方式	代码直接调用（如按钮回调、测试函数）	设备状态变化（如连接、监听）
控制粒度	精确到单次操作（点亮 / 关闭 / 闪烁次数）	基于状态的复杂逻辑（渐变、无限闪烁）
适用场景	临时交互、调试、单次触发	长期状态反馈（如连接成功常亮）
代码耦合	独立调用，不依赖状态机	依赖设备状态枚举和映射关系

五、总结

从简单的 gpio_set_level 到复杂的状态驱动、多线程安全控制，每一步都需要兼顾 “细节正确性” 与 “系统扩展性”。这次实践不仅让我掌握了 ESP32 的 LED 控制方法，更重要的是理解了：优秀的嵌入式代码，是硬件特性与软件逻辑的高效协同，是当前功能与未来扩展的平衡设计。

LED 行为与设备状态（启动、连接、监听等）深度绑定，如 OnStateChanged() 方法根据状态自动切换闪烁频率、亮度或颜色（例：启动时高频闪烁，连接时常亮）。这种设计让 LED 成为设备状态的 “可视化接口”，提升了用户体验和故障排查效率。

多线程环境下，通过 std::mutex（如 SingleLed 的 TurnOn() 方法）或 ESP-IDF 互斥锁保证操作原子性，避免竞态条件。同时，析构函数中释放定时器（esp_timer_stop）和外设资源（led_strip_del），培养了 “初始化 – 使用 – 释放” 的完整资源管理意识。

兼容性设计的巧妙处理
当硬件未连接 LED 时，使用 NoLed 类（空实现）替代空指针，避免运行时错误（如 Board::GetLed() 返回 NoLed 实例）。这种 “默认安全” 的设计思想，确保代码在不同硬件平台上的鲁棒性。

PWM 与定时器的灵活应用

亮度调节：通过 LEDC 外设实现 PWM 占空比控制（如 GpioLed::SetBrightness 将 0~100 映射到 PWM duty 值），支持平滑渐变（背光调节）。
动画效果：利用定时器（esp_timer）实现周期性闪烁、呼吸灯、滚动灯效（如 CircularStrip 的 Scroll 方法），理解了 “硬件定时 + 软件逻辑” 的协同工作模式。

代码复用与模块化的价值
不同 LED 类共享基类 Led 的 OnStateChanged() 接口，设备状态切换时统一调用，减少重复代码。例如，CompactWifiBoardLCD 硬件平台只需指定 BUILTIN_LED_GPIO，即可复用 SingleLed 的全部功能，体现了 “一次编写，多处复用” 的工程化优势。

文章版权归作者所有，未经允许请勿转载。如内容涉嫌侵权，请在本页底部进入<联系我们>进行举报投诉!

THE END