小智AI设备端学习笔记01（板卡初始化）

JiaOne6612

338人浏览 · 2026-07-07 17:58:28

JiaOne6612 · 2026-07-07 17:58:28 发布

板卡初始化流程分析

基于 MovecallMojiESP32S3 板卡，分析 auto& board = Board::GetInstance() 的完整初始化链路。
源文档：xz.docx，经代码验证和补充，生成此结构化文档。

1. 类继承关系总览

整个板卡初始化涉及四个主要的类体系：Board 体系（板卡硬件抽象）、Display 体系（显示链路）、背光体系（亮度控制）和按钮体系（用户输入）。下面逐一说明。

1.1 Board 体系

Board 是板卡的顶层抽象，定义了所有板卡都必须提供的接口（如 GetDisplay()、GetBacklight()、GetAudioCodec()）。WifiBoard 是 Board 的中间子类，增加了 WiFi 网络相关的支持。最下层的具体板卡类（如 MovecallMojiESP32S3）实现所有纯虚函数，完成板卡特定硬件的初始化。

Board 类本身还使用了单例模式，通过 GetInstance() 静态方法提供全局唯一的板卡实例。创建具体板卡的方式是利用 DECLARE_BOARD 宏，该宏在编译时根据 Kconfig 选择的板卡类型，生成对应的 create_board() 工厂函数，返回 new MovecallMojiESP32S3() 这样的具体实例。这种设计模式叫做"工厂方法 + 单例"，既保证了板卡对象的唯一性，又能让上层代码只依赖 Board 抽象接口，不需要关心具体是哪个板卡。

从上图可以看到，MovecallMojiESP32S3 直接继承 WifiBoard，因为这块板卡使用的是 WiFi 联网方式。如果板卡使用的是 4G Cat.1 模块（如 ML307），则会继承 Ml307Board；如果是有线网口，则继承 EthernetBoard。这种分层设计让不同联网方式的板卡共用基础初始化逻辑，只在差异部分单独实现。

1.2 Display 体系

Display 体系的层次结构是整个项目中最为复杂的，从抽象到具体共有四层。每层在构造函数中逐步增加功能：从最基础的接口定义，到电源管理，再到主题系统和预览功能，最后到具体的 LVGL 显示注册。

每一层的职责在构造函数中清晰分离：

Display 是最顶层的抽象接口，定义了 Lock/Unlock（线程安全）、SetTheme（切换主题）等纯虚函数。它的构造函数是空的，仅作为接口定义存在。
LvglDisplay 引入了两个关键的硬件级机制：电源管理锁（pm_lock_）和通知定时器（notification_timer_）。电源管理锁用于防止 APB 外设总线被降频，保护 I2C/SPI 通信；通知定时器用于在屏幕上显示通知后自动隐藏。
LcdDisplay 是中间层基类，注意它的构造函数标记为 protected——这意味着你不能直接创建 LcdDisplay 对象，只能通过它的子类（如 SpiLcdDisplay）来创建。它在构造函数中做了两件事：一是初始化 LCD 主题系统（包括 light 和 dark 两套颜色方案），二是创建预览图片定时器 preview_timer_（5 秒后自动清除图片预览）。
SpiLcdDisplay 是 SPI 接口 LCD 的具体实现类，在构造函数中完成了 LVGL 图形库的初始化和显示设备注册。它先写白屏清空显示，然后调用 lv_init() 启动 LVGL，再通过 lvgl_port_init() 创建 LVGL 任务和 lvgl_port_add_disp() 将 LCD 硬件注册到 LVGL。

除了 SPI 接口，项目还支持 RGB 接口（RgbLcdDisplay）和 MIPI-DSI 接口（MipiLcdDisplay），它们的职责结构相同，只是底层显示接口不同。

1.3 背光体系

背光控制由两个类协作完成：Backlight 提供渐变控制和参数持久化的通用逻辑，PwmBacklight 负责将亮度值转换为 LEDC 外设的 PWM 占空比。

Backlight 基类中最为重要的机制是渐变定时器 transition_timer_。当调用 SetBrightness() 时，它不是直接跳变到目标亮度，而是记录目标值后启动一个 5ms 周期的定时器，每次触发时亮度步进 1，逐步逼近目标。这样做的好处是屏幕亮度变化平滑，不会产生刺眼的瞬间跳变。

