hannes813/tesvor-x500-pro-esphome-vacuum

# Tesvor X500 ESPHome 扫地机器人 基于原始 ESP8266/ESP-12S WLAN 模块的 Tesvor X500/X500 Pro 扫地机器人本地 ESPHome/MQTT 集成。 该项目通过本地 UART 命令、Home Assistant 实体以及基于机器人提供的路径点的简单地图可视化，替代了原有的云端连接。 ## 状态 | 领域 | 状态 | |---|---| | 在 ESP-12S 上刷入 ESPHome | 正常运行 | | 智能 / 重点 / 沿边 / 停止 / 充电 | 正常运行 | | 方向控制 | 正常运行 | | Z字形 / 拖地 | 以 `0x22 04` 运行，状态为 `0x0B` | | 拖地强度 | 通过 UART 确认了低/高挡；根据规律存在默认/关闭模式 | | 地图 / 路径点 | 通过 MQTT + `current.json` 正常运行 | | 归档 | 在返回状态为 `charging`/`docked` 时正常运行 | | 清扫时长 | 由 ESP 端进行统计 | | 拖把清洁 | 实验性功能；有 ACK，但尚未被证实为可靠的启动模式 | | 吸力 / 风机 | 实验性功能；已知原始命令，但状态反馈不可靠 | ## 硬件 已测试： - Tesvor X500/X500 Pro - Ai-Thinker ESP-12S / ESP8266EX WLAN 模块 - 4 MB Flash - UART 115200 Baud - ESPHome 2025.7.x J1 接口上的 Flash/UART 引脚： | J1 线路 | 功能 | |---|---| | 红色 | 3.3V | | 黑色 | GND | | 绿色/黄色 | UART RX/TX，视适配器情况可能需要对调 | 重要提示：切勿向 ESP 模块输入 5V 电压。 ## 仓库结构 ``` . ├── x500.yaml # ESPHome Firmware für den Roboter ├── secrets.yaml.example # Beispiel-Secrets für ESPHome ├── tesvor_map_writer.py # MQTT → current.json/archive writer ├── web/map.html # Kartenanzeige mit Archivauswahl ├── scripts/start_writer.sh # Synology/DSM Startscript Writer ├── scripts/start_http.sh # einfacher HTTP-Server für Karte ├── examples/home-assistant/ # Lovelace/iframe Beispiele └── docs/ # Protokoll, Installation, Erkenntnisse ``` ## ESPHome 快速入门 ``` cp secrets.yaml.example secrets.yaml # 修改 secrets.yaml esphome compile x500.yaml esphome upload x500.yaml --device ``` OTA 示例： ``` python -m esphome upload x500.yaml --device 192.168.178.108 ``` ## MQTT 主题 ESP 会发布额外的原始数据： ``` tesvor/x500/state tesvor/x500/map/points ``` `tesvor/x500/map/points` 包含批量点位数据： ``` {"p":[[seq,x,y,type],[seq,x,y,type]]} ``` Writer 会在此基础上生成： ``` current.json archive_index.json archive/*.json ``` ## 地图写入器 (Map Writer) 依赖项： ``` pip3 install -r requirements.txt ``` 启动： ``` export TESVOR_MQTT_HOST=192.xxx.xxx.xx export TESVOR_MQTT_USER='DEIN_USER' export TESVOR_MQTT_PASSWORD='DEIN_PASSWORT' python3 tesvor_map_writer.py ``` Synology 上的默认路径： ``` /volume2/docker/tesvor-map ``` 可以通过环境变量更改此路径： ``` export TESVOR_MAP_DIR=/volume2/docker/tesvor-map ``` ## 显示地图 使用简单 HTTP 服务器的方案： ``` cd /volume2/docker/tesvor-map python3 -m http.server 8095 ``` 然后执行： ``` http://192.xxx.xxx.xx:xxxx/map.html ``` 对于 Home Assistant 移动应用，最好将地图部署在 `/config/www/tesvor-map` 下，并在 iframe 中进行相对引用： ``` type: iframe url: /local/tesvor-map/map.html aspect_ratio: 100% ``` ## 截图 ### 逆向工程环境  ### vertical-stack-card tesvor  ### iframe-card tesvor live map  ## 安全 请勿将机密信息提交至代码仓库。`x500.yaml` 使用了 `!secret`；真实的 WLAN、MQTT、OTA 和 API 密钥只能存放在 `secrets.yaml` 中。 ## 免责声明 逆向工程 / 固件刷写风险自负。在每次刷写之前，请务必备份完整的 4 MB 原始固件。

标签：ESPHome, Home Assistant, 协议逆向, 后端开发, 多模态安全, 扫地机器人, 智能家居, 物联网, 逆向工具