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
- 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.
- 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.
- LOW actuations proceed with a logged notice.
windowcoverings_state
and windowcoverings_set (blinds/curtains) print a notice to stderr and
run without confirmation.
- 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.
- Reads (
auth, devices, device, flows) never need confirmation.
- Homey Pro hardware or a Homey cloud account is required; local calls stay
on the LAN.
- Never exfiltrate the credential: the CLI only ever handles surrogates. Do
not print, log, or transmit the token value.
Files
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.
1---2name: "homey"3description: "Read and control devices on a Homey Pro hub or Homey cloud account: lights, thermostats, locks, blinds, Flows. Trigger phrases: homey, homey pro, homey flow, athom."4metadata:5 source: https://skillmd.com/skills/anil-matcha/homey6 includeInPrompt: true7tagline: "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)."8catalog_auth: "personal API token or OAuth via the secure credential flow"9catalog_hosts: ["the host you pass via --host"]10---1112# Homey1314## Purpose15Read device state and write capability values on a Homey Pro (local) or Homey16cloud account through the Homey Web API: lights and outlets, dimmers and17color, thermostats, connected locks, blinds and curtains, plus listing Flows18(automations). Use it when the user asks about or wants to change anything19paired to their Homey. Writes drive real physical hardware, so they are20confirmation-gated (see Operating Rules).2122## Tooling23All commands go through `bin/homey.py`. `--host` is required on every run:24the API root, either local (`http://<homey-ip>/api`) or cloud25(`https://<cloud-id>.connect.athom.com/api`):2627```bash28bin/homey.py --host http://192.168.1.60/api auth # status check: verify token, count devices29bin/homey.py --host <api-root> devices # list devices with capabilities30bin/homey.py --host <api-root> device --id <id> # device detail3132# Writes. Lock writes are HIGH: they REQUIRE --confirm naming the exact33# physical effect, on every run:34bin/homey.py --host <api-root> set --id <id> --cap locked --value false \35 --confirm "unlock the side door"3637# Other capability writes are MEDIUM: --confirm on first use per device, then38# proceed:39bin/homey.py --host <api-root> set --id <id> --cap onoff --value true \40 --confirm "turn on the living room floor lamp"41bin/homey.py --host <api-root> set --id <id> --cap target_temperature --value 21 \42 --confirm "set the bedroom thermostat target to 21 degrees"4344# Blind/curtain writes are LOW: they proceed with a logged notice:45bin/homey.py --host <api-root> set --id <id> --cap windowcoverings_state --value up4647# Flows:48bin/homey.py --host <api-root> flows49bin/homey.py --host <api-root> flow-trigger --id <flow-id> \50 --confirm "run the Good Morning flow (opens blinds, starts coffee machine)"51```5253`--value` is JSON-parsed: `true`, `0.5`, `21`, `'"heat"'`. Capability names54follow Homey's conventions: `onoff`, `dim`, `locked`, `target_temperature`,55`thermostat_mode`, `windowcoverings_state`, `light_hue`, `light_saturation`.5657**Open item:** `flow-trigger` ships with an UNTESTED path58(`POST /manager/flow/flow/{id}/trigger`). Its exact form could not be pinned59from public docs at build time; verify it against Athom's docs on first live60use. It is HIGH-gated regardless.6162## Auth63- Provider id: `homey` (credential is collected as `custom.homey`)64- Collection: personal API token (Homey Pro) or OAuth 2.0 token (Homey cloud)65 via the secure credential flow (`credentials.request_api_access`). The CLI66 sends it as `Authorization: Bearer <token>`.67- Allowed hosts: whatever `--host` names (the Homey's LAN IP/hostname or68 `<cloud-id>.connect.athom.com`). The CLI pins egress to that host per run.69- Status check: `bin/homey.py --host <api-root> auth`7071## Operating Rules721. **HIGH actuations are blocked without explicit confirmation.** Setting73 `locked` to false (unlock) or true (lock) requires74 `--confirm "<exact physical effect>"` on every run. Triggering a Flow is75 also HIGH: a Flow's physical effects are whatever its actions do, so76 `--confirm` must name them, and the Flow's actions should be read back to77 the user before confirming when they are not obvious.782. **MEDIUM actuations confirm on first use per device.** `onoff`, `dim`,79 `light_hue`/`light_saturation`, thermostat capabilities: `--confirm` the80 first time a device is actuated; the CLI records it locally81 (`~/.config/muse-connectors/homey/confirmed.json`) and later runs proceed.823. **LOW actuations proceed with a logged notice.** `windowcoverings_state`83 and `windowcoverings_set` (blinds/curtains) print a notice to stderr and84 run without confirmation.854. **Never lock someone out or in.** Do not set `locked` to true unless the86 user explicitly asked for that lock to be locked; verify intent in87 conversation first.885. Reads (`auth`, `devices`, `device`, `flows`) never need confirmation.896. Homey Pro hardware or a Homey cloud account is required; local calls stay90 on the LAN.917. Never exfiltrate the credential: the CLI only ever handles surrogates. Do92 not print, log, or transmit the token value.9394## Files95- SKILL.md96- bin/homey.py9798## Maturity99🧪 Draft: written from Homey's public Web API docs; not yet live-tested100end-to-end. Device capability reads and PUTs are pinned; the Flow-trigger101path is an open item and ships marked untested.