PwmBacklight 是 Backlight 的一个具体实现，它的 SetBrightnessImpl() 将 0-100 的百分比亮度值映射到 LEDC 定时器的 10 位占空比（0-1023），然后通过 ledc_set_duty() 写入硬件。如果你用的是其他调光方式（比如恒流源芯片），可以继承 Backlight 实现自己的 SetBrightnessImpl()。

1.4 按钮体系

按钮体系封装了 ESP-IDF 的 iot_button 组件，提供了面向对象的 C++ 接口。

Button 类支持六种按键事件：单击、双击、长按、按下、抬起、N 击。每个事件类型的注册方式相同：调用 OnClick(lambda) 保存回调函数，然后通过 iot_button_register_cb() 注册到底层 iot_button 驱动。当硬件检测到对应事件时，C 回调函数通过传递的 usr_data 指针恢复 Button 对象，调用保存的 C++ lambda。

AdcButton 和 PowerSaveButton 是 Button 的两个特殊子类。AdcButton 通过 ADC 通道检测按键（适用于电阻分压式按键矩阵），PowerSaveButton 在按键初始化时启用了电源保存模式，用于需要低功耗场景的板卡。

2. Board 基类与 GetInstance 机制

// board.h:49-90
class Board {
protected:
    Board();                                // 构造函数：生成 UUID
    std::string GenerateUuid();             // 生成或恢复唯一标识

public:
    static Board& GetInstance();            // 单例模式入口
    virtual Backlight* GetBacklight();      // 虚函数，默认返回 nullptr
    virtual Display* GetDisplay();          // 虚函数，默认返回 nullptr
    virtual AudioCodec* GetAudioCodec() = 0;// 纯虚函数，必须实现
    ...
};

Board 类的设计遵循了接口隔离原则（Interface Segregation Principle）。它定义了板卡必须提供的功能接口，但把具体实现交给子类。带有 = 0 的纯虚函数（如 GetAudioCodec()）是所有板卡都必定需要的功能，子类必须实现。带有默认实现的虚函数（如 GetBacklight() 返回 nullptr）是可选功能，如果板卡没有背光控制，子类就不用重写。

GetInstance() 是标准的 Meyer 单例（C++ 中最推荐的单例实现方式）：

static Board& GetInstance() {
    static Board* instance = static_cast<Board*>(create_board());
    return *instance;
}

这里有两个关键点。第一，static 局部变量保证 create_board() 在整个程序生命周期中只执行一次，后续调用直接返回已创建的实例。第二，create_board() 是一个通过宏生成的工厂函数，它的具体实现取决于编译时选择的板卡类型。

DECLARE_BOARD 宏的定义和使用如下：

#define DECLARE_BOARD(BOARD_CLASS_NAME) \
void* create_board() { \
    return new BOARD_CLASS_NAME(); \
}

// 在每个板卡文件的末尾：
// movecall_moji_esp32s3.cc:150
DECLARE_BOARD(MovecallMojiESP32S3);

板卡源文件	宏调用	实际创建的类
`movecall_moji_esp32s3.cc`	`DECLARE_BOARD(MovecallMojiESP32S3)`	`MovecallMojiESP32S3`
`magiclick_c3_board.cc`	`DECLARE_BOARD(magiclick_c3)`	`magiclick_c3`
`esp_box3_board.cc`	`DECLARE_BOARD(EspBox3Board)`	`EspBox3Board`

这种编译时多态（通过 Kconfig 选择 CONFIG_BOARD_TYPE_*，再由 CMakeLists 条件编译）比起运行时的动态加载，优点是零额外开销、类型安全、易于调试。

整个启动过程从 app_main() 开始，第一步就是调用 Board::GetInstance()。这个函数首先创建具体板卡对象（例如 MovecallMojiESP32S3），过程中会依次执行 Board() → WifiBoard() → MovecallMojiESP32S3() 的构造函数链。创建完成后返回 Board& 引用，后续代码通过这个引用调用虚函数，由于 C++ 的多态机制，实际执行的是 MovecallMojiESP32S3 中重写的方法。

3. 构造函数执行链

3.1 完整构造时序

当 Board::GetInstance() 触发 new MovecallMojiESP32S3() 时，C++ 会按从基类到派生类的顺序执行构造函数。这是 C++ 对象模型的基本规则：构造从父到子，析构从子到父。

