1. 为什么要在 Wokwi 上跑 FreeRTOS 多传感器房间监测

手头没有开发板，或者板子还在快递路上，但又想先把 FreeRTOS 的多任务框架跑通——这是我最近折腾这个项目最直接的动机。STM32 加 FreeRTOS 的组合在嵌入式圈子里早就不是新鲜事，但真正让这套方案变得"零门槛"的，是 Wokwi 这个在线仿真平台。它把 STM32 芯片、传感器外设、串口终端全部搬到了浏览器里，你不需要装 Keil、不需要连 ST-Link、不需要担心烧录把芯片锁了，打开网页就能跑代码。

这个项目的核心目标很明确：用 STM32 作为主控，在 FreeRTOS 上创建多个任务，分别采集温度、湿度、光照、距离这几类房间环境数据，再通过串口把结果输出出来。听起来简单，但它几乎覆盖了 FreeRTOS 入门阶段所有关键知识点——任务创建、优先级分配、队列通信、互斥锁保护共享资源、堆栈大小估算、软件定时器。你把这套东西吃透，后面做任何基于 STM32 的毕业设计或者智能家居小项目，骨架都是现成的。

适合谁来参考？如果你刚学完 FreeRTOS 的任务创建 API，但不知道真实项目里任务该怎么划分；或者你手上有 STM32 但懒得搭硬件，想先在仿真里验证逻辑；再或者你在做基于 STM32 的课程设计，需要一个能直接跑起来的多传感器框架——这篇内容都能给你省下不少试错时间。我踩过的坑、调过的参数、以及 Wokwi 上那些文档里没写的限制，下面都会一条条讲清楚。

2. Wokwi 仿真环境的真实能力边界

2.1 它到底能仿真什么，不能仿真什么

很多人第一次用 Wokwi 会有一个误解，以为它是个"万能仿真器"。实际上它的定位是"逻辑验证级仿真"，不是"时序精确级仿真"。这句话什么意思？就是说它能正确模拟 GPIO 电平变化、I2C 通信协议、UART 数据收发、定时器中断这些逻辑行为，但它不会去模拟真实的电压跌落、信号抖动、电磁干扰。对于 FreeRTOS 任务调度这种偏软件逻辑的验证，它完全够用；但如果你想验证 ADC 采样的精度或者电源纹波对系统的影响，那还是得上真实硬件。

具体到我们这个项目，Wokwi 支持的 STM32 型号主要是 STM32F103 系列（C8T6 那款蓝色小板子的仿真），传感器方面它内置了 DHT22 温湿度传感器、HC-SR04 超声波测距模块、光敏电阻（LDR）配合 ADC 的模型，还有 SSD1306 OLED 显示屏。这些正好覆盖了"房间监测"需要的数据类型。你不需要额外找库，Wokwi 的元件库里直接拖出来就能用。

但有几个限制必须提前知道。第一，Wokwi 的仿真速度不是实时的，它跑的是"逻辑时间"，你设一个 1000ms 的延时，仿真里可能几毫秒就跳过去了，所以你不能用它来测"任务实际执行耗时"。第二，它的中断响应延迟是理想化的，不会出现真实硬件上那种中断嵌套导致的抖动。第三，串口输出的波特率在仿真里不影响实际速度，你设 115200 和 9600 在仿真里看起来一样快，但真实硬件上这个参数很关键。

2.2 为什么选 Wokwi 而不是 Proteus

这个问题我被问过很多次。Proteus 确实功能更强大，能仿真模拟电路、能做 PCB 联调，但它的 STM32 仿真配置极其繁琐——你要手动加载 hex 文件、配置时钟树、有时候还要处理元件库版本不匹配的问题。Wokwi 的优势在于"开箱即用"：你在网页上画好电路图，代码编译好直接就能跑，串口终端就在旁边，改一行代码刷新一下就能看到结果。对于 FreeRTOS 这种需要反复调整任务优先级和堆栈大小的场景，Wokwi 的迭代速度比 Proteus 快一个数量级。

