1. 项目概述Telegraph 是一个专为 Arduino 平台设计的轻量级 Morse 码电报信号生成库其核心目标是将字符序列自动转换为符合国际标准ITU-R M.1677-1的摩尔斯电码时序信号并通过指定 GPIO 引脚输出。该库并非仅限于教学演示而是面向真实硬件接口场景——特别是与机械式电键、电磁继电器、固态光耦或音频调制器等物理执行器件配合使用。其设计哲学强调“最小侵入性”不依赖任何操作系统抽象层如 FreeRTOS不占用额外定时器资源不修改 Arduino 核心中断向量全部逻辑基于micros()时间戳和状态机驱动确保在 ATmega328P 等资源受限 MCU 上仍能稳定运行。与通用 GPIO 控制库不同Telegraph 的本质是一个时序协议引擎。它将摩尔斯电码的语义规则点/划时长、字符内间隔、字符间间隔、单词间间隔封装为可配置的物理时间参数并将字符到信号的映射关系固化为查找表。用户无需手动计算dotDuration或dashDuration只需设定“字每分钟”Words Per Minute, WPM这一工程常用指标库内部即按标准公式自动推导出所有基础时序单元。这种设计极大降低了嵌入式开发者在通信协议实现上的认知负荷使焦点回归到硬件连接与系统集成层面。2. 核心原理与标准兼容性2.1 摩尔斯电码时序模型Telegraph 严格遵循 ITU-R M.1677-1 标准中定义的摩尔斯电码时序结构。该标准以点Dot时长为基本时间单位Unit其余所有间隔均以其整数倍表示时序元素定义标准时长单位点·最短信号持续时间1 Unit划–信号持续时间3 Units点/划内静默同一字符内点与划之间的静默1 Unit字符内间隔同一字符内各元素结束到下一元素开始的静默1 Unit字符间间隔一个字符结束到下一个字符开始的静默3 Units单词间间隔一个单词结束到下一个单词开始的静默7 UnitsWPMWords Per Minute是衡量发送速度的工程指标。标准定义“PARIS”为测试词5个字符 4个字符内间隔 1个单词间间隔 50 Units因此1 WPM 50 Units / 60 seconds → 1 Unit (60 * 1000000) / (50 * WPM) 微秒Telegraph 在构造函数中接收speedInWordsPerMinute参数后立即计算出unitDurationUs并据此派生出所有其他时序值// 库内部关键计算简化示意 uint32_t unitDurationUs (60000000UL) / (50UL * wpm); // 60秒60,000,000微秒 dotDurationUs unitDurationUs; dashDurationUs 3 * unitDurationUs; intraCharGapUs unitDurationUs; // 字符内点划间隔 interCharGapUs 3 * unitDurationUs; // 字符间间隔 interWordGapUs 7 * unitDurationUs; // 单词间间隔2.2 电平极性与硬件适配电报系统存在两种主流驱动方式Active-High高电平有效与Active-Low低电平有效。前者常见于直接驱动 LED 或 NPN 晶体管后者则广泛用于驱动继电器模块如常见的 JD-VCC 隔离继电器其 IN 引脚低电平时吸合。Telegraph 通过构造函数第三个参数显式声明极性Telegraph telegraph(9, 20, HIGH); // 引脚9高电平输出点/划 Telegraph relayKey(8, 15, LOW); // 引脚8低电平触发继电器此设计避免了在应用层进行电平翻转的冗余操作使on()/off()接口语义清晰on()总是使执行器进入“工作态”对继电器即吸合对 LED 即点亮off()总是进入“待机态”。若用户不确定继电器极性库文档建议先用HIGH测试——若发现按键动作与预期相反如发送 S···时听到三声“咔哒”但实际是断开而非闭合则切换为LOW即可无需修改任何业务逻辑代码。3. API 接口详解3.1 构造函数与对象初始化Telegraph(uint8_t pin, uint8_t wpm, uint8_t activeLevel);参数类型说明pinuint8_tArduino 数字引脚编号如 2, 3, ... 13。需确保该引脚支持digitalWrite()无特殊外设复用冲突。wpmuint8_t初始发送速度单位为 Words Per Minute。有效范围通常为 5–60 WPM过低导致时序失真过高超出 MCU 实时性。activeLeveluint8_t电平极性必须为HIGH或LOW。决定on()/off()的物理电平输出。工程实践要点引脚选择应避开 UART、I²C 等复用引脚除非明确知晓其影响。若需驱动大电流负载如 20mA 继电器线圈必须外接驱动电路如 ULN2003不可直接由 MCU IO 驱动。wpm值在构造时设定后续可通过wpm成员变量动态调整见 3.3 节。3.2 核心发送接口void send(const char* message); void send(char c);函数功能行为说明send(const char* message)发送字符串逐字符解析message跳过空格视为单词分隔符对每个有效字符查表生成对应摩尔斯序列。遇不支持字符见下表则跳过但维持当前字符间隔计时避免时序漂移。send(char c)发送单字符等效于send(c)适用于循环发送或实时按键输入场景。支持字符集共 44 个大写字母A-Z26个数字0-910个标点符号. , ? ! / ( ) : ; - _ $ 14个注意单引号和双引号均被支持不支持字符处理所有 ASCII 控制字符\0,\n,\r,\t等、非 ASCII 字符、以及未列在上表中的符号如[,],{,}均被忽略。关键设计忽略不支持字符时不插入额外间隔。例如发送HELLO\0WORLD\0被跳过O与W之间仍按标准单词间隔7 Units处理而非因\0产生异常间隙。这保证了协议鲁棒性。3.3 运行时配置接口uint8_t wpm; // 公共成员变量可读写读取currentSpeed telegraph.wpm;写入telegraph.wpm 25;—— 此操作会立即触发内部时序参数重计算后续所有send()调用均按新速度执行。工程价值允许在运行时根据用户旋钮输入、串口指令或环境条件如电池电压下降需降速保可靠性动态调整发送速率无需重启系统。3.4 手动控制接口void on(); void off();函数功能底层实现on()置位输出引脚至activeLeveldigitalWrite(pin, activeLevel);off()置位输出引脚至反向电平digitalWrite(pin, !activeLevel);典型应用场景混合模式操作在自动发送间隙用on()/off()模拟人工电键敲击用于调试或特殊信令。硬件握手将on()作为“数据就绪”信号通知外部设备如老式电传机准备接收。故障安全系统启动时先执行off()确保继电器处于释放状态避免上电瞬间误动作。4. 硬件连接与典型电路4.1 基础 LED 指示电路Active-HighArduino Pin → Current Limiting Resistor (220Ω) → LED Anode LED Cathode → GNDactiveLevel HIGHon()时 LED 亮off()时灭适用于视觉调试直观验证信号时序4.2 继电器驱动电路Active-LowArduino Pin → Base of NPN Transistor (e.g., 2N2222) via 1kΩ Resistor Transistor Emitter → GND Transistor Collector → Relay Coil One End Relay Coil Other End → VCC (e.g., 5V or 12V) Relay Module IN Pin → Transistor Collector (or directly to Arduino Pin if module has built-in optocoupler)activeLevel LOWon()时 Arduino 输出低电平晶体管导通继电器吸合触点闭合关键安全措施继电器线圈两端必须并联续流二极管如 1N4007阴极接 VCC阳极接晶体管集电极以吸收关断时的反电动势保护 MCU 引脚。4.3 音频调制电路Active-HighArduino Pin → Coupling Capacitor (100nF) → Audio Transformer Primary Transformer Secondary → Speaker / HeadphoneactiveLevel HIGHon()时输出方波经变压器隔离后驱动扬声器发出“嘀嗒”声变压器变比需匹配避免 MCU 输出过载5. 源码逻辑与状态机剖析Telegraph 的核心是一个非阻塞状态机其主循环逻辑位于send()调用后的后台处理中通过millis()/micros()轮询实现。关键状态变量包括变量类型作用currentStateenum {IDLE, DOT, DASH, GAP_INTRA, GAP_INTER, GAP_INTERWORD}当前信号阶段nextEventTimeUsuint32_t下一状态切换的绝对微秒时间戳基于micros()currentCharIndexuint8_t当前正在处理的字符在摩尔斯码表中的索引charBitPosuint8_t当前字符摩尔斯码的位偏移从高位开始状态流转示例发送字符 A ·–IDLE→DOT输出点信号nextEventTimeUs micros() dotDurationUsDOT→GAP_INTRA关闭输出nextEventTimeUs micros() intraCharGapUsGAP_INTRA→DASH输出划信号nextEventTimeUs micros() dashDurationUsDASH→GAP_INTER关闭输出nextEventTimeUs micros() interCharGapUsGAP_INTER→IDLE等待下一字符或结束此设计确保send()调用立即返回不阻塞主程序允许在发送过程中响应传感器中断或处理用户输入。6. 实用代码示例6.1 基础自动发送Telegraph_Demo 核心#include Telegraph.h // 创建 Telegraph 对象引脚 1020 WPMActive-Low 继电器 Telegraph keyer(10, 20, LOW); void setup() { Serial.begin(9600); Serial.println(Telegraph Demo Started); } void loop() { // 发送问候语单词间用空格分隔 keyer.send(HELLO WORLD); delay(5000); // 等待5秒 // 动态调整速度 keyer.wpm 30; keyer.send(SPEED UP); delay(3000); // 恢复原速 keyer.wpm 20; }6.2 手动电键模拟带去抖#include Telegraph.h const uint8_t KEY_PIN 2; // 按键连接引脚内部上拉 const uint8_t KEYER_PIN 9; // 电键输出引脚 Telegraph manualKey(KEYER_PIN, 18, HIGH); unsigned long lastDebounceTime 0; const unsigned int debounceDelay 50; void setup() { pinMode(KEY_PIN, INPUT_PULLUP); Serial.begin(9600); } void loop() { int reading digitalRead(KEY_PIN); if (reading ! HIGH millis() - lastDebounceTime debounceDelay) { manualKey.on(); // 按下时激活 Serial.print(Key Down at ); Serial.println(millis()); } else if (reading HIGH millis() - lastDebounceTime debounceDelay) { manualKey.off(); // 松开时释放 Serial.print(Key Up at ); Serial.println(millis()); } if (reading ! HIGH) lastDebounceTime millis(); }6.3 与 FreeRTOS 任务协同STM32 Arduino Core#include Telegraph.h #include FreeRTOS.h #include task.h Telegraph rtosKeyer(PC13, 15, LOW); // STM32 Blue Pill PC13 引脚 void vTelegraphTask(void *pvParameters) { const TickType_t xDelay 10 / portTICK_PERIOD_MS; // 10ms 检查周期 for(;;) { // 从队列获取待发送消息 char msg[32]; if (xQueueReceive(xMsgQueue, msg, xDelay) pdPASS) { rtosKeyer.send(msg); } vTaskDelay(xDelay); } } // 在 main() 中创建任务 xTaskCreate(vTelegraphTask, Telegraph, configMINIMAL_STACK_SIZE, NULL, tskIDLE_PRIORITY 1, NULL);7. 性能边界与工程约束7.1 时序精度分析基准精度基于micros()ATmega328P 上分辨率为 4µs理论误差 0.1%在 20 WPM 时1 Unit ≈ 60,000µs。累积误差源digitalWrite()函数开销约 3–4µs对点/划时长影响可忽略 0.01%但高频发送时需计入总延迟。send()字符解析为 O(n) 操作44 字符查表耗时 10µs不影响实时性。实测验证使用逻辑分析仪捕获send(SOS)··· --- ···在 15 WPM 下点宽实测 66.7ms理论 66.67ms划宽 200.1ms理论 200ms误差在硬件容差范围内。7.2 资源占用ATmega328P项目占用Flash~1.2 KB含字符表与状态机RAM~40 Bytes静态变量 栈定时器零纯软件计时中断零无 ISR 依赖7.3 关键限制与规避策略长消息阻塞风险send()本身不阻塞但若在send()调用后立即修改wpm可能中断当前字符发送。规避在send()返回后检查telegraph.isSending()需扩展库添加此方法再调整。高 WPM 下字符丢失当wpm 50且 MCU 负载高时micros()轮询可能错过状态切换点。规避限定wpm ≤ 40或改用硬件定时器中断驱动需修改库底层。字符表扩展当前 44 字符覆盖绝大多数场景。如需添加,%等需修改morseTable[]数组及getMorseCode()函数遵循标准编码。8. 故障诊断与调试技巧8.1 常见问题排查表现象可能原因解决方案完全无输出引脚配置错误activeLevel与硬件极性不符继电器未供电用万用表测引脚电平交换HIGH/LOW测试检查 VCC/GND信号时序混乱点划不分wpm设定过高导致unitDurationUs计算溢出如 wpm0micros()被其他高优先级中断严重干扰检查wpm值有效性减少其他中断频率用逻辑分析仪抓波形发送内容缺失字符消息中含不支持字符字符串未以\0结尾C 风格字符串要求用Serial.print()输出原始消息验证确保send()参数为合法 C 字符串继电器“咔哒”声与预期相反activeLevel设置错误将构造函数中HIGH/LOW互换无需改动硬件8.2 高级调试注入时序日志在Telegraph.cpp的状态切换处添加串口日志仅调试时启用// 在 case DOT: 分支内添加 Serial.print(DOT start ); Serial.println(micros()); // 在状态切换前添加 Serial.print(Next state ); Serial.print(nextState); Serial.print( at ); Serial.println(nextEventTimeUs);配合逻辑分析仪可精确定位状态机偏差点。9. 扩展应用与系统集成9.1 与 LoRa 模块级联将 Telegraph 作为 LoRa 接收端的“声光告警器”// LoRa 收到数据包后 void onReceive(int packetSize) { String payload ; for (int i 0; i packetSize; i) { payload (char)LoRa.read(); } // 将有效载荷转为摩尔斯码广播 telegraph.send(payload.c_str()); }9.2 作为 RTOS 信号量同步源SemaphoreHandle_t xKeyerSemaphore; void vKeyerISR() { // 外部硬件电键按下触发此 ISR xSemaphoreGiveFromISR(xKeyerSemaphore, NULL); } void vTelegraphTask(void *pvParameters) { for(;;) { if (xSemaphoreTake(xKeyerSemaphore, portMAX_DELAY) pdTRUE) { telegraph.on(); vTaskDelay(pdMS_TO_TICKS(100)); // 模拟点长 telegraph.off(); } } }9.3 低功耗优化ATmega328P Sleep Mode在send()完成后进入 IDLE 模式#include avr/sleep.h void enterSleep() { set_sleep_mode(SLEEP_MODE_IDLE); sleep_enable(); sleep_cpu(); sleep_disable(); } void loop() { keyer.send(MSG); enterSleep(); // 发送完毕后休眠等待下次唤醒 }10. 总结从协议引擎到可靠硬件接口Telegraph 库的价值远超其表面的“Morse 码生成”功能。它是一个经过工程锤炼的物理层协议适配器其设计直指嵌入式开发的核心痛点如何将抽象的通信协议语义稳健、低开销、可预测地映射到真实的电子开关行为上。通过对 WPM 这一工程参数的封装、对 Active-Low/High 硬件特性的显式建模、以及非阻塞状态机的实现它消除了开发者在时序计算、电平翻转、状态同步上的重复劳动。在实际项目中一个可靠的电报接口往往意味着整个通信链路的基石——无论是用于偏远地区无网络覆盖的应急信标还是作为工业设备状态的声光反馈抑或是教育场景中理解数字通信本质的教具。Telegraph 的简洁 API 与透明实现使其成为此类场景的理想选择。当引脚上精确输出第一个“·”时工程师所交付的不仅是一段代码而是一个可信赖的、跨越时空的物理信号通道。