LED-Germany/05_Docs/DEV_PROGRESS.md

# ESP32-C6 Matter + ESP-NOW 混合固件开发进度（单色灯 + 双色温灯）

## 1. 项目目标（来自《项目制作需求》）

- 基于 ESP32（候选：C3/C6），开发 Matter + ESP-NOW 混合固件。
- 支持两类灯：
  - 单色灯：开关 + 调光（白光）。
  - 双色温灯：开关 + 调光 + 调色温（暖/冷）。
- 开发阶段：Wi-Fi commissioning（通过 Wi-Fi 完成配网）。
- 最终目标：Wi-Fi 完成配网、Thread 实现本地 mesh 控制（混合网络模式）。
- 需要 OTA、QR 码生成、VID/PID/DAC 相关出厂数据与认证准备支持。
- 交付：双版本（或可配置）源码仓库 + Factory/OTA 固件 + 烧录/QR 脚本 + 测试报告 + 技术文档。

## 1.1 关键硬性约束与解决方案

- 量产遥控器固件不变，且 ESP-NOW 固定信道为 `channel=1`。
- **问题**：若使用 Matter-over-Wi-Fi，Wi-Fi STA 信道会被路由器决定，与 ESP-NOW 固定 ch1 冲突。
- **解决方案**：利用 ESP32-C6 的**双射频**能力：
  - **Wi-Fi 2.4GHz 射频**：专用于 ESP-NOW（固定 channel 1，不连接路由器做 STA）
  - **802.15.4 射频**：专用于 Matter over Thread（与 Wi-Fi 射频完全独立）
  - **BLE**：用于 Matter commissioning（配网阶段）
- 结论：单芯片 ESP32-C6 可实现 ESP-NOW + Matter 共存，无需依赖路由器信道。

## 1.2 需求对齐清单（当前工程状态）

| 需求项 | 状态 | 备注 |
| --- | --- | --- |
| ESP-NOW 代码功能 100% 保持 | 部分 | 已按遥控器协议实现 RX/配对/命令映射，但信道冲突仍未解决为“量产可用”方案 |
| Matter clusters: OnOff / LevelControl | 已完成 | 双 endpoint 已跑通 |
| Matter clusters: Groups / Scenes | 已完成（已验证） | 已在 App 上验证可创建/应用场景 |
| ColorControl（双色温） | 已完成（开发态） | 当前实现为 ColorTemperature；已确认硬件为 SK6812 RGBW 模块，调色温方向正常 |
| ESP-NOW 组播/广播组命令→所有控制器同步→Matter 状态更新 | 已完成（已稳定） | 控制器能处理 cmd 并更新 Matter 属性；组控一致性/延迟表现正常，无需再测试 |
| QR 码配网（Apple/Google/Alexa/RainMaker） | 部分 | iOS Home 已验证；Google/Alexa/RainMaker 未做系统性验证 |
| OTA（HTTP 远程服务器） | 已完成 | 已实现 HTTP OTA（从远程服务器下载固件），可通过 Matter shell 命令触发，已验证升级后 App version 变更 |
| Matter 标准 OTA | 暂停 | 采用 HTTP OTA（远程服务器）方案，不再推进标准 Matter OTA |
| 断电重置（如 3 次开关机） | 已完成（已稳定） | 已实现并验证：3 次重启触发 Matter 工厂重置（含 5 秒确认窗）；已测试稳定，无需再测 |
| 交付：源码/编译说明/bin/脚本/测试报告 | 进行中 | 文档与脚本需要补齐并固化 |

## 1.4 当前进度总览（已完成 vs 未完成）

### 1.4.1 已完成

