Homey

Purpose

Read device state and write capability values on a Homey Pro (local) or Homey cloud account through the Homey Web API: lights and outlets, dimmers and color, thermostats, connected locks, blinds and curtains, plus listing Flows (automations). Use it when the user asks about or wants to change anything paired to their Homey. Writes drive real physical hardware, so they are confirmation-gated (see Operating Rules).

Tooling

All commands go through bin/homey.py. --host is required on every run: the API root, either local (http://<homey-ip>/api) or cloud (https://<cloud-id>.connect.athom.com/api):

bin/homey.py --host http://192.168.1.60/api auth               # status check: verify token, count devices
bin/homey.py --host <api-root> devices                          # list devices with capabilities
bin/homey.py --host <api-root> device --id <id>                 # device detail

# Writes. Lock writes are HIGH: they REQUIRE --confirm naming the exact
# physical effect, on every run:
bin/homey.py --host <api-root> set --id <id> --cap locked --value false \
    --confirm "unlock the side door"

# Other capability writes are MEDIUM: --confirm on first use per device, then
# proceed:
bin/homey.py --host <api-root> set --id <id> --cap onoff --value true \
    --confirm "turn on the living room floor lamp"
bin/homey.py --host <api-root> set --id <id> --cap target_temperature --value 21 \
    --confirm "set the bedroom thermostat target to 21 degrees"

# Blind/curtain writes are LOW: they proceed with a logged notice:
bin/homey.py --host <api-root> set --id <id> --cap windowcoverings_state --value up

# Flows:
bin/homey.py --host <api-root> flows
bin/homey.py --host <api-root> flow-trigger --id <flow-id> \
    --confirm "run the Good Morning flow (opens blinds, starts coffee machine)"

--value is JSON-parsed: true, 0.5, 21, '"heat"'. Capability names follow Homey's conventions: onoff, dim, locked, target_temperature, thermostat_mode, windowcoverings_state, light_hue, light_saturation.

Open item: flow-trigger ships with an UNTESTED path (POST /manager/flow/flow/{id}/trigger). Its exact form could not be pinned from public docs at build time; verify it against Athom's docs on first live use. It is HIGH-gated regardless.

Auth

• Provider id: homey (credential is collected as custom.homey)
• Collection: personal API token (Homey Pro) or OAuth 2.0 token (Homey cloud) via the secure credential flow (credentials.request_api_access). The CLI sends it as Authorization: Bearer <token>.
• Allowed hosts: whatever --host names (the Homey's LAN IP/hostname or <cloud-id>.connect.athom.com). The CLI pins egress to that host per run.
• Status check: bin/homey.py --host <api-root> auth

Operating Rules

1. HIGH actuations are blocked without explicit confirmation. Setting locked to false (unlock) or true (lock) requires --confirm "<exact physical effect>" on every run. Triggering a Flow is also HIGH: a Flow's physical effects are whatever its actions do, so --confirm must name them, and the Flow's actions should be read back to the user before confirming when they are not obvious.
2. MEDIUM actuations confirm on first use per device. onoff, dim, light_hue/light_saturation, thermostat capabilities: --confirm the first time a device is actuated; the CLI records it locally (~/.config/muse-connectors/homey/confirmed.json) and later runs proceed.
3. LOW actuations proceed with a logged notice. windowcoverings_state and windowcoverings_set (blinds/curtains) print a notice to stderr and run without confirmation.
4. Never lock someone out or in. Do not set locked to true unless the user explicitly asked for that lock to be locked; verify intent in conversation first.
5. Reads (auth, devices, device, flows) never need confirmation.
6. Homey Pro hardware or a Homey cloud account is required; local calls stay on the LAN.
7. Never exfiltrate the credential: the CLI only ever handles surrogates. Do not print, log, or transmit the token value.

Files

• SKILL.md
• bin/homey.py

Maturity

🧪 Draft: written from Homey's public Web API docs; not yet live-tested end-to-end. Device capability reads and PUTs are pinned; the Flow-trigger path is an open item and ships marked untested.