Hw Firmware

---
name: hw-firmware
description: "Embedded firmware development capability pack for ESP32-S3/C3 + Arduino framework. Covers firmware architecture (super loop / FreeRTOS / event-driven), peripheral driver wrapping (I2C/SPI), low-power deep-sleep design, communication protocols (WiFi/BLE/MQTT/HTTPS/OTA), arduino-cli build & upload, three-layer firmware testing, and hardware documentation generation. Use for any embedded firmware, ESP32/Arduino, IoT device code, or hardware bring-up task."
version: 0.1.0
type: reference-based
keywords: ["firmware", "固件", "嵌入式", "embedded", "ESP32", "ESP32-S3", "ESP32-C3", "Arduino", "arduino-cli", "MCU", "单片机", "外设驱动", "peripheral driver", "I2C", "SPI", "OLED", "E-ink", "墨水屏", "deep sleep", "低功耗", "low power", "功耗预算", "RTC", "WiFi", "BLE", "MQTT", "OTA", "通信协议", "state machine", "状态机", "FreeRTOS", "编译上传", "烧录", "upload", "partition table", "分区表", "串口调试", "serial debug", "引脚映射", "pin map", "接线图"]
---

# HW Firmware Capability Pack

> Deliverable is compilable firmware code + hardware docs, not sketches. Scope: ESP32-S3/C3 primary, Arduino framework (STM32/nRF out of scope for v1). Toolchain: arduino-cli (verified) + optional PlatformIO for static analysis. Standard kit: Seeed XIAO ESP32-S3, SH1106 OLED (I2C 0x3C), E-ink (GxEPD2), DA7280 haptic (I2C 0x4A), built-in touch/WiFi/BLE.

---

## Step 1: Context Detection

| User Signal | Load Reference |
|---|---|
| new firmware, main loop, 架构设计, state machine, 状态机, FreeRTOS, task scheduling, 模块划分, config.h layout | `references/firmware-architecture.md` |
| new peripheral, 外设驱动, I2C/SPI device, OLED, E-ink, haptic, touch, sensor init, driver library choice, 驱动封装 | `references/peripheral-drivers.md` |
| battery, 电池寿命, deep sleep, 低功耗, 功耗预算, RTC memory, wake source, 唤醒, hibernation | `references/low-power-design.md` |
| WiFi, BLE, MQTT, HTTP/HTTPS API, OTA update, 联网, 配网, TLS, reconnect, 断线重连 | `references/communication.md` |
| compile, upload, 编译, 烧录, arduino-cli flags, partition table, 分区表, library version, FW version, sketch.yaml | `references/build-upload.md` |
| test, 测试, serial debug, 串口调试, self-test, [TEST] logs, regression, mock, 自动化验证 | `references/firmware-testing.md` |
| pin map, 引脚映射, wiring, 接线图, README, API docs, data flow diagram, D2/Typst 文档 | `references/firmware-documentation.md` |
| before declaring ANY firmware deliverable done — acceptance / pass-fail check, 验收 | `references/quality-criteria.md` |
| before gate review / accepting firmware work — expert persona review, 专家审查 | `references/review-checklist.md` |

**Multi-signal**: load all matched references. Every capability's reference ends with its pass/fail + reviewer pointers — follow them before calling the work complete.

---

## Step 2: Decision Entry Point

**Q1 — What stage is the request?**
- New device firmware from scratch → `firmware-architecture.md` first (pattern selection → module layout), then per-peripheral `peripheral-drivers.md`
- Adding one peripheral to existing firmware → `peripheral-drivers.md`
- Device must run on battery → `low-power-design.md` MUST be read at ARCHITECTURE time, not after (power is not a retrofit)
- Needs network/cloud/phone connection → `communication.md`
- Code done, getting it onto the board → `build-upload.md`, then `firmware-testing.md`
- Producing docs for a finished firmware → `firmware-documentation.md`

**Q2 — Architecture pattern?** (reasoned selection, never default silently)
- ≤5 peripherals, no real-time need → Super Loop (millis() timers)
- WiFi + display + sensors in parallel → FreeRTOS (Core 0 = WiFi/BLE stack reserved; user tasks pinned to Core 1)
- Deep-sleep dominant, duty cycle < 5% → Event-driven (+ FreeRTOS only if post-wake work is parallel)

**Q3 — Battery powered?**
- Yes → sleep mode chosen from the current table in `low-power-design.md` (Light Sleep for <1ms response, Deep Sleep for periodic wake, Hibernation for timer-only) and a per-phase power budget table is REQUIRED

---

## Step 3: Core Judgment Rules (always apply)

