1. muwerk：面向资源受限嵌入式平台的协作式调度器与MQTT风格任务通信框架

muwerk 是一个专为微控制器设计的轻量级协作式调度器（cooperative scheduler），其核心目标是在从 ATtiny85（仅8KB Flash）到 ESP32、Linux 等全谱系嵌入式平台上，提供确定性、可预测且低开销的任务调度能力。它并非抢占式实时操作系统（RTOS），而是采用“协作”模型——每个任务在完成自身工作后主动让出CPU控制权，由调度器决定下一个执行的任务。这种设计极大降低了上下文切换开销与内存占用，使其能在仅有数百字节RAM的8位MCU上稳定运行，同时又具备在32位平台进行复杂系统集成的能力。

与传统裸机循环（ while(1) ）或简单状态机相比，muwerk 提供了结构化的任务生命周期管理、精确的时间间隔调度、以及一套抽象程度极高的任务间通信机制。该通信机制借鉴了MQTT协议的核心思想：基于主题（topic）的发布/订阅（pub/sub）模型。这意味着任务无需知道彼此的具体地址或存在，只需向一个逻辑主题发布消息，或订阅某个主题以接收相关通知。这种松耦合设计显著提升了固件的模块化程度与可维护性，是构建如传感器网络、IoT边缘节点、可组合功能单元（mupplets）等复杂系统的理想基础。

muwerk 的设计哲学强调“最小依赖”与“最大兼容”。它不依赖标准C库（libc）、POSIX API 或任何平台特定的HAL层，唯一外部依赖是 ustd —— 一个同样由同一作者开发的微型标准库（micro-stdlib）。ustd 提供了跨平台的 Queue （队列）、 Map （哈希映射）、 Array （动态数组）等基础容器类，其API设计精简，内存布局紧凑，所有操作均避免动态内存分配（ malloc/free ），全部使用静态或栈上内存，从根本上杜绝了内存碎片与分配失败的风险。这种“零堆依赖”的特性，是muwerk能在ATtiny等极端资源受限平台上可靠运行的根本保障。

1.1 系统架构与分层设计

muwerk 的整体架构遵循清晰的分层原则，各层职责分明，便于理解、调试与移植：

+-------------------------------+
| Apps / User Applications      | ← 用户编写的顶层应用逻辑
+-------------------------------+
| +-------------------------------+
| | Mupplets (Sensor Drivers, IO) | ← 可复用的功能模块，通过muwerk接口暴露服务
+-------------------------------+
| |                               |
| +------------+   +----------------+   +---------------------+
| | Testcode   |   | munet (ESPx)   |   | Console / Debug     |
| +------------+   +----------------+   +---------------------+
| |               |                  |                       |
+----------------------------------------------+
|                muwerk Scheduler              | ← 核心：协作调度 + MQTT-style IPC
+----------------------------------------------+
|                ustd Library                  | ← 基础：Queue, Map, Array, Platform Abstraction
+----------------------------------------------+
| +------------+ +------------+ +----------------+
| | Mac/Linux  | | Arduino SDK| | ESP8266/32 SDK |
| +------------+ +------------+ +----------------+
|    OS & Frameworks (for build & debug)        |
+-----------------------------------------------+

• Apps 层 ：用户直接编写的业务逻辑，例如一个环境监测应用，它会创建多个任务（温湿度采集、LED指示、网络上报）并协调它们。
• Mupplets 层 ：这是muwerk生态的关键创新。Mupplets 是封装了特定硬件驱动（如BME280传感器、OLED显示屏）或软件功能（如PID控制器、数据滤波器）的独立进程。它们通过muwerk的pub/sub接口对外提供服务，例如发布 /sensor/bme280/temperature 主题的数据，或订阅 /control/led/state 主题来响应开关指令。这使得不同开发者编写的模块可以像乐高积木一样即插即用。
• muwerk 核心层 ：包含两个核心子系统：
  • Scheduler ：负责任务的注册、时间片管理、执行调度与统计。
  • Pub/Sub IPC ：提供 publish() 和 subscribe() API，底层使用ustd::Queue实现消息队列，并支持主题匹配（wildcard）。