- HTTP OTA（远程服务器下载固件，shell 命令触发），并验证升级成功后 `App version` 变更（2.0 → 2.1）
- Matter clusters: Groups / Scenes 已在 App 上验证可创建/应用场景
- 分区表调整为双 OTA（`ota_0`/`ota_1`/`otadata`），固件大小可容纳 OTA 升级
- OTA 触发命令已接入 Matter shell（`matter esp ota <http://url>`）
- 已可在 Windows 上稳定完成 build/flash/monitor（含 GN/Pigweed 环境）
- 断电重置（工厂重置）：已实现并验证 3 次重启触发 factory reset（含 5 秒确认窗），重置后进入可重新配网状态
- 修复断电计数不生效问题：将 NVS key 缩短到 15 字符以内并加入兼容读取逻辑
- ESP-NOW 配对与多设备联调：已支持“单遥控器（Zone1/Zone2）+ APP”控制两台 ESP32-C6 灯具；并修复“电源重启触发配对时未及时广播配对 beacon”的问题，提升遥控器绑定成功率

### 1.4.2 未完成（待办）

- 多生态验证：Google Home / Alexa / RainMaker 的 commissioning + 控制验证
- 交付物固化：一键环境初始化/构建脚本、烧录脚本、测试报告与完整技术文档

## 3. 已完成的关键里程碑

### 3.1 构建与烧录链路打通（Windows）

- 已实现：`idf.py build` 成功、可 `flash` 到 COM4、可 `monitor` 观察启动日志。
- 已解决的关键构建问题（历史记录）：
  - `gn command not found`：定位 `gn.exe` 并加入 PATH。
  - Pigweed 环境变量缺失：补齐 `_PW_ACTUAL_ENVIRONMENT_ROOT`。
  - 链接错误 `undefined reference to mbedtls_hkdf`：启用 `CONFIG_MBEDTLS_HKDF_C=y`。
  - app 分区过小：切换到自定义分区表 `partitions.csv`（双 OTA），并设置 flash size=16MB（与硬件一致），最小 app 分区 `0x1E0000`。
  - Windows 反斜杠路径导致 CMake `Invalid character escape`：CMakeLists 里将 env path 转为 CMake path。

补充：构建该工程的关键环境变量（PowerShell 会话级别）：

- `ESP_MATTER_PATH=D:\ESP-LED\esp-matter-gh`
- `ESP_MATTER_DEVICE_PATH=D:\ESP-LED\esp-matter-gh\device_hal\device\esp32c6_devkit_c`
- `_PW_ACTUAL_ENVIRONMENT_ROOT=D:\ESP-LED\esp-matter-gh\connectedhomeip\connectedhomeip\third_party\pigweed\repo\environment`
- GN 工具路径（将目录加入 PATH）：
  - `...\third_party\pigweed\repo\environment\cipd\packages\pigweed`（包含 `gn.exe`）

### 3.2 Matter 双 endpoint 架构（已运行验证）

- 当前固件创建两个 endpoint：
  - Endpoint 1：单色灯（OnOff + LevelControl）。
  - Endpoint 2：双色温灯（OnOff + LevelControl + ColorControl(ColorTemperature)）。
- 串口日志已确认：
  - `RGB light created with endpoint_id 1`
  - `CCT light created with endpoint_id 2`

### 3.3 驱动层对接（已跑通）

- Endpoint 1（单色灯）：LEDC PWM 驱动（GPIO4/5/6）。
- Endpoint 2（双色温灯）：RMT 驱动 SK6812（GPIO2）。

### 3.4 日志报错修复

- 修复启动时 `E data_model: Cluster cannot be NULL.`：
  - 原因：对不含 ColorControl 的 endpoint 调用 `attribute::get(endpoint, ColorControl...)`。
  - 处理：先检查 `cluster::get(endpoint, ColorControl::Id)` 是否存在，再读取 ColorMode / Hue / Temp 等属性。

### 3.5 iOS Home / Matter Commissioning + 控制验证（已完成）

- 现状：手机端已完成配网，Home App 可同时控制两个灯的开关/亮度/（CCT 灯）色温。
- 关键修复：为满足 iOS Home 的发现/配网流程，已启用 BLE commissioning：
  - `CONFIG_BT_ENABLED=y`
  - `CONFIG_BT_NIMBLE_ENABLED=y`
  - `CONFIG_ENABLE_CHIPOBLE=y`
