Hubitat

Hubitat

Purpose

Read device states and invoke capability commands on a Hubitat Elevation hub through the official Maker API app: lights and dimmers, deadbolt locks, garage door controllers, thermostats, location modes, and the Hubitat Safety Monitor (HSM). Use it when the user asks about or wants to change anything paired to their Hubitat hub. Commands drive real physical hardware, so writes are confirmation-gated (see Operating Rules).

Tooling

All commands go through bin/hubitat.py. --host is required on every run: the local Maker API base URL (http://<hub-ip>/apps/api/<app-id>) or the cloud relay URL the Maker API app issues:

bashCopy code
bin/hubitat.py --host http://192.168.1.50/apps/api/12 auth        # status check: verify token, count devices
bin/hubitat.py --host <base> devices                               # list devices with current attributes
bin/hubitat.py --host <base> device --id <id>                      # device detail
bin/hubitat.py --host <base> events --id <id>                      # recent device events

# Writes. lock/unlock and garage open/close are HIGH: they REQUIRE --confirm
# naming the exact physical effect, on every run:
bin/hubitat.py --host <base> command --id <id> --command unlock \
    --confirm "unlock the front door deadbolt"
bin/hubitat.py --host <base> command --id <id> --command close \
    --confirm "close the garage door"

# Lights, dimmers, thermostats are MEDIUM: --confirm on first use per device,
# then proceed:
bin/hubitat.py --host <base> command --id <id> --command on \
    --confirm "turn on the kitchen lights"
bin/hubitat.py --host <base> command --id <id> --command setLevel --param 30 \
    --confirm "dim the hallway lights to 30 percent"
bin/hubitat.py --host <base> command --id <id> --command setHeatingSetpoint --param 68 \
    --confirm "set the thermostat heating target to 68"

# Modes and HSM are MEDIUM (first use needs --confirm):
bin/hubitat.py --host <base> modes
bin/hubitat.py --host <base> mode-set --id <mode-id> --confirm "set house mode to Away"
bin/hubitat.py --host <base> hsm
bin/hubitat.py --host <base> hsm-set --state armAway \
    --confirm "arm the Hubitat Safety Monitor in Away mode"

--param values become extra path segments in order (setLevel takes the level; setHeatingSetpoint takes the degrees). Device command names follow the device's capabilities: on, off, setLevel, lock, unlock, open, close, setThermostatMode, setCoolingSetpoint, and so on.

Auth

• Provider id: hubitat (credential is collected as custom.hubitat)
• Collection: Maker API access token via the secure credential flow (credentials.request_api_access). On the hub: Apps > Maker API, enable the devices Muse may touch, and copy the access token shown for the app instance. The CLI appends it as ?access_token=<token> on every request. Note that the token travels in the query string: prefer the local LAN URL over the cloud relay when possible, and treat the token like a password.
• Allowed hosts: whatever --host names (local hub IP/hostname or the cloud relay host). The CLI pins egress to that host per run.
• Status check: bin/hubitat.py --host <base> auth

Operating Rules

1. HIGH actuations are blocked without explicit confirmation. lock, unlock, open, and close (deadbolts, garage doors) require --confirm "<exact physical effect>" on every run. Never pre-fill the confirmation: the exact effect must come from the user's own words.
2. MEDIUM actuations confirm on first use per device. Lights, dimmers, thermostat commands, location-mode changes, and HSM arm/disarm need --confirm the first time; the CLI records it locally (~/.config/muse-connectors/hubitat/confirmed.json) and later runs proceed. Arming HSM enables intrusion/smoke/water monitoring and siren/strobe alerts: say so when confirming.
3. Never lock someone out or in. Do not lock a door unless the user explicitly asked for that lock to be locked; verify intent in conversation before the first lock command on any device.
4. Reads (auth, devices, device, events, modes, hsm) never need confirmation.
5. The Maker API only exposes devices the user enabled in the app. If a device is missing, enable it in the hub's Maker API settings first.
6. Local calls stay on the LAN with no cloud dependency; the cloud relay URL works remotely but routes the token through Hubitat's cloud.
7. Never exfiltrate the credential: the CLI only ever handles surrogates. Do not print, log, or transmit the token value (and remember it travels in the query string, so never paste a full request URL anywhere).

Files

• SKILL.mdCheck Domain?
• bin/hubitat.py

Maturity

🧪 Draft: written from Hubitat's public Maker API docs; not yet live-tested end-to-end. The command path-segment form and the HSM/mode endpoints are untested against a real hub.