SuperAPI AI Directory

amaran-lights

General & other

View repository

Updated 10-30 16:19

About this skill

amaran lights CLI

Direct Bluetooth Mesh control of amaran studio lights. The amaran CLI talks to the lights over BLE mesh (Telink protocol) — the amaran Desktop app is not required at runtime and must be quit while using the CLI (it holds the BLE connections).

Requirements

  • macOS with Bluetooth on; grant Bluetooth permission to the terminal when prompted.
  • Python 3.10+.
  • One-time: the amaran Desktop app must have paired the lights at least once — its local database contains the mesh keys needed to join the network.

Install

cd amaran-cli                 # repo containing this file
python3 -m venv .venv
.venv/bin/pip install -e .
ln -sf "$PWD/.venv/bin/amaran" ~/.local/bin/amaran   # or any dir in PATH

Setup (one time)

amaran setup     # imports mesh keys + light list from the amaran Desktop DB
amaran lights    # shows your lights: keys, mesh addresses, MACs

Config is written to ~/.config/amaran/lights.json and can be edited by hand (light key fields are the CLI target names).

Commands

amaran on  [target]                  # turn on (wake)
amaran off [target]                  # turn off (sleep)
amaran bright <0-100> [target]       # brightness percent
amaran cct <0-100> <kelvin> [target] # brightness + color temp (e.g. 4300, 5600)
amaran cct 60 3200 --gm 5 [target]   # optional green/magenta shift -10..+10
amaran hsi <0-100> <hue> <sat> [target]  # color: hue 0-360, sat 0-100 (RGB fixtures only)
amaran status [target]               # query current state from the lights
amaran repl                          # interactive mode: stays connected, much faster
amaran scan                          # list nearby mesh lights (raw BLE view)
amaran lights                        # list configured lights (no BLE)

Targeting

  • Omit the target (or use all) to address the whole group at once.
  • Targets are case-insensitive substrings of the light keys/names shown by amaran lights. A substring matching several lights hits all of them (e.g. a shared model name), a full key hits exactly one.
  • Always run amaran lights first on a new setup to learn the actual target names — never guess them.

Agent operating rules

  1. If a command fails with "no mesh proxy connection", tell the user to quit the amaran Desktop app and enable Bluetooth, then retry.
  2. status replies occasionally get lost in the mesh — retry once before concluding a light is unreachable.
  3. After changing settings, verify with amaran status when the result matters (commands are fire-and-forget with mesh retries, no ack).
  4. Use amaran repl for sequences of several adjustments — direct commands reconnect each time (~5-10s); the REPL stays connected.
  5. Not every fixture supports every mode: bi-color lights do CCT only; HSI and --gm require RGBWW fixtures. A rejected mode fails silently — check status.
  6. Individual fixtures may cap brightness (power/thermal limits). If a light ignores brightness but accepts CCT/on/off, report it to the user instead of retrying in a loop.

Linking this skill

Drop or symlink this file wherever your agent loads skills from, e.g.:

mkdir -p ~/.config/opencode/skills
ln -s "$PWD" ~/.config/opencode/skills/amaran-lights   # dir containing SKILL.md