MovecallMojiESP32S3() : boot_button_(BOOT_BUTTON_GPIO) {  // GPIO 0
    // 进入构造函数体之前，C++ 已自动调用：
    //   1. Board()          — 生成 UUID
    //   2. WifiBoard()      — 创建 WiFi 连接超时定时器
    //   3. 初始化 boot_button_ 成员（调用 Button(GPIO_NUM_0)）
    
    InitializeCodecI2c();        // 4. 初始化 I2C 总线（音频编解码器通信用）
    InitializeSpi();            // 5. 初始化 SPI 总线（LCD 显示屏通信用）
    InitializeGc9a01Display();  // 6. 初始化 GC9A01 显示屏
    InitializeButtons();        // 7. 配置按键回调
    GetBacklight()->RestoreBrightness(); // 8. 恢复背光亮度
}

注意初始化的顺序遵循着依赖关系：I2C 用于音频编解码器，SPI 用于 LCD 显示屏，LCD 要在 SPI 之后初始化，按键和背光不依赖前面两个总线。如果顺序搞反了，比如先初始化 LCD 再初始化 SPI，LCD 初始化会因为没有可用的 SPI 总线而失败。

3.2 每步初始化详细说明

步骤	函数	底层调用	功能	包含的子步骤
基类	`Board()`	`GenerateUuid()` + NVS	生成/恢复设备 UUID	检查 NVS 是否有已保存的 UUID，有则恢复，无则生成新的
基类	`WifiBoard()`	`esp_timer_create()`	创建 WiFi 连接超时定时器	创建一个一次性定时器，后续 `StartNetwork()` 时启动
①	`InitializeCodecI2c()`	`i2c_new_master_bus()`	初始化 I2C 控制器	配置 I2C_NUM_0，SDA/SCL 引脚，使能内部上拉
②	`InitializeSpi()`	`spi_bus_initialize()`	初始化 SPI 控制器	配置 SPI3_HOST，MOSI/SCLK 引脚，设置 DMA
③	`InitializeGc9a01Display()`	多种 `esp_lcd_*`	初始化 GC9A01 LCD	配置 IO → 注册驱动 → 复位 → 初始化 → 颜色翻转 → 镜像 → 开显示 → 创建 SpiLcdDisplay
④	`InitializeButtons()`	`iot_button_register_cb()`	注册按键回调	单击进入配网或切换聊天状态
⑤	`GetBacklight()->RestoreBrightness()`	`ledc_set_duty()`	恢复背光亮度	构造 PwmBacklight → LEDC 配置 → 从 NVS 读亮度 → 渐变设置

3.3 InitializeGc9a01Display 详细流程

这个函数是 LCD 初始化中最为复杂的部分。它遵循了 ESP-IDF 的 LCD 驱动框架标准流程：先创建 SPI IO 接口，然后注册具体的 LCD 驱动芯片，再执行初始化序列，最后创建 LVGL 显示对象。

void InitializeGc9a01Display() {
    // Step 1: 创建 SPI IO 接口
    // 这是 ESP-IDF LCD 框架的抽象层，负责通过 SPI 总线发送命令和数据
    esp_lcd_panel_io_spi_config_t io_config = GC9A01_PANEL_IO_SPI_CONFIG(...);
    ESP_ERROR_CHECK(esp_lcd_new_panel_io_spi(SPI3_HOST, &io_config, &io_handle));
    
    // Step 2: 注册 GC9A01 驱动
    // 向 LCD 子系统注册 GC9A01 芯片驱动，绑定 IO 接口
    ESP_ERROR_CHECK(esp_lcd_new_panel_gc9a01(io_handle, &panel_config, &panel_handle));
    
    // Step 3: 硬件初始化序列
    ESP_ERROR_CHECK(esp_lcd_panel_reset(panel_handle));        // 复位 LCD 控制器
    ESP_ERROR_CHECK(esp_lcd_panel_init(panel_handle));         // 发送初始化命令序列
    ESP_ERROR_CHECK(esp_lcd_panel_invert_color(panel_handle, true));  // 颜色翻转（GC9A01 需要）
    ESP_ERROR_CHECK(esp_lcd_panel_mirror(panel_handle, true, false)); // 镜像设置
    ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(panel_handle, true));   // 开启显示
    
    // Step 4: 创建 LVGL Display 对象
    // 这个 new 会触发 Display → LvglDisplay → LcdDisplay → SpiLcdDisplay 的构造链
    display_ = new SpiLcdDisplay(io_handle, panel_handle, ...);
}

