VOV S7 Pro 新风系统接入 Home Assistant

DrChris

> 本文记录我把 VOV S7 Pro 新风系统接入 Home Assistant 的完整实战过程。

> 这不是官方方案，也不是安装一个 HACS 集成就能完成的标准教程。最终采用的路线是：**微信小程序抓包 → Reqable 验证接口 → Node-RED 调用厂商 HTTP API → 映射为 Home Assistant 实体 → 编写自动化**。

> 本文重点是路线、判断方法、控制逻辑和踩坑经验。账号、Token、设备 ID、家庭 ID、服务器地址等敏感内容均已脱敏。

一、项目目标

我的设备是 VOV S7 Pro 新风系统。官方通过微信小程序控制，但 Home Assistant 中没有现成的官方集成，网上也很难找到可以直接套用的成熟案例。

我希望最终实现：

- 在 Home Assistant 中控制设备电源；
- 控制新风风量和排风风量；
- 切换智能、睡眠和排风等模式；
- 控制负离子等附加功能；
- 在 HA 中显示设备回传的空气数据；
- 可以通过自动化、场景和 HomeKit/Siri 参与全屋联动；
- 尽量保留官方小程序本身的控制能力。

最终上述核心目标已经实现。

二、为什么没有直接走常规集成路线

面对一个没有现成 HA 集成的设备，我通常按下面的顺序判断：

1. Home Assistant 官方集成；
2. HACS 第三方集成；
3. 局域网协议、MQTT、Modbus 或开放 API；
4. Tuya、米家等已有生态的本地或云端接入；
5. 官方 App／微信小程序抓包；
6. 必要时才考虑硬件改造。

VOV S7 Pro 的实际情况是：没有找到可直接使用的 HA 集成，官方控制入口又是微信小程序。因此，与其一开始就拆机分析通信，更高效的切入点是观察小程序控制设备时究竟发出了什么网络请求。

这也是本项目最关键的判断：**小程序能控制设备，就意味着手机与服务器之间一定存在可复现的调用。**

三、整体架构

最终的数据路径如下：
———————————
Home Assistant
      ↓
Node-RED
      ↓ HTTP 请求
VOV 云端接口
      ↓
VOV S7 Pro
———————————

设备状态和空气数据则沿相反方向查询并回写到 HA。

需要说明的是，这套方案依赖厂商云端接口，并非纯局域网控制。只要接口地址、鉴权方式或小程序协议发生变化，就可能需要重新抓包调整。

四、准备工作

1.软件和环境

- Home Assistant；
- Node\-RED，并完成与 Home Assistant 的连接；
- 手机微信及能够正常控制设备的 VOV 小程序；
- Reqable，用于 HTTPS 抓包和请求重放；
- 一台与手机处于同一网络、便于运行 Reqable 的电脑。

2.抓包前必须理解的几个字段

实际字段名称可能随接口版本变化，但通常会遇到：

- 登录态或 Token；
- 用户 ID；
- 家庭／项目 ID；
- 设备 ID；
- 接口服务器地址；
- 请求签名、时间戳或随机数；
- `Content-Type`、`Authorization` 等请求头；
- 表示具体动作和档位的请求体。

五、第一阶段：抓取微信小程序的控制请求

1. 配置 Reqable

让手机流量经过 Reqable 所在电脑的代理，并在手机端安装、信任 Reqable 的 HTTPS 证书。配置完成后，先用普通网页测试是否能够看到 HTTPS 请求。

如果只能看到 CONNECT 或域名，看不到请求路径和正文，通常说明证书没有正确安装或信任，HTTPS 尚未成功解密。

2. 缩小抓包范围

微信本身会产生大量请求，因此不要一开始就在请求海洋里盲找。我的方法是每次只执行一个动作，并记录准确时间：

1. 清空或暂停现有记录；
2. 在小程序中只按一次“电源开”；
3. 立即暂停抓包并寻找新增请求；
4. 再分别测试电源关、新风档位、排风档位和各模式；
5. 比较相邻请求中哪些字段发生变化。

筛选时优先观察：

• 小程序操作瞬间出现的 POST 请求；
• 请求体中含设备 ID、档位、模式名称或布尔值的请求；
• 响应中出现成功码、设备状态或传感器数据的请求；
• 多次执行相同操作时结构稳定、仅参数变化的请求。

