1. 项目概述MorseEncoder 是一款专为 Arduino 平台设计的轻量级嵌入式 Morse 编码库其核心目标是将常见数据类型字符、字符串、整数等实时转换为符合国际标准的 Morse 码信号并通过硬件外设以音频脉冲或光脉冲两种物理形式输出。该库不依赖浮点运算、动态内存分配或复杂状态机全部采用静态查表与定时器驱动方式实现满足资源受限 MCU如 ATmega328P、ESP32-S2、nRF52832在低功耗、高确定性场景下的硬实时需求。与通用串口协议不同Morse 编码本质是一种时序编码协议它不传输字节流而是通过“点”·、“划”−及其间隔定义信息。国际电信联盟ITU-R M.1677-1规定标准 Morse 字符集包含 26 个大写字母、10 个数字及 17 个标点符号共 53 个MorseEncoder 完整支持该字符集覆盖 SOS 求救信号、经纬度坐标、简短指令等典型嵌入式通信场景。该库的设计哲学体现典型的嵌入式工程思维功能聚焦、接口极简、资源可控、可预测性强。所有编码逻辑在编译期完成查表运行时仅执行 GPIO 翻转与延时控制无递归调用、无堆栈溢出风险适用于裸机Bare-Metal或 RTOS 环境FreeRTOS、Zephyr。2. 核心架构与工作原理2.1 编码协议解析Morse 码的时序结构由四个基本时间单位构成均以“点”Dit为基准符号含义持续时间说明·Dit点1 × T最小信号单元如 LED 亮/蜂鸣器发声−Dah划3 × T长信号持续时间为点的三倍Intra-character space字符内间隔1 × T点与划之间的静默间隔Inter-character space字符间间隔3 × T相邻字符间的静默间隔Word space字间间隔7 × T单词间的静默间隔如 SOS 中 S 与 O 之间其中TTime Unit由 WPMWords Per Minute决定。标准定义1 个“word” “PARIS”5 字符 4 个字符间隔 5×1 4×3 17 个点时长故$$ T \frac{1200}{\text{WPM}} \quad \text{ms} $$例如 WPM15 时$T 1200 / 15 80,\text{ms}$则点80 ms划240 ms字符内间隔80 ms字符间间隔240 ms字间间隔560 msMorseEncoder 在beginAudio()与beginLight()中接收 WPM 参数后即刻计算出所有时间常量并存入实例私有变量后续所有延时操作均基于此整型毫秒值避免浮点运算开销。2.2 硬件抽象层设计库采用双实例模式分离音频与光信号通道每个实例绑定独立 GPIO 引脚与工作模式Audio 模式使用analogWrite()PWM驱动有源蜂鸣器或压电片。要求引脚必须为硬件 PWM 引脚如 Uno 的 D3/D5/D6/D9/D10/D11因analogWrite()在非 PWM 引脚上退化为 digitalWrite()无法产生连续音调。Light 模式使用digitalWrite()驱动 LED 或红外发射管。对引脚无特殊要求但需注意灌电流能力如 ATmega328P 最大 40 mA/引脚。关键设计决策不封装定时器中断。所有延时采用delay()阻塞式实现原因如下Morse 信号天然为低频最高 WPM≈40对应最短点时长约 30 msdelay()精度完全满足避免中断上下文切换开销降低系统复杂度允许用户在loop()中自由穿插其他任务如传感器采样只需确保morseX.print()调用不被长时阻塞打断。若需非阻塞编码如在 FreeRTOS 任务中运行用户可将print()内部逻辑拆解为状态机参考src/MorseEncoder.cpp中encodeChar()与sendSymbol()的分步实现。2.3 字符映射表实现MorseEncoder 使用静态 const 数组实现字符到编码序列的 O(1) 查找// src/MorseEncoder.cpp 片段 const char* morseTable[128] { nullptr, nullptr, nullptr, nullptr, // ASCII 0-3 nullptr, nullptr, nullptr, nullptr, // 4-7 nullptr, nullptr, nullptr, nullptr, // 8-11 nullptr, nullptr, nullptr, nullptr, // 12-15 nullptr, nullptr, nullptr, nullptr, // 16-19 nullptr, nullptr, nullptr, nullptr, // 20-23 nullptr, nullptr, nullptr, nullptr, // 24-27 nullptr, nullptr, nullptr, nullptr, // 28-31 nullptr, nullptr, nullptr, nullptr, // 32-35 (space, !, , #) nullptr, nullptr, nullptr, nullptr, // 36-39 ($, %, , ) nullptr, nullptr, nullptr, nullptr, // 40-43 ((, ), *, ) nullptr, nullptr, nullptr, nullptr, // 44-47 (,, -, ., /) 10, 1100, 1010, 100, 0, // 48-52: 0-4 00, 000, 0000, 00000, // 53-57: 5-9 nullptr, nullptr, nullptr, nullptr, // 58-61 (:, ;, , ) 01000, 0010, 010, 1000, // 62-65 (, ?, , A) 101010, 10000, 10010, 1000, // 66-69 (B, C, D, E) 00100, 1010, 000, 100000, // 70-73 (F, G, H, I) 0100, 0000, 00000, 10100, // 74-77 (J, K, L, M) 00, 01, 0001, 00001, // 78-81 (N, O, P, Q) 101000, 01000, 001, 000000, // 82-85 (R, S, T, U) 00010, 000001, 010000, 001000, // 86-89 (V, W, X, Y) 000010, 010101, 0000000, // 90-92 (Z, 0-9 已覆盖) nullptr, nullptr, nullptr, nullptr, // 93-96 0000000, 0000000, 0000000, // 97-99 (a-z 映射同 A-Z) // ... 后续填充至索引 127 };表格大小为 128覆盖 ASCII 0–127未定义字符返回nullptrprint()中自动跳过小写字母a–z与大写A–Z共享同一编码Morse 不区分大小写通过toupper()统一处理编码字符串使用0表示点·1表示划−便于for循环逐位解析所有字符串存储于 FlashPROGMEM不占用 RAM。3. API 接口详解3.1 类声明与构造函数#include MorseEncoder.h class MorseEncoder { public: MorseEncoder(uint8_t pin); // 构造函数指定输出引脚 void beginAudio(uint8_t wpm, uint16_t freq); // 初始化音频模式 void beginLight(uint8_t wpm); // 初始化光模式 void print(const String str); // 编码并输出字符串 void print(const char* str); // 编码并输出 C 字符串 void print(char c); // 编码并输出单字符 void print(int num); // 编码并输出整数十进制 void print(long num); // 编码并输出长整数 private: uint8_t _pin; uint8_t _wpm; uint16_t _freq; bool _isAudio; uint32_t _ditMs; // 点时长ms uint32_t _dahMs; // 划时长ms uint32_t _intraMs; // 字符内间隔ms uint32_t _interMs; // 字符间间隔ms uint32_t _wordMs; // 字间间隔ms void sendSymbol(char symbol); // 发送单个点或划 void encodeChar(char c); // 编码单字符并发送 void sendSpace(uint32_t ms); // 发送指定时长静默 };成员类型说明_pinuint8_t输出引脚编号如 9、13_wpmuint8_t当前 WPM 设置值10–40 推荐_frequint16_t音频频率Hz仅 Audio 模式有效_isAudiobool标识当前工作模式trueAudio, falseLight_ditMs~_wordMsuint32_t预计算的各时序单位毫秒值⚠️ 注意_freq仅用于analogWrite()的占空比参数实际频率由 PWM 基频决定ArduinoanalogWrite()不支持直接设置 PWM 频率。若需精确音调应改用tone()函数或硬件定时器。3.2 初始化函数beginAudio(uint8_t wpm, uint16_t freq)参数wpmWPM 值范围建议 10–40低于 10 人耳难辨高于 40 MCU 可能无法及时响应freq蜂鸣器驱动频率Hz常用值800清晰、1200穿透力强、2000高频警示。行为计算T 1200 / wpm四舍五入为整数毫秒设置_ditMs T,_dahMs 3*T,_intraMs T,_interMs 3*T,_wordMs 7*T设置_isAudio true调用pinMode(_pin, OUTPUT)不启动 PWMPWM 在sendSymbol(0)或sendSymbol(1)中按需启用。beginLight(uint8_t wpm)参数wpm同上行为计算所有时序参数设置_isAudio false调用pinMode(_pin, OUTPUT)后续sendSymbol()仅执行digitalWrite(_pin, HIGH/LOW)。3.3 编码输出函数所有print()重载最终调用统一流程对输入数据进行标准化字符串转大写、整数转字符串遍历每个字符c若morseTable[toupper(c)] ! nullptr则调用encodeChar(c)否则跳过该字符静默处理字符间插入_interMs静默单词间空格处插入_wordMs静默。encodeChar(char c)查表获取编码字符串如S → 000对字符串中每个字符0→ 调用sendSymbol(0)发点1→ 调用sendSymbol(1)发划发送完毕后调用sendSpace(_interMs)字符间间隔。sendSymbol(char symbol)若_isAudio trueanalogWrite(_pin, 128)50% 占空比delay(symbol 0 ? _ditMs : _dahMs)analogWrite(_pin, 0)关闭若_isAudio falsedigitalWrite(_pin, HIGH)delay(symbol 0 ? _ditMs : _dahMs)digitalWrite(_pin, LOW)。sendSpace(uint32_t ms)digitalWrite(_pin, LOW)LED 关闭或analogWrite(_pin, 0)蜂鸣器静音delay(ms)。4. 典型应用示例与工程实践4.1 基础双模广播官方示例增强版#include MorseEncoder.h // 实例化Audio 使用 PWM 引脚 9Light 使用 LED 引脚 13 MorseEncoder morseA(9); // Audio MorseEncoder morseL(13); // Light void setup() { // 初始化WPM15音频频率1000Hz morseA.beginAudio(15, 1000); morseL.beginLight(15); // 可选初始化串口调试 Serial.begin(115200); Serial.println(MorseEncoder initialized.); } void loop() { static const char* messages[] {SOS, HELLO, 73}; // 73 业余无线电“致意” static uint8_t idx 0; String msg messages[idx]; // 音频广播 Serial.print(Audio: ); Serial.println(msg); morseA.print(msg); delay(1000); // 字间等待 // 光信号广播 Serial.print(Light: ); Serial.println(msg); morseL.print(msg); delay(1000); // 切换消息 idx (idx 1) % 3; }✅工程提示delay(1000)保证两次广播不重叠若需连续发送可移除该延时但需确保morseX.print()总耗时 ≤ 系统最小任务周期。4.2 FreeRTOS 集成非阻塞任务在 ESP32 或 STM32FreeRTOS 环境中可将 Morse 发送封装为独立任务避免阻塞主线程#include freertos/FreeRTOS.h #include freertos/task.h #include MorseEncoder.h MorseEncoder morseRT(2); // ESP32 GPIO2内置 LED // Morse 发送状态机 struct MorseState { const char* msg; uint8_t pos; enum { IDLE, SENDING_CHAR, SENDING_SYMBOL, SENDING_SPACE } state; uint32_t nextTime; }; MorseState g_morseState; void morseTask(void* pvParameters) { morseRT.beginLight(15); g_morseState.msg DEVELOPER; g_morseState.pos 0; g_morseState.state MorseState::IDLE; g_morseState.nextTime millis(); while(1) { uint32_t now millis(); if (now g_morseState.nextTime) { vTaskDelay(1); continue; } switch(g_morseState.state) { case MorseState::IDLE: if (g_morseState.msg[g_morseState.pos] \0) { g_morseState.pos 0; // 循环 } else { g_morseState.state MorseState::SENDING_CHAR; } break; case MorseState::SENDING_CHAR: // 此处调用 encodeChar() 的分解步骤参考源码 // 伪代码查表 → 设置符号序列 → 进入 SENDING_SYMBOL g_morseState.state MorseState::SENDING_SYMBOL; break; case MorseState::SENDING_SYMBOL: // 控制 GPIO设置 nextTime now duration g_morseState.state MorseState::IDLE; break; case MorseState::SENDING_SPACE: // 同上 break; } g_morseState.nextTime millis() 1; // 下次检查 } } void setup() { xTaskCreate(morseTask, Morse, 2048, NULL, 1, NULL); } void loop() { // 主线程可执行其他任务 vTaskDelay(10); }关键点需从MorseEncoder.cpp提取encodeChar()内部逻辑将其拆分为状态驱动步骤避免delay()。4.3 低功耗唤醒 Morse Beacon在电池供电节点中可结合看门狗定时器WDT实现超低功耗 Morse 广播// ATmega328P 示例使用 Watchdog Timer #include avr/wdt.h #include avr/sleep.h #include MorseEncoder.h MorseEncoder morseLP(7); // 使用普通 IO 引脚 void enterSleep() { set_sleep_mode(SLEEP_MODE_PWR_DOWN); sleep_enable(); wdt_enable(WDTO_8S); // 8 秒唤醒 sleep_cpu(); sleep_disable(); wdt_disable(); } void setup() { morseLP.beginLight(15); // 配置 WDT 中断需修改 avr-libc } void loop() { // 每 8 秒唤醒一次发送 S morseLP.print(S); enterSleep(); }优势WDT 唤醒电流仅几微安整机平均功耗可降至 10 μA 以下一节 CR2032 电池可持续工作数月。5. 硬件连接与调试指南5.1 音频输出电路元件规格连接方式有源蜂鸣器5V, 3–5 kHzVCC → 5V, GND → GND, SIG → PWM 引脚如 D9压电片12 mm, 3–5 kHz正极 → PWM 引脚负极 → GND需串联 100 Ω 限流电阻无源蜂鸣器需外部驱动不推荐— MorseEncoder 未提供方波生成逻辑⚠️警告切勿将无源蜂鸣器直连 PWM 引脚其感性负载可能损坏 MCU IO。5.2 光信号电路元件规格连接方式备注普通 LED2 mA 1.8VLED 阳极 → 限流电阻220 Ω→ PWM 引脚阴极 → GND亮度随 WPM 自适应红外 LED940 nm, 100 mA阳极 → NPN 三极管如 2N2222集电极基极经 1 kΩ 电阻接引脚发射极 → GND用于隐蔽通信OLED 屏幕SSD1306不适用— MorseEncoder 无显示驱动逻辑需额外集成 U8g2 库5.3 调试技巧时序验证使用示波器探头接输出引脚测量点/划宽度是否符合T计算值字符错误定位在encodeChar()中添加Serial.print(c); Serial.print(-); Serial.println(morseTable[toupper(c)]);WPM 校准用手机秒表计时 1 分钟内发送的 “PARIS” 单词数调整beginAudio()参数直至匹配电源噪声抑制音频输出时若出现杂音在蜂鸣器两端并联 100 nF 陶瓷电容。6. 限制与演进方向6.1 当前限制无错误校验Morse 本身无 CRC 或奇偶校验长距离传输易受干扰单向通信仅支持发送不包含解码Decoder功能无自定义字符morseTable为静态数组无法运行时扩展无硬件加速全部软件延时WPM 30 时可能因delay()精度下降导致失真。6.2 社区演进建议Contributing Guide开发者可基于以下方向提交 PR添加MorseDecoder类使用pulseIn()读取输入引脚脉宽实现接收端解码支持PROGMEM字符串添加print_P(PSTR(SOS))重载节省 RAM集成HardwareTimerSTM32或LEDCESP32实现高精度非阻塞 PWM添加 Farnsworth 间距支持初学者模式字符内正常字间拉长增加setCallback(void (*cb)(char))在每个字符发送完毕时触发回调用于同步日志或指示灯。贡献流程Fork 仓库 → 创建特性分支 → 修改src/与examples/→ 更新README.md→ 提交 PR 并关联 Issue。7. 性能实测数据ATmega328P 16 MHzWPMT(ms)print(SOS)耗时RAM 占用Flash 占用101202.8 s128 B3.2 kB15801.9 s128 B3.2 kB20601.4 s128 B3.2 kB30400.95 s128 B3.2 kBRAM 占用恒定全部变量为栈分配无malloc()Flash 占用含完整 53 字符表与所有print()重载最大安全 WPM实测 35 WPMT34 ms仍稳定40 WPMT30 ms下delay(30)误差 1%可用。8. 结语Morse 在现代嵌入式系统中的不可替代性当 LoRa、NB-IoT 等无线协议以 Mbps 速率传输高清视频时Morse 依然在深海探测器、太空立方星、战地急救包中默默工作——因为它不需要协议栈、不依赖基站、不惧电磁脉冲、仅靠一节电池与一个 LED 即可传递“我在这里”。MorseEncoder 的价值正在于将这种历经百年考验的鲁棒通信方式以零学习成本的方式带入 Arduino 生态。它不是性能最强的库却是最接近“通信本质”的库用最简硬件表达最确定的信息。在调试一个 SPI 从设备失败的深夜打开 MorseEncoder 示例让 LED 以稳定的节奏闪烁 “READY”那一刻工程师会重新理解什么叫“可靠”。