labsensacional/mrstar-ble-light

# mrstar-ble-light 使用 Python 控制廉价的**“MR Star” / GATT-DEMO RGB BLE 灯** —— 无需应用，无需云端。这是对这些灯具使用的未公开 GATT 协议进行逆向工程的结果。 如果你的 RGB 灯带/灯具通过蓝牙广播为 **`GATT-DEMO`**，且其 Android 应用为 **“MR Star”**（`com.frok.mrstar`），本项目可以直接控制它。

## 这是哪种灯？ 我进行逆向工程的设备是一款 **RGB LED 落地角落灯**（安装在小三脚架上的一根垂直灯管，高约 110 厘米）。这些产品以许多品牌名称销售，但规格几乎完全相同： - **RGB** 颜色、亮度以及约 117 种内置动画效果 - 三种控制方式：**24 键 IR 遥控器**、**“MR Star” 手机应用**，以及 **Bluetooth LE**（本项目使用的方式） - **音乐 / 节奏音频传感器**模式（随声音反应） - 通过 BLE 广播为 **`GATT-DEMO`** 我购买的确切型号（阿根廷）： [RGB 110cm 落地角落灯 — App 控制 + 节奏音频传感器 (MercadoLibre)](https://www.mercadolibre.com.ar/luz-led-esquinera-rgb-110cm-control-app-sensor-audio-ritmico/up/MLAU3903930125?pdp_filters=item_id:MLA1754575091) 如果你的设备外观与此类似、具有上述规格，或者在 BLE 扫描中显示为 `GATT-DEMO`，本项目应该对你适用。 ## 一行代码概述协议 ``` Write char 0000fff3-... Frame: BC 55 Colors in HSV ``` 完整分析（反编译的命令表及其发现过程）：参见 [`docs/ble_reverse_engineering.md`](docs/ble_reverse_engineering.md)。 ## 5 秒内体验（无需灯具，无需 Bluetooth） ``` python3 examples/protocol_demo.py ``` 打印每个命令的原始帧字节，并展示 RGB→HSV 转换 —— 即真实的控制器通过 BLE 写入的确切字节。 ## 安装 ``` pip install bleak ``` ## 搭配真实灯具使用 ``` python3 examples/scan.py # find your light's address python3 mrstar_light.py on python3 mrstar_light.py color 255 120 0 # RGB; auto-converted to HSV python3 mrstar_light.py brightness 50 python3 mrstar_light.py mode running python3 mrstar_light.py speed 40 python3 mrstar_light.py direction reverse python3 mrstar_light.py list-modes ``` ### 选择设备 没有硬编码 MAC 地址。地址按以下顺序解析： 1. `--mac AA:BB:CC:DD:EE:FF` 2. `MRSTAR_MAC` 环境变量 3. 自动扫描第一个 `GATT-DEMO` 设备 ``` python3 mrstar_light.py --mac AA:BB:CC:DD:EE:FF green export MRSTAR_MAC=AA:BB:CC:DD:EE:FF # then omit --mac ``` ## 作为库使用 ``` import asyncio from mrstar_light import build_color_hsv, build_power, send async def main(): addr = "AA:BB:CC:DD:EE:FF" await send(addr, build_power(True), build_color_hsv(255, 0, 128)) asyncio.run(main()) ``` 所有 `build_*` 函数都是纯函数（返回 `bytes`），因此无需任何 Bluetooth 协议栈即可轻松测试或重用。 ## 注意事项 - 控制器在断电时会忽略颜色/效果更改，因此 CLI 会在发送非电源命令前自动发送“开机”指令。 - 网络传输中的颜色格式为 HSV（色调 0–360，饱和度 0–1000）；系统已为你处理了 RGB→HSV 转换。 - 已在 Linux 上通过 `bleak` 配合 BlueZ 进行了测试；由于 `bleak` 是跨平台的，因此 macOS / Windows 理论上也能正常工作。 ## 许可证 MIT —— 参见 [LICENSE](LICENSE)。

标签：Python, 云资产清单, 无后门, 智能家居, 物联网, 硬件控制, 蓝牙, 计算机取证, 逆向工具, 逆向工程