dallanwagz/idotmatrix-ha

# iDotMatrix — 本地控制与 Home Assistant 集成 对 **iDotMatrix HXS-002 / NL-XSD-32** 32×32 BLE LED 面板进行无云、无 App 控制 —— 通过对厂商 Android App 逆向工程推导，并已在**真实硬件上验证**。可通过任何 Python/Bluetooth 主机或 Home Assistant 进行驱动，无需厂商 App 或云服务。 ## 目录说明 | 路径 | 说明 | |---|---| | `custom_components/idotmatrix/` | Home Assistant 集成（支持通过 HACS 安装；符合 Core-PR 规范）。`protocol.py` 是一个**纯净、无依赖、经过单元测试**的协议模块。 | | `tools/idm_cli.py` | 独立的 `bleak` CLI —— 可从任何主机扫描/连接/驱动该面板。 | | `tools/idm_daemon.py` + `idmctl.py` | 用于交互式操作的持久连接驱动程序。 | | `tools/idm_image.py` | 分块图片上传实验（参见协议说明）。 | | `tests/test_protocol.py` | 18 个基于硬件抓包数据的黄金帧测试。 | | `docs/PROTOCOL.md` | 完整的 BLE 协议规范及黄金帧。 | | `docs/SECURITY-APK-COMPARISON.md` | Play Store 与 e-toys.cn APK 的安全性分析。 | | `decompiled/`, `apks/`, `captures/`, `research/` | 逆向工程工作资料（体积较大的二进制文件已被 gitignore）。 | ## 快速开始（任何带有 Bluetooth 的主机） ``` python3 -m venv venv && ./venv/bin/pip install bleak ./venv/bin/python tools/idm_cli.py scan # find your IDM-xxxxxx export IDM_ADDR= ./venv/bin/python tools/idm_cli.py color 255 0 0 # fill red ./venv/bin/python tools/idm_cli.py bright 50 ./venv/bin/python tools/idm_cli.py clock 0 ./venv/bin/python tools/idm_cli.py countdown 1 5 0 # start a 5:00 countdown ``` 该面板同一时间仅接受**一个** BLE 连接 —— 在进行本地控制时，请保持厂商 App 处于断开状态。当连接断开时，它会恢复为空闲动画，因此 HA 集成会保持一个持久连接。 ## 已支持功能（已在硬件上验证） 开/关机、亮度、全屏 RGB、时钟（日期 + 24小时制标志）、倒计时、秒表、记分板、180° 翻转、屏幕开/关、实时 DIY 像素绘制，以及**完整的 32×32 图片上传**（RGB 栅格，分块传输 + CRC32）。请参阅[命令目录](docs/PROTOCOL.md#command-catalog)。HA 的 `idotmatrix.set_image` 服务可上传任何图片文件（自动缩放至 32×32）。 ## Home Assistant 通过 HACS 作为自定义仓库安装，然后通过 UI 添加设备（它会通过 Bluetooth 被自动发现为 `IDM-*`）。需要在面板附近配备一个 Bluetooth 适配器或 ESPHome/Shelly Bluetooth 代理。该集成提供了一个 **light**（开/关 + 亮度 + 颜色）、一个**翻转**开关、**同步时间** / **重置**按钮、一个**时钟面板**选择器，以及一个通用的 `idotmatrix.send_command` 服务来处理其他所有操作。 ## 安全提示 包装盒上的二维码提供了一个来自 `api.e-toys.cn` 的“本地服务器” APK。它与 Play Store 上的构建版本相同，但经过了 **DEX 加壳（Baidu Protect）并请求了额外的权限**（自主安装、读取手机状态、开机启动、获取任务列表）。**请使用 Play Store 的版本。** 完整分析：[`docs/SECURITY-APK-COMPARISON.md`](docs/SECURITY-APK-COMPARISON.md)。 ## 鸣谢 已与 [`derkalle4/python-idotmatrix-library`](https://github.com/derkalle4/python3-idotmatrix-library) 和 [`8none1/idotmatrix`](https://github.com/8none1/idotmatrix) 进行了交叉验证。

标签：Home Assistant, LED屏幕控制, Python, 云资产清单, 无后门, 智能家居, 物联网, 蓝牙低功耗, 逆向工具, 逆向工程