• ustd 底层 ：提供跨平台的、无堆内存依赖的基础数据结构与平台抽象（如 ustd::Serial , ustd::Timer ），是muwerk可移植性的基石。
• OS/Framework 层 ：muwerk本身不关心底层是Arduino Core、ESP-IDF还是Linux pthreads。它通过ustd提供的统一接口与之交互，因此可以在Mac/Linux上编译运行，用于配合GDB/Valgrind进行深度调试，极大提升了开发效率。

1.2 协作式调度原理与工程实践

协作式调度的本质是“信任”与“自律”。调度器不会强制中断一个正在运行的任务，它完全依赖于任务自身的合作行为。这带来了两大工程优势：一是极致的确定性，任务的执行时间窗口是可精确计算的；二是极低的系统开销，没有中断服务程序（ISR）抢占、没有复杂的寄存器压栈/出栈、没有任务控制块（TCB）的动态管理。

在muwerk中，一个任务被定义为一个无参数、无返回值的C++函数：

void myTask() {
    // 任务主体逻辑
    // ... 执行传感器读取、数据处理、IO操作等 ...
    
    // 关键：任务必须在此处主动让出控制权
    // muwerk调度器会在所有已注册任务轮询完毕后，再次调用此函数
}

调度器的主循环（通常置于Arduino的 loop() 函数中）极其简洁：

void loop() {
    sched.loop(); // 这是整个muwerk调度器的“心脏”
}

sched.loop() 的内部执行流程如下：

1. 时间检查 ：查询底层定时器（由ustd::Timer提供），判断是否有任务到达其预定的执行周期。
2. 任务分发 ：对于所有已到期的任务，按注册顺序依次调用其函数指针。
3. 状态更新 ：更新每个任务的执行计数、耗时统计等信息。
4. 空闲处理 ：若当前无任务到期，调度器可选择进入低功耗模式（需平台支持）或执行空闲回调。

这种模型对任务编写者提出了明确要求： 任何可能造成长时间阻塞的操作都必须被拆解或异步化 。例如，一个需要100ms延时的任务，绝不能写 delay(100) ，因为这会阻塞整个调度器。正确的做法是：

• 使用muwerk的 add() 函数注册一个周期为100ms的任务；
• 或者，在任务内部使用ustd::Timer进行非阻塞计时，将长操作分解为多个短步骤，在每次 loop() 中只执行一小部分。

这种约束看似严苛，实则是嵌入式系统健壮性的基石。它迫使开发者思考并发与时间，避免了因一个任务卡死而导致整个系统瘫痪的灾难性故障。

2. 核心API详解与实战配置

muwerk的API设计秉承“少即是多”（Less is More）的原则，核心接口数量极少，但每个接口都经过深思熟虑，覆盖了绝大多数嵌入式场景。

2.1 任务调度API

int add(TaskFunction task, const char* name, uint32_t interval_us)

这是创建周期性任务的唯一入口。其参数含义如下表所示：

参数	类型	说明
task	typedef void (*TaskFunction)()	指向任务函数的函数指针。该函数必须是 void func(void) 签名。
name	const char*	任务的字符串标识符，用于统计、调试和日志。长度建议不超过16字节。
interval_us	uint32_t	任务的执行周期，单位为微秒（µs）。这是调度器启动后，该任务被调用的固定时间间隔。

关键工程细节 ：

• 最小周期限制 ：不同平台的最小可行周期差异巨大。ESP8266约为50µs，而ATtiny85可能高达数毫秒。这取决于底层定时器的分辨率与调度器本身的执行开销。在实际项目中，应通过 $SYS/stat 统计信息验证任务是否能按预期频率执行。
• 任务ID（tID） ：函数返回一个整型ID，它是该任务在调度器内部的唯一索引。此ID可用于后续的统计查询或（在高级用法中）任务控制。
• 静态函数限制（ATtiny） ：在ATtiny等超低资源平台，由于ustd::function<>的实现限制， task 参数必须是一个 static 函数，不能是lambda或成员函数。