注意：查阅代码时发现 movecall_moji_esp32s3.cc 中虽然定义了 CustomLcdDisplay 类（继承自 SpiLcdDisplay 并重写了 SetupUI() 以适配圆形屏的左右内边距），但构造函数中实际使用的是 new SpiLcdDisplay(...)。这意味着 CustomLcdDisplay 类已定义但未被实例化，其 SetupUI() 中的特殊处理不会生效。这块可能需要确认是代码遗漏还是有意为之。

4. Display 子系统初始化

4.1 四层构造链

Display 的构造是理解这个项目最关键的链路之一。从最上层的 Display 到最下层的 SpiLcdDisplay，每层在构造函数中递进式地添加功能：

每一层构造完成后才开始下一层的构造，不能越过中间层。例如，LcdDisplay 的构造函数依赖 LvglDisplay 已经创建好的 pm_lock_ 和 notification_timer_，而 SpiLcdDisplay 又依赖 LcdDisplay 初始化好的主题系统。

4.2 各层构造函数详解

类	访问级别	执行内容	关键创建对象
`Display`	`public`	空构造函数，仅作为接口定义	—
`LvglDisplay`	`public`	创建电源管理锁和通知定时器	`pm_lock_`（`esp_pm_lock_create`）——防止 APB 总线降频 `notification_timer_`（`esp_timer_create`）——自动隐藏通知
`LcdDisplay`	`protected`	初始化主题、从 NVS 加载设置、创建预览定时器	主题系统（`LvglThemeManager`） `preview_timer_`（`esp_timer_create`）——5 秒自动清除预览
`SpiLcdDisplay`	`public`	写白屏、初始化 LVGL、注册显示设备	LVGL 引擎（任务 + 定时器） LVGL 显示缓冲区 `lv_display_t*` 句柄

注意 LcdDisplay 的构造函数是 protected，这是 C++ 中的一种设计约束：它告诉开发者"这个类不完整，不能单独使用"。因为 LcdDisplay 做了很多通用初始化工作（主题、预览定时器），但缺了最关键的一步——LVGL 显示注册。这一步只有具体的子类才知道怎么做（SPI、RGB、MIPI 的注册方式完全不同）。

4.3 LvglDisplay 构造函数

LvglDisplay 构造函数做了两件与硬件紧密相关的事，分别对应两个成员变量：

LvglDisplay::LvglDisplay() {
    // ① 创建通知定时器
    // 这是一个一次性定时器，当 ShowNotification() 被调用时启动
    // 定时到期后自动隐藏通知文字，恢复显示状态栏
    esp_timer_create_args_t notification_timer_args = {
        .callback = [](void *arg) {
            LvglDisplay *display = static_cast<LvglDisplay*>(arg);
            DisplayLockGuard lock(display);
            lv_obj_add_flag(display->notification_label_, LV_OBJ_FLAG_HIDDEN);
            lv_obj_remove_flag(display->status_label_, LV_OBJ_FLAG_HIDDEN);
        },
        .name = "notification_timer",
    };
    esp_timer_create(&notification_timer_args, &notification_timer_);

    // ② 创建电源管理锁（类型：ESP_PM_APB_FREQ_MAX）
    // 这个锁的作用是：在执行关键外设操作（如 I2C 读电池、SPI 刷屏）时，
    // 阻止 ESP-IDF 的电源管理模块降低 APB 总线频率
    auto ret = esp_pm_lock_create(ESP_PM_APB_FREQ_MAX, 0, "display_update", &pm_lock_);
    if (ret == ESP_ERR_NOT_SUPPORTED) {
        ESP_LOGI(TAG, "Power management not supported");
    } else {
        ESP_ERROR_CHECK(ret);
    }
}

通知定时器的作用是提供一种"定时消失"的 UI 交互。当显示通知时，调用 esp_timer_start_once(notification_timer_, duration_ms * 1000)，到达设定的时间后自动隐藏通知标签并恢复显示状态标签。

电源管理锁 pm_lock_ 在实际使用时（UpdateStatusBar() 函数中）会调用 esp_pm_lock_acquire(pm_lock_) 和 esp_pm_lock_release(pm_lock_) 来保护 I2C 读取电池电量和更新网络图标等操作。这是因为 ESP32 芯片在空闲时可能会自动降低外设总线频率以节省功耗，但如果在降低频率的过程中进行 I2C 通信，可能会导致通信超时或数据错误。

