iAmChumby/govee-cli

# govee-cli [](https://github.com/iAmChumby/govee-cli/actions/workflows/ci.yml)     通过 BLE 从终端控制 Govee 智能灯。无需云端、无需应用、无需账号。 我通过硬件 GATT dump 和社区研究逆向了 BLE 协议，并在真实的 H6056 上进行了验证。这是一个周末项目，使用 [Claude Code](https://claude.ai/code) 构建。 ## 安装说明 ``` git clone https://github.com/iAmChumby/govee-cli cd govee-cli python3 -m venv .venv && source .venv/bin/activate pip install -e . ``` 需要 Python 3.11+ 和 Bluetooth（内置或 USB dongle 均可）。 在 Windows 上，请使用 `py` 代替 `python3`，并使用 `.venv\Scripts\activate` 进行激活。 ## 快速开始 ``` # 设置你的设备一次 govee-cli config --mac D0:C9:07:FE:B6:F0 # 使用它 govee-cli power on govee-cli brightness 75 govee-cli color FF5500 govee-cli temp 4000 ``` ## 命令 | 命令 | 描述 | |---------|-------------| | `power on\|off` | 开启或关闭电源 | | `brightness <0-100>` | 设置亮度 | | `color ` | 设置 RGB 颜色 | | `temp <2700-6500>` | 设置色温 (Kelvin) | | `segments ` | 为单个区段着色 (H6056: 0–5) | | `scene ` | 播放内置场景（使用 `scene list` 查看全部） | | `effect ` | 播放关键帧动画 | | `scan` | 查找附近的 Govee BLE 设备 | | `info` | 打印设备状态 | | `schedule list\|add\|remove` | 管理基于时间的规则 | | `daemon [--once]` | 运行调度程序 | | `group add\|list\|` | 管理设备组 | | `config` | 查看或更新配置 | | `completion bash\|zsh\|fish` | Shell 自动补全脚本 | ## DIY 效果 JSON 关键帧文件，每个区段一个。关键帧之间的颜色会进行插值处理。 ``` { "name": "Crossfade", "fps": 10, "loop": true, "segments": [ {"id": 0, "keyframes": [ {"t": 0, "color": "FF0000"}, {"t": 2000, "color": "0000FF"}, {"t": 4000, "color": "FF0000"} ]} ] } ``` ``` govee-cli effect scenes/demo.json govee-cli effect scenes/party.json --fps 5 --no-loop ``` `scenes/` 目录下提供了一些示例效果。 ## 调度 ``` govee-cli schedule add --name "Morning" --time 07:00 --days Mon,Tue,Wed,Thu,Fri --command "power on" govee-cli schedule add --name "Bedtime" --time 23:00 --days Mon,Tue,Wed,Thu,Fri,Sat,Sun --command "power off" govee-cli schedule list govee-cli daemon ``` ## Shell 自动补全 ``` eval "$(govee-cli completion bash)" # bash eval "$(govee-cli completion zsh)" # zsh govee-cli completion fish | source # fish ``` ## 状态 | 功能 | 状态 | |---------|--------| | 开启/关闭电源 | ✅ 已验证 (H6056) | | 亮度 | ✅ 已验证 (H6056) | | RGB 颜色 | ✅ 已验证 (H6056) | | 白光色温 | ✅ 已验证 (H6056) | | 独立区段颜色 | ✅ 可用 — 独立区段寻址尚未验证 | | 内置场景 | ✅ 大部分可用 — 有少数需要我尚未逆向的多包协议 | | DIY 效果 | ✅ 已验证 (H6056) | | 调度与 daemon | ✅ 可用 | | Shell 自动补全 | ✅ bash / zsh / fish / powershell | | 设备状态 (info) | ⚠️ 仅限电源 — H6056 无法通过 BLE 报告亮度/颜色 | | 分组 | ✅ 已构建 — 未测试，需要第二台设备 | | 录制 / 回放 | ⏳ 存根 — 需要 btmon 会话 | | 音乐同步 | ⏳ 尚未开始 | ## 协议 所有命令均通过一个 GATT 写入特征以 20 字节的数据包发送： ``` [0x33] [cmd_type] [payload padded to 18 bytes] [XOR checksum] ``` 在 H6056 上通过 GATT dump 确认的 UUID： - **Service:** `00010203-0405-0607-0809-0a0b0c0d1910` - **Write:** `00010203-0405-0607-0809-0a0b0c0d2b11` - **Notify:** `00010203-0405-0607-0809-0a0b0c0d2b10` Govee 设备以随机的 BLE 地址进行广播，而不是静态 MAC。CLI 会自动处理此问题 — 使用贴纸上的 MAC 进行配置，它会在每次连接时解析该地址。 `--adapter` 选项（仅限 Linux）允许您选择特定的 `hciX` 接口。在 Mac 和 Windows 上此选项会被忽略 — bleak 会使用系统默认值。 完整的编码细节位于 `govee_cli/ble/protocol.py` 中。 ## 设备说明 已在 **H6056 Flow Plus**（6 区段，RGBICWW）上测试。基本命令应该也能在其他 Govee BLE 设备上运行 — 其服务 UUID 和数据包格式在整个产品线中是一致的。如果您测试了其他型号，请提交一个 issue。 ## 开发 ``` pytest # run tests mypy govee_cli # type check ruff check govee_cli # lint ruff check --fix govee_cli # auto-fix ``` ## 许可证 MIT

标签：Govee灯控, Python, 命令行工具, 无后门, 智能硬件, 物联网, 蓝牙低功耗