典型配置示例 ：

// 在全局作用域定义任务
static void sensorReadTask() {
    int temp = readTemperature();
    publish("/sensor/temp", String(temp).c_str()); // 发布到MQTT主题
}

static void ledBlinkTask() {
    static bool state = false;
    digitalWrite(LED_PIN, state ? HIGH : LOW);
    state = !state;
}

// 在setup()中注册
void setup() {
    // 注册一个每1000ms（1秒）执行一次的传感器任务
    int sensorID = sched.add(sensorReadTask, "sensor", 1000000L);
    
    // 注册一个每500ms（0.5秒）执行一次的LED闪烁任务
    int ledID = sched.add(ledBlinkTask, "led", 500000L);
}

void loop()

这是调度器的执行入口， 必须 被置于主循环中。它的实现逻辑决定了整个系统的实时性表现。

// 调度器内部伪代码
void Scheduler::loop() {
    uint32_t now = timer.micros(); // 获取当前微秒时间戳
    
    for (int i = 0; i < taskCount; i++) {
        Task& t = tasks[i];
        // 检查是否到达下次执行时间
        if (now >= t.nextExecTime) {
            // 更新下次执行时间（保持周期性）
            t.nextExecTime += t.interval_us;
            
            // 记录执行开始时间，用于统计
            uint32_t start = timer.micros();
            
            // 执行任务函数
            t.func();
            
            // 记录执行结束时间，计算耗时
            uint32_t end = timer.micros();
            t.lastExecTime = end - start;
            t.totalExecTime += t.lastExecTime;
            t.execCount++;
        }
    }
}

2.2 MQTT风格通信API

muwerk的IPC机制是其区别于其他轻量级调度器的最大亮点。它将复杂的任务间通信抽象为简单的 publish / subscribe 操作，极大地简化了系统集成。

bool publish(const char* topic, const char* payload, size_t len = 0)

向指定主题发布一条消息。 payload 可以是任意二进制数据， len 为其长度。若 len 为0，则 payload 被视为以 \0 结尾的C字符串。

bool subscribe(const char* topic, MessageHandler handler)

订阅一个主题，并注册一个回调函数 handler 。当有消息发布到该主题（或其匹配的主题）时， handler 将被调用。

MessageHandler 的函数签名定义为：

typedef void (*MessageHandler)(const char* topic, const char* payload, size_t len);

主题匹配规则 ： muwerk支持两级通配符，与MQTT v3.1.1规范一致：

• + 匹配单个层级。例如， /sensor/+/temperature 匹配 /sensor/bme280/temperature 和 /sensor/dht22/temperature 。
• # 匹配多层级。例如， /sensor/# 匹配 /sensor/bme280/temperature 、 /sensor/dht22/humidity 以及 /sensor/any/nested/path 。

工程化配置要点 ：

• 内存安全 ： publish() 和 subscribe() 的 topic 和 payload 指针在调用时必须有效。muwerk内部会进行浅拷贝（仅复制指针），因此调用者必须确保这些数据在消息被消费前不会被释放。对于动态生成的payload，推荐使用 ustd::String 或静态缓冲区。
• 线程安全 ：在协作式调度下， publish() 和 subscribe() 本身是线程安全的，因为它们只操作内部队列，而队列的读写发生在同一个上下文（ sched.loop() ）中。但在与硬件中断（如UART RX ISR）交互时，需额外同步。

完整通信示例 ：

// 定义一个处理接收到的控制命令的回调
void onControlCommand(const char* topic, const char* payload, size_t len) {
    if (len == 2 && strncmp(payload, "ON", 2) == 0) {
        digitalWrite(RELAY_PIN, HIGH);
    } else if (len == 3 && strncmp(payload, "OFF", 3) == 0) {
        digitalWrite(RELAY_PIN, LOW);
    }
}

