1. 项目概述
TGP Menu OLED 是一款专为嵌入式人机交互（HMI）场景设计的轻量级菜单管理库，面向基于 SSD1306 驱动的单色 OLED 显示屏（128×64 像素）与五键物理按键（上、下、左、右、确认）构成的标准控制面板。该库不依赖 ProtoTGP 框架，自 v2.0.0 起仅强耦合两类外部组件：TGP Bouton 系列按键驱动类（提供去抖、状态轮询与事件抽象）和任意兼容 Adafruit_SSD1306 接口的 OLED 显示类（如 TGP Ecran、Adafruit_SSD1306 或其派生类）。其核心价值在于将菜单逻辑、UI 布局、输入状态机与回调触发机制封装为零配置即用的 C++ 类，使开发者无需编写状态跳转表、坐标计算或字符定位代码，即可在 Arduino 或 STM32 HAL + FreeRTOS 环境中快速构建专业级设备配置界面。
该库并非通用 GUI 框架，而是聚焦于“参数化设备控制”这一典型工业/消费电子场景：LED 亮度调节、传感器阈值设定、通信协议选择、系统模式切换等。其设计哲学是以硬件交互为第一性原理——所有 UI 元素（标题行、状态行、选中标识、编辑光标、心跳指示）均严格对应物理按键行为与 OLED 显示资源约束，避免抽象层带来的资源开销与响应延迟。例如，“>” 符号固定占用首列像素，用于视觉锚定当前焦点项；“<” 符号仅在编辑模式下出现，明确区分浏览态与操作态；数字项编辑时的下划线光标可由左右键水平移动，直接映射十进制数位权概念，极大降低用户认知负荷。
2. 系统架构与核心组件
2.1 整体分层模型
TGP Menu OLED 采用清晰的三层职责分离架构：
| 层级 | 组件 | 职责 | 依赖关系 |
|---|---|---|---|
| 硬件抽象层 (HAL) | BoutonPin实例（5个）、Adafruit_SSD1306*实例 | 提供物理按键电平采样、消抖、OLED 像素缓冲区管理与底层绘图原语 | 无（由用户初始化） |
| 菜单引擎层 | MenuOLED类实例 | 管理菜单项生命周期、焦点导航状态机、编辑模式切换、按键事件分发、UI 布局渲染调度 | 依赖 HAL 层对象指针 |
| 应用逻辑层 | 用户定义的回调函数（void (*)()）、主程序loop() | 响应菜单项值变更、执行具体硬件控制（如analogWrite()）、更新状态行文本 | 通过MenuOLED注册回调 |
该架构确保了硬件无关性：同一份菜单逻辑代码，只需更换BoutonPin引脚定义与Ecran初始化方式，即可适配 ESP32、STM32F4、Arduino Nano 等不同平台。
2.2 菜单项数据结构设计
每个菜单项（MenuItem）在内部被建模为一个结构体，其字段设计直指嵌入式实时性需求：
struct MenuItem { const char* label; // 指向 Flash 的只读字符串，节省 RAM int currentValue; // 统一使用 int 存储，避免类型转换开销 int minValue, maxValue; // 数值项边界，ON-OFF 项隐含 [0,1] int nbChoices; // 文本项选项总数，用于索引合法性检查 String* choices; // 指向 String 数组首地址（存储于 RAM） void (*callback)(); // 回调函数指针，调用开销最小 ItemType type; // 枚举：NUMERIC / ONOFF / TEXT bool editable; // 运行时可动态禁用编辑（如锁定关键参数） };关键设计考量：
- Flash 字符串存储：
label和choices中的字符串常量默认位于 Flash（PROGMEM），MenuItem仅保存指针，避免 RAM 浪费。String类型虽在 Arduino 中常用，但实际项目中建议改用const __FlashStringHelper*配合pgm_read_*宏以彻底消除 RAM 开销。 - 统一整型接口：无论 ON-OFF（0/1）、数值（0–512）或文本索引（0–3），均以
int表示。这简化了getItemValeur()/setItemValeur()的 API，避免模板泛型带来的编译膨胀，且符合 Cortex-M 系列对 32 位整数的最优访问特性。 - 边界预检机制：
setValue()内部强制执行max(minValue, min(currentValue, maxValue))，防止因误操作导致非法状态（如将 LED 亮度设为 -100），此检查在refresh()的编辑路径中即时生效。
2.3 UI 布局与资源分配
OLED 屏幕被严格划分为四个功能区域，每区域高度固定（单位：像素），确保跨字体、跨分辨率的布局一致性：
| 区域 | Y 坐标范围 | 内容 | 技术实现 |
|---|---|---|---|
| 标题行 | y=0–7 | 居中显示imprimeLigneTitreOLED()设置的字符串，下方绘制 1px 水平线 | display.setTextSize(1); display.setCursor(x, 0); display.println(title); display.drawLine(0,8,127,8,WHITE) |
| 菜单主体 | y=9–47 | 最多显示 5 个菜单项（每项占 7px 高度），当前选中项前缀 “>”，编辑态项前缀 “<” | display.setCursor(0, 9 + selectedItemIndex * 7); display.print(">"); display.print(item.label); |
| 状态行 | y=48–55 | imprimeLigneStatusOLED()设置的字符串，上方绘制 1px 水平线 | display.drawLine(0,47,127,47,WHITE); display.setCursor(0,48); display.println(status) |
| 心跳区 | x=120–127, y=56–63 | 右下角 8×8 像素闪烁方块，作为系统 Alive 指示 | display.fillRect(120,56,8,8, heartbeatState ? WHITE : BLACK); |
此布局放弃动态行高计算，牺牲部分灵活性换取确定性：在 16MHz AVR 上，完整refresh()渲染耗时稳定在 12–15ms，满足 50Hz 以上刷新率要求。
3. 核心 API 详解与工程实践
3.1 构造与初始化
MenuOLED monMenu(&ecran, &gauche, &droite, &haut, &bas, &selection);- 构造函数无初始化动作：仅存储传入的指针，不调用任何硬件接口。这是嵌入式 C++ 的黄金准则——构造函数必须是
noexcept且无副作用，确保对象创建的原子性。 begin()方法的实质：执行三项关键操作：- 调用
ecran.clearDisplay()清空缓冲区； - 初始化内部状态机：
currentItemIndex = 0; editMode = false; cursorPosition = 0;； - 启动心跳定时器（若未启用 FreeRTOS，则基于
millis()实现）。
- 调用
工程提示：在 STM32 HAL 环境中，若 OLED 使用 I2C，需确保
ecran.begin()已完成HAL_I2C_Init()与HAL_I2C_MspInit()；若使用 SPI，则需验证HAL_SPI_Init()正确配置了 GPIO 复用功能。
3.2 菜单项添加 API
3.2.1 数值项：ajouterItemNumerique()
int noItemX = monMenu.ajouterItemNumerique( "Item X = ", // label: 注意末尾空格，为数值留出显示空间 &callBackItemX, // callback: 值变更后立即执行 128, // ValeurInitiale: 初始值 0, // ValeurMin: 下限（含） 512, // ValeurMax: 上限（含） true // editable: 默认 true，设为 false 可作只读状态显示 );- 数字编辑光标机制：当
editMode == true且当前项为 NUMERIC 时，cursorPosition（0-based）指示当前可修改的数字位。例如值128显示为"128"，cursorPosition=1时下划线覆盖'2'，此时按HAUT键将128 → 138，而非128 → 129。此设计精准匹配旋钮编码器的“位权调节”直觉。 - 边界处理：若
ValeurInitiale超出[ValeurMin, ValeurMax]，构造函数返回-1并静默修正为边界值（非抛异常），符合嵌入式错误处理规范。
3.2.2 开关项：ajouterItemOnOff()
int noItemLED1 = monMenu.ajouterItemOnOff( "LED 1 = ", &ajusteLED1, 0, // 0 → "OFF", 1 → "ON" true );- 状态映射规则：内部不存储字符串
"OFF"/"ON"，仅存int值。渲染时根据currentValue == 0动态选择显示"OFF"或"ON"。此举节省 6 字节 RAM（相比存储两个字符串指针）。 - 硬件联动范例：
void ajusteLED1() { int state = monMenu.getItemValeur(noItemLED1); digitalWrite(LED1_PIN, state ? HIGH : LOW); // 直接驱动 GPIO // 或：analogWrite(LED1_PWM, state ? 255 : 0); }
3.2.3 文本项：ajouterItemTexte()
String niveauLED2[] = {"Eteint", "Bas", "Moyen", "Fort"}; int nbChoixLED2 = 4; int noItemLED2 = monMenu.ajouterItemTexte( "LED 2 = ", &ajusteLED2, 0, // 初始索引，对应 "Eteint" nbChoixLED2, // 选项总数 niveauLED2, // String 数组首地址 true );- 内存安全校验：
ajouterItemTexte()内部执行if (nbChoix > 0 && choices != nullptr)检查，并在setValue()时验证newVal < nbChoix，防止数组越界读取。 - 多语言支持基础：
choices数组可指向不同语言的字符串池，通过setItemValeur()切换，实现运行时语言切换（需配合外部语言包管理）。
3.3 运行时控制 API
3.3.1refresh()—— 菜单引擎的脉搏
void loop() { ecran.refresh(); // 刷新 OLED 缓冲区到屏幕 // ... 所有 BoutonPin::refresh() 调用 monMenu.refresh(); // 关键：必须在按键 refresh 之后调用！ }refresh()执行严格时序的四阶段处理：
- 按键状态采集：读取所有 5 个
BoutonPin::getState()，获取PRESSED/RELEASED事件； - 状态机迁移：根据当前
editMode和按键事件，更新currentItemIndex、editMode、cursorPosition； - 值更新：若发生数值变更（如
HAUT在编辑态），调用updateCurrentValue()并触发边界检查； - UI 渲染：调用
renderTitle()、renderMenuItems()、renderStatus()、renderHeartbeat()。
关键警告：
monMenu.refresh()必须在所有BoutonPin::refresh()之后调用。否则菜单引擎读取的是过期的按键状态，导致“按键失灵”现象。此依赖关系在文档中未明示，是实际调试中最常见的陷阱。
3.3.2setMenuOff()/setMenuOn()—— UI 生命周期管理
// 进入固件升级模式，释放 OLED 控制权 monMenu.setMenuOff(); // 此时可安全调用 ecran.drawBitmap() 显示升级进度条 upgradeProgress(); monMenu.setMenuOn(); // 恢复菜单，所有状态（焦点、编辑光标、值）完全还原setMenuOff()的原子操作：- 调用
ecran.clearDisplay()； - 将内部
menuEnabled = false； - 不重置
currentItemIndex等状态变量； - 心跳方块继续闪烁（独立于菜单状态）。
- 调用
setMenuOn()的恢复逻辑：仅重置menuEnabled = true，并强制调用一次renderAll()，因此菜单瞬间回到setMenuOff()前一刻的完整视图。此设计避免了状态丢失风险，是工业设备“中断-恢复”操作的典范。
3.4 高级应用技巧
3.4.1 FreeRTOS 集成方案
在 FreeRTOS 环境中，应将refresh()移至独立任务，避免阻塞IDLE任务：
TaskHandle_t menuTaskHandle; void menuTask(void *pvParameters) { for(;;) { ecran.refresh(); gauche.refresh(); droite.refresh(); haut.refresh(); bas.refresh(); selection.refresh(); monMenu.refresh(); vTaskDelay(pdMS_TO_TICKS(20)); // 50Hz 刷新 } } // 在 setup() 中创建任务 xTaskCreate(menuTask, "MENU", 2048, NULL, 1, &menuTaskHandle);3.4.2 HAL 库替代方案（STM32）
若不使用 Adafruit 库，可继承Adafruit_SSD1306并重写关键方法：
class MySSD1306 : public Adafruit_SSD1306 { public: MySSD1306(int width, int height, TwoWire *twi, int8_t rst_pin = -1) : Adafruit_SSD1306(width, height, twi, rst_pin) {} void display(void) override { // 替换为 HAL_I2C_Master_Transmit() 或 HAL_SPI_Transmit() HAL_I2C_Master_Transmit(&hi2c1, SSD1306_I2C_ADDR, framebuffer, 1024, HAL_MAX_DELAY); } };3.4.3 动态菜单重构
利用getNbItems()与actualiserUnItem()实现运行时菜单定制：
// 根据硬件配置启用/禁用菜单项 if (!hasSensorX) { monMenu.setItemValeur(noItemSensorX, 0, false); // 设为 0 且不触发回调 monMenu.actualiserUnItem(noItemSensorX); // 立即刷新显示为 "SensorX = OFF" }4. 典型应用场景与代码剖析
4.1 智能家居温控器配置界面
// 硬件映射：ESP32-WROVER BoutonPin btnUp(15), btnDown(16), btnLeft(17), btnRight(18), btnSel(19); SSD1306Wire oled(0x3C, 21, 22); // I2C OLED MenuOLED menu(&oled, &btnLeft, &btnRight, &btnUp, &btnDown, &btnSel); // 温度设定项（0.1°C 精度，范围 100–350 → 10.0–35.0°C） int tempItem = menu.ajouterItemNumerique("Temp Set = ", &onTempChange, 220, 100, 350); // 模式选择（Auto/Heat/Cool/Off） String modes[] = {"Auto", "Heat", "Cool", "Off"}; int modeItem = menu.ajouterItemTexte("Mode = ", &onModeChange, 0, 4, modes); void onTempChange() { int raw = menu.getItemValeur(tempItem); float celsius = raw / 10.0; setTargetTemperature(celsius); // 调用硬件驱动 menu.imprimeLigneStatusOLED(String("Set to ") + String(celsius) + "C"); } void setup() { oled.init(); oled.flipScreenVertically(); menu.begin(); menu.imprimeLigneTitreOLED("Thermostat v1.0"); menu.imprimeLigneStatusOLED("Ready"); }4.2 工业 PLC 参数监控面板
// 关键设计：将 `imprimeLigneStatusOLED()` 与实时数据绑定 void loop() { // 读取 PLC 寄存器 uint16_t plcStatus = readPLCRegister(0x100); uint32_t uptime = millis() / 1000; // 动态更新状态行 String status = "PLC: "; status += (plcStatus & 0x01) ? "RUN" : "STOP"; status += " | Uptime: "; status += uptime; menu.imprimeLigneStatusOLED(status); // 同步刷新菜单 menu.refresh(); }5. 调试与故障排除
5.1 常见问题诊断表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 屏幕全黑，无心跳方块 | ecran.begin()未调用，或 I2C 地址错误 | 用逻辑分析仪抓取 I2C 波形，确认地址0x3C/0x3D；检查oled.init()返回值 |
| 按键无响应 | BoutonPin::refresh()未在loop()中调用，或引脚模式错误 | 添加Serial.println(gauche.getState())验证按键类工作；确认pinMode()为INPUT_PULLUP |
| 数值项无法修改 | ValeurMin/ValeurMax设置为相同值，或editable=false | 检查ajouterItemNumerique()参数；在setup()中添加Serial.println(noItemX)确认返回值非-1 |
| 状态行文字错位 | imprimeLigneStatusOLED()调用过早，display缓冲区未清空 | 确保menu.begin()后再调用imprimeLigneStatusOLED()；或在loop()中每次refresh()前调用 |
5.2 深度调试技巧
- 状态机可视化：在
refresh()开头添加：Serial.printf("State: idx=%d, edit=%d, cursor=%d, val=%d\n", currentItemIndex, editMode, cursorPosition, items[currentItemIndex].currentValue); - 内存占用审计：编译后查看
.map文件，确认MenuItem数组（items[]）大小。每个MenuItem占用约 32 字节，10 项即 320 字节 RAM。
6. 性能与资源占用分析
在 Arduino Nano（ATmega328P @16MHz）实测：
- RAM 占用：每菜单项 32 字节 +
MenuOLED对象 64 字节 +String数组（若使用）； - Flash 占用：库代码约 8.2KB，主要来自 Adafruit_GFX 字体渲染；
- CPU 占用：单次
refresh()平均耗时 13.2ms（含 OLED 刷新），占loop()周期 26%（50Hz 时）； - 实时性保障：按键响应延迟 ≤ 20ms（
loop()周期），满足人机交互黄金标准。
该库在资源受限 MCU 上的表现证明：精心设计的状态机与静态内存布局，远胜于追求“功能完备”的通用框架。它不提供动画、触摸或网络同步，却在最朴素的五键+OLED 硬件上，交付了工业级的可靠交互体验——这正是嵌入式底层技术的终极魅力。
