freertos-patterns

ESP32 和 RP2040 的 FreeRTOS 模式

当需要解决 ESP32 或 RP2040 上的实际并发问题时，使用此技能。让主流程保持聚焦，并加载与用户具体问题匹配的详细参考资料。

资源

• references/patterns-task-creation.md - 任务生命周期、优先级、栈大小和任务启动
• references/patterns-queues.md - 使用队列进行任务间通信
• references/patterns-synchronization.md - 互斥锁、信号量、临界区和 ISR 协调
• references/patterns-memory.md - 栈大小、堆检查和监控
• references/patterns-advanced.md - 看门狗、通知、事件组、定时器和亲和性
• assets/workflow.mmd - 架构概览

适用场景

当请求涉及以下内容时，使用此技能：

• ESP32 上的多个并发任务
• 任务优先级或抢占
• 队列、信号量、互斥锁或通知设计
• RP2040 setup1 和 loop1 的多核协调
• 看门狗安全的长时间运行行为
• 调试竞态条件、栈溢出或死锁

以下情况不要使用此技能：

• 目标是 UNO 或其他单核开发板
• 简单的 millis() 调度器就能解决问题
• 请求仅涉及一个阻塞循环，且不需要并发

工作流

对于控制系统的任务/资源所有权、动作时序或截止时间预算，请从 realtime-control-design 开始。实际使用 RTOS 原语时再回到此处。原生 ESP-IDF 使用其自身移植层的栈单位、亲和性和临界区规则；将 Arduino/RP2040 示例用于其他框架前，务必检查所选 SDK。

1. 首先确认目标平台：
   • ESP32 -> FreeRTOS 任务模型
   • RP2040 -> 双核协调模型
2. 确定主要问题：
   • 任务启动 -> 打开 patterns-task-creation.md
   • 通信 -> 打开 patterns-queues.md
   • 共享数据或 ISR 信号传递 -> 打开 patterns-synchronization.md
   • 栈或堆风险 -> 打开 patterns-memory.md
   • 看门狗、通知、定时器或亲和性 -> 打开 patterns-advanced.md
3. 每次只解决一个同步边界。除非设计确实需要，否则不要混杂队列、互斥锁和通知方面的建议。
4. 明确说明特定开发板的细节。ESP32 FreeRTOS 指南与 RP2040 多核指南不可互换。

核心规则

• 优先选择能够解决问题的最简单并发原语。
• 明确保护共享状态。“大概安全”并不安全。
• 在 ESP32 上使用 vTaskDelay() 或事件驱动阻塞，绝不要在任务中使用 delay()。
• 仔细规划栈大小，并通过运行时证据进行验证。
• 对于 RP2040，在共享数据之前明确各核心的所有权。

验证

• 确认每个任务或核心都有明确且唯一的职责。
• 根据具体数据路径检查队列深度、通知流或互斥锁覆盖范围。
• 对于 ESP32，如果任务栈大小不确定，请使用 uxTaskGetStackHighWaterMark() 检查栈余量。
• 验证程序能够持续推进，不会死锁或忙等。
• 如果涉及 ISR，请确认同步原语在该平台上可安全用于 ISR。

常见故障模式

• 任务栈大小不足
• 在 FreeRTOS 任务中使用 delay()
• 共享数据未受保护
• 锁定顺序不一致导致死锁
• RP2040 核心启动假设缺乏互斥锁或所有权规范

集成

• 当用户需要完整草图而非设计指导时，与 arduino-code-generator 结合使用。
• 只有在并发设计看起来合理，但仍存在硬件时序问题时，才与 circuit-debugger 结合使用。
• 当并发设计需要任务、队列或事件流图时，与 mermaid-diagram-generator 结合使用。

共享输出契约

使用共享 Arduino 技能契约： 说明假设、所需工具与版本、实现步骤、 按证明阶段划分的测试/证据、已知限制，以及恢复/安全注意事项。