void setup() {
    // 订阅控制主题
    sched.subscribe("/control/relay", onControlCommand);
    
    // 启动一个任务，定期发布状态
    sched.add([]() {
        static int counter = 0;
        String status = "UP:" + String(counter++);
        publish("/status/system", status.c_str());
    }, "status", 5000000L); // 每5秒发布一次
}

3. 系统监控与调试： $SYS/stat 统计机制深度解析

在嵌入式系统开发中，“看不见的bug”往往比“崩溃的bug”更难排查。muwerk内置的 $SYS/stat 统计机制，正是为了解决这一痛点而生。它将原本需要连接JTAG/SWD调试器、设置断点、单步跟踪才能获取的系统运行时信息，转化为一条条可通过串口或MQTT轻松获取的JSON消息，实现了“可观测性即服务”。

3.1 统计信息的触发与格式

统计信息的发布是 按需触发 的，而非持续广播，这避免了对带宽和CPU的无谓消耗。其触发方式是向主题 $SYS/stat/get 发布一条消息，其负载（payload）为一个十进制数字字符串，代表统计采样周期（毫秒）。

// 在setup()中，向统计服务发送请求
publish("$SYS/stat/get", "1000"); // 请求每1000ms（1秒）发布一次统计

一旦触发，调度器将开始周期性地向 $SYS/stat 主题发布JSON格式的统计对象。其字段含义如下表所示：

字段	类型	含义	工程价值
dt	integer	自上次统计样本以来的微秒数（delta time）。	验证采样周期是否准确，诊断系统是否过载。
syt	integer	操作系统（OS）所占用的微秒数。在muwerk中，此值通常为0，因为muwerk自身就是调度器。	为未来扩展预留，区分内核与应用开销。
apt	integer	muwerk任务（application tasks）所占用的总微秒数。	核心指标 ：反映所有用户任务的总CPU消耗。若 apt 持续接近 dt ，说明CPU已饱和，需优化任务或增加周期。
mat	integer	muwerk调度器自身（housekeeping）所占用的微秒数。	核心指标 ：反映调度器开销。正常值应远小于 apt （<1%）。若异常升高，可能表明任务注册过多或统计功能本身被滥用。
upt	integer	系统总运行时间（uptime），单位为秒。	用于计算长期稳定性、平均无故障时间（MTBF）。
mem	integer	当前可用的自由内存（free memory），单位为字节。	关键指标 ：在无MMU的MCU上，此值是 INT_MAX （2147483647），表示未启用内存统计；在Linux/macOS上，它返回 sysconf(_SC_AVPHYS_PAGES) 的真实值。用于预警内存泄漏。
tsks	integer	当前注册的muwerk任务总数。	快速确认任务注册是否成功，排查任务丢失问题。
tdt	array of arrays	任务详情数组。每个子数组包含： [task-name, tid, sched_time, exec_count, avg_exec_time, late_count] 。	最精细的诊断数据 ：可定位哪个任务耗时最长、是否频繁延迟（ late_count >0表示该任务多次未能按时执行，是系统过载的直接证据）。

3.2 统计数据的实战解读与故障诊断

让我们结合一个真实的统计样本进行深度分析：

{
  "dt": 500001,
  "syt": 0,
  "apt": 347452,
  "mat": 10,
  "upt": 2,
  "mem": 2147483647,
  "tsks": 2,
  "tdt": [
    ["task1", 1, 50000, 10, 99240, 7],
    ["task2", 2, 75000, 7, 34937, 0]
  ]
}

• 宏观健康度评估 ：

  • dt ≈ 500ms，符合预期（我们请求了500ms采样）。
  • apt (347452 µs) / dt (500001 µs) ≈ 69.5%，说明CPU约70%的时间在执行用户任务，30%空闲，系统负载健康。
  • mat 仅为10µs，证明调度器开销微乎其微。