- 串口日志关键特征（表示 BLE commissioning 正常）：
  - `Configuring CHIPoBLE advertising ...`
  - `CHIPoBLE advertising started`
  - `Commissioning window opened`
- 设备启动时可打印 Onboarding Codes（用于手动输入/生成二维码）：
  - MT 串（SetupQRCode）：`MT:Y.K9042C00KA0648G00`
  - 11 位码（Manual pairing code）：`34970112332`
- 注意：上述二维码/手动码为开发阶段示例/测试参数（默认 VID/PID 等），量产需替换正式 VID/PID、DAC/CD/工厂数据与每台唯一的 onboarding 信息。

### 3.6 单芯片双射频方案验证成功（2026-01-07）

- **架构**：ESP32-C6 单芯片同时运行：
  - **Thread (802.15.4)**：Matter 网络层
  - **Wi-Fi (channel 1)**：ESP-NOW 接收（不连接路由器）
  - **BLE**：Matter commissioning
- **关键配置**：
  - `CONFIG_ENABLE_WIFI_STATION=n`：禁用 Matter Wi-Fi STA
  - `CONFIG_ENABLE_THREAD=y`：启用 Matter over Thread
  - 独立初始化 Wi-Fi 用于 ESP-NOW，固定 channel 1
- **验证通过的日志特征**：
  - `OpenThread started: OK`
  - `Wi-Fi channel fixed to 1 for ESP-NOW`
  - `ESP-NOW RX initialized`
  - `CHIPoBLE advertising started`
  - `Server Listening...`
- **固件大小**：~2MB（含 Thread + Wi-Fi + BLE + ESP-NOW）
- **状态**：设备稳定启动，无崩溃

### 3.7 HTTP OTA（远程服务器）验证成功（2026-01-15）

- **目标**：支持“远程服务器方式”OTA（HTTP），不依赖 HTTPS/TLS，固件体积可控。
- **实现概览**：
  - 使用 `esp_http_client` + `esp_ota_*` 实现分段下载与写入 OTA 分区。
  - 提供 Matter shell 命令触发：`matter esp ota <http://url>`。
  - 仅支持 `http://`，拒绝 `https://` 以减小固件体积。
- **验证结果（串口日志特征）**：
  - `HTTP OTA progress: ... 100%`
  - `HTTP OTA upgrade successful! Rebooting in 3 seconds...`
  - 重启后：`Loaded app from partition at offset 0x210000`（切换到 ota_1）
  - 重启后：`App version: 2.1`（已确认版本号随固件更新）

### 3.8 多设备控制联调进展（APP + ESP-NOW 遥控器）（2026-01-15）

- **目标**：一台遥控器 + 手机 App 同时控制两台 ESP32-C6 灯具（两块开发板）。
- **实现状态**：
  - App 侧（iOS Home）已可同时添加两台设备并分别控制。
  - 遥控器侧支持 Zone1/Zone2 独立绑定不同灯具（通过 ESP-NOW 配对流程完成）。
- **配对机制（开发态）**：
  - 3 次重启：触发 Matter factory reset（5 秒确认窗）。
  - 5 次重启：进入 ESP-NOW pairing mode（5 秒确认窗）。
  - 遥控器在目标 Zone 下长按配对键，设备收到 `0xA5` 后退出配对模式。
- **关键修复**：
  - 修复“电源重启触发配对模式后，因 Wi-Fi 连接状态导致配对 beacon 未及时广播”的问题：进入配对后将主动启动配对 beacon 广播，确保遥控器可发现并完成绑定。

## 4. 当前仍在进行中的问题/待验证点

### 4.1 单色灯输出"白光"的定义与实现（已确定：RGB 三路混白）

- 当前单色灯硬件接法为 RGB 三路 PWM（GPIO4/5/6）。
- 已做的软件调整：将 RGB 三路占空比设置为 1:1:1（同亮度混色）以尽量呈现白光。
- 已确认：单色灯即 RGB 三路混白方案（不做单通道白灯条改造）。
- 注意：RGB 分立灯珠近距离仍可能看到“三色点”，属于物理结构；可通过扩散罩/导光改善。