另外 Wokwi 支持直接导入 Arduino 框架或者裸机 STM32 代码，它底层用的是 QEMU 的 STM32 模拟，所以你的 HAL 库调用基本都能正常工作。我实测下来，标准外设库和 HAL 库在 Wokwi 上跑 FreeRTOS 都没问题，但要注意它默认的时钟配置可能和你的代码不一致，这个后面会细说。

2.3 环境搭建中最容易忽略的三个细节

第一个细节是时钟树配置。Wokwi 的 STM32F103 默认外部晶振是 8MHz，但如果你在代码里用SystemClock_Config()配置成 72MHz 主频，仿真里不会报错，但某些定时器相关的延时函数可能会表现异常。我的建议是在 Wokwi 里先把主频设成 72MHz 标准配置，和真实硬件保持一致，这样代码移植回去不用改。

第二个细节是串口引脚映射。Wokwi 的 STM32 仿真里，USART1 默认映射到 PA9（TX）和 PA10（RX），这个和真实硬件一致。但如果你在代码里重映射到其他引脚，仿真里可能收不到数据。我一开始想把串口挪到 PB6/PB7 方便布线，结果折腾了半天发现 Wokwi 对重映射的支持不完整，最后还是老老实实用 PA9/PA10。

第三个细节是FreeRTOS 的堆空间。Wokwi 仿真的 STM32F103C8T6 只有 20KB RAM，这个和真实芯片一样。FreeRTOS 的configTOTAL_HEAP_SIZE如果设得太大，编译能过但运行时会直接卡死。我建议从 10KB 开始试，创建四五个任务加两个队列，10KB 是够的。如果你还要加 OLED 显示缓冲，那得再压缩到 8KB 左右。

3. 多传感器任务划分与优先级设计

3.1 为什么不能把所有传感器读一遍再统一处理

新手最容易犯的错误，就是写一个超级循环：读温度、读湿度、读光照、读距离、然后延时一秒，循环往复。这在裸机编程里没问题，但在 FreeRTOS 项目里就是浪费了 RTOS 的核心价值。RTOS 的意义在于让不同实时性要求的事情并行处理——温度变化慢，一秒读一次足够；距离检测需要快速响应，可能 100ms 就要更新一次；串口输出不能阻塞传感器采集，否则你读 DHT22 那 2 秒的转换时间里，超声波数据就全丢了。

所以正确的做法是按"数据更新频率"和"实时性要求"来划分任务。我的方案是四个采集任务加一个输出任务：

这里有个细节：DHT22 的温度和湿度其实是同一次通信读出来的，分成两个任务反而要读两次，效率低。但为了演示"多任务独立采集"这个模式，我故意拆开了。实际项目中你应该合并成一个 DHT22Task，用队列把温湿度一起发出去。

3.2 优先级分配背后的逻辑

距离检测任务优先级最高（3），因为它对实时性最敏感。HC-SR04 的工作原理是发一个 10us 的触发脉冲，然后等回波高电平，高电平持续时间就是距离。如果你在等回波的时候被其他任务抢占，测量结果就会偏大。虽然 FreeRTOS 的抢占式调度不会让高优先级任务等太久，但为了保险，距离任务还是给最高优先级。

温度湿度任务优先级中等（2），因为 DHT22 的转换时间长达 2 秒，这期间任务会调用vTaskDelay让出 CPU，不会阻塞其他任务。光照任务优先级最低（1），因为光照变化最慢，而且光敏电阻的 ADC 读取本身就有噪声，读太快也没意义。

打印任务优先级也是 1，但它是事件驱动的——只有收到队列消息才执行。这里有个坑：如果打印任务优先级太低，队列满了它还没被调度，数据就会丢。所以我在队列满的时候做了丢弃最旧数据的处理，而不是死等。

3.3 队列通信的设计与容量估算

四个采集任务和打印任务之间用队列通信。我用了两个队列：一个xSensorQueue用来传传感器数据，一个xPrintQueue用来传格式化后的字符串。为什么不直接用一个？因为传感器数据的结构体和字符串的生命周期管理不一样，分开更清晰。

