samcgn/xyaoled-control

# xyaoled-control 非官方Python库和CLI，用于直接通过低功耗蓝牙（BLE）驱动**"XYAO-LED"风格64x16 RGB BLE像素矩阵**（由*XYAO LED*手机应用控制，广告名为`XyaoLED...`），无需应用。 它可以显示静态文本、分页和**硬件滚动**文本、单色像素艺术、**全彩图像**和**动画**（多帧GIF/视频剪辑）。 BLE线格式已逆向工程，以与您拥有的硬件兼容。 本项目与设备供应商无关，也未获得其认可。 ## 功能 - 静态文本、多页文本、平滑设备端滚动文本（任何颜色、任何字体） - 从图像文件或内置图案创建单色像素艺术 - 全彩图像（任何图片，适配64x16） - 从动画GIF创建动画 - 电源、亮度、清屏/播放列表 - 用于检查您自己的设备BLE流量的捕获解析器 ## 要求 - Python 3.10+ - [`bleak`](https://github.com/hbldh/bleak)（跨平台BLE）和`Pillow` ``` pip install -r requirements.txt ``` ## 快速开始 设备必须开启电源且**未**连接到手机应用（每次只能连接一个BLE中心）。地址会自动通过名称发现；您可以使用`--address`或`XYAO_ADDRESS`环境变量覆盖它。 ``` # text python -m xyaoled.text "HELLO" --color 0,255,0 python -m xyaoled.text "a long running message" --scroll --color 255,0,0 python -m xyaoled.text "HELLO WORLD 123" --pages # 单色像素艺术（图像文件或内置图案） python -m xyaoled.image heart --color 255,0,0 python -m xyaoled.image mylogo.png --color 0,128,255 --clear # 全彩+动画 python -m xyaoled.gif photo.jpg --clear python -m xyaoled.gif animation.gif --clear # 实用工具 python -m xyaoled.text "CLEAR" --dry-run # render without sending python tools/parse_capture.py capture.pklg # inspect a BLE capture ``` 将`--dry-run`添加到任何命令中，以预览ASCII/命令而不连接。 将`--clear`添加到先清除循环播放列表（否则每次发送都会附加到它）。 ## 握手/初始化帧 每个会话都以初始化握手开始。设备验证绑定到时间戳的小令牌；它接受之前捕获的初始化帧原样。一个示例帧已捆绑，并适用于参考单元。**如果您的设备没有响应**（您从未看到`88 ff 00 05 ...`通知），请从官方应用捕获您自己的初始化帧并提供它： ``` export XYAO_INIT_HEX=99aa002eff881f0000000100.... # your captured TYPE=0x0000 frame ``` `tools/parse_capture.py`可以帮助您在PacketLogger `.pklg`捕获中找到它（查找第一个值以`99 aa 00 2e ff 88 1f 00 00 00 01`开头的写入）。 ## 平台说明（BLE权限） - **macOS**：您从其中运行Python的终端/应用需要*蓝牙*隐私权限（系统设置→隐私与安全→蓝牙）。在最近的macOS中，您可能还需要开发者的"蓝牙"日志配置文件，以使用PacketLogger捕获HCI流量。BLE外围地址是每台机器的CoreBluetooth UUID，因此它是自动发现的，而不是硬编码的。 - **Linux**：需要BlueZ；地址是BD_ADDR（`AA:BB:...`）。 - **Windows**：通过WinRT后端工作。 ## 协议 有关完整逆向工程的线格式（帧布局、命令、1位/全彩/动画图像格式、校验和）的详细信息，请参阅[PROTOCOL.md](PROTOCOL.md)。 ## 免责声明 仅用于个人、互操作性使用与您自己的硬件。不提供任何保证。向嵌入式硬件发送格式错误的数据风险自负。与供应商无关。 ## 许可证 MIT — 请参阅[LICENSE](LICENSE)。

标签：BLE, GIF 动画, LED 显示, Python 库, RGB, XYAO-LED, 云资产清单, 互操作性, 像素矩阵, 像素艺术, 全彩图像, 图像处理, 图形动画, 文本显示, 无应用程序, 滚动文本, 蓝牙, 设备控制, 逆向工具, 逆向工程