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() 调度器就能解决问题
• 请求仅涉及一个阻塞循环，且没有并发需求

工作流

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 技能规范：说明假设、所需工具和版本、实施步骤、各验证阶段的测试／证据、已知限制，以及恢复／安全说明。