xSensorQueue的容量我设的是 10。为什么是 10？因为最坏情况下，距离任务 100ms 发一次，打印任务如果被阻塞了 1 秒，那队列里会积压 10 条距离数据。超过 10 条就说明打印任务出问题了，这时候丢弃新数据比无限积压更安全。队列项的大小是sizeof(SensorMsg_t)，这个结构体我定义成：

typedef struct { uint8_t type; // 0=温度, 1=湿度, 2=光照, 3=距离 float value; uint32_t timestamp; } SensorMsg_t;

算一下大小：1 字节类型 + 4 字节浮点 + 4 字节时间戳，加上对齐填充大概是 12 字节。10 个项就是 120 字节，对 20KB RAM 来说完全没压力。

xPrintQueue的容量设的是 5，每项是一个 64 字节的字符串。为什么是 64？因为串口输出一行类似[1234ms] Temp: 25.6C这样的内容，加上结束符不会超过 64 字节。5 个项就是 320 字节，也还好。

注意：队列项的大小在创建队列时就固定了，你传大结构体进去，FreeRTOS 会按值拷贝。如果结构体超过 16 字节，建议传指针而不是传值，否则拷贝开销会很明显。我这里 12 字节还能接受，再大就该用指针加内存池了。

4. DHT22 与 HC-SR04 在仿真里的驱动写法

4.1 DHT22 的单总线时序怎么在 Wokwi 里跑通

DHT22 用的是单总线协议，一根数据线完成双向通信。它的时序要求比较严格：主机拉低至少 1ms 作为起始信号，然后释放，DHT22 会拉低 80us 再拉高 80us 作为响应，接着连续输出 40 位数据，每位以 50us 低电平开始，高电平持续时间决定是 0 还是 1（26-28us 是 0，70us 是 1）。

在真实硬件上，这段代码通常要用微秒级延时加关中断来保证时序。但在 Wokwi 里，因为仿真时间不是实时的，你用HAL_Delay或者vTaskDelay反而会出问题——仿真的时间粒度和真实微秒延时对不上。我的做法是用一个简单的delay_us函数，基于SysTick或者DWT计数器做忙等待。Wokwi 对 DWT 的支持还行，但更稳妥的是用空循环做粗略延时，然后在仿真里微调循环次数。

具体代码逻辑是这样的：先把数据引脚设成推挽输出，拉低 1ms 以上，然后设成浮空输入，等待 DHT22 的响应。这里有个关键点——Wokwi 的 DHT22 模型响应很快，你不需要等太久，但也不能不等。我实测下来，拉低 2ms 再释放，然后轮询引脚电平变化，能稳定读到数据。

读 40 位数据的时候，每一位都要先等低电平结束，再等多久来判断 0 或 1。Wokwi 里这个时间比例是准确的，所以你可以用一个计数器：高电平期间循环计数，如果计数值超过某个阈值就是 1，否则是 0。这个阈值需要在仿真里试出来，我用的值是 40 左右（基于空循环计数）。

4.2 HC-SR04 的触发与回波捕获

HC-SR04 的逻辑比 DHT22 简单：Trig 引脚给一个 10us 以上的高电平脉冲，然后 Echo 引脚会输出一个高电平，高电平持续时间就是声波往返时间。距离计算公式是距离(cm) = 高电平时间(us) / 58。

在 FreeRTOS 任务里做这件事，有两种方案。方案一是用vTaskDelay做粗略延时，然后轮询 Echo 引脚，用esp_timer_get_time类似的微秒计时函数记录高电平持续时间。方案二是用输入捕获定时器，让硬件自动测量脉宽。Wokwi 对 STM32 定时器输入捕获的支持还可以，但配置起来比较麻烦，我建议先用轮询方案跑通逻辑，后面再优化。

轮询方案的具体步骤：Trig 拉高，延时 10us，Trig 拉低。然后在一个循环里等 Echo 变高，记录起始时间；再等 Echo 变低，记录结束时间。两个时间差就是脉宽。这里要注意加超时保护——如果 Echo 一直不变低，说明传感器坏了或者没接好，任务不能死等，要设一个最大等待时间（比如 30ms），超时就返回错误值。

提示：Wokwi 的 HC-SR04 模型在触发后大约 1ms 内就会返回 Echo 信号，仿真里看起来很快。但真实硬件上，如果距离较远，Echo 高电平可能持续几十毫秒。所以你的超时时间要按最大量程算，HC-SR04 最大测距 4 米，对应脉宽约 23ms，超时设 30ms 比较安全。

4.3 光敏电阻的 ADC 读取与滤波

光敏电阻在 Wokwi 里是作为一个可变电阻模型存在的，你需要把它和一个固定电阻串联分压，然后接到 STM32 的 ADC 引脚上。我用的引脚是 PA0，对应 ADC1 的通道 0。

ADC 读取本身很简单，HAL_ADC_Start然后HAL_ADC_GetValue就行。但问题是光敏电阻的读数噪声很大，直接输出会看到数值一直在跳。我在任务里做了一个简单的滑动平均滤波：维护一个长度为 8 的数组，每次读新值就替换最旧的值，然后求平均。这样输出就稳定多了。

滤波窗口为什么选 8？因为 8 是 2 的幂，求平均可以用移位代替除法，在 STM32 这种没有硬件浮点单元的芯片上，整数移位比浮点除法快很多。当然如果你用的是 STM32F4 系列带 FPU 的芯片，直接浮点除也没问题。

另外要注意 ADC 的参考电压。Wokwi 默认是 3.3V，和真实硬件一致。光敏电阻分压后的电压范围大概在 0.5V 到 3.0V 之间，对应 ADC 值大约 620 到 3720。你可以根据这个范围做一个简单的映射，把 ADC 值转换成"亮度百分比"输出，这样更直观。

5. 堆栈溢出与优先级反转的排查实录

5.1 任务跑着跑着就卡死：一次堆栈溢出的完整排查

项目第一次跑起来的时候，串口输出正常了几秒钟，然后整个系统就卡住了，连看门狗都没反应。我一开始怀疑是队列满了导致的死锁，但检查了队列操作都有超时保护，不应该死等。后来把configCHECK_FOR_STACK_OVERFLOW设成 2，重新编译运行，发现触发了vApplicationStackOverflowHook，这才定位到是堆栈溢出。

哪个任务溢出了？我在钩子函数里把当前任务名打印出来，发现是 PrintTask。原因是我给 PrintTask 分配了 512 words 的栈，看起来不少，但里面用了sprintf格式化字符串，这个函数在 STM32 上会消耗大量栈空间，尤其是格式化浮点数的时候。512 words 就是 2KB，sprintf格式化一个浮点数可能就要吃掉几百字节，再加上函数调用链，2KB 确实紧张。

解决方案有两个：一是把 PrintTask 的栈加到 1024 words，二是改用更轻量的格式化方式。我选了后者，因为 20KB RAM 实在经不起挥霍。具体做法是不用sprintf的浮点格式化，而是把浮点数拆成整数部分和小数部分，用整数运算拼字符串。比如 25.6 度，先取整数 25，再取小数 6，然后手动拼成 "25.6"。这样栈消耗直接降了一个数量级。

5.2 优先级反转是怎么发生的，怎么避免

另一个坑是优先级反转。现象是距离任务偶尔会延迟很久才执行，导致测距数据出现明显跳变。排查后发现是距离任务和打印任务共享了一个 I2C 资源（我后来加了个 OLED 显示），打印任务持有互斥锁的时候被中优先级的光照任务抢占了，而距离任务在等这个锁，结果高优先级的距离任务被中优先级的光照任务"压"住了。

这就是典型的优先级反转。FreeRTOS 的互斥锁支持优先级继承，但前提是你用的是xSemaphoreCreateMutex创建的互斥锁，而不是二值信号量。我一开始图省事用了二值信号量，结果就没有优先级继承机制。改成互斥锁之后，打印任务持有锁的时候，它的优先级会被临时提升到和距离任务一样高，光照任务就抢不了它了，锁释放后优先级恢复，问题解决。

注意：优先级继承只能缓解优先级反转，不能完全消除。最好的办法还是尽量减少共享资源，或者把共享资源的访问时间缩到最短。比如 OLED 显示，不要在整个刷新过程中持锁，而是先把要显示的内容准备好，最后一次性写进去。

5.3 堆空间不足的隐蔽表现

还有一个不容易发现的问题：FreeRTOS 的堆空间不足时，xTaskCreate会返回pdFAIL，但如果你没检查返回值，任务就不会被创建，系统看起来在跑，但某个功能就是没反应。我遇到过光照任务一直没数据的情况，查了半天才发现是堆不够了，任务创建失败。

怎么估算堆空间？每个任务的栈是从堆里分配的，队列也是从堆里分配的。四个采集任务加一个打印任务，栈加起来大概是 256+256+128+256+1024 = 1920 words，也就是 7.7KB。两个队列加起来约 440 字节。再加上 FreeRTOS 内核本身的开销，10KB 的堆是够的。但如果你还要加软件定时器、事件组这些，就得再留余量。

我的建议是在main里创建完所有任务和队列后，打印一下xPortGetFreeHeapSize()的返回值，看看还剩多少。如果剩余小于 2KB，就说明太紧张了，得优化。

6. 串口输出格式与调试信息的组织

6.1 为什么输出格式要统一时间戳

多任务系统的调试信息如果没有统一的时间基准，你根本分不清哪条数据是先发生的。我在每条输出前面都加了[xxxxms]的时间戳，这个时间戳来自xTaskGetTickCount()，单位是 tick，我设的configTICK_RATE_HZ是 1000，所以 1 tick 就是 1ms。

有了时间戳，你就能看出任务调度的真实顺序。比如你发现距离数据每 100ms 出现一次，温度数据每 2000ms 出现一次，说明任务周期设置生效了。如果时间戳出现跳跃，比如从 5000ms 直接跳到 8000ms，那说明系统在这 3 秒内被某个任务阻塞了，这就是排查性能问题的线索。

6.2 输出内容的结构化设计

每条输出我固定成这样的格式：

[时间戳] 类型: 数值 单位

比如：

[1234ms] Temp: 25.6 C [1234ms] Humi: 60.2 % [1300ms] Light: 75 % [1350ms] Dist: 42 cm

为什么用这种格式？因为它既方便人看，也方便机器解析。如果你后面想用 Python 脚本抓串口数据做可视化，直接按空格分割就能提取字段。我试过用这种格式输出，然后用一个简单的 Python 脚本画实时曲线，效果很好。

另外，错误信息我也做了统一处理。比如 DHT22 读取失败，输出[1234ms] Temp: ERROR，而不是直接打印一堆调试信息。这样你在串口终端里一眼就能看出哪些数据是有效的，哪些是无效的。

6.3 串口输出的性能考量

在 115200 波特率下，一个字符大约 87us，一行 30 个字符就是 2.6ms。如果你每秒输出 10 行，那就是 26ms 的串口占用时间。对于 FreeRTOS 来说，这个时间不算长，但如果你的打印任务优先级设得太高，它就会频繁抢占其他任务。

我的做法是把打印任务的优先级设成最低（1），并且用队列做缓冲。采集任务只管往队列里扔数据，打印任务慢慢往外发。这样即使串口发送慢，也不会影响采集任务的实时性。队列满了就丢弃最旧的数据，保证系统不会因为串口阻塞而卡死。

还有一个细节：printf函数本身不是线程安全的，多个任务同时调用会出问题。所以我只在打印任务里调用printf，其他任务通过队列把数据传给它。这样就避免了重入问题。

7. 从仿真到真实硬件的移植清单

7.1 代码层面需要改什么

Wokwi 上跑通的代码，移植到真实 STM32 开发板上，大部分不用改，但有几处必须调整。第一是时钟配置，Wokwi 的默认时钟和真实板子的晶振可能不一样，你要根据板子上的晶振频率重新配置SystemClock_Config()。第二是引脚定义，Wokwi 里你用的引脚在真实板子上可能被其他外设占用了，比如 PA9/PA10 如果接了 USB 转串口芯片，那你就不能再用它接其他东西。

第三是延时函数。Wokwi 里用空循环做的微秒延时，在真实硬件上因为主频不同，循环次数要重新校准。更稳妥的做法是用硬件定时器做微秒延时，比如用一个基本定时器配置成 1MHz 计数，然后读计数器值来实现精确延时。

7.2 硬件上容易踩的坑

真实硬件上第一个坑是 DHT22 的上拉电阻。Wokwi 里 DHT22 模型内部可能自带弱上拉，但真实 DHT22 的数据线必须接一个 4.7K 到 10K 的上拉电阻到 3.3V，否则读出来的数据全是 0 或者全是 1。我一开始忘了接，折腾了半天以为代码有问题。

第二个坑是 HC-SR04 的供电。HC-SR04 工作电压是 5V，但它的 Echo 输出也是 5V 电平，直接接到 STM32 的 3.3V 引脚上可能会损坏芯片。你需要用一个电阻分压或者电平转换模块，把 5V 降到 3.3V。这个在仿真里不会体现，但真实硬件上必须处理。

第三个坑是光敏电阻的选型。Wokwi 里的光敏电阻模型是理想化的，但真实光敏电阻的阻值范围差异很大，有的在亮处是几 KΩ，有的在暗处是几 MΩ。你要根据实际型号调整分压电阻的阻值，让 ADC 读数落在有效范围内。

7.3 移植后的验证步骤

移植到真实硬件后，不要一上来就跑完整系统。我的建议是分步验证：先跑一个最简单的 LED 闪烁程序，确认时钟和 GPIO 正常；然后跑串口打印，确认波特率正确；接着单独测试每个传感器，确认数据能读出来；最后再把 FreeRTOS 多任务系统跑起来。这样出问题的时候，你能快速定位是哪一层的问题。

另外，真实硬件上一定要开看门狗。Wokwi 里系统卡死了你刷新一下页面就行，但真实硬件卡死了只能断电重启。用IWDG独立看门狗，在主任务里定期喂狗，一旦某个任务死循环或者阻塞太久，看门狗就会复位系统，避免设备"假死"。

8. 这套框架还能怎么扩展

这个多传感器房间监测的骨架，其实可以往很多方向延伸。最直接的是加一个 OLED 显示屏，把数据从串口搬到屏幕上，这样就不需要电脑了。Wokwi 支持 SSD1306，你只需要加一个显示任务，从队列里取数据然后刷新屏幕。注意 OLED 刷新比较慢，I2C 速率设 400KHz 比较合适，刷新频率不要超过 10Hz，否则会占用太多 CPU。

另一个方向是加数据存储。用 STM32 的 SPI 接口接一个 W25Q64 Flash 芯片，把传感器数据按时间戳存进去，这样就能做历史数据回放。FreeRTOS 里可以创建一个低优先级的存储任务，定期把队列里的数据写入 Flash。注意 Flash 写入有寿命限制，不要每条数据都写，可以攒够一个扇区再写。

还可以加报警功能。当温度超过阈值或者距离小于安全值时，触发蜂鸣器或者 LED 报警。这个可以用 FreeRTOS 的软件定时器来做，定时检查最新数据，超过阈值就触发一个事件。软件定时器的回调函数里不要做耗时操作，只发一个信号量或者任务通知，让报警任务去处理具体动作。

如果你想把数据传到手机或者云端，可以加一个 ESP8266 或者 ESP32 做 WiFi 透传。STM32 通过串口把数据发给 ESP8266，ESP8266 再通过 MQTT 协议上传。这个架构在智能家居项目里很常见，FreeRTOS 这边只需要加一个串口发送任务就行。

我个人在实际操作中的体会是，FreeRTOS 的学习曲线在前两天最陡，任务创建、队列、信号量这几个概念一旦理清楚，后面就是查 API 手册的事了。Wokwi 这个平台最大的价值是让你把注意力集中在 RTOS 的逻辑上，而不是被硬件调试分散精力。等你把仿真里的多任务调度跑顺了，再上真实硬件，会发现大部分问题都是硬件层面的，软件框架本身已经很稳了。