3. 建立“动作—请求”对照表

不要发现一个请求就急着写 Node-RED。先把官方小程序里的每个动作分别抓一遍，建立对照表。

本项目中确认可调用的控制类别包括：

|功能  |抓包中确认的命令／方法                       |
|----|----------------------------------|
|电源  |`power on`、`power off`            |
|新风风量|`freshairV1` ～ `freshairV10`      |
|排风风量|`exhaustAirV1` ～ `exhaustAirV10`  |
|负离子 |`negativeiOn`、`negativeiOFF`|
|睡眠模式|`sleep`                           |
|智能模式|`intelligent`                     |
|排风模式|`axhaust`                         |

这里的名称是抓包过程中用于区分动作的命令／方法标识，不代表所有机器、固件版本或服务器区域都一定完全相同。应以自己抓到的请求为准。

六、第二阶段：先在 Reqable 中重放，不要直接写 HA

找到疑似控制请求后，我没有马上进入 Node-RED，而是先使用 Reqable 的重放／编辑功能验证。

验证顺序如下：

1. 原封不动重放一次抓到的请求；
2. 确认设备实际产生对应动作；
3. 只修改一个参数，例如把新风档位从 1 改为 2；
4. 再次发送，观察设备动作；
5. 分别验证电源、档位、模式和附加功能；
6. 记录请求成功时的响应结构。

这一步非常重要，因为它能把问题分成两部分：

• Reqable 重放都失败：问题在接口、鉴权、请求字段或 Token；
• Reqable 成功、Node-RED 失败：问题才在 Node-RED 的请求构造。

否则一上来就在 HA 和 Node-RED 中调试，会同时面对实体、流程、HTTP、鉴权和设备五层问题，很难定位。

## 七、第三阶段：在 Node\-RED 中复现 HTTP 请求

### 1\. 最小可用流程

最初只需要四类节点：

```text
Inject／HA 触发节点
        ↓
Function 或 Change 节点
        ↓
HTTP Request 节点
        ↓
Debug 节点
```

Function／Change 节点负责准备：

- 请求方法；
- 已脱敏的接口 URL；
- 必要的 Headers；
- JSON 请求体；
- 设备 ID 和动作参数。

HTTP Request 节点发送请求，Debug 节点必须在初期保留，用来观察状态码和响应正文。不要只看节点有没有变绿；HTTP 200 也不一定代表设备动作成功，还要检查业务返回码。

2. 请求结构示意

以下只是结构示意，字段名必须换成自己抓到的真实内容：
————————————————————
javascript
msg.method = "POST";
msg.url = "https://<VOV_API_HOST>/<CONTROL_PATH>";
msg.headers = {
  "Content-Type": "application/json",
  "Authorization": "<TOKEN>"
};
msg.payload = {
  "deviceId": "<DEVICE_ID>",
  "command": "<CAPTURED_COMMAND>"
};
return msg;
———————————————————
不要直接照抄这段字段名称。正确做法是把 Reqable 中已验证成功的 URL、Header 和 Body 等比例迁移到 Node-RED。

3. 建议把凭据与动作分开

为了后期维护，不要在十几个 Function 节点中各复制一遍 Token 和设备 ID。可以将固定参数集中放在安全的环境变量、Node-RED 凭据配置或统一的子流程中；各动作节点只传递命令。

这样 Token 变化时只需要改一处，也能降低导出流程时意外泄露凭据的风险。

八、第四阶段：映射成 Home Assistant 实体

单纯在 Node\-RED 中点 Inject 已经能控制设备，但真正实用的目标是把它包装成 HA 能理解的实体。

本项目最终形成的核心实体包括：

- 电源开关：`switch.vov_s7_pro_dian_yuan`；
- 排风控制：`fan.vov_s7_pro_pai_feng`；
- 新风／排风风量选择；
- 负离子开关；
- 智能、睡眠和排风等模式控制；

1. 为什么风量适合使用 fan 或 select

我早期考虑过把风量映射到 `climate`，但实际并不理想。新风机的核心是开关、送风、排风、档位和工作模式，不是恒温器。最后使用 `fan` 配合 `select`／滑块更符合设备语义，也更容易维护。

建议分工：