### Architecture (`references/firmware-architecture.md`)
1. **config.h is the single hardware-config source**: every pin defined there with GPIO number + physical marker comment; all I2C addresses centralized; time constants with `_MS` suffix. Magic numbers scattered in code = FAIL.
2. **Non-blocking discipline**: no `delay()` in loop() (except `delay(1)` yield); all timing via millis() diffs; all I2C ops have timeouts.
3. **Koopman-derived limits**: functions ≤50 lines, cyclomatic complexity <15, nesting ≤2, ISR ≤25 lines and only sets a flag / enqueues — never loops, logic, or I2C/SPI inside an ISR.
4. **Memory budget**: Flash <75%, RAM <60% (headroom for runtime + OTA). Verify from compile output every build.
5. **Static analysis before human review** (cheap checks first): compile with all warnings → zero warnings, no suppression; `pio check` → 0 high severity.
6. Init order respects shared buses: I2C bus → OLED → haptic → other I2C; SPI → E-ink → SD; WiFi/BLE last.

### Drivers (`references/peripheral-drivers.md`)
7. **Every driver init() returns bool and probes the bus first** (I2C address responds?) before calling library init; all public functions check the ready flag. init returning void = undetectable failure = FAIL.
8. **Graceful degradation, never while(1)**: OLED fails → Serial output; haptic fails → fallback/skip; WiFi fails → offline mode keeps running.
9. One `.h` per peripheral; Serial logs prefixed `[OK]/[WARN]/[ERR]`; `snprintf`/`F()` instead of String concatenation (heap fragmentation).

### Low Power (`references/low-power-design.md`)
10. **Power is designed at architecture stage**, never retrofitted. Deep-sleep entry sequence: save state to RTC memory (`RTC_DATA_ATTR`, 8KB max) → deinit peripherals (WiFi off, btStop, E-ink `hibernate()`) → GPIO hold → configure wake source → sleep. Everything else in RAM is lost.
11. WiFi is the top power cost: cache channel + BSSID in RTC memory for fast reconnect (<1s vs ~3s); power budget table must include the WiFi-connect phase and boot.

### Communication (`references/communication.md`)
12. **Timeout everything**: WiFi connect 10s default, never `while(!connected)` unbounded; reconnects non-blocking (millis, not delay).
13. **Security floor**: CA-cert verification in production (`setInsecure()` dev-only, tagged `[DEV ONLY]`); secrets in NVS/config portal, never hardcoded; JsonDocument capacity bounded (unbounded parse of a hostile/huge response = OOM crash).

### Build & Test (`references/build-upload.md`, `references/firmware-testing.md`)
14. **Lock library versions** (sketch.yaml / platformio.ini); inject and Serial-print `FW_VERSION` at boot; partition table matched to chip flash size and OTA needs.
15. **Three test layers**: L1 compile (mandatory, zero error), L2 host-side logic, L3 on-target hardware with machine-parseable `[TEST] name: PASS/FAIL` logs. Test failure paths (missing peripheral, WiFi timeout), not just happy path.

### Docs (`references/firmware-documentation.md`)
16. Docs derive from code: pin table extracted from config.h (must match line-for-line); diagrams in D2 (version-controllable text, not GUI screenshots); README lets a newcomer wire and flash from scratch.

### Universal
17. **编造数据 = FAIL. 不确定标注 [ASSUMPTION].** Applies to every capability — power numbers, memory figures, library versions all traceable.
18. **Acceptance gate**: before declaring any firmware capability done, check its section in `references/quality-criteria.md`; before gate review / accepting firmware work, run the matching persona checklist in `references/review-checklist.md`.

---

## Anti-Patterns

### Firmware Architecture
- ❌ 魔法数字散落在代码各处（→ 集中到 config.h）
- ❌ loop() 中用 delay(1000) 做定时（→ millis() 非阻塞）
- ❌ 外设 init 失败时 while(1) 卡死（→ 优雅降级）
- ❌ 全局变量满天飞（→ 按模块用 struct 封装状态）
- ❌ setup() 中不做 I2C scan 就假设外设存在
- ❌ FreeRTOS 任务不指定 Core（→ pinToCore 明确绑定）
- ❌ ISR 中做循环/复杂逻辑/I2C/SPI 操作（→ ISR 只设 flag，主循环处理）
- ❌ 用 #define 替代 const/inline/enum（→ 类型安全 + 调试可见）
- ❌ 假设硬件状态在 deep sleep 后保留（→ 唤醒后必须重新初始化外设）