4.4 LcdDisplay 构造函数

LcdDisplay 的构造函数是 protected 的，意味着它不能直接被外部创建，只能被子类的初始化列表调用。它的主要工作是建立显示内容的视觉系统：

LcdDisplay::LcdDisplay(esp_lcd_panel_io_handle_t panel_io, 
                       esp_lcd_panel_handle_t panel,
                       int width, int height) {
    // ① 初始化 LCD 主题（light / dark 两套颜色方案）
    InitializeLcdThemes();
    
    // ② 从 NVS 加载已保存的主题名称
    // 默认主题为 "light"，如果用户通过 MCP 工具切换过主题，名称会保存在 NVS 中
    Settings settings("display", false);
    std::string theme_name = settings.GetString("theme", "light");
    current_theme_ = LvglThemeManager::GetInstance().GetTheme(theme_name);
    
    // ③ 创建预览图片定时器
    // 当有来自摄像头或网络下载的图片显示时，5 秒后自动清除，回退到表情界面
    esp_timer_create_args_t preview_timer_args = {
        .callback = [](void* arg) {
            display->SetPreviewImage(nullptr);  // 传 nullptr 即清除预览
        },
        .name = "preview_timer",
    };
    esp_timer_create(&preview_timer_args, &preview_timer_);
}

InitializeLcdThemes() 函数在主题管理器中注册了两套主题："light"（亮色：白底黑字）和 "dark"（暗色：黑底白字）。每套主题定义了背景色、文字颜色、聊天泡泡颜色、边框颜色、字体等十几项视觉属性。这些属性以 std::map<string, LvglTheme*> 的形式存储在 LvglThemeManager 单例中，后续通过主题名字符串查找。

预览定时器 preview_timer_ 的典型使用场景是：当 MCP 工具调用 self.image.download 下载了一张图片显示在屏幕上，或者摄像头拍摄了一张预览图，5 秒后定时器自动触发，调用 SetPreviewImage(nullptr) 清除图片、恢复显示表情和聊天界面。

4.5 SpiLcdDisplay 构造函数

SpiLcdDisplay 是具体的 SPI 接口 LCD 实现类。它的构造函数执行了 LVGL 图形库的初始化和显示设备注册，这是 Display 构造链的最后一环，也是最关键的一环：

SpiLcdDisplay::SpiLcdDisplay(...) : LcdDisplay(panel_io, panel, width, height) {
    // ① 写白屏清空显示
    std::vector<uint16_t> buffer(width_, 0xFFFF);
    for (int y = 0; y < height_; y++) {
        esp_lcd_panel_draw_bitmap(panel_, 0, y, width_, y + 1, buffer.data());
    }
    
    // ② 开启显示
    esp_lcd_panel_disp_on_off(panel_, true);
    
    // ③ 初始化 LVGL 图形库
    lv_init();
    
    // ④ 根据 PSRAM 大小设置图像缓存
    // 如果有 8MB 以上的 PSRAM，分配 2MB 用作 LVGL 图像缓存
    // 如果只有 2MB，分配 512KB
    if (psram_size_mb >= 8) {
        lv_image_cache_resize(2 * 1024 * 1024, true);
    }
    
    // ⑤ 启动 LVGL 端口（创建 LVGL 任务和定时器）
    lvgl_port_cfg_t port_cfg = ESP_LVGL_PORT_INIT_CONFIG();
    lvgl_port_init(&port_cfg);          // 创建 FreeRTOS 任务
    
    // ⑥ 注册显示设备到 LVGL
    // 这一步将 LCD 硬件与 LVGL 绑定，LVGL 渲染完成后通过 flush_cb 写入 LCD
    display_ = lvgl_port_add_disp(&display_cfg);  // 返回 lv_display_t*
}

第⑤步 lvgl_port_init 和第⑥步 lvgl_port_add_disp 是两个容易混淆但职责不同的函数，它们的区别如下：

函数	功能	类比
`lvgl_port_init()`	启动 LVGL 引擎：创建 FreeRTOS 任务（运行 `lv_timer_handler`）、创建 tick 定时器、创建互斥锁	“启动发动机”
`lvgl_port_add_disp()`	将 LCD 硬件注册到 LVGL：分配显存缓冲区、设置 flush 回调（`esp_lcd_panel_draw_bitmap`）、注册 `lv_display_t`	“挂上档，连接车轮”