• 微观任务剖析 ：

  • task1 ( tid=1 )：周期50ms ( sched_time=50000 )，在500ms内应执行10次（ 500/50=10 ）， exec_count=10 ，完美匹配。其平均执行时间为99240µs（≈9.9ms），远超其50ms的周期！这是一个 严重警告 ： task1 的执行时间（9.9ms）已经占据了其周期（50ms）的近20%。虽然当前还能勉强跟上，但如果 task1 的执行时间再增长1ms，它就会开始“迟到”， late_count 将从0变为正数。
  • task2 ( tid=2 )：周期75ms，执行7次（ 500/75≈6.66 ，向下取整为6，但此处为7，说明有1次是上一周期的“余量”），平均执行时间34937µs（≈35ms），占其周期的46.7%，压力较大但尚可接受。

故障诊断结论 ： task1 是系统的瓶颈。必须对其进行重构：

• 将其9.9ms的长操作（如 delay(10) ）替换为非阻塞的、分步执行的逻辑。
• 或者，将其拆分为多个更小的、周期更长的任务。
• 或者，降低其执行优先级（在muwerk中，通过调整注册顺序实现，先注册的先执行）。

3.3 调试利器：Console类与mutop工具

除了 $SYS/stat ，muwerk还提供了 ustd::Console 类，它是一个可扩展的串口命令行界面（CLI），是现场调试的终极武器。

Console 类允许你将一个 HardwareSerial 实例绑定到muwerk，并注册自定义命令。例如， mu_console 示例中包含了 list_tasks 、 publish 、 subscribe 等内置命令，你可以通过串口输入 list_tasks 来实时查看所有注册任务的状态。

更强大的是 mutop 工具。这是一个运行在PC端的Python脚本，它连接到MQTT Broker，订阅 $SYS/stat 主题，并将接收到的JSON数据解析、格式化为一个类似Linux top 命令的实时终端界面。它能动态显示每个任务的CPU占用率、执行延迟、内存使用趋势等，是进行系统性能调优不可或缺的伙伴。

4. 生态协同：munet、mupplets与ustd的无缝集成

muwerk的强大，不仅在于其自身，更在于它作为“粘合剂”，将整个 ustd 生态中的各个组件有机地连接在一起，形成一个高度可组合、可复用的嵌入式软件栈。

4.1 munet：网络能力的透明桥接

munet 是专为ESP8266/ESP32设计的网络模块，它实现了Wi-Fi连接、NTP时间同步、OTA固件升级和MQTT客户端等功能。muwerk与munet的集成是“零感知”的：muwerk的 publish() 和 subscribe() 调用，会自动被munet捕获，并通过其内部的 PubSubClient 库转发到远程MQTT Broker；反之，从Broker接收到的消息，也会被munet自动路由回muwerk的内部pub/sub总线。

这种设计意味着：

• 你的 sensorReadTask 无需关心网络细节，它只管向 /sensor/temp 发布数据。
• 你的 onControlCommand 回调也无需关心消息是来自本地另一个任务，还是来自千里之外的手机App。
• 整个系统的网络拓扑对应用层完全透明，极大降低了网络编程的复杂度。

4.2 mupplets：功能模块的标准化封装

mupplets 是muwerk生态的“应用商店”。一个典型的mupplet，例如 mupplet-sensor-bme280 ，其代码结构如下：

class BME280Mupplet {
public:
    BME280Mupplet(uwk::Scheduler& s) : sched(s) {
        // 在构造函数中注册任务和订阅
        sched.add([this]() { this->readAndPublish(); }, "bme280", 2000000L); // 每2秒读取
        sched.subscribe("/control/bme280", [this](...) { this->handleControl(...); });
    }

private:
    void readAndPublish() {
        float temp = bme.readTemperature();
        publish("/sensor/bme280/temperature", String(temp).c_str());
        // 同时发布湿度、气压...
    }
};

用户只需在 setup() 中创建一个 BME280Mupplet 实例，并传入 sched 引用，该传感器的所有功能（采集、发布、响应控制）便自动激活。这彻底改变了嵌入式开发的范式：开发者不再是从零开始写驱动，而是像搭积木一样，将一个个经过充分测试的 mupplet 组合起来，快速构建出复杂的应用。