### Peripheral Drivers
- ❌ 不检测外设就直接调用库函数（→ init 先 probe）
- ❌ 驱动内用 delay() 等待（→ 用 millis 或让调用者决定）
- ❌ 用 String 类做频繁拼接（→ snprintf + char[]，避免堆碎片）
- ❌ I2C 操作无超时（→ Wire.setTimeOut()）
- ❌ 所有外设代码堆在 main.ino（→ 每个外设独立 .h）
- ❌ init 失败 while(1) 死循环（→ return false + 降级）
- ❌ 关中断/持锁时间过长（→ 最小化临界区，尽快释放）
- ❌ 跳过静态分析直接人工 review（→ 先跑 pio check，再人工审查）

### Low Power Design
- ❌ Deep Sleep 前不关 WiFi（→ WiFi.disconnect(true) + WIFI_OFF）
- ❌ 不用 RTC_DATA_ATTR 就假设变量保留（→ Deep Sleep 清除所有 RAM）
- ❌ E-ink 不 hibernate 就 Deep Sleep（→ E-ink 控制器持续耗电）
- ❌ 功耗估算不含 WiFi 连接阶段（→ 这是最耗电的阶段）
- ❌ 定时唤醒间隔硬编码（→ 用 config.h 定义 SLEEP_DURATION_S）
- ❌ 唤醒后重新校准触摸（→ 用 RTC 存 baseline）
- ❌ 把功耗管理当事后优化（→ 必须在架构阶段设计，不能后补）

### Communication
- ❌ WiFi.begin() 后 while(!connected) 无超时（→ millis 超时）
- ❌ setInsecure() 在生产固件中使用（→ 嵌入 CA 证书）
- ❌ API key 硬编码在 .ino 文件中（→ NVS / config portal）
- ❌ MQTT 重连用 delay() 阻塞（→ millis 非阻塞重连）
- ❌ 不检查 HTTP 返回码就解析 body（→ 先检查 200）
- ❌ WiFi 每次 Deep Sleep 唤醒都全量 scan（→ RTC 缓存 channel）
- ❌ JsonDocument 不设 capacity 上限（→ 异常/恶意超大 JSON 导致 OOM crash）

### Build & Upload
- ❌ 库版本不锁定（→ sketch.yaml 指定精确版本）
- ❌ 忽略编译 warnings（→ --warnings more + 逐条解决）
- ❌ 分区表不匹配 Flash 大小（→ 先确认芯片型号和 Flash 容量）
- ❌ 上传前不检查端口（→ arduino-cli board list 确认）
- ❌ 不记录构建参数（→ 写入 build.log 或 Makefile）
- ❌ 生产固件用 debug 分区表（→ 切换到 OTA 分区表）

### Firmware Testing
- ❌ 不测试就上传（→ 至少 L1 编译测试）
- ❌ 测试日志无结构（→ [TEST] 前缀 + PASS/FAIL）
- ❌ 只测试 happy path（→ 必须测试外设缺失和超时）
- ❌ 自测代码和生产代码混在一起（→ #ifdef SELF_TEST 隔离）
- ❌ 测试依赖特定 WiFi 网络（→ AP 模式或 mock）
- ❌ 不记录内存使用变化（→ 每次编译记录 Flash/RAM %）

### Firmware Documentation
- ❌ 引脚映射表和代码不同步（→ 从 config.h 自动提取）
- ❌ README 缺少接线说明（→ 新人必须知道如何连线）
- ❌ 用截图而非文本描述引脚（→ 不可搜索、不可维护）
- ❌ API 文档只有函数名没有参数说明
- ❌ 图表用 GUI 工具画（→ D2 文本格式可版本控制）
- ❌ 文档和代码分开仓库（→ 同仓库、同 PR 更新）

---

## Anti-Skip Table

| Shortcut Attempt | Required Action |
|---|---|
| "It compiles, ship it" | MUST run L1 with warnings enabled (zero warnings) + on-target `[TEST]` self-test per `firmware-testing.md` — compile success alone proves nothing about hardware |
| "The peripheral is surely connected" | MUST probe (I2C scan / init() bool) before use; missing-device path must degrade, not while(1) |
| "I'll optimize power later" | MUST design sleep strategy + power budget at architecture stage (`low-power-design.md`) — power is not a retrofit |
| "setInsecure() is fine for now" | MUST tag `[DEV ONLY]` and embed CA cert before production per `communication.md` |
| "Latest library version is fine" | MUST pin exact versions in sketch.yaml (`build-upload.md`) — unpinned builds are unreproducible |
| "Memory is probably fine" | MUST check compile output: Flash <75%, RAM <60% — record % every build |
| "Docs can lag the code" | MUST regenerate pin table from config.h and sync docs in the same PR (`firmware-documentation.md`) |
| "Deliverable done, moving on" | MUST check `references/quality-criteria.md` pass/fail section + run the persona checklist in `references/review-checklist.md` first |