1. 项目概述runner是一个面向 Arduino 平台的轻量级命令行 shell 框架库其核心目标是为资源受限的嵌入式系统提供类 Unix 风格的交互式命令执行能力。它并非简单的串口字符串解析器而是一套具备完整命令注册、流式 I/O 重定向、事件驱动执行、管道与状态管理能力的嵌入式 shell 运行时环境。该库的设计哲学强调“以流为中心”stream-centric——所有输入、输出、错误通道均抽象为Stream接口从而天然兼容Serial、SoftwareSerial、Wire、SD、EEPROM等任意实现了Stream的硬件或软件外设驱动。在传统 Arduino 开发中调试与控制往往依赖硬编码的Serial.print()或手动轮询按键/传感器触发逻辑。runner将这一过程范式化开发者将功能封装为可注册的Command对象将外设抽象为可寻址的Stream对象再通过统一的Interface实例进行集中管理。最终用户可通过串口终端输入pm 13 OUTPUT、dw 13 1、free等命令实时操控硬件、查询系统状态、甚至构建多级数据处理流水线。这种设计显著提升了固件的可观测性、可调试性与现场可配置性尤其适用于工业现场调试、教育实验平台、IoT 设备远程维护等场景。1.1 系统架构runner采用分层模块化架构各组件职责清晰、耦合度低Interface全局命令与流注册中心。它是整个系统的“操作系统内核”负责维护所有已注册的Command和Stream实例的哈希映射表内部使用String键索引并提供add()、find()、trigger()等核心调度接口。Shell命令行解释器实例。每个Shell绑定一组输入/输出/错误流Stream in/out/err并提供run()方法从输入流中读取命令行、解析参数、调用Interface::run()执行并将结果写入对应流。Shell可独立创建多个实例分别绑定至不同物理通道如Serial用于调试SoftwareSerial用于 Modbus 通信。EntryT类型安全的注册项句柄。T为Command*或Stream*Entry封装了名称、类型标识及对底层对象的引用确保findT()调用时的编译期类型检查。Command命令抽象基类。所有具体命令如PinMode、FreeMemory均继承自此类必须实现run()方法。run()接收Interface* scope用于跨命令上下文访问、String args[]命令名参数数组、以及Stream in/out/errI/O 通道返回int8_t状态码0 表示成功。StreamI/O 抽象基类。Arduino 标准库中所有串口、文件、网络等设备均继承自Streamrunner直接复用此标准无需额外适配层。该架构支持运行时动态增删命令与流且允许多个Shell实例共享同一Interface实现“一套命令多路终端”的部署模式极大增强了系统的灵活性与可扩展性。2. 核心 API 详解2.1Interface类接口Interface是runner的中枢调度器其 API 设计遵循最小完备原则所有操作均围绕“注册-查找-执行”三元组展开。方法签名参数说明返回值作用void add(String name, Command* ptr)name: 命令别名如pmptr:Command派生类实例指针void将命令注册到全局表name作为后续run()或trigger()的键void add(String name, Stream* ptr)name: 流别名如serialptr:Stream派生类实例指针void将流注册到全局表供重定向,,或Shell构造时引用int8_t run(String cmd, Stream in, Stream out, Stream err)cmd: 命令名in/out/err: 执行时使用的 I/O 流0成功-1命令未找到-2执行失败在指定流上同步执行单条命令args从in中解析结果写入out/errvoid trigger(String cmd, Stream in, Stream out, Stream err)同run()void异步触发所有同名命令如setup、loop常用于事件驱动循环EntryT findT(String name)name: 注册项名称T为Command*或Stream*EntryT实例类型安全查找返回封装了名称、类型与指针的句柄ref()可获取原始指针关键实现细节add()内部使用String作为哈希键因此命令名区分大小写且需保证唯一性。重复注册同名项将覆盖前值。run()的参数解析逻辑位于Shell::run()中Interface::run()仅负责路由。args[]数组首元素args[0]固定为命令名后续为用户输入的空格分隔参数dw 13 1→args[0]dw, args[1]13, args[2]1。trigger()是runner事件模型的核心。runner::setup与runner::loop是预定义的事件名os.trigger(runner::setup)会执行所有注册名为setup的命令如初始化 GPIO、启动传感器os.trigger(runner::loop)则在主循环中周期性调用所有loop命令如读取传感器、发送心跳包。2.2Shell类接口Shell是命令行解释器的具体实现其设计聚焦于流式交互与重定向支持。方法签名参数说明返回值作用Shell(Stream in, Stream out, Stream err)构造时绑定 I/O 流默认SerialShell实例创建 Shell 实例in/out/err为默认通道int8_t run()无0成功-1输入流无数据-2解析失败从in读取一行命令解析后调用Interface::run()执行结果写入out/errvoid bind(String event loop)event: 触发事件名默认loopvoid将run()绑定至Interface::trigger(event)实现自动轮询执行void set(Stream in, Stream out, Stream err)新 I/O 流void动态切换 Shell 的默认 I/O 通道重定向机制Shell支持类 Unix 的重定向符号解析逻辑在run()内部完成 stream_name将stream_name指向的Stream作为本次命令的in参数覆盖默认in。 stream_name将stream_name指向的Stream作为本次命令的out参数覆盖默认out。 stream_name将stream_name指向的Stream作为本次命令的err参数覆盖默认err。| N创建大小为N字节的内存缓冲区作为前一命令的out与后一命令的in的管道echo hello |12 cat。例如cat serial i2c eeprom表示执行cat命令其输入来自i2c流标准输出写入serial流标准错误写入eeprom流。2.3EntryT类接口EntryT提供类型安全的注册项访问避免 C 风格强制类型转换带来的安全隐患。方法签名参数说明返回值作用String const* name无指向注册名的const String*获取注册项名称T ref()无T类型指针Command*或Stream*获取底层对象指针类型由模板参数T确保String type()无Command或Stream获取注册项类型字符串表示static bool verify(EntryBase* arg)arg: 基类指针true若arg是EntryT实例运行时类型校验用于泛型代码典型用法// 注册命令 os.add(pm, new runner::cmd::PinMode()); // 查找并安全调用 auto entry os.findrunner::Command*(pm); if (entry.verify(entry)) { auto cmd entry.ref(); // 编译期确保 cmd 是 Command* cmd-run(os, args, Serial, Serial, Serial); }3. 内置命令集与工程实践3.1 Arduino 硬件命令runner.ArduinoCommands.hpp该头文件将 Arduino 标准 API 封装为Command实现零成本抽象。所有命令均严格遵循Command::run()签名参数解析采用空格分割无复杂语法。命令别名参数格式示例底层调用工程要点PinModepmpin modepm 13 OUTPUTpinMode(13, OUTPUT)mode支持INPUT/OUTPUT/INPUT_PULLUP字符串映射DigitalWritedwpin valuedw 13 1digitalWrite(13, HIGH)value支持0/1或LOW/HIGHDigitalReaddrpindr 2digitalRead(2)返回值通过out.println()输出AnalogReadarpinar A0analogRead(A0)支持A0~A7符号常量AnalogWriteawpin valueaw 9 128analogWrite(9, 128)value范围0~255Tonetopin [frequency] [duration]to 8 1000 500tone(8, 1000, 500)frequency/duration为可选参数内存优化提示Tone命令在 ATmega328PArduino Uno上占用约 1.2KB Flash若内存紧张建议条件编译排除#ifdef USE_TONE_CMD ... #endif。3.2 工具命令runner.utils.hpp工具命令聚焦于系统诊断与数据流操作是调试与维护的核心。命令别名功能典型用法实现要点FreeMemoryfree打印当前可用堆内存freeMemory()free调用avr-libc的malloc.h函数结果以字节为单位输出Infoinfo列出所有已注册的Command与Stream名称及类型info遍历Interface内部注册表调用Entry::type()与Entry::nameStreamDumpdump对指定Stream执行十六进制转储dump sd逐字节读取Stream按00 01 02 ... FF格式输出每行 16 字节Echoecho回显所有参数echo hello worldout.print(args[1]); for(int i2; iargc; i) out.print( ); out.println(args[i]);Catcat读取并输出指定Stream全部内容cat eeprom循环stream.read()直至stream.available()0out.write()输出Statusstatus生成恢复当前系统状态的命令序列status eeprom遍历所有Command若其实现status()方法则调用并输出否则跳过Triggertrigger触发指定事件名的所有命令trigger setup封装Interface::trigger()调用使事件触发可从 shell 发起Flushflush调用指定Stream的flush()方法flush serialstream.flush()对Serial有效对File可能无效Shellsh在指定Stream上启动嵌套 shellsh sd创建新Shell实例set()指定流调用run()Status命令深度解析Status是runner状态持久化的关键。其工作流程为status命令遍历Interface中所有EntryCommand*对每个Entry调用Entry::ref()-status(name, out)仅当Command子类重写了virtual void status(const String, Stream) const时该方法才被调用status()方法应输出一条可直接执行的命令行如pm 13 OUTPUT用于重建当前状态。例如PinMode命令本身不保存状态故status不输出其信息但自定义的MyCmd若实现了status()则status命令会将其输出。这使得status eeprom与sh eeprom可构成完整的“配置保存-恢复”闭环。4. 自定义命令开发指南4.1 继承Command类推荐这是最灵活、功能最全的方式适用于需要状态保持、复杂逻辑或status()支持的命令。#include runner.hpp struct MySensorReader : public runner::Command { RUNNER_COMMAND(MySensorReader) // 必须宏生成 type() 实现 // 状态变量非静态每个实例独立 float lastReading 0.0; uint32_t readCount 0; int8_t run(runner::Interface* scope, String args[], Stream in, Stream out, Stream err) override { // 参数校验 if (args.length() 2) { err.println(Usage: sensor pin); return -1; } uint8_t pin args[1].toInt(); if (pin 23) { // ATmega2560 最大引脚 err.println(Invalid pin number); return -2; } // 读取模拟值并转换假设为温度传感器 int val analogRead(pin); lastReading (val * 5.0 / 1024.0) * 100.0; // 简单线性换算 readCount; // 输出结果 out.print(Sensor ); out.print(pin); out.print(: ); out.print(lastReading, 2); out.println( C); return 0; } // status() 方法输出恢复当前状态的命令 void status(const String name, Stream o) const override { // 此处可输出初始化命令如设置引脚模式 // o.println(name String(lastPin)); // 若有 lastPin 成员 } }; // 全局实例 MySensorReader sensorCmd;关键点RUNNER_COMMAND(MySensorReader)宏展开为String type() const override { return Command; }是Entry类型识别所必需。run()中args[0]是命令名sensorargs[1]及之后为用户参数。status()方法在Status命令调用时执行用于生成可重放的配置命令。4.2 使用FuncCommand快速原型适用于无状态、逻辑简单的函数封装避免类定义开销。#include runner.hpp // Lambda 方式 auto ledToggle new runner::FuncCommand( [](runner::Interface* scope, String args[], Stream in, Stream out, Stream err) - int8_t { static bool state false; uint8_t pin 13; if (args.length() 1) pin args[1].toInt(); state !state; digitalWrite(pin, state ? HIGH : LOW); out.print(LED ); out.print(pin); out.print( ); out.println(state ? ON : OFF); return 0; }, led // 命令名 ); // setup() 中注册 os.add(led, ledToggle);限制FuncCommand无法实现status()因其无成员变量故Status命令对其无输出。5. 高级应用流重定向与管道实战5.1 多外设协同工作流假设系统连接了SD卡SD.open(config.txt)返回File继承Stream与WireI2C 总线TwoWire继承Stream可构建如下工作流# 1. 将 I2C 设备寄存器内容转储到 SD 卡 dump i2c sd # 2. 从 SD 卡读取配置并写入 EEPROM假设 eeprom 是 EEPROMStream 实例 cat sd eeprom # 3. 读取 EEPROM 并通过串口输出调试 cat eeprom serial实现步骤在setup()中注册流#include SD.h #include Wire.h File configFile; if (SD.begin(4)) { configFile SD.open(config.txt, FILE_READ); if (configFile) os.add(sd, configFile); // 注意File 对象需全局声明 } os.add(i2c, Wire); // Wire 是全局 TwoWire 实例 os.add(eeprom, eepromStream); // 自定义 EEPROMStreamdump命令会从i2c流读取需Wire实现read()cat命令会将sd流内容写入eeprom流。5.2 管道数据处理利用|操作符构建内存缓冲管道实现数据过滤与转换# 1. 生成测试数据 echo Hello World from Arduino |16 tolower serial此命令要求tolower命令存在其run()方法需从in流读取最多 16 字节将每个字符转为小写写入out流。管道内存管理|16分配 16 字节栈空间runner不进行动态内存分配符合嵌入式实时性要求。缓冲区大小需根据命令处理能力谨慎选择过大易耗尽 RAM。6. 内存与性能考量runner在 ATmega328P2KB SRAM上的实测内存占用如下Arduino IDE 1.8.19-Os优化组件Flash 占用RAM 占用说明最小InterfaceShell~1.8KB~120B仅含核心调度逻辑全部 Arduino 命令3.2KB40BTone贡献最大 Flash全部 Utils 命令2.1KB80BStreamDump需 64B 栈缓冲总计Uno~7.1KB~240B接近 Flash 上限32KBRAM 安全优化策略按需包含仅#include所需命令头文件避免链接未使用代码。禁用冗余命令注释掉#include runner.ArduinoCommands.hpp手动添加必要命令。减少Shell实例单Shell足够多实例增加 RAM 开销。调整缓冲区Shell::run()默认读取 64 字节命令行可修改runner.hpp中SHELL_BUFFER_SIZE为 32。runner的设计严格遵循嵌入式约束无动态内存分配new仅在setup()中显式调用、无递归、栈使用可控、所有 API 为同步阻塞式确保在 FreeRTOS 或裸机环境下均可稳定运行。其价值不在于替代复杂操作系统而在于以极小代价赋予 Arduino “可交互、可诊断、可配置”的现代固件特性。