### 4.2 双色温灯的“暖/冷”实现（已确认：SK6812 RGBW）

- 已确认：双色温灯硬件为 SK6812 RGBW 模块，采用 RMT 单线驱动。
- 当前实现：Matter ColorTemperature（mireds）→ 颜色映射 → SK6812 输出；调色温方向已验证正确。
- 注意：SK6812 RGBW 的“色温”属于近似实现（需要 RGB 参与补色），效果取决于映射/校准策略。
- 状态：当前效果表现正常，无需再做专项“色温校准/一致性测试”。

### 4.3 Flash 容量提示告警（已解决）

- 现象：启动时提示检测到 16MB，但固件镜像头标记为 4MB：
  - `Detected size(16384k) larger than the size in the binary image header(4096k)`
- 影响：通常可运行，但不利于后续分区与 OTA 风险控制。
- 已处理并确认：将工程 Flash size 配置调整为 16MB（`CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y`），已复测确认告警消失。

## 5. 控制器/遥控器（ESP-NOW）现状梳理（已读源码）

- 控制器原码路径：`D:\ESP-LED\控制器原码\Ecolight\...`
- 协议：ESP-NOW（channel=1）
- Pairing beacon magic：`0xABCDEF01`（4字节）
- 命令（1字节）：
  - `0x01` Toggle
  - `0x02` On
  - `0x03` Brightness Up
  - `0x04` Brightness Down
  - `0x05` Off
  - `0xA5` Pairing Confirm

结论：控制器原码与甲方提供的遥控器一致，且该 ESP-NOW 遥控协议可接入当前 Matter 灯固件（C6 端作为 ESPNOW 接收端），收到命令后同步更新 Matter 属性。

## 6. VID/PID/DAC/QR 码阶段性策略

- 开发阶段可以使用示例/测试用的 VID/PID/证书链推进开发。
- 后续拿到正式 VID/PID/DAC 后：
  - 替换证书与出厂数据。
  - 重新生成 QR。
  - 通常需要恢复出厂并重新配网（属正常流程）。

## 7. 下一步开发路线图（按阶段）

### 阶段 A：功能验证与参数固化（短期）

- 单色灯：明确硬件定义（RGB 混白 vs 单路白灯条），固化白光方案。
- 双色温：已确认 SK6812 RGBW，固化色温映射与效果参数（端点/曲线/gamma/限幅），并确认通道顺序与供电/信号稳定性。
- 建立功能测试用例并记录：
  - endpoint 1：开/关、亮度
  - endpoint 2：开/关、亮度、色温

### 阶段 B：ESP-NOW + Matter 共存（核心）

- 在 C6 Matter 固件中加入 ESPNOW RX：
  - 接收 1-byte 命令并映射到 endpoint 1/2 的 Matter 属性更新。
  - 目标：遥控器控制灯，Matter 侧状态同步。
- 解决 Wi-Fi channel 与 ESPNOW channel=1 的冲突（以“遥控器固件不变”为前提）：
  - 方案 1（最小改动，但依赖环境）：路由器/热点 2.4G 固定 `channel=1`。
  - 方案 2（推荐量产架构）：双芯片/双射频解耦（ESP-NOW 固定 ch1 与 Matter Wi-Fi 任意信道互不影响）。
  - 方案 3（与 Addendum 对齐）：Wi-Fi 用于 commissioning，日常控制走 Thread（需要 Thread Border Router 环境），从而避免 Wi-Fi 信道对 ESP-NOW 的牵制。
- 性能目标：端到端延迟 < 20ms（需要定义测量方法和基准）。

### 7.2 芯片选型建议（C3 vs C6）

- 若坚持单芯片承载 Matter（含 Groups/Scenes/OTA/多生态）+ 应用逻辑 + ESPNOW：更推荐 ESP32-C6。
  - 原因：内存与资源更充足，Matter 生态适配与稳定性更优，且可扩展 Thread（满足 Addendum）。