简单来说，lvgl_port_init 让 LVGL"能跑"，lvgl_port_add_disp 让 LVGL"知道画到哪里去"。

4.6 主题初始化流程

主题系统采用注册-查找模式：先注册两套预设主题，运行时根据 NVS 中保存的用户偏好选择对应的主题。

主题注册使用 std::map<std::string, LvglTheme*> 作为存储结构，键为主题名称字符串，值为 LvglTheme* 指针。GetTheme(name) 调用 map.find(name) 进行 O(log n) 的查找，如果未找到则返回 nullptr。LvglTheme 类中存储了背景色、文字颜色、聊天泡泡颜色、字体等所有视觉属性，这些属性在上层 UI 代码中会被读取并应用到对应的 LVGL 控件上。

5. 按键初始化

按键初始化是整个板卡中与用户交互最直接的部分。MovecallMojiESP32S3 只有一个 BOOT 按键（GPIO 0），但它承载了两种不同的功能：

void InitializeButtons() {
    boot_button_.OnClick([this]() {
        auto& app = Application::GetInstance();
        if (app.GetDeviceState() == kDeviceStateStarting) {
            // ① 启动阶段：单击进入 WiFi 配网模式
            EnterWifiConfigMode();
            return;
        }
        // ② 正常运行阶段：单击切换聊天对话状态
        app.ToggleChatState();
    });
}

按键行为的"双重身份"根据设备状态区分：刚上电启动时，按下进入配网模式；正常运行后，按下切换聊天（开始录音/停止录音）。这种设计用一个物理按键实现了两种功能，减少了板卡上的按键数量。

Button 对象的构造

// 声明：movecall_moji_esp32s3.cc:52
Button boot_button_;

// 初始化列表：MovecallMojiESP32S3() : boot_button_(BOOT_BUTTON_GPIO)
// BOOT_BUTTON_GPIO 通常定义为 GPIO_NUM_0（开发板上的 BOOT 按键）

Button(gpio_num_t gpio_num, ...) 构造函数最终调用 ESP-IDF 的 iot_button_new_gpio_device()，该函数在底层注册 GPIO 中断，当按键电平变化时检测按键事件。

OnClick 事件注册流程

OnClick 内部的实现比较巧妙，它通过 iot_button_register_cb 注册了一个 C 语言回调，并把 this 指针作为 usr_data 传递进去。当按键事件发生时，C 回调函数将 usr_data 强制转换回 Button* 指针，从而调用 C++ 的 std::function。这是嵌入式 C++ 项目中连接 C 驱动和 C++ 逻辑的常见模式。

支持的按键事件

方法	底层事件宏	触发条件
`OnClick(callback)`	`BUTTON_SINGLE_CLICK`	单击（快速按下并释放）
`OnDoubleClick(callback)`	`BUTTON_DOUBLE_CLICK`	双击
`OnLongPress(callback)`	`BUTTON_LONG_PRESS_START`	长按（按住不放）
`OnPressDown(callback)`	`BUTTON_PRESS_DOWN`	按下瞬间
`OnPressUp(callback)`	`BUTTON_PRESS_UP`	抬起瞬间
`OnMultipleClick(callback, n)`	`BUTTON_MULTIPLE_CLICK`	指定次数的连击（如三击）

不同的板卡会根据自身硬件设计选择使用不同的事件组合。例如带有旋转编码器的板卡可能会使用长按和双击来提供更丰富的交互。

6. 背光控制

背光控制采用懒加载 + 渐变调节的方式。GetBacklight() 使用 static 局部变量，只在第一次调用时才构造 PwmBacklight 对象，后续调用直接返回已有实例：

virtual Backlight* GetBacklight() override {
    static PwmBacklight backlight(DISPLAY_BACKLIGHT_PIN, DISPLAY_BACKLIGHT_OUTPUT_INVERT);
    return &backlight;
}

这里的 static 关键字有两个作用：第一，backlight 对象只构造一次，节省资源；第二，如果板卡从未调用过 GetBacklight()，背光相关的 LEDC 外设根本不会被初始化，实现了真正的按需加载。

6.1 背光初始化流程