- `switch`：电源、负离子等二态功能；
- `fan`：主风机或排风机的开关与速度；
- `select`：明确的档位或模式枚举；
- `button`：只执行一次、不保持状态的模式指令。

2. 档位映射

抓包得到的是 `freshairV1`～`freshairV10`、`exhaustAirV1`～`exhaustAirV10` 这样的命令，而 HA 的 fan 常使用百分比。因此需要建立一张固定映射表，避免在不同流程中各自换算。

九、VOV S7 Pro 最关键的控制约束

项目完成后，真正容易出错的并不是“请求能不能发出去”，而是不同风路和模式之间存在联动关系。

我最终采用并验证的手动调速逻辑是：

- 手动调整排风时，新风自动设为 1；
- 手动调整新风时，排风自动设为 1；
- 手动调速时，智能、睡眠、排风等互斥模式需要退出；
- 睡眠模式下，新风和排风可进入 0，而普通手动档位本身不能直接调到 0；
- 智能模式由设备自动调整风量；
- 单独排风模式下，新风为 0、排风为 1。

这套逻辑经历过调整。早期也测试过“调整一侧时，另一侧设为 0”的方案，但实际使用后改成另一侧保持 1，更符合日常通风需求。

因此，帖子读者不应只复制单个 HTTP 请求，还要理解整套状态机。否则 HA 显示的状态与设备实际模式很容易互相打架。

十、状态同步：能控制不等于接入完成

只实现 HA → 设备的单向控制，会出现一个明显问题：在官方小程序中调整设备后，HA 不知道状态已经改变。

完整方案应增加状态查询流程：

1. 定时调用设备状态接口；
2. 解析返回 JSON；
3. 分别提取电源、风量、模式和传感器数据；
4. 写回对应 HA 实体；
5. 对控制后的短时间内查询做适当延迟，避免云端尚未更新就把旧值写回来。

十一、项目中踩过的坑

1.  把“发现请求”误认为“接口已经搞定”

抓到一个看似相关的请求并不代表它能独立重放。必须确认鉴权字段、设备字段、时间戳以及请求体是否完整，并以设备实际动作为准。

2.  一开始就做完整 HA 面板

如果没有先在 Reqable 中验证，再直接堆 HA 实体和 Node\-RED 流程，任何失败都很难判断是哪一层造成的。正确顺序应是：单请求重放成功 → Node\-RED Inject 成功 → HA 单实体成功 → 再做模式联动和界面。

3. 用 climate 表达新风机

虽然 `climate` 看起来功能很多，但设备并不是空调。最终用 fan、select、switch 和 sensor 分拆，语义和控制都更清楚。

4. 只做控制，不做回读

这会导致小程序、设备和 HA 三边状态不一致。即使暂时无法做到实时推送，也应至少增加定时查询和控制后的延迟回读。

5. 忽略模式互斥

智能、睡眠、排风和手动调速不是可以任意叠加的独立开关。若不在流程中统一管理，HA 可能显示“智能模式开启”，同时又在发送固定档位命令。

6. 调试完成后忘记保护 Token

Node-RED 导出 JSON、Reqable 会话、截图、Debug 输出都可能包含 Token、Cookie、用户 ID、设备 ID 和服务器地址。分享前必须逐项检查。

十二、当前成果与局限

目前我的 VOV S7 Pro 已经完成：

• 微信小程序接口抓取；
• Reqable 请求重放；
• Node-RED 调用控制接口；
• 电源、新风、排风、风量、模式和负离子控制；
• HA 实体映射；
• 手动模式与智能／睡眠／排风模式的联动；
• 十分钟未调整后，按时段自动恢复智能或睡眠模式。

目前方案的主要局限：

• 依赖厂商云端和有效鉴权；
• Token 或接口协议变化后可能需要重新抓包；
• 不同固件、账号区域或小程序版本的字段；
• 本文没有公开任何可复用的私人 Token、设备 ID 或完整请求地址。

十三 、结语

这个项目真正有价值的地方，不只是把一台 VOV S7 Pro 接进了 Home Assistant，而是验证了一条可以复用的路线。灵感是来自要接入海尔智家用了Reqable抓取refresh token，以此为延伸联想到用相同的方法抓取VOV S7Pro的数据包。

如果后续接口发生变化，我也会继续更新本文。