- 若控制器仍使用 ESP32-C3：需要评估以下风险项：
  - Matter + BLE commissioning + OTA + Groups/Scenes 的 RAM/Flash 压力。
  - 与 ESPNOW 同时运行的峰值内存/任务栈/队列占用。
- 当路由器信道不可控且遥控器固件不变时：
  - 单芯片方案存在先天信道冲突。
  - 需要硬件/架构调整（例如额外加一颗 C3 专做 ESPNOW 固定 ch1，C6 专做 Matter/Wi-Fi/Thread，通过 UART/SPI 同步状态）。

### 7.3 方案 A（双芯片解耦）系统架构（量产推荐）

#### 7.3.1 总体思路

- MCU1（ESP-NOW 控制器，建议 ESP32-C3）：
  - 只负责：ESP-NOW（固定 ch1）、遥控器配对/命令接收、组控广播一致性、驱动输出（PWM/RMT/恒流等）。
  - 不连接路由器（或不承担 Matter Wi-Fi）。
- MCU2（Matter 控制器，建议 ESP32-C6）：
  - 只负责：Matter over Wi-Fi（commissioning/长久在线/多生态）、（可选）Thread、Matter OTA、Groups/Scenes/状态机。
  - 通过 UART/SPI 与 MCU1 交换“控制命令/状态变化/诊断”。

补充确认：本项目采用 UART 作为 MCU1↔MCU2 通信方式。

#### 7.3.2 数据流与一致性目标

- 遥控器 → MCU1（ESP-NOW RX）→
  - MCU1 先本地执行灯控（保证延迟与体验不变）
  - MCU1 同步上报事件给 MCU2（用于 Matter 属性更新与组/场景一致性）
- App/Matter → MCU2（属性更新/命令）→ MCU2 下发到 MCU1 → MCU1 执行驱动输出 → MCU1 回报最终状态给 MCU2（闭环）

#### 7.3.3 量产可测的关键指标

- 遥控器端到端延迟（按键到灯输出）：目标 < 20 ms（以 MCU1 本地执行为准）
- Matter 状态同步延迟（灯输出到 Matter 属性更新可见）：给出目标与测量方法（建议 < 200 ms）
- 长期稳定性：Wi-Fi/Matter 长久在线，不影响 MCU1 的 ESP-NOW 实时性

#### 7.3.4 PCB/硬件接口建议（小改动范围）

- UART：
  - MCU1_TX -> MCU2_RX（GPIO 待定：MCU1=____ / MCU2=____）
  - MCU1_RX <- MCU2_TX（GPIO 待定：MCU1=____ / MCU2=____）
- 可选硬件流控（建议预留焊盘，量产可按稳定性决定是否启用）：
  - MCU2->MCU1 `RESET_REQ`（请求 MCU1 执行：清码/恢复出厂/重新配对/进入测试）
  - MCU1->MCU2 `IRQ_EVT`（有新事件/状态上报，降低轮询开销）
- 电平：两者均为 3.3V TTL（无需电平转换）
- 调试：建议预留测试点（TX/RX/GND）便于产线与现场抓包

## 8. 测试计划（面向交付物）

### 8.1 遥控器 + ESP-NOW（不改固件）

- 工厂重置：三次断电/复位触发工厂重置（含 5 秒确认窗）
- 配对：五次断电/复位进入配对模式；遥控器 slot 长按配对
- 单控：0x01..0x05 全命令覆盖，重复按键/长按/连发
- 组控：遥控器广播组命令，多个控制器同步输出一致
- 延迟：示波器/逻辑分析仪测量（按键触发到 GPIO/PWM 变化），记录 P50/P95

### 8.2 Matter 多生态（MCU2）

- Apple Home / Google Home / Alexa（至少两项）commissioning 演示
- Clusters：OnOff/LevelControl/Groups/Scenes（双色温含 ColorControl）
- OTA：升级演示 + 回滚验证

### 8.3 共存与稳定性

