用途 amaran-lights 提供 amaran CLI,用于从命令行直接控制 amaran/Aputure 蓝牙 Mesh 摄影棚灯具。它通过 BLE mesh(Telink 协议)与灯具通信,运行时不需要 amaran Desktop 应用;但使用 CLI 期间必须退出该桌面应用,因为桌面应用会占用 BLE 连接。
环境要求
- macOS,且蓝牙已开启;终端被提示时需授予蓝牙权限。
- Python 3.10+。
- 一次性前提:amaran Desktop 应用至少曾完成过灯具配对,因为其本地数据库包含加入 mesh 网络所需的 mesh 密钥。
安装 cd amaran-cli python3 -m venv .venv .venv/bin/pip install -e . ln -sf "$PWD/.venv/bin/amaran" ~/.local/bin/amaran # 或 PATH 中任意目录
首次设置 amaran setup # 从 amaran Desktop 数据库导入 mesh 密钥和灯具列表 amaran lights # 显示灯具:keys、mesh 地址、MAC 配置写入 ~/.config/amaran/lights.json,可手动编辑(灯具 key 字段即 CLI 目标名)。
主要命令
- amaran on [target]:开灯(唤醒)
- amaran off [target]:关灯(休眠)
- amaran bright <0-100> [target]:亮度百分比
- amaran cct <0-100> <kelvin> [target]:亮度 + 色温(如 4300、5600)
- amaran cct 60 3200 --gm 5 [target]:可选绿/品红偏移 -10..+10
- amaran hsi <0-100> <hue> <sat> [target]:颜色,色相 0-360、饱和度 0-100(仅 RGB 灯具)
- amaran status [target]:查询灯具当前状态
- amaran repl:交互模式,保持连接,速度更快
- amaran scan:列出附近 mesh 灯具(原始 BLE 视图)
- amaran lights:列出已配置灯具(不发起 BLE 连接)
目标选择 省略 target 或使用 all 会一次性作用于整组。target 是 amaran lights 所示灯具 key/名称的大小写不敏感子串;子串匹配多个灯具时会命中全部(例如共享型号名),完整 key 只命中一个。新环境应先运行 amaran lights 获知实际目标名,不要猜测。
使用注意
- 若命令报错 "no mesh proxy connection",应让用户退出 amaran Desktop 应用并开启蓝牙后重试。
- status 回复偶尔会在 mesh 中丢失,应先重试一次再判定灯具不可达。
- 命令为发后不管并带 mesh 重试、没有确认;结果重要时应在修改后用 amaran status 验证。
- 连续多次调整应使用 amaran repl:直接命令每次都会重新连接(约 5-10 秒),REPL 保持连接。
- 并非所有灯具支持所有模式:双色温灯仅支持 CCT;HSI 和 --gm 需要 RGBWW 灯具。被拒绝的模式会静默失败,需检查 status。
- 个别灯具可能因功率/温度限制而限制亮度;如果灯具忽略亮度但接受 CCT/开关,应向用户报告,而不是循环重试。
接入技能 可将该文件放置或软链接到智能体加载技能的位置,例如: mkdir -p ~/.config/opencode/skills ln -s "$PWD" ~/.config/opencode/skills/amaran-lights # 包含 SKILL.md 的目录
限制 资料仅说明支持 macOS,未提及其他平台;功能依赖 amaran Desktop 曾完成配对以提供 mesh 密钥;具体灯具型号对模式与亮度的支持存在差异。