AndrewDemsDS/hisense-w41h1

# 海信 AEH-W41H1 — 通过自定义 Matter 固件实现去云化 将海信 **`AEH-W41H1`** 空调 Wi-Fi 模块（Realtek **RTL8710C / AmebaZ2**）上的 ConnectLife 云替换为自定义 **Matter** 固件，实现通过 Home Assistant 进行本地控制 — **完全去云化**。 **用户指南：** 操作和开发者指南（调试、HA 控制、OTA、恢复、构建流水线）位于 [`firmware/docs/`](firmware/docs/) 和 [`reverse-engineering/docs/`](reverse-engineering/docs/) 中。 ## 您将获得 - **本地 Matter 控制** — 空调可调试接入 `python-matter-server` / Home Assistant；无需 ConnectLife，无需 `hijuconn` 云。 - **完整的控制面板** — HVAC 模式（包括 Auto）、设定温度（16–32 °C）、风速（6 档）、垂直摆风，以及 Eco / Quiet / Turbo / Sleep 等特殊模式。 - **能耗监控** — 实时功率（W）+ 电压，根据总线电流代理推导得出。 - **通过 Wi-Fi 进行 OTA 更新** — 首次使用 CH341 刷入后，其余所有更新均可无线进行。 ## 工作原理 ``` Home Assistant ─┬─ python-matter-server ── Matter/Wi-Fi ──► RTL8710C module (custom AmebaZ2 Matter firmware) │ RS-485 (9600 8N1) ▼ A/C mainboard ``` 该模块运行 Realtek AmebaZ2 Matter `room_air_conditioner` 示例，并通过**我们的 RS-485 驱动**桥接 Matter 属性 ↔ 空调内部 RS-485 总线（协议已进行逆向工程 + 嗅探验证 — 参见 [`reverse-engineering/docs/03`](reverse-engineering/docs/03-rs485-ac-protocol.md))。 ## 硬件 | | | |---|---| | SoC | Realtek RTL8710C (AmebaZ2)，安全启动 **关闭** | | Flash | GD25Q32 4 MB (JEDEC `c84016`) | | A/C 总线 | UART0 **TX=PA_14 RX=PA_13** @ 9600 8N1 (无 DE/RE)；日志控制台 PA_16 | | 模块端口 | 4 针：**5 V · GND · RS-485 A · B**（由空调供电 — 实验室电源会导致无线电掉电） | | 首次刷写 | CH341A SPI 编程器 + GD25Q32 上的 SOIC-8 夹（之后永远使用 OTA） | ## 仓库结构 | 路径 | 内容 | |---|---| | `firmware/src/rs485-driver/` | 总线驱动 (`hisense_rs485.{h,cpp}`) + 纯粹的 `matter_aircon_map.h` + `power_estimate.h` — **我们的代码 (MIT)** | | `firmware/src/sdk-edits/` | Matter 集成：`matter_drivers.cpp` 胶水代码、`.zap`、`0xFFF1FC00` 厂商集群定义，以及 `core-patches/` — 外加记录了每一处 SDK 原地修改的 `README.md` | | `firmware/scripts/` | `ota-release.sh` (构建/打包/刷写/OTA)、`gen-creds.sh`、Matter 辅助工具 | | `firmware/flasher/` | pyusb CH341A 刷写工具（按扇区验证 + 重试 — 使用此工具，**而不是 flashrom**） | | `firmware/test/` | 无硬件 QA — 主机编解码器 + Matter 映射测试 + `virtual_ac.py` 模拟器 | | `firmware/docs/` | 接线图、认证、QA 策略、能耗监控，以及 OTA/构建流程 (`10-firmware-ota-procedure.md`) | | `reverse-engineering/` | 协议/硬件/云/OTA 逆向工程，`tools/` (嗅探器、解码器)，`esphome/` (ESP32 替换配置) | | `patches/` | 您对两个 SDK 的差异补丁（可通过 `git apply` 应用；基础提交记录在 [`NOTICE.md`](NOTICE.md) 中） | | `dumps/` | ⚠️ **仅限本地，已 gitignore 忽略** — 原始闪存内容（Wi-Fi 凭据 + 设备 RSA 密钥 + 厂商 blob）。切勿公开。 | ## 快速开始 ### 1. 前置条件 - 带有 `arm-none-eabi` 工具链和 Python 3 的 Linux 系统。 - **Realtek AmebaZ2 SDK** 及其 **Matter 组件**，以及 **connectedhomeip**，版本需锁定在 [`NOTICE.md`](NOTICE.md) 中指定的提交。**这些不包含在内**（Realtek 的 SDK 是专有的）。 - **CH341A** 编程器 + SOIC-8 夹（仅限首次刷写）。 - 运行带有 `--enable-test-net-dcl`（测试认证）的 `python-matter-server` + Home Assistant。 ### 2. 设置构建树（两个步骤，按顺序执行） ``` firmware/setup.sh # 1) fetch the 3 SDKs into ~/ameba-dev + check out the pinned commits scripts/setup.sh # 2) apply patches/ + the Matter-overlay edits, copy our source in ``` 版本锁定信息位于 [`versions.env`](versions.env)；完整的出处 + 许可在 [`UPSTREAM.md`](UPSTREAM.md) 中。 使用 `--recurse-submodules` 克隆，以同时获取 `integrations/` 下的 HA 配套集成。 ### 3.（可选）您自己的调试凭据 ``` firmware/scripts/gen-creds.sh # unique discriminator + passcode (don't ship the shared test code) ``` ### 4. 构建 ``` firmware/scripts/ota-release.sh build # → firmware_is.bin (+ clip image + .ota) ``` ### 5. 首次刷写（CH341，仅需一次） 从 [Releases](https://github.com/AndrewDemsDS/hisense-w41h1/releases) 下载预构建镜像（每个 `amebaz2-vX.Y.Z` / `esp32-vX.Y.Z` 标签都附带了构建好的二进制文件 + `SHA256SUMS`），或者在第 4 步自行构建。然后： ``` python3 firmware/flasher/ch341flash.py firmware/built-images/flash_rac-integrated-vN.bin ``` 仅写入 `0x0–0x140000` 会保留 Matter 调试 KV → 更新时无需重新调试。 ### 6. 调试接入 打开配对窗口（遥控器 **Horizon Airflow × 6 → 显示 "77"**），然后调试接入 `python-matter-server`（使用您在第 3 步生成的代码，或 SDK 测试代码 `34970112332`）。在 HA 中添加 Matter 集成并控制空调。 ### 7. 更新 — OTA，无需夹子 ``` firmware/scripts/ota-release.sh release --bump --flash ``` ## 发布与 CI 每次推送/PR 时都会运行仅主机的 lint 门禁（编解码器 + Matter 映射 + 虚拟 AC + `.zap` 连续性 + 版本）。推送签名标签会构建并发布附带了固件的 GitHub Release： `amebaz2-vX.Y.Z`（版本号来自 `firmware/src/version.txt`）和 `esp32-vX.Y.Z`（来自 `firmware/esp32-matter/CMakeLists.txt` 的 `PROJECT_VER`）。这两个发布构建都在一个持有 Realtek SDK + ESP-IDF/esp-matter 的自托管 `sdk-builder` runner 上运行；有关 runner 的设置，请参见 wiki 上的构建流水线页面。 ## 认证与凭据 CSA **测试** 凭据（VID `0xFFF1`/PID `0x8001`）— 仅用于开发，未获认证。详情见：[`NOTICE.md`](NOTICE.md#matter-credentials)。 ## 为您的整个家庭去云化 一旦本地控制正常工作，请阻止模块的 WAN 出站流量（拒绝 `*.hijuconn.com` + OTA 主机） — 参见 [`reverse-engineering/docs/04`](reverse-engineering/docs/04-cloud-and-firewall.md)。关于通过空中刷写（OTA）**其他**设备（通过原厂固件中休眠的 Matter stack，无需 CH341）的研究在 [issues](https://github.com/AndrewDemsDS/hisense-w41h1/issues) 中进行追踪 (Fleet-OTA)。 ## AI 协助 我在代码、逆向工程和文档方面借助了 AI 协助来构建此项目。提交记录中带有 `Assisted-by: AI` 尾缀。 ## 许可 原始代码和文档：**MIT** ([`LICENSE`](LICENSE))。第三方组件（Realtek SDK — 专有，未在本仓库内置；connectedhomeip — Apache-2.0）以及凭据注意事项：[`NOTICE.md`](NOTICE.md)。

标签：Home Assistant, Matter协议, RS-485通信, 嵌入式固件, 智能家居, 本地控制, 物联网, 逆向工具