SimpleMorse：轻量级Arduino摩尔斯码按钮解码库

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 采用三层结构设计严格遵循嵌入式系统关注点分离原则层级模块职责关键约束硬件抽象层HALButtonInput封装统一封装按钮电平采样、软件消抖、边沿检测逻辑所有 I/O 操作仅调用digitalRead()不启用外部中断或定时器协议解析层PLMorseDecoder状态机管理符号缓冲区、字符查表、空格触发解码、退格回退使用固定长度char symbolBuffer[6]最大支持 5 符号终止符无 malloc/free应用接口层APISimpleMorse类封装提供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/DashsymbolBuffer索引递增最多存 5 符号symbolBuffer[0]到symbolBuffer[4]SYMBOL_BUILD → CHAR_DECODESpace 按钮按下 → 自动在symbolBuffer末尾写入\0→ 调用lookupChar()查表 → 成功则strcat(textBuffer, decodedChar)失败则追加 CHAR_DECODE / SYMBOL_BUILD → BACKSPACEBack 按钮按下 → 若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对应物理按钮接地端默认启用内部上拉按钮按下为 LOWbackPin可选参数设为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());若symbolBufferLen0返回空字符串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 UnoATmega328P上完整库实例化仅消耗142 字节 SRAM含 6128 缓冲区 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[] { /* 包含自定义项 */ }; #endif5. 硬件连接与抗干扰设计5.1 推荐电路拓扑按钮功能推荐引脚外部电路电气特性DotD2按钮一端接 D2另一端接地D2 内部上拉启用按下时digitalRead()返回LOWDashD3同上与 Dot 独立避免误触发SpaceD4同上关键此按钮必须与其他按钮物理隔离防止连击误判BackD5同上可选若省略backPin255PCB 设计建议所有按钮走线远离高频信号如晶振、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–50ms6. 典型应用场景与代码示例6.1 基础串口监控示例bare.ino#include SimpleMorse.h SimpleMorse morse(3, 2, 4, 5); // Dash3, Dot2, Space4, Back5 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 LCDPCF8574T 驱动需配合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 跨平台测试矩阵平台MCUFlash 使用SRAM 使用最大稳定采样率备注Arduino UnoATmega328P4.2 KB142 B250 Hzupdate()平均耗时 38μsATtiny85ATtiny853.1 KB138 B180 Hz需关闭Serial以释放 UARTESP32-WROOMESP32124 KB146 B1.2 kHz双核下可将update()分配至 APP CPURaspberry Pi PicoRP20408.7 KB144 B850 HzPIO 协处理器可卸载消抖逻辑7.2 关键性能指标最小点/划间隔≥ 50ms满足人类操作极限实测可稳定识别 40 WPM 电报速度空格响应延迟从 Space 按下到textBuffer更新 ≤ 120μs16MHz退格操作延迟≤ 85μs立即生效无视觉残留全缓冲区清空时间clearBuffers()函数执行时间 23μs恒定8. 故障排查与调试指南8.1 常见问题速查表现象可能原因解决方案stateChange()永不返回true按钮未正确接地begin()未调用引脚编号错误用万用表测按钮两端电压确认按下时为 0V检查pinMode是否被其他库覆盖解码字符全为 symbolBuffer内容与查表项不匹配如多空格、符号顺序错添加Serial.print(Raw: ); Serial.println(morse.getSymbol());观察原始输入文本显示乱码如ABtextBuffer被其他代码越界写入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)接口支持混合输入模式按钮定时器生态集成提供 PlatformIOlibrary.json元数据支持一键安装编写 Zephyr RTOS 移植层drivers/morse/simple_morse.c教育工具链开发 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说明。