- Wi-Fi 长久在线（24h/72h）期间，遥控器控制无明显延迟/无丢包异常
- 异常恢复：
  - MCU1 重启不影响 MCU2（Matter 仍在线；状态恢复后同步）
  - MCU2 重启不影响 MCU1（遥控器控制不中断；MCU2 恢复后重新拉取状态）

## 9. Matter 功能测试用例（建议用 chip-tool 记录）

### Endpoint 1（单色灯：开关/调光）

```bash
chip-tool onoff on 1 1
chip-tool onoff off 1 1
chip-tool levelcontrol movetolevelwithonoff 1 1 10 0 0
chip-tool levelcontrol movetolevelwithonoff 1 1 200 0 0
```

### Endpoint 2（双色温灯：开关/调光/色温）

```bash
chip-tool onoff on 1 2
chip-tool onoff off 1 2
chip-tool levelcontrol movetolevelwithonoff 1 2 20 0 0
chip-tool levelcontrol movetolevelwithonoff 1 2 220 0 0
chip-tool colorcontrol movetocolortemperature 1 2 153 0 0
chip-tool colorcontrol movetocolortemperature 1 2 450 0 0
```

## 10. 风险与注意事项

- ESPNOW channel 固定为 1：当路由器信道不可固定到 1 且遥控器固件不可改时，单芯片方案存在先天冲突，需要改架构。
- 单色灯“白光”体验可能受硬件（RGB 三色灯珠）限制，软件无法消除近距离三色颗粒。
- 双色温（SK6812 RGBW）“色温”为近似实现：不同亮度下可能存在色偏；需要通过端点/曲线/gamma 与 RGB/W 分配进行校准。
- Thread + Wi-Fi 混合网络模式需要明确最终产品拓扑与测试方法。

## 11. MCU 间通信协议草案（方案 A）

### 11.1 物理层与链路建议

- UART：建议 921600 或 1Mbps，8N1
- 帧格式：固定 header + version + flags + type + seq + len + payload + CRC32
- 可靠性建议：
  - 带 `seq` 与 `ACK`（至少对“状态设置/模式切换/工厂重置”等关键命令）
  - 对“按键事件上报”可不必 ACK，但需要丢包容忍（MCU2 以 MCU1 的最终状态为准）

### 11.1.1 帧格式（建议稿，可直接实现）

- `SOF`：2 bytes，固定 `0x55 0xAA`
- `VER`：1 byte，协议版本（初版 `0x01`）
- `FLAGS`：1 byte
  - bit0：是否需要 ACK
  - bit1：是否为 ACK 包
  - bit2：错误包
  - bit3..7：预留
- `TYPE`：1 byte，消息类型
- `SEQ`：2 bytes，递增序号（小端）
- `LEN`：2 bytes，payload 长度（小端，0..1024 建议上限）
- `PAYLOAD`：LEN bytes
- `CRC32`：4 bytes（对从 `VER` 到 `PAYLOAD` 的 CRC32，小端）

### 11.1.2 ACK/重试/超时（建议稿）

- 对 `FLAGS.need_ack=1` 的包：
  - 接收方在成功处理后回 `ACK` 包（`FLAGS.is_ack=1`，`SEQ` 原样回显，`TYPE`=原 TYPE 或 `TYPE=ACK(0x7F)` 二选一）
  - 发送方超时 `T_ACK=50ms` 未收到 ACK：重发，最多 `N_RETRY=3`
  - 连续失败后进入降级策略：记录错误计数并上报 `EVT_DIAG`（或触发重新握手）
- 对 `EVT_KEY_CMD`：可 `need_ack=0`（允许丢）；但要求 MCU1 后续用 `EVT_LOCAL_STATE` 做闭环状态同步

### 11.1.3 上电/复位握手（建议稿）

- MCU2 启动后发送 `HELLO`（包含 MCU2 fw_ver/proto_ver/boot_reason）
- MCU1 回 `HELLO_RSP`（包含 MCU1 fw_ver/proto_ver、灯型/能力、当前输出状态摘要）
- MCU2 收到后发送 `GET_STATE`（拉取完整状态），并以此刷新 Matter 属性（避免 MCU2 重启后状态漂移）

