Bewinxed/philips-homerun-xu7100-local

 # Philips HomeRun XU7100 Local（非官方） 为 Philips HomeRun XU7100 扫地机器人提供本地控制。它通过 LAN 使用 Tuya 协议直接与机器人通信，因此清扫、地图构建、诊断和自定义语音包均可脱离云端运行。它提供了一个 Web UI、一个 JSON API 以及一个 Home Assistant 集成。 ## 兼容性 基于 **Philips HomeRun XU7100**（ODM 名称“Dustin 7100”，固件 4.6.49）构建并验证。未在其他型号设备上进行测试。 Philips HomeRun 系列的其他产品（例如 XU3000、XU5000 和 XU9000 系列）以及其他基于 Tuya 的激光扫地机器人共享相同的协议族，因此大部分内容在经过一些数据点调整后很可能是适用的。确切的数据点编号和命令帧是从某一台特定机器人上读取的，因此请将它们视为一个很好的参考起点，而不是对其他型号的保证。在写入数据点之前，请使用 `./homerun learn` 和 `./homerun sniff` 确认您设备上的数据点。 ## 开发初衷 这台机器人不再返回充电基座，并卡在了一张旧地图上。恢复出厂设置无济于事，且没有本地维修选项。这个项目正是通过对它网络通信方式的逆向工程诞生的，从而让它可以完全在局域网内运行，而无需被更换。 最初的问题结果证明是机械方面的，而不是传感器故障。完整的分析记录在 [docs/ROOT_CAUSE.md](docs/ROOT_CAUSE.md) 中。简而言之：充电基座坡道边缘比地板略微凸起，防撞板将其识别为墙壁，而每次对接失败都让机器人以为自己被绑架了，从而丢弃了本次会话的地图。在坡道下方垫一个薄垫片就解决了这个问题。 ## 功能说明 - **直接局域网控制。** 通过 6668 端口上的 Tuya 3.3 协议进行启动、暂停、停止、回充和定位。控制操作无需经过云端往返。 - **实时状态。** 状态、电量、吸力、水量、当前任务和故障，通过 Server-Sent Events (SSE) 流式传输到 UI。 - **交互式地图。** 机器人以逐像素 ID 的形式存储房间，没有多边形数据，因此地图是从光栅数据解码的，房间轮廓也是从中追踪出来的。您可以选择房间、设置每个房间的吸力和清扫次数，还可以进行重命名和合并。 - **自定义语音包。** 用主机通过局域网提供的自定义音频替换机器人的 75 条语音提示中的任意一条。包含一个 Voice Studio，可以编写文本、使用 ElevenLabs 生成语音，并将语音包安装到机器人上。详情请参阅 [docs/VOICE_PACKS.md](docs/VOICE_PACKS.md)。 - **诊断。** 易耗品磨损情况、寿命总计、模式切换以及解码后的故障位图。 - **Home Assistant。** `homeassistant/` 下的自定义组件可暴露扫地机器人实体。 - **模拟器。** 在未配置 `local_key` 的情况下，整个技术栈可针对内存中的模拟机器人运行，方便您进行开发测试。 ## 工作原理 该机器人运行在 Tuya Linux SDK 主板上。控制数据点作为小型 AES 加密帧通过局域网传输，这就是为什么可以直接进行本地控制而无需依赖云端的原因。地图是一个例外：激光扫地机器人通过 Tuya P2P 或云端传输地图数据，而不是局域网数据点通道，因此存储的地图是通过 Tuya 云 API 获取并在本地渲染的。 ``` flowchart TD UI["Web UI
Svelte 5 + Tailwind"] -->|REST + SSE| SRV HA["Home Assistant"] -->|REST| SRV["backend/server.py
Flask API"] SRV --> CTRL["controller
real robot or simulator"] CTRL -->|"LAN · tinytuya · AES · port 6668"| ROBOT(["Robot
Tuya 3.3"]) SRV -->|stored-map fetch| CLOUD["Tuya cloud OpenAPI"] CLOUD --> MAP["map_vector.py
decode raster + trace rooms"] MAP --> SRV ``` 核心模块： - `backend/controller.py` 将语义操作映射到 Tuya 数据点，并在同一接口下提供真实后端和模拟器。 - `backend/voice_studio.py` 和 `backend/custom_voice.py` 负责构建并安装语音包。 - `backend/room_overrides.py` 在本地存储您的重命名和合并操作，因为机器人无法通过局域网应用这些更改。 - `backend/map_vector.py` 负责从光栅图像中追踪房间轮廓。 - `backend/tuya_cloud.py` 负责签名并调用 Tuya 云 OpenAPI 以获取存储的地图。 命令协议、数据点映射和语音帧格式记录在 [docs/COMMAND_PROTOCOL.md](docs/COMMAND_PROTOCOL.md) 中。 ## 安装说明 环境要求：Python 3.12、Node 22，以及一个与机器人配对的应用账号绑定的 Tuya IoT 云项目。 ``` # Python deps python3 -m venv .venv && .venv/bin/pip install -r requirements.txt # 配置 cp config.example.json config.json # 填写你的 device id、ip 以及 Tuya cloud client id/secret # 从你的 Tuya 项目中获取机器人的 local key ./getrobotkey # runs the tinytuya wizard, writes robot_secrets.json # 构建 web UI cd web/app && npm install && npm run build && cd ../.. # 运行 ./homerun start # http://localhost:8787 ``` 在未配置 `local_key` 的情况下，服务器将针对模拟器启动，因此您可以在连接真实机器人之前先体验 UI。 `homerun` 脚本也是其他所有操作的入口：`homerun build`、`homerun cloud`、`homerun voice `、`homerun sniff` 等等。在不带任何已知命令的情况下运行它即可查看完整列表。 ## Home Assistant 将 `homeassistant/custom_components/homerun_local` 复制到您的 Home Assistant `custom_components` 目录中，并将其指向后端 URL。它会显示扫地机器人的状态、电量，并提供启动、停止、回充和定位命令。 ## 文档说明 - [docs/COMMAND_PROTOCOL.md](docs/COMMAND_PROTOCOL.md) 涵盖了数据点映射、导航帧和语音帧族，已在本机器上验证。 - [docs/VOICE_PACKS.md](docs/VOICE_PACKS.md) 涵盖了自定义语音是如何被逆向工程的、确切的语音包格式以及 ElevenLabs Voice Studio。 - [docs/ROOT_CAUSE.md](docs/ROOT_CAUSE.md) 涵盖了对接失败问题的调查。 - [docs/API_CONTRACT.md](docs/API_CONTRACT.md) 涵盖了后端的 HTTP API。 ## 安全与范围 本项目与 Philips 或 Tuya 无任何关联。它是通过观察一台机器人的进出流量构建的，因此数据点编号和命令帧特定于此型号和固件，在您的设备上可能会有所不同。部分帧是通过观察机器人的实际移动来确认的，而非来自官方规范。请将未记录的数据点视为盲目写入时不安全的项，因为其中一个很有可能是地图重置。 敏感信息不会保留在仓库中。`config.json`、`robot_secrets.json`、ElevenLabs 密钥以及保存的家庭地图均已被 gitignore 忽略。请在运行前复制 `.example` 文件并填入真实的值。 ## 许可证 MIT。详情请见 [LICENSE](LICENSE)。

标签：Home Assistant, MITM代理, TCP SYN 扫描, Tuya协议, Web UI, 局域网控制, 智能家居, 机器人吸尘器, 物联网, 逆向工具