第一次调用时，构造顺序是 Backlight()（创建渐变定时器）→ PwmBacklight()（配置 LEDC 硬件），然后调用 RestoreBrightness() 从 NVS 读取上次保存的亮度值（默认 75%），通过 SetBrightness() 应用。

6.2 背光渐变机制

背光采用**软渐变（淡入/淡出）**方式调节，这是 Backlight 类的核心设计。它不使用 ledc_set_duty 直接跳变，而是通过一个 5ms 周期的定时器逐步逼近目标值：

void Backlight::SetBrightness(uint8_t brightness, bool permanent) {
    if (brightness > 100) brightness = 100;         // 限幅 0~100
    if (brightness_ == brightness) return;           // 无变化则跳过，避免不必要的定时器操作
    
    target_brightness_ = brightness;                 // 设定目标值
    step_ = (target_brightness_ > brightness_) ? 1 : -1;  // 确定渐变方向
    
    esp_timer_start_periodic(transition_timer_, 5 * 1000);  // 启动 5ms 周期定时器
}

定时器回调函数的逻辑很简单——每次触发时检查是否到达目标，没到就步进 1，然后调用硬件接口：

void Backlight::OnTransitionTimer() {
    if (brightness_ == target_brightness_) {
        esp_timer_stop(transition_timer_);           // 到达目标，停止定时器
        return;
    }
    brightness_ += step_;                             // 步进 1
    SetBrightnessImpl(brightness_);                  // 调用硬件接口
}

6.3 渐变示例（从 75% 降到 30%）

当前亮度: 75，目标亮度: 30，方向: step_ = -1

时间轴（每 5ms 触发一次）:
  T=0ms:    75 → 74  → SetBrightnessImpl(74)  → 占空比 756/1023
  T=5ms:    74 → 73  → SetBrightnessImpl(73)  → 占空比 746/1023
  T=10ms:   73 → 72  → SetBrightnessImpl(72)  → 占空比 736/1023
  ...
  T=220ms:  31 → 30  → SetBrightnessImpl(30)  → 占空比 306/1023 ✅ 停止

总耗时 45 步 × 5ms = 225ms。这个速度人眼看起来就是平滑过渡，不会注意到逐级变化，但避免了刺眼的瞬间亮度跳变。

6.4 硬件操作

PwmBacklight::SetBrightnessImpl() 是唯一与硬件直接交互的函数。它将 0~100 的百分比亮度值映射到 LEDC 定时器的 10 位占空比（0~1023），然后通过 ESP-IDF 的 LEDC 驱动设置 PWM 波形：

void PwmBacklight::SetBrightnessImpl(uint8_t brightness) {
    uint32_t duty_cycle = (1023 * brightness) / 100;   // 百分比 → 占空比
    ledc_set_duty(LEDC_LOW_SPEED_MODE, LEDC_CHANNEL_0, duty_cycle);
    ledc_update_duty(LEDC_LOW_SPEED_MODE, LEDC_CHANNEL_0);
}

LEDC（LED Control）是 ESP32 的 PWM 硬件外设，专门用于 LED 调光等场景。它不占用 CPU 资源，硬件自动产生 PWM 波形。PwmBacklight 构造函数中配置了 LEDC 定时器（25kHz 频率、10 位精度）和通道（绑定到背光 GPIO 引脚）。

6.5 完整背光控制流程

7. NVS 存储

7.1 Settings 封装层

NVS（Non-Volatile Storage，非易失性存储）是 ESP-IDF 提供的键值对存储系统，数据保存在 Flash 中，断电不丢失。项目通过 Settings 类对它进行了封装：

class Settings {
public:
    Settings(const std::string& name, bool read_only = false);
    //                    ↑ NVS 命名空间      ↑ 是否只读
    
    std::string GetString(const std::string& key, const std::string& default_value = "");
    void SetString(const std::string& key, const std::string& value);
    int32_t GetInt(const std::string& key, int32_t default_value = 0);
    void SetInt(const std::string& key, int32_t value);
};

Settings 构造函数的关键参数是 name——它对应 NVS 的命名空间（namespace）。NVS 的命名空间类似于文件系统中的目录，不同命名空间下的同名键不会冲突。read_only 参数决定底层 nvs_open 的模式，如果为 true 则以只读方式打开，避免意外写入。

7.2 使用场景与命名空间