4.3 ustd：跨平台的坚实基石

最后，一切的可移植性都归功于 ustd 。它通过一系列精巧的预处理器宏（如 __AVR__ , __ESP32__ , __linux__ ）和模板特化，为不同平台提供了统一的API。例如， ustd::Timer 在AVR上可能基于 millis() ，在ESP32上基于 esp_timer_get_time() ，在Linux上则基于 clock_gettime(CLOCK_MONOTONIC, ...) 。对muwerk而言，它只调用 timer.micros() ，完全无需关心底层实现。

这种“一次编写，处处编译”的能力，使得muwerk的代码可以在ATtiny85上进行功能验证，在ESP32上进行性能压测，并在Mac上利用Valgrind进行内存泄漏分析，真正实现了嵌入式开发的现代化流水线。

5. 工程化部署与最佳实践

将muwerk引入一个真实项目，远不止于 #include "scheduler.h" 。以下是一套经过实践检验的工程化部署指南。

5.1 内存规划与静态分配

muwerk默认使用静态内存池。在 Scheduler 类的构造中，它会预先分配一个固定大小的 Task 数组（默认大小为16）。这个值必须在编译时确定，因为它关系到 .bss 段的大小。

最佳实践 ：

• 在 platform.h 中，根据项目需求定义 MUWERK_TASK_COUNT 。例如，一个中等复杂度的ESP32项目，可设为32。
• 对于ATtiny项目，应严格控制在4-8之间，并在 setup() 中通过 if (sched.taskCount() >= MUWERK_TASK_COUNT) { /* error */ } 进行运行时校验。
• 所有任务函数、回调函数、以及 publish() 的 payload ，都应尽可能使用 static 变量或全局缓冲区，避免在栈上分配大数组。

5.2 中断与实时性保障

muwerk本身不管理硬件中断，但它与中断的交互至关重要。

黄金法则 ：

• 禁止在ISR中调用 publish() 或 subscribe() 。这些API会操作内部队列，不是原子操作。
• 正确做法 ：在ISR中，仅设置一个 volatile 标志位或向一个 ustd::Queue （其 push() 是原子的）放入一个轻量级事件（如 enum Event {TEMP_READY, BUTTON_PRESSED} ）。然后，在一个muwerk任务中轮询该队列，并执行相应的 publish() 操作。

// 在ISR中（例如，ADC转换完成中断）
volatile bool adcReady = false;
void IRAM_ATTR onAdcComplete() {
    adcReady = true;
}

// 在muwerk任务中
void adcTask() {
    if (adcReady) {
        adcReady = false;
        int value = analogRead(A0);
        publish("/adc/value", String(value).c_str());
    }
}

5.3 版本演进与向后兼容

muwerk的版本历史（如0.6.x系列）清晰地展示了其演进路径：从最初的纯调度器，到加入 $SYS/stat ，再到引入 Console 、 munet 集成、 mupplets 概念。每一次重大更新都伴随着 ustd 库的同步升级（如0.6.0的头文件重命名）。

工程建议 ：

• 在 platformio.ini 或 library.properties 中，严格锁定 muwerk 和 ustd 的版本号，避免因自动更新导致的编译失败。
• 利用GitHub Actions CI，为所有目标平台（ATmega328P, ESP32, Linux）配置自动化构建与测试，确保每次提交都不会破坏现有功能。

muwerk的最终形态，不是一个孤立的调度器，而是一个以协作式调度为核心、以MQTT风格通信为纽带、以 ustd 为基石、以 munet 和 mupplets 为羽翼的完整嵌入式软件生态系统。它代表了一种新的嵌入式开发范式：通过高度抽象的、声明式的API，让开发者能够专注于业务逻辑本身，而将底层的并发、通信、网络等复杂性，交由经过千锤百炼的、轻量级的、开源的基础设施来处理。