pgchenu/airwell-ir-homeassistant

# airwell-ir-homeassistant 本仓库记录了我成功将那台极其老旧的 Airwell 空调（型号 stxlm9rc）与其糟糕透顶的“RC-4”红外遥控器进行集成的过程。不过你很幸运，我不会在这里分享我接线时的挣扎、在 Broadlink RM4 mini 上浪费的无数个小时，也不会诉说面对严重腐蚀的 RC-4 时的那种绝望。 本仓库记录了我成功将那台极其老旧的 Airwell 空调（型号 stxlm9rc）与其糟糕透顶的“RC-4”红外遥控器进行集成的过程。 Airwell RC4 使用 **`AIRWELL`** 协议（34位 Manchester 编码 @ 38 kHz，如 IRremoteESP8266 中所实现）。Airwell 设备是贴牌的 **Electra**，因此这很可能适用于其他 Electra 系列的遥控器。 在大多数情况下，Home Assistant 的集成都能正常工作。然而，你会受到糟糕的红外发射的困扰，这会导致空调的实际状态与 Home Assistant 上的空调接口状态不同步。我添加了一些按钮来强制开启/关闭空调，并实现“虚拟”同步空调状态。 ## 警告 我不是开发者，也不是软件工程师。只是一个有大把时间并且订阅了 Claude 的人。你可以猜到，这一切全凭“凭感觉编程”（vibe coding）。尽管如此，它的运行效果却出奇地好。 我有一些发现，主要是关于 ESPHome 的。你可以在 [`doc.md`](doc.md) 中阅读它们。 ## 状态 — 正常工作 - ✅ ESP32 (Tasmota-ir) 发送 AIRWELL 帧；空调有反应。 - ✅ 完整的状态合成（模式 / 风扇 / 温度），无需捕获 —— 已针对真实的遥控器进行了验证。 - ✅ 带有正确**电源切换**处理的终端控制。 - ✅ Home Assistant `climate` 实体 → 可暴露给 Apple HomeKit。 ## 工作原理（1分钟版本） - 当 *I FEEL* 关闭时，这 34 位的帧是 **(电源, 模式, 风扇, 温度)** 的确定性函数（中间的 5 位是 I FEEL 室温字段；关闭时为 `0` → 无校验和）。目前不支持 “I FEEL” 功能。 - **模式/风扇/温度是绝对且幂等的。** **电源（第 33 位）是一个真正的切换开关（TRUE TOGGLE）**，而且红外是单向的 —— 因此我们追踪一个**假设的**电源状态，并且只有在它需要改变时才发送切换指令。 - 一个小编码器将状态转换为数值；Tasmota 的 `IRSend AIRWELL` 负责发送它。 帧布局（MSB 优先）： | 位 | 字段 | |---|---| | 33 | 电源切换 (1 = 切换电源 + 应用状态；0 = 仅状态) | | 32–30 | 模式: COOL=1 HEAT=2 AUTO=3 DEHUM=4 FAN=5 | | 29–28 | 风扇: 字段 = 风速−1 (风速 1–4) | | 27–23 | I FEEL 室温 (0 = 关闭) | | 22–19 | 温度: 字段 = °C−15 (16–30 °C) | | 18–0 | 恒定尾部 `0x2` | 每个帧重复发送三次。 `encode(power=0, COOL, fan=2, temp=22) == 0x050380002` ## 硬件 - ESP32（任意型号；ESP32-D 即可）+ **2N2222** 三极管 + **950 nm 红外 LED** + 电阻，LED 由 **GPIO25** 驱动。（参见 `images/driver_schematic.jpg`，见*下文*。） - 刷入 **Tasmota-ir** (`tasmota32-ir`)，GPIO25 设置为 `IRsend`。  ## 仓库结构 | 路径 | 内容 | |---|---| | [`airwell.py`](airwell.py) | AIRWELL 34位编码/解码器（唯一事实来源）。`uv run airwell.py selftest` | | [`ac_ctl.py`](ac_ctl.py) | 通过 Tasmota HTTP 进行终端控制，包含假设状态切换逻辑 | | [`airwell_ac.yaml`](airwell_ac.yaml) | HA 包 —— `climate.airwell_ac` 恒温器 + 重新同步按钮 | | [`HA_SETUP.md`](HA_SETUP.md) | Home Assistant + HomeKit 设置指南 | | [`doc.md`](doc.md) | 项目备忘 / 发现 | | [`plan.md`](plan.md) | 工作笔记 | | [`TUTORIAL.md`](TUTORIAL.md) | 完整的逐步复制指南 | | `send_rm4.py`, `capture_rm4.py` | Broadlink RM4 脚本 —— *已废弃*（RM4 发射器太弱）；仅作保留以供参考 | ## 快速开始 ``` # 1. 验证 encoder uv run airwell.py selftest # 2. 向你的 Tasmota blaster 发送一个 frame（AC 应该会有反应） curl 'http:///cm?cmnd=IRSend%20%7B%22Protocol%22%3A%22AIRWELL%22%2C%22Bits%22%3A34%2C%22Data%22%3A%220x250380002%22%7D' # 3. 终端控制（记住 host + 假设状态） uv run ac_ctl.py on --host uv run ac_ctl.py set --temp 24 uv run ac_ctl.py off ``` Home Assistant + HomeKit：参见 [`HA_SETUP.md`](HA_SETUP.md) 和 `TUTORIAL.md`。 Python 依赖项以行内方式声明 (PEP 723)；使用 **`uv run`** 运行脚本 —— 它会自动安装依赖。 ## 致谢 - [petrklus/airwellhvac](https://github.com/petrklus/airwellhvac) —— 原始的 RC4 逆向工程。非常感谢 [Petr Klus](https://github.com/petrklus) 为我的遥控器所做的出色工作。他让我得以证实我的观察结果。 - [IRremoteESP8266](https://github.com/crankyoldgit/IRremoteESP8266) —— `AIRWELL` 协议。 - [Tasmota](https://tasmota.github.io/)，[jcwillox/hass-template-climate](https://github.com/jcwillox/hass-template-climate)。

标签：ESP32, Home Assistant, 智能家居, 物联网, 空调控制, 红外遥控, 逆向工具