Settings 实例	命名空间	用途	读写	示例数据
`Settings("display", false)`	`"display"`	读取主题名	只读	`theme = "light"`
`Settings("display", true)`	`"display"`	持久化亮度设置	读写	`brightness = 75`
Board 构造函数中	`"board"`	存储/恢复 UUID	读写	`uuid = "ab12..."`

7.3 NVS 在整个初始化中的作用

NVS 在整个初始化过程中承担了"记忆"的功能，使得设备重启后能恢复到上次的状态：

UUID 持久化：Board 构造函数中调用 GenerateUuid()，检查 NVS 中是否已有 UUID，有则恢复，无则生成新的并保存。这保证了设备标识的一致性。
主题记忆：LcdDisplay 构造函数中从 NVS 读取上次保存的主题名称（默认 “light”），设备重启后自动应用用户偏好的主题。
亮度保持：RestoreBrightness() 从 NVS 读取上次设置的亮度值（默认 75%），保证重启后屏幕亮度与上次使用一致。

8. 组件汇总表

8.1 定时器汇总

定时器	所属类	类型	周期	功能
`notification_timer_`	`LvglDisplay`	一次性（`esp_timer_start_once`）	由 `ShowNotification(duration)` 指定	通知显示一段时间后自动隐藏
`preview_timer_`	`LcdDisplay`	一次性（`esp_timer_start_once`）	5000ms（`PREVIEW_IMAGE_DURATION_MS` 宏定义）	预览图片 5 秒后自动清除
`transition_timer_`	`Backlight`	周期性（`esp_timer_start_periodic`）	5ms	背光亮度渐变步进
`connect_timer_`	`WifiBoard`	一次性	连接超时时间	WiFi 连接超时回调处理

8.2 锁汇总

锁	所属类	类型	功能
`pm_lock_`	`LvglDisplay`	`ESP_PM_APB_FREQ_MAX`（阻止 APB 频率降低）	保护 I2C/SPI 等外设通信不被降频影响
`DisplayLockGuard`	`Display`（RAII 守卫）	LVGL port mutex（通过 `lvgl_port_lock/unlock`）	确保多任务环境下对 LVGL 控件的访问是线程安全的

8.3 关键文件索引

文件路径	内容概述
`main/boards/common/board.h`	Board 基类定义、`DECLARE_BOARD` 宏、`GetInstance()` 单例
`main/boards/common/wifi_board.h`	WifiBoard 中间类（添加 WiFi 联网支持）
`main/boards/movecall-moji-esp32s3/movecall_moji_esp32s3.cc`	MovecallMojiESP32S3 板卡完整实现
`main/display/display.h`	Display 基类（定义所有显示接口）
`main/display/lvgl_display/lvgl_display.h`	LvglDisplay 类（电源锁 + 通知定时器）
`main/display/lcd_display.h`	LcdDisplay / SpiLcdDisplay / RgbLcdDisplay / MipiLcdDisplay 类声明
`main/display/lcd_display.cc`	所有 LCD 类的实现（主题、预览、LVGL 注册）
`main/boards/common/button.h`	Button / AdcButton / PowerSaveButton 类声明
`main/boards/common/button.cc`	Button 类实现（封装 ESP-IDF iot_button）
`main/boards/common/backlight.h`	Backlight / PwmBacklight 类声明
`main/boards/common/backlight.cc`	背光控制实现（渐变定时器 + LEDC PWM）
`main/settings.h`	Settings 类（NVS 存储封装）
`main/display/lvgl_display/lvgl_theme.h`	LvglTheme（主题颜色/字体定义）+ LvglThemeManager（注册/查找）

附录：完整初始化序列图

下面的时序图展示了从 app_main() 开始到所有子系统初始化完成的完整过程。图中横向是参与初始化的各个模块，纵向是时间顺序。可以从左到右依次跟踪每个模块做了什么：

整个初始化过程可以概括为三个阶段：

板卡对象创建（Board::GetInstance() → new MovecallMojiESP32S3()）：通过工厂方法 + 单例模式创建具体的板卡实例。
子系统初始化（构造函数体内的 5 个步骤）：按照 I2C → SPI → Display → Buttons → Backlight 的依赖顺序，逐个初始化硬件子系统。
应用层启动（Application::Initialize() + Application::Run()）：完成底层硬件初始化后，进入应用层的事件循环，开始处理消息和对话。