ripe-avocado/miro_ha
GitHub: ripe-avocado/miro_ha
一个 Home Assistant 自定义集成，通过非官方云 API 将 MIRO 品牌智能设备直接接入 HA，完整保留精细控制参数并支持 27 种设备型号。
Stars: 0 | Forks: 0
# MIRO SmartHome (MIRO SmartHome) — Home Assistant 集成
无需经过 SmartThings，将 MIRO 设备直接连接到 Home Assistant。
直接使用 MIRO SmartHome 应用 (`com.miro.mirotapp`) 所使用的非官方云 API。
与在 SmartThings 集成中被强制归类为 4 档风量和 2 种旋转不同，
本集成完全保留了 **1~100 档风量以及 0/30/60/90/120 度的旋转角度**。
## 支持设备
由于我们直接将应用服务器返回的设备定义制作成表格 (`models.json`) 并使用，
因此以下 27 种设备的控制值范围并非推测，而是 **与官方应用完全一致**。
| 分类 | 型号 | HA 实体 |
| --- | --- | --- |
| 风扇 | MF01, MF02, **MF03**, MAF01 | `fan` |
| 循环扇 | MC01 | `fan` |
| 空气净化器 | MP500G, MP600G, MPUV20, MPUV24, AP500, OSHS01, MP1000~1003 | `fan` |
| 加湿器 | NR07, NR08, NR10, AR05, MH5000, MH7000, MH8K, MH9K | `humidifier` |
| 香薰机 | DF01, DIF01, DIF02 | `switch` + `select` |
| 传感器 | RD01 | `switch` + 传感器 |
将空气净化器创建为 `fan` 是 Home Assistant 的惯例。
### 验证级别 — 请务必阅读
| 状态 | 对象 |
| --- | --- |
| **真机验证** | **MF03** (风扇) — 电源、风量、旋转、模式控制，温湿度及电池状态
**NR07** (加湿器) — 电源控制，喷雾强度自动切换，缺水检测 | | 仅验证定义 | 其余 25 种 — 我们已通过服务器元数据和实际设备定义 (`feature`) 确认了实体配置，但 **未能向真机发送实际测试命令** | 由于我们确认了风扇和加湿器 **完全使用相同的 API 运行**，因此结构相同的 空气净化器、循环扇和香薰机也很可能正常运行。但对此我们无法提供保证。 如果遇到问题，请通过 issue 告知我们，我们会尽力修复。 ## 生成的实体 这是通过交叉比对设备实际报告的功能列表 (`feature`) 和型号表来生成的。 **型号不具备的功能不会生成对应的实体。** | 实体 | 示例 | | --- | --- | | `fan` | 电源、风量、运行模式、左右旋转 | | `humidifier` | 电源、运行模式、当前湿度 | | `sensor` | 温度、湿度、**电池余量**、细粉尘、气体、CO₂、照度、滤芯余量、定时器剩余时间 | | `binary_sensor` | **充电中**、已安装电池、缺水、更换滤芯、连接状态 | | `select` | 旋转范围、定时器、喷雾强度、照明、亮度、香味、喷射级别等 | | `switch` | 童锁、提示音、紫外线杀菌、上下旋转等 | 部分实体（定时器剩余时间、已安装电池、连接状态）默认处于禁用状态。 如有需要，请在设备页面中手动开启。 ### 特意不生成的项 对于无法确定数值体系的项目，我们 **绝对不会靠推测去发送命令。** 相反，我们会在安装时将跳过的内容记录在日志中。 - MF03 的舒适模式详细设置 (`Bias`, `FanSpeedHigh/Low`, `SensorTemperature/Humidity`) - 加湿器的目标湿度阈值 (`HumidityRule1~3`) - NR08 的关闭照明 (`LightMode` — 因为无法从应用定义中找到开启该功能的具体数值) ## 安装 ### HACS 1. HACS → 右上角 ⋮ → **Custom repositories** 2. 输入本存储库地址，并在类别中选择 **Integration** 3. 从列表中安装 `MIRO SmartHome` 4. **重启 Home Assistant** ### 手动复制 将 `custom_components/mirot/` 文件夹复制到 HA 配置目录下的 `custom_components/` 中，然后重新启动。 ## 配置 **设置 → 设备与服务 → 添加集成 → MIRO SmartHome** 输入 MIRO SmartHome 应用所使用的 **账号和密码**，系统将自动发现设备。 您可以在集成卡片的 **配置** 中更改状态轮询间隔（默认为 5 秒，可设为 5~300 秒）。 ## 工作原理 MIRO 服务器不提供 MQTT 或 WebSocket 推送，只能进行轮询。 我们在每个轮询周期都会附加 `sync` 选项进行查询，该请求会向设备下达“上报状态”的指令， 并返回 **上一周期的旧值**。新值会在约 1 秒后写入服务器缓存，并在下个周期被读取到。 因此，状态信息的滞后最多只会保持 **在一个轮询周期以内**。 即使您使用遥控器或设备本体按键进行操作，HA 也会在轮询周期内同步更新状态。 当您发送控制命令时，系统会立刻重新读取状态，以便加快同步速度。 由于设备通过无线方式连接，有时可能会漏掉某个周期的响应。此时， 我们将使用服务器缓存的数据进行替代；如果这也失败了， 我们最多会在 **连续 3 次** 内保持上一次的有效值。 不会因为单次延迟而导致实体闪烁变为 `unavailable` 状态。 ## 注意事项 - **调节风量会自动开启处于关闭状态的设备。** 设备的默认机制即是如此。 - **在自动、自然或睡眠模式下，无法直接更改风量。** 集成系统会自动 先将其切换到手动模式，然后再应用风量设置。 - 如果将旋转范围设置为非 0 的值，旋转功能将被开启；如果设为 0，则会被关闭。此功能已与设备同步。 - **加湿器开启电源时，喷雾强度会自动设为“微弱”。** 您无需单独指定强度。 - **缺水状态 (`EmptyWater`) 仅在设备运行期间显示。** 如果关闭电源，即使没水该状态也会被解除， 请在编写通知自动化时留意这一点。 - 部分型号可能不会上报温湿度传感器的数据。例如 NR07 加湿器的温湿度传感器位于 无线遥控器上，如果遥控器未上报数据，对应实体将保持为 `unavailable` 状态。 - 网络连接中断的设备，其实体会显示为 `unavailable`。 - 如果您使用了未包含在表格中的新型号，则只会生成 On/Off 控制和传感器。 您可以使用 `python3 tools/gen_models.py --download` 命令来更新型号表。 ## 工具 - [tools/miro_cli.py](tools/miro_cli.py) — 用于在不依赖 HA 的情况下直接测试 API 的 CLI。 用于排查问题是由集成端还是服务器端引起的。**请在提交 issue 时附上使用该工具导出的输出结果。** - [tools/gen_models.py](tools/gen_models.py) — 从服务器元数据生成型号表。 ``` pip3 install requests cryptography python3 tools/miro_cli.py login python3 tools/miro_cli.py devices python3 tools/miro_cli.py status ``` ## 许可证 MIT
**NR07** (加湿器) — 电源控制，喷雾强度自动切换，缺水检测 | | 仅验证定义 | 其余 25 种 — 我们已通过服务器元数据和实际设备定义 (`feature`) 确认了实体配置，但 **未能向真机发送实际测试命令** | 由于我们确认了风扇和加湿器 **完全使用相同的 API 运行**，因此结构相同的 空气净化器、循环扇和香薰机也很可能正常运行。但对此我们无法提供保证。 如果遇到问题，请通过 issue 告知我们，我们会尽力修复。 ## 生成的实体 这是通过交叉比对设备实际报告的功能列表 (`feature`) 和型号表来生成的。 **型号不具备的功能不会生成对应的实体。** | 实体 | 示例 | | --- | --- | | `fan` | 电源、风量、运行模式、左右旋转 | | `humidifier` | 电源、运行模式、当前湿度 | | `sensor` | 温度、湿度、**电池余量**、细粉尘、气体、CO₂、照度、滤芯余量、定时器剩余时间 | | `binary_sensor` | **充电中**、已安装电池、缺水、更换滤芯、连接状态 | | `select` | 旋转范围、定时器、喷雾强度、照明、亮度、香味、喷射级别等 | | `switch` | 童锁、提示音、紫外线杀菌、上下旋转等 | 部分实体（定时器剩余时间、已安装电池、连接状态）默认处于禁用状态。 如有需要，请在设备页面中手动开启。 ### 特意不生成的项 对于无法确定数值体系的项目，我们 **绝对不会靠推测去发送命令。** 相反，我们会在安装时将跳过的内容记录在日志中。 - MF03 的舒适模式详细设置 (`Bias`, `FanSpeedHigh/Low`, `SensorTemperature/Humidity`) - 加湿器的目标湿度阈值 (`HumidityRule1~3`) - NR08 的关闭照明 (`LightMode` — 因为无法从应用定义中找到开启该功能的具体数值) ## 安装 ### HACS 1. HACS → 右上角 ⋮ → **Custom repositories** 2. 输入本存储库地址，并在类别中选择 **Integration** 3. 从列表中安装 `MIRO SmartHome` 4. **重启 Home Assistant** ### 手动复制 将 `custom_components/mirot/` 文件夹复制到 HA 配置目录下的 `custom_components/` 中，然后重新启动。 ## 配置 **设置 → 设备与服务 → 添加集成 → MIRO SmartHome** 输入 MIRO SmartHome 应用所使用的 **账号和密码**，系统将自动发现设备。 您可以在集成卡片的 **配置** 中更改状态轮询间隔（默认为 5 秒，可设为 5~300 秒）。 ## 工作原理 MIRO 服务器不提供 MQTT 或 WebSocket 推送，只能进行轮询。 我们在每个轮询周期都会附加 `sync` 选项进行查询，该请求会向设备下达“上报状态”的指令， 并返回 **上一周期的旧值**。新值会在约 1 秒后写入服务器缓存，并在下个周期被读取到。 因此，状态信息的滞后最多只会保持 **在一个轮询周期以内**。 即使您使用遥控器或设备本体按键进行操作，HA 也会在轮询周期内同步更新状态。 当您发送控制命令时，系统会立刻重新读取状态，以便加快同步速度。 由于设备通过无线方式连接，有时可能会漏掉某个周期的响应。此时， 我们将使用服务器缓存的数据进行替代；如果这也失败了， 我们最多会在 **连续 3 次** 内保持上一次的有效值。 不会因为单次延迟而导致实体闪烁变为 `unavailable` 状态。 ## 注意事项 - **调节风量会自动开启处于关闭状态的设备。** 设备的默认机制即是如此。 - **在自动、自然或睡眠模式下，无法直接更改风量。** 集成系统会自动 先将其切换到手动模式，然后再应用风量设置。 - 如果将旋转范围设置为非 0 的值，旋转功能将被开启；如果设为 0，则会被关闭。此功能已与设备同步。 - **加湿器开启电源时，喷雾强度会自动设为“微弱”。** 您无需单独指定强度。 - **缺水状态 (`EmptyWater`) 仅在设备运行期间显示。** 如果关闭电源，即使没水该状态也会被解除， 请在编写通知自动化时留意这一点。 - 部分型号可能不会上报温湿度传感器的数据。例如 NR07 加湿器的温湿度传感器位于 无线遥控器上，如果遥控器未上报数据，对应实体将保持为 `unavailable` 状态。 - 网络连接中断的设备，其实体会显示为 `unavailable`。 - 如果您使用了未包含在表格中的新型号，则只会生成 On/Off 控制和传感器。 您可以使用 `python3 tools/gen_models.py --download` 命令来更新型号表。 ## 工具 - [tools/miro_cli.py](tools/miro_cli.py) — 用于在不依赖 HA 的情况下直接测试 API 的 CLI。 用于排查问题是由集成端还是服务器端引起的。**请在提交 issue 时附上使用该工具导出的输出结果。** - [tools/gen_models.py](tools/gen_models.py) — 从服务器元数据生成型号表。 ``` pip3 install requests cryptography python3 tools/miro_cli.py login python3 tools/miro_cli.py devices python3 tools/miro_cli.py status ``` ## 许可证 MIT
标签：API 集成, Home Assistant, 智能家居, 智能家电控制, 物联网, 逆向工具