Madhat69/pyidotmatrix

# pyidotmatrix 面向 iDotMatrix BLE 像素显示屏的无预设、async-first 的 Python SDK。 采用 GPL-3.0-or-later 许可证 — 请参阅 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。 本项目有两个同等重要的目标： 1. **iDotMatrix 显示屏的权威 Python SDK** — 控制一个面板 应该感觉像是在控制一台设备，而不是在构造数据包。 2. **设备协议的参考实现和文档** — 每一个经过验证的逆向工程发现都会汇总于此；每一个 未经验证的发现都会被明确标记为实验性的。协议研究是 一等贡献（一份优质的硬件探测日志与一项新功能同等重要）。 有关完整的架构审查、带有证据的功能清单以及迈向 1.0 的路径，请参阅 [docs/ROADMAP.md](docs/ROADMAP.md)。 ## 安装 尚未发布到 PyPI。从检出的代码安装： ``` pip install -e . # library pip install -e .[test] # + test tooling ``` 要求 Python 3.12–3.14。通过 [bleak](https://github.com/hbldh/bleak) 进行 BLE 连接 （支持 Windows/Linux/macOS）。 ## 协议成熟度一览 | 子系统 | 状态 | |---|---| | BLE 传输（重连、ack、通知） | ✅ 经过硬件验证 | | Framebuffer（DIY 全帧 + 进入/退出模式） | ✅ | | Graffiti（局部像素更新） | ✅ | | 图像 / GIF（适配 + 原生播放） | ✅ | | 原生时钟 | ✅ | | 闹钟（定时器槽位、内容和蜂鸣） | ✅ | | 文本（设备渲染） | ⚠ 在 32×32 上破损 — 修复中 | | 特效 / 颜色 | ✅（与厂商应用相比有所简化） | | 倒数 / 秒表 / 记分牌 | ⚠ 来源已确认 | | 每周计划 | ⚠ 部分已验证 | | 音乐同步 / eco / 实验性 | ⚠/❓ | ✅ 经过硬件验证 · ⚠ 实验性（来源已确认，但未验证） · ❓ 逆向工程进行中。带有完整证据的表格：ROADMAP §3。 ## 架构层 ``` protocol/ pure byte builders (no I/O), one per device feature transport/ BLE connection lifecycle, chunked writes, reconnect supervision display/ DisplayBackend interface + BleDisplay (hardware) and SimulatorDisplay client.py IDotMatrixClient — full-feature facade over one connection imaging.py canvas-fitting helpers (image adaptation) ``` 驱动程序负责将字节传输到设备。它不进行调度、渲染应用帧、对帧进行差异比对，也不决定是使用全帧还是像素更新 — 这些都是调用者的任务。 ## 两个接口 **DisplayBackend** — 最小化的帧处理管道接口（`show_frame`、`set_pixels`、亮度、电源）。`BleDisplay` 和 `SimulatorDisplay` 都实现了该接口，因此调用者与后端无关。 ``` from pyidotmatrix import BleDisplay, BleTransport, ScreenSize, SimulatorDisplay display = BleDisplay(ScreenSize.SIZE_32x32, BleTransport(mac_address=None)) await display.connect() await display.show_frame(rgb_bytes) # full frame (32*32*3 bytes) await display.set_pixels((0, 255, 0), [(1, 1)]) # partial update sim = SimulatorDisplay(ScreenSize.SIZE_32x32, on_frame=lambda buf: ...) # no hardware ``` **IDotMatrixClient** — 完整的原生功能外观模式；包含所有设备功能，并与 `.display` 共享同一个连接。 ``` from pyidotmatrix import IDotMatrixClient, ScreenSize client = IDotMatrixClient(ScreenSize.SIZE_32x32) await client.connect() await client.countdown.start(25, 0) # e.g. a Pomodoro (device runs it natively) await client.clock.show() await client.text.show("HELLO", font_path=...) await client.gif.upload_file("anim.gif") await client.display.show_frame(rgb_bytes) # rendered frames, same connection ``` 功能命名空间：`chronograph`、`countdown`、`clock`、`scoreboard`、`eco`、`color`、`graffiti`、`effect`、`music_sync`、`text`、`gif`、`common` 以及 `display`。 ### 设备确认 对于每一个被识别的命令（接受/拒绝），设备都会推送一个状态 ack。 您可以被动地观察它们，或者等待特定命令的 ack： ``` # passive: 为每个命令的 ack 触发 unsubscribe = client.add_response_listener(lambda ack: print(ack.command_type, ack.accepted)) # active (opt-in): 发送命令并等待其 ack，或者在 timeout 时为 None from idotmatrix.protocol import common ack = await client.await_device_ack(common.build_set_brightness(60)) ``` **值得了解的协议真相：** ack 确认的是*接收*，而不是*执行效果* — 设备可以接受一个命令但不执行它。SDK 会记录这些情况，而不是掩盖它们（详见 ROADMAP §4）。 ### 生命周期与可观测性 ``` client.set_auto_reconnect(True) # arm/disarm reconnect at runtime unsub = client.add_event_listener(print) # write failures, reconnects snap = client.snapshot() # address, connected, write_size, reconnect_count, last_failure await client.show_image("photo.png") # adapt to the screen and display ``` 监听器注册会返回一个可调用的取消订阅对象。抛出异常的监听器会被隔离 — 它不会破坏连接处理逻辑。 **低 MTU 面板：** 传输层信任特征值报告的写入大小。在 BlueZ 下，某些 iDotMatrix 面板会少报此值（约 20 字节）；在这些设备上，传入 `BleTransport(..., write_size_override=514)` 即可获得全速帧刷新。 ## 测试 ``` pip install -e .[test] pytest ``` 协议构建器由逐字节精确的黄金测试覆盖。硬件探测脚本位于 `probes/` 中 — 由人工针对真实面板运行，从不在 CI 中执行。 ## 贡献 逆向工程是一等贡献：硬件探测结果、BLE 数据包捕获、固件/型号对比以及协议文档，与代码一样宝贵。请从 `probes/` 开始，并参考 `docs/` 中各处提及的逆向工程笔记。 ## 致谢 本 SDK 建立在以下开发者的逆向工程传承之上： [8none1](https://github.com/8none1/idotmatrix)、 [derkalle4](https://github.com/derkalle4/python3-idotmatrix-client) (GPLv3)、 和 [markusressel](https://github.com/markusressel/idotmatrix-api-client) — 请参阅 [NOTICE](NOTICE)。

标签：LED像素屏, Python SDK, 云资产清单, 协议文档, 物联网, 硬件控制, 蓝牙低功耗, 计算机取证, 逆向工具, 逆向工程