### 11.2 消息类型（最小集）

- `EVT_KEY_CMD`（MCU1→MCU2）：遥控器命令事件
  - 字段：cmd(0x01..0x05/扩展)、src_mac、timestamp、group_mode/slot
- `EVT_LOCAL_STATE`（MCU1→MCU2）：MCU1 本地执行后的最终状态
  - 字段：endpoint/light_id、onoff、level、cct（如有）、transition_time
- `SET_STATE`（MCU2→MCU1）：来自 Matter 的控制请求
  - 字段：目标灯/组、onoff/level/cct、期望渐变时间
- `SET_MODE`（MCU2→MCU1）：模式切换（配对、清码、恢复出厂、进入测试模式）
- `HEARTBEAT`（双向）：存活与版本信息（fw_ver、proto_ver、uptime、heap）

建议补充类型：

- `GET_STATE`（MCU2→MCU1）：请求 MCU1 上报完整状态
- `EVT_DIAG`（双向）：错误码/计数器（CRC 错、丢包、重试次数、WDT、重启原因）

### 11.2.1 字段定义建议（便于落地与调试）

- `light_id`：1 byte
  - `0x01` 单色灯
  - `0x02` 双色温灯
- `onoff`：1 byte（0/1）
- `level`：1 byte（0..254，按 Matter 约定）
- `cct_mireds`：2 bytes（小端，按 Matter ColorTemperatureMireds）
- `transition_ms`：2 bytes（小端）
- `timestamp_ms`：4 bytes（小端，MCU1 uptime 毫秒）

### 11.3 一致性原则（避免双写打架）

- MCU1 为“灯输出唯一权威”（source of truth for physical output）。
- MCU2 为“ Matter 属性权威”（source of truth for ecosystem state）。
- MCU2 更新 Matter 属性应以 `EVT_LOCAL_STATE` 为准，而不是以 `EVT_KEY_CMD` 直接推导（防止执行失败/限幅/场景叠加导致不一致）。

## 11.4 PCB 连线清单（方案 A，UART）

- UART：
  - MCU1_TX -> MCU2_RX（GPIO 待定：MCU1=____ / MCU2=____）
  - MCU1_RX <- MCU2_TX（GPIO 待定：MCU1=____ / MCU2=____）
- 可选硬件流控（建议预留焊盘，量产可按稳定性决定是否启用）：
  - MCU1_RTS / MCU1_CTS
  - MCU2_RTS / MCU2_CTS
- 额外控制/中断线（建议预留）：
  - MCU2->MCU1 `RESET_REQ`（请求 MCU1 执行：清码/恢复出厂/重新配对/进入测试）
 - MCU1->MCU2 `IRQ_EVT`（有新事件/状态上报，降低轮询开销）
- 电平：两者均为 3.3V TTL（无需电平转换）
- 调试：建议预留测试点（TX/RX/GND）便于产线与现场抓包

## 13. 可对外汇报摘要（可直接发甲方）

本阶段已完成 ESP32-C6 Matter + ESP-NOW 混合固件的核心功能联调：固件已实现双 endpoint（单色灯 + 双色温灯）并通过 iOS Home 完成 Matter commissioning 与控制验证；同时接入甲方量产遥控器的 ESP-NOW 协议（channel=1、命令 0x01..0x05/0xA5），可通过“5 次重启进入配对模式 + 遥控器 Zone 配对”实现一台遥控器（Zone1/Zone2）分别绑定两台 ESP32-C6 灯具。当前 APP（iOS Home）与遥控器均可对两台设备进行控制；设备支持 HTTP OTA（远程服务器下载升级，支持双 OTA 分区切换），已验证升级后版本号变化。下一步将推进 Google Home/Alexa/RainMaker 等生态兼容性测试，并固化交付脚本、测试报告与完整技术文档。