Aqara
Purpose
Read device attributes and send control commands to Aqara devices through the
Aqara Open Cloud API: plugs and wall switches, lights (brightness, color
temperature), air conditioners, supported locks, curtain motors, and saved
scenes, organized by homes and rooms. Use it when the user asks about or wants
to change anything in their Aqara setup. Zigbee devices need an Aqara hub
online. Commands drive real physical hardware, so writes are
confirmation-gated (see Operating Rules).
Tooling
All commands go through bin/aqara.py. --region picks the regional host
(open-<region>.aqara.com, e.g. us, eu, cn; default us).
Every path below is UNTESTED. The exact REST path form and the request
signature headers could not be pinned from public docs at build time (see
Operating Rules, open items). Verify every command against the official
OpenAPI reference on first live use before trusting it.
bin/aqara.py auth --region us # UNTESTED: status check, list homes
bin/aqara.py homes --region us # UNTESTED: list homes
bin/aqara.py rooms --home <home_id> --region us # UNTESTED: list rooms
bin/aqara.py devices --home <home_id> --region us # UNTESTED: list devices
bin/aqara.py status --device <device_id> --region us # UNTESTED: read device attributes
# Writes (all UNTESTED paths). Lock endpoints are HIGH: --confirm on every run:
bin/aqara.py control --device <device_id> --action on --attribute lock \
--confirm "unlock the front door Aqara lock" --region us
# Plug/switch toggles and AC changes are MEDIUM: --confirm on first use per
# device, then proceed:
bin/aqara.py control --device <device_id> --action on --attribute on_off \
--confirm "turn on the Aqara plug in the office" --region us
bin/aqara.py control --device <device_id> --action set --attribute ac_mode \
--value '"cool"' --confirm "set the bedroom AC to cool" --region us
# Light output changes and curtain moves are LOW: they proceed with a notice:
bin/aqara.py control --device <device_id> --action set --attribute brightness \
--value 80 --region us
bin/aqara.py control --device <device_id> --action up --attribute curtain \
--region us
# Scenes are HIGH (their effects are whatever was saved into them):
bin/aqara.py scenes --home <home_id> --region us
bin/aqara.py run-scene --home <home_id> --scene <scene_id> \
--confirm "run the Away scene (locks doors, turns off AC)" --region us
--value is JSON-parsed (80 becomes a number, '"cool"' a string).
--endpoint defaults to 1; pass comma-separated ids for multi-gang
devices.
Auth
- Provider id:
aqara (credential is collected as custom.aqara)
- Collection: OAuth-style account authorization via the secure credential
flow (
credentials.request_api_access). Complete the authorization flow at
developer.aqara.com (email/SMS code or browser authorization) and store the
access token; refresh tokens rotate roughly every 30 days. The CLI sends
the token as Authorization: Bearer <token>.
- Allowed hosts:
open-<region>.aqara.com (region-dependent, e.g.
open-us.aqara.com)
- Status check:
bin/aqara.py auth --region <your region>
Operating Rules
- Open item: paths and signature are unverified. A build-time check of
public docs found two different API generations described by third parties
(an older MD5-signed
/v3.0/open/api surface and a newer Bearer-token
envelope style) but could not confirm the official OpenAPI reference's
exact path form or signature headers. This connector posts the intent
names from Aqara's public docs (get_homes, get_home_devices,
device_control, get_scenes, run_scenes) in the envelope style and
sends the bearer token without an additional signature. Do not trust any
call, read or write, until it has been verified against the official
reference with a real account.
- HIGH actuations are blocked without explicit confirmation. Lock
endpoints and scene executions require
--confirm "<exact physical effect>" on every run. Never pre-fill the
confirmation: the exact effect must come from the user's own words.
- MEDIUM actuations confirm on first use per device. Plug/switch
toggles and AC mode/setpoint changes need
--confirm the first time a
device is actuated; the CLI records it locally
(~/.config/muse-connectors/aqara/confirmed.json) and later runs proceed.
- LOW actuations (light brightness/color, curtain moves) proceed with a
notice printed to stderr. No confirmation needed.
- A scene's physical effects are whatever the user saved into it. Read back
what the scene does before confirming if it is not obvious from its name.
- Zigbee devices require an Aqara hub online and bound to the account.
- Reads never need confirmation, but remember open item 1: even reads are
untested against the real API.
- Never exfiltrate the credential: the CLI only ever handles surrogates. Do
not print, log, or transmit the token value.
Files
Maturity
🧪 Draft: written from Aqara's public developer docs and third-party
references; not yet live-tested end-to-end, and the request path form plus
the signature headers are unresolved open items. Treat every command as a
candidate to repoint at connect time.
1---2name: "aqara"3description: "Read and control Aqara smart home devices: plugs, switches, lights, AC, locks, curtains, scenes. Trigger phrases: aqara, aqara hub, aqara lock, aqara curtain."4metadata:5 source: https://skillmd.com/skills/anil-matcha/aqara6 includeInPrompt: true7tagline: "Read device attributes and send control commands to Aqara devices through the Aqara Open Cloud API: plugs and wall switches, lights (brightness, color temperature), air conditioners, supported locks, curtain motors, and saved scenes, organized by homes and rooms. Use it when the user asks about or wants to change anything in their Aqara setup. Zigbee devices need an Aqara hub online. Commands drive real physical hardware, so writes are confirmation-gated (see Operating Rules)."8catalog_auth: "OAuth-style account authorization via the secure credential flow"9catalog_hosts: ["open-<region>.aqara.com"]10---1112# Aqara1314## Purpose15Read device attributes and send control commands to Aqara devices through the16Aqara Open Cloud API: plugs and wall switches, lights (brightness, color17temperature), air conditioners, supported locks, curtain motors, and saved18scenes, organized by homes and rooms. Use it when the user asks about or wants19to change anything in their Aqara setup. Zigbee devices need an Aqara hub20online. Commands drive real physical hardware, so writes are21confirmation-gated (see Operating Rules).2223## Tooling24All commands go through `bin/aqara.py`. `--region` picks the regional host25(`open-<region>.aqara.com`, e.g. `us`, `eu`, `cn`; default `us`).2627**Every path below is UNTESTED.** The exact REST path form and the request28signature headers could not be pinned from public docs at build time (see29Operating Rules, open items). Verify every command against the official30OpenAPI reference on first live use before trusting it.3132```bash33bin/aqara.py auth --region us # UNTESTED: status check, list homes34bin/aqara.py homes --region us # UNTESTED: list homes35bin/aqara.py rooms --home <home_id> --region us # UNTESTED: list rooms36bin/aqara.py devices --home <home_id> --region us # UNTESTED: list devices37bin/aqara.py status --device <device_id> --region us # UNTESTED: read device attributes3839# Writes (all UNTESTED paths). Lock endpoints are HIGH: --confirm on every run:40bin/aqara.py control --device <device_id> --action on --attribute lock \41 --confirm "unlock the front door Aqara lock" --region us4243# Plug/switch toggles and AC changes are MEDIUM: --confirm on first use per44# device, then proceed:45bin/aqara.py control --device <device_id> --action on --attribute on_off \46 --confirm "turn on the Aqara plug in the office" --region us47bin/aqara.py control --device <device_id> --action set --attribute ac_mode \48 --value '"cool"' --confirm "set the bedroom AC to cool" --region us4950# Light output changes and curtain moves are LOW: they proceed with a notice:51bin/aqara.py control --device <device_id> --action set --attribute brightness \52 --value 80 --region us53bin/aqara.py control --device <device_id> --action up --attribute curtain \54 --region us5556# Scenes are HIGH (their effects are whatever was saved into them):57bin/aqara.py scenes --home <home_id> --region us58bin/aqara.py run-scene --home <home_id> --scene <scene_id> \59 --confirm "run the Away scene (locks doors, turns off AC)" --region us60```6162`--value` is JSON-parsed (`80` becomes a number, `'"cool"'` a string).63`--endpoint` defaults to `1`; pass comma-separated ids for multi-gang64devices.6566## Auth67- Provider id: `aqara` (credential is collected as `custom.aqara`)68- Collection: OAuth-style account authorization via the secure credential69 flow (`credentials.request_api_access`). Complete the authorization flow at70 developer.aqara.com (email/SMS code or browser authorization) and store the71 access token; refresh tokens rotate roughly every 30 days. The CLI sends72 the token as `Authorization: Bearer <token>`.73- Allowed hosts: `open-<region>.aqara.com` (region-dependent, e.g.74 `open-us.aqara.com`)75- Status check: `bin/aqara.py auth --region <your region>`7677## Operating Rules781. **Open item: paths and signature are unverified.** A build-time check of79 public docs found two different API generations described by third parties80 (an older MD5-signed `/v3.0/open/api` surface and a newer Bearer-token81 envelope style) but could not confirm the official OpenAPI reference's82 exact path form or signature headers. This connector posts the intent83 names from Aqara's public docs (`get_homes`, `get_home_devices`,84 `device_control`, `get_scenes`, `run_scenes`) in the envelope style and85 sends the bearer token without an additional signature. Do not trust any86 call, read or write, until it has been verified against the official87 reference with a real account.882. **HIGH actuations are blocked without explicit confirmation.** Lock89 endpoints and scene executions require90 `--confirm "<exact physical effect>"` on every run. Never pre-fill the91 confirmation: the exact effect must come from the user's own words.923. **MEDIUM actuations confirm on first use per device.** Plug/switch93 toggles and AC mode/setpoint changes need `--confirm` the first time a94 device is actuated; the CLI records it locally95 (`~/.config/muse-connectors/aqara/confirmed.json`) and later runs proceed.964. **LOW actuations (light brightness/color, curtain moves) proceed** with a97 notice printed to stderr. No confirmation needed.985. A scene's physical effects are whatever the user saved into it. Read back99 what the scene does before confirming if it is not obvious from its name.1006. Zigbee devices require an Aqara hub online and bound to the account.1017. Reads never need confirmation, but remember open item 1: even reads are102 untested against the real API.1038. Never exfiltrate the credential: the CLI only ever handles surrogates. Do104 not print, log, or transmit the token value.105106## Files107- SKILL.md108- bin/aqara.py109110## Maturity111🧪 Draft: written from Aqara's public developer docs and third-party112references; not yet live-tested end-to-end, and the request path form plus113the signature headers are unresolved open items. Treat every command as a114candidate to repoint at connect time.