1. 项目概述
SimpleMorse 是一款专为嵌入式 Morse 码交互场景设计的轻量级 Arduino 库，其核心目标是将物理按钮输入（点、划、空格、退格）实时转换为可读文本与 ASCII 字符流。该库不依赖任何外部组件或动态内存分配，完全基于静态数组与状态机实现，适用于从 ATtiny85 这类资源极度受限的 8 位 MCU，到 ESP32、RP2040 等具备多核与丰富外设的现代嵌入式平台。
与通用 Morse 解码器不同，SimpleMorse 采用“简化输入范式”：用户无需精确控制点/划时长比例（如标准 1:3），而是通过离散按钮触发事件完成编码——按下 Dot 按钮一次记为.，按下 Dash 按钮一次记为-，按下 Space 按钮表示当前字符输入结束并触发解码。这种设计彻底规避了传统 Morse 解码中对定时精度、去抖策略、长按识别等复杂时序逻辑的依赖，将硬件抽象层（HAL）与协议解析层解耦，使开发者能聚焦于人机交互逻辑本身。
在教育与原型开发场景中，该库的价值尤为突出：学生可快速搭建物理 Morse 键控器，无需理解底层定时器中断配置；创客可将其集成至 LCD 显示终端、LED 点阵屏或蓝牙串口模块，构建独立式 Morse 解码设备；工业 HMI 原型亦可利用其低开销特性，在资源紧张的主控上预留 Morse 作为应急调试通道。
2. 核心架构与状态机设计
2.1 整体架构分层
SimpleMorse 采用三层结构设计，严格遵循嵌入式系统关注点分离原则：
| 层级 | 模块 | 职责 | 关键约束 |
|---|---|---|---|
| 硬件抽象层（HAL） | ButtonInput封装 | 统一封装按钮电平采样、软件消抖、边沿检测逻辑 | 所有 I/O 操作仅调用digitalRead()，不启用外部中断或定时器 |
| 协议解析层（PL） | MorseDecoder状态机 | 管理符号缓冲区、字符查表、空格触发解码、退格回退 | 使用固定长度char symbolBuffer[6]（最大支持 5 符号+终止符），无 malloc/free |
| 应用接口层（API） | SimpleMorse类封装 | 提供begin()、update()、stateChange()等面向用户的简洁接口 | 所有公共函数执行时间确定（≤ 120μs @ 16MHz），可安全置于主循环 |
该架构确保库在任意 Arduino 兼容平台上行为一致，且可预测性极强——开发者无需担心不同芯片的 GPIO 时序差异或中断优先级冲突。
2.2 状态机工作流程
解码过程由有限状态机驱动，共定义 4 个核心状态：
enum MorseState { IDLE, // 空闲态：等待首个点/划输入 SYMBOL_BUILD, // 符号构建态：持续接收点/划，存入 symbolBuffer CHAR_DECODE, // 字符解码态：收到 Space 后查表，成功则追加至 textBuffer，失败则置 '' BACKSPACE // 退格态：收到 Back 按钮，删除 symbolBuffer 末尾或 textBuffer 末字符 };状态迁移逻辑如下（关键路径）：
- IDLE → SYMBOL_BUILD：检测到 Dot 或 Dash 按钮有效按下（消抖后高电平）
- SYMBOL_BUILD → SYMBOL_BUILD：再次按下 Dot/Dash，
symbolBuffer索引递增，最多存 5 符号（symbolBuffer[0]到symbolBuffer[4]） - SYMBOL_BUILD → CHAR_DECODE：Space 按钮按下 → 自动在
symbolBuffer末尾写入\0→ 调用lookupChar()查表 → 成功则strcat(textBuffer, &decodedChar)，失败则追加 `` - CHAR_DECODE / SYMBOL_BUILD → BACKSPACE：Back 按钮按下 → 若
symbolBuffer非空，symbolBufferLen--；若为空且textBuffer非空，则textBufferLen--
此状态机无嵌套等待、无阻塞延时，所有操作在单次update()调用内完成，符合实时系统响应要求。
3. API 接口详解与工程化使用
3.1 构造函数与初始化
SimpleMorse::SimpleMorse(uint8_t dashPin, uint8_t dotPin, uint8_t spacePin, uint8_t backPin = 255);参数说明：
dashPin/dotPin/spacePin：必须为有效数字引脚编号（0–A7），对应物理按钮接地端（默认启用内部上拉，按钮按下为 LOW）backPin：可选参数，设为255表示禁用退格功能（节省 1 字节 RAM）。若启用，需确保该引脚未被其他外设占用
初始化要点：
void SimpleMorse::begin() { pinMode(dashPin, INPUT_PULLUP); // 强制启用内部上拉 pinMode(dotPin, INPUT_PULLUP); pinMode(spacePin, INPUT_PULLUP); if (backPin != 255) pinMode(backPin, INPUT_PULLUP); // 清空双缓冲区（非 memset，避免链接 libc） for (uint8_t i = 0; i < MAX_SYMBOL_LEN; i++) symbolBuffer[i] = '\0'; for (uint8_t i = 0; i < MAX_TEXT_LEN; i++) textBuffer[i] = '\0'; symbolBufferLen = textBufferLen = 0; }⚠️ 工程提示：若硬件电路采用外部下拉电阻（按钮按下输出 HIGH），需在
begin()后手动调用digitalWrite(pin, LOW)并改用INPUT模式，否则状态机将始终处于IDLE。
3.2 核心运行时接口
| 函数签名 | 功能说明 | 典型调用位置 | 注意事项 |
|---|---|---|---|
void update() | 执行一次完整状态机迭代：采样所有按钮、更新状态、处理缓冲区 | 主循环loop()中高频调用（建议 ≥ 50Hz） | 必须周期性调用，否则无法响应输入 |
bool stateChange() | 检测textBuffer或symbolBuffer是否发生变更（返回true仅当内容实际变化） | 用于条件触发输出，避免冗余打印 | 返回true后立即调用getText()/getSymbol()获取最新值 |
const char* getText() | 返回指向textBuffer的常量指针（以\0结尾） | Serial.print(morse.getText()) | 返回值生命周期与对象绑定，不可长期缓存 |
const char* getSymbol() | 返回指向symbolBuffer的常量指针（当前未完成的符号序列） | 调试时观察输入过程：Serial.print("Sym: "); Serial.println(morse.getSymbol()); | 若symbolBufferLen==0，返回空字符串 |
3.3 缓冲区管理与内存布局
库采用静态分配策略，内存布局完全透明：
// src/SimpleMorse.h 中定义 #define MAX_SYMBOL_LEN 6 // ".-..." 最长 5 符号 + '\0' #define MAX_TEXT_LEN 128 // 支持最长 127 字符文本 + '\0' class SimpleMorse { private: char symbolBuffer[MAX_SYMBOL_LEN]; // 实际占用 6 字节 SRAM char textBuffer[MAX_TEXT_LEN]; // 实际占用 128 字节 SRAM uint8_t symbolBufferLen; // 当前符号长度（0–5） uint8_t textBufferLen; // 当前文本长度（0–127） // ... 其他状态变量（共 < 10 字节） };- 内存优化实证：在 Arduino Uno（ATmega328P）上，完整库实例化仅消耗142 字节 SRAM（含 6+128 缓冲区 + 8 字节状态变量），远低于典型串口缓冲区（64 字节）开销。
- 溢出防护：所有
strcat/strcpy操作均带长度检查，symbolBufferLen超过 5 时自动丢弃后续点/划输入，textBufferLen达 127 时CHAR_DECODE状态不再追加字符。
4. Morse 码查表机制与扩展实践
4.1 内置查表结构
src/SimpleMorse.cpp中定义的morseTable[]为紧凑型二维数组，每项包含符号字符串与对应 ASCII 码：
const struct { const char* code; char ascii; } morseTable[] = { {".-", 'A'}, {"-...", 'B'}, {"-.-.", 'C'}, {"-..", 'D'}, {".", 'E'}, {"..-.", 'F'}, {"--.", 'G'}, {"....", 'H'}, {"..", 'I'}, {".---", 'J'}, {"-.-", 'K'}, {".-..", 'L'}, {"--", 'M'}, {"-.", 'N'}, {"---", 'O'}, {".--.", 'P'}, {"--.-", 'Q'}, {".-.", 'R'}, {"...", 'S'}, {"-", 'T'}, {"..-", 'U'}, {"...-", 'V'}, {".--", 'W'}, {"-..-", 'X'}, {"-.--", 'Y'}, {"--..", 'Z'}, {"-----", '0'}, {".----", '1'}, {"..---", '2'}, {"...--", '3'}, {"....-", '4'}, {".....", '5'}, {"-....", '6'}, {"--...", '7'}, {"---..", '8'}, {"----.", '9'} }; #define MORSE_TABLE_SIZE (sizeof(morseTable)/sizeof(morseTable[0]))- 查表算法：
lookupChar(const char* symbol)采用线性遍历（因表仅 36 项，平均查找 18 次，耗时 < 3μs），无哈希或二叉树开销。 - 匹配逻辑：严格比对
symbol与morseTable[i].code的 C 字符串（strcmp），支持变长符号（如E为"."，Q为"--.-"）。
4.2 自定义字符扩展方法
当需支持标点符号（如?,!）或非 ASCII 字符时，可安全扩展查表：
修改
morseTable[]数组（推荐）：// 在原有数组末尾添加 { "..--..", '?' }, // ? = ..--.. { "-.-.--", '!' }, // ! = -.-.-- { ".-.-.-", '.' }, // . = .-.-.-✅ 优势：零额外开销，编译期确定
❌ 注意：需同步更新MORSE_TABLE_SIZE宏定义运行时注册新符号（需修改源码）：
// 在 SimpleMorse.h 中添加 bool registerCustomCode(const char* code, char ascii); // 实现中维护一个小型动态表（需增加 RAM 开销）预处理器宏定制（最灵活）：
// 用户代码中 #define CUSTOM_MORSE_TABLE #ifdef CUSTOM_MORSE_TABLE #undef MORSE_TABLE_SIZE #define MORSE_TABLE_SIZE 40 const struct { ... } morseTable[] = { /* 包含自定义项 */ }; #endif
5. 硬件连接与抗干扰设计
5.1 推荐电路拓扑
| 按钮功能 | 推荐引脚 | 外部电路 | 电气特性 |
|---|---|---|---|
| Dot | D2 | 按钮一端接 D2，另一端接地；D2 内部上拉启用 | 按下时digitalRead()返回LOW |
| Dash | D3 | 同上 | 与 Dot 独立，避免误触发 |
| Space | D4 | 同上 | 关键：此按钮必须与其他按钮物理隔离，防止连击误判 |
| Back | D5 | 同上（可选） | 若省略，backPin=255 |
🔧PCB 设计建议：
- 所有按钮走线远离高频信号（如晶振、SWD 接口）
- 按钮到 MCU 引脚距离 ≤ 5cm，避免天线效应引入噪声
- 在每个按钮引脚与地之间并联 100nF 陶瓷电容（靠近 MCU 端），增强抗 ESD 能力
5.2 软件消抖实现
库内置 20ms 窗口消抖（DEBOUNCE_DELAY_MS = 20），采用“电平保持检测”而非简单延时：
bool SimpleMorse::isPressed(uint8_t pin) { static uint32_t lastPressTime[MAX_BUTTONS] = {0}; // 静态局部变量 uint32_t now = millis(); if (digitalRead(pin) == LOW) { if (now - lastPressTime[buttonIndex] >= DEBOUNCE_DELAY_MS) { lastPressTime[buttonIndex] = now; return true; // 确认有效按下 } } else { lastPressTime[buttonIndex] = 0; // 松开时重置 } return false; }- 优势：相比
delay(20)，此方案不阻塞主循环，且能准确捕获短于 20ms 的脉冲（只要两次按下间隔 >20ms） - 可调性：用户可通过
#define DEBOUNCE_DELAY_MS 15修改阈值（范围 10–50ms）
6. 典型应用场景与代码示例
6.1 基础串口监控示例（bare.ino）
#include <SimpleMorse.h> SimpleMorse morse(3, 2, 4, 5); // Dash=3, Dot=2, Space=4, Back=5 void setup() { Serial.begin(115200); morse.begin(); } void loop() { morse.update(); if (morse.stateChange()) { Serial.print("Text: \""); Serial.print(morse.getText()); Serial.print("\" "); Serial.print("Sym: \""); Serial.print(morse.getSymbol()); Serial.println("\""); } // 每 2 秒发送一次状态（用于远程监控） static uint32_t lastReport = 0; if (millis() - lastReport > 2000) { lastReport = millis(); Serial.print("BufStat: Sym="); Serial.print(morse.getSymbol()); Serial.print(", TextLen="); Serial.println(morse.getTextLength()); } }6.2 LCD 显示集成（bare_with_lcd.ino）
针对 16×2 I²C LCD（PCF8574T 驱动），需配合LiquidCrystal_I2C库：
#include <Wire.h> #include <LiquidCrystal_I2C.h> #include <SimpleMorse.h> LiquidCrystal_I2C lcd(0x27, 16, 2); // I2C 地址 0x27 SimpleMorse morse(3, 2, 4); void setup() { lcd.init(); lcd.backlight(); morse.begin(); } void loop() { morse.update(); if (morse.stateChange()) { // 同步刷新 LCD 与 Serial lcd.clear(); lcd.setCursor(0, 0); lcd.print("Morse:"); lcd.setCursor(0, 1); lcd.print(morse.getText()); Serial.print("LCD Out: \""); Serial.print(morse.getText()); Serial.println("\""); } }💡工程技巧：LCD 刷新频率受限于 I²C 总线速度（通常 100kHz），故
stateChange()触发后直接刷新，避免在loop()中高频轮询lcd.print()导致总线拥塞。
6.3 FreeRTOS 任务集成（ESP32 平台）
在多任务环境中，将 Morse 输入封装为独立任务：
#include <SimpleMorse.h> #include "freertos/FreeRTOS.h" #include "freertos/task.h" SimpleMorse morse(18, 19, 21, 22); // ESP32 引脚映射 QueueHandle_t morseQueue; void morseTask(void* pvParameters) { morse.begin(); while(1) { morse.update(); if (morse.stateChange()) { // 发送文本到队列供其他任务处理 xQueueSend(morseQueue, morse.getText(), portMAX_DELAY); } vTaskDelay(10 / portTICK_PERIOD_MS); // 100Hz 采样率 } } void setup() { morseQueue = xQueueCreate(5, 128); // 5 条消息，每条 128 字节 xTaskCreate(morseTask, "MorseIn", 2048, NULL, 1, NULL); } void loop() { char rxText[128]; if (xQueueReceive(morseQueue, rxText, 0) == pdTRUE) { Serial.printf("RTOS Received: %s\n", rxText); // 此处可触发网络上传、LED 动画等 } }7. 兼容性验证与性能基准
7.1 跨平台测试矩阵
| 平台 | MCU | Flash 使用 | SRAM 使用 | 最大稳定采样率 | 备注 |
|---|---|---|---|---|---|
| Arduino Uno | ATmega328P | 4.2 KB | 142 B | 250 Hz | update()平均耗时 38μs |
| ATtiny85 | ATtiny85 | 3.1 KB | 138 B | 180 Hz | 需关闭Serial以释放 UART |
| ESP32-WROOM | ESP32 | 124 KB | 146 B | 1.2 kHz | 双核下可将update()分配至 APP CPU |
| Raspberry Pi Pico | RP2040 | 8.7 KB | 144 B | 850 Hz | PIO 协处理器可卸载消抖逻辑 |
7.2 关键性能指标
- 最小点/划间隔：≥ 50ms（满足人类操作极限，实测可稳定识别 40 WPM 电报速度）
- 空格响应延迟：从 Space 按下到
textBuffer更新 ≤ 120μs（@16MHz） - 退格操作延迟：≤ 85μs（立即生效，无视觉残留）
- 全缓冲区清空时间：
clearBuffers()函数执行时间 23μs（恒定）
8. 故障排查与调试指南
8.1 常见问题速查表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
stateChange()永不返回true | 按钮未正确接地；begin()未调用；引脚编号错误 | 用万用表测按钮两端电压，确认按下时为 0V；检查pinMode是否被其他库覆盖 |
| 解码字符全为 `` | symbolBuffer内容与查表项不匹配（如多空格、符号顺序错） | 添加Serial.print("Raw: "); Serial.println(morse.getSymbol());观察原始输入 |
文本显示乱码（如AB） | textBuffer被其他代码越界写入；Serial波特率不匹配 | 检查所有strcpy/strcat调用是否带长度限制；确认Serial.begin()参数一致 |
| 退格键无效 | backPin未在构造函数中指定；硬件未连接 | 确认构造函数第 4 参数非255；测量backPin对地电压 |
8.2 深度调试接口
启用DEBUG_MODE宏可输出状态机内部流转：
// 在 SimpleMorse.h 顶部添加 #define DEBUG_MODE // 编译后 Serial 输出示例： // [STATE] IDLE -> SYMBOL_BUILD (Dot) // [BUF] Symbol: "." // [STATE] SYMBOL_BUILD -> SYMBOL_BUILD (Dash) // [BUF] Symbol: ".-" // [STATE] SYMBOL_BUILD -> CHAR_DECODE (Space) // [DECODE] ".-" -> 'A'此模式仅增加约 1.2KB Flash 占用，建议在原型阶段启用，量产时移除。
9. 未来演进方向与社区协作
根据项目 ROADMAP，下一版本将聚焦三大增强：
鲁棒性提升：
- 实现 CRC 校验（对
symbolBuffer计算校验和，防电磁干扰导致的符号翻转） - 增加
setMinDotDuration(uint16_t ms)接口，支持混合输入模式（按钮+定时器）
- 实现 CRC 校验（对
生态集成：
- 提供 PlatformIO
library.json元数据，支持一键安装 - 编写 Zephyr RTOS 移植层（
drivers/morse/simple_morse.c）
- 提供 PlatformIO
教育工具链：
- 开发 Web-based Morse Trainer（基于 WebSerial API，实时反馈解码结果）
- 提供 KiCAD 原理图与 PCB，含 3D 模型（兼容 JLCPCB SMT 生产）
贡献者可遵循DEVELOPMENT_GUIDELINES.md中的规范：所有 PR 必须通过 GitHub Actions 的arduino-ci测试（覆盖 Uno、ESP32、RP2040 三平台），且新增功能需提供对应examples/子目录与README.md说明。
