| name | homematic |
| description | Read Homematic IP Home Control Unit state and prepare guarded smart-home control messages without exposing HCU credentials. |
| user-invocable | true |
| requires | {"bins":["node"]} |
| credentials | [{"id":"homematic-hcu-auth-token","kind":"bearer","required":true,"secret_ref":{"source":"store","id":"HOMEMATIC_HCU_AUTH_TOKEN"},"scope":"Homematic IP HCU Connect API WebSocket authtoken header","how_to_obtain":"Enable HCU developer mode, generate an activation key, use\n`node skills/homematic/homematic.cjs http-request auth-token` and\n`confirm-token`, then set the confirmed Connect API auth token as\n`HOMEMATIC_HCU_AUTH_TOKEN` through browser admin at\n`/admin/secrets`; if browser admin is unavailable,\nuse `/secret set HOMEMATIC_HCU_AUTH_TOKEN \"<token>\"` in browser `/chat`\nor TUI; local console fallback:\n`hybridclaw secret set HOMEMATIC_HCU_AUTH_TOKEN \"<token>\"`.\n"},{"id":"homematic-hcu-activation-key","kind":"header","required":false,"secret_ref":{"source":"store","id":"HOMEMATIC_HCU_ACTIVATION_KEY"},"scope":"One-time HCU Connect API token enrollment","how_to_obtain":"Generate an activation key from HCUweb developer mode and set it only\nlong enough to enroll the Connect API client as\n`HOMEMATIC_HCU_ACTIVATION_KEY` through browser admin at\n`/admin/secrets`; if browser admin is unavailable,\nuse `/secret set HOMEMATIC_HCU_ACTIVATION_KEY \"<activation-key>\"` in\nbrowser `/chat` or TUI; local console fallback:\n`hybridclaw secret set HOMEMATIC_HCU_ACTIVATION_KEY \"<activation-key>\"`.\n"}] |
| metadata | {"hybridclaw":{"category":"home-automation","short_description":"Homematic IP HCU state reads and guarded device control planning.","tags":["homematic","homematic-ip","hcu","smart-home","building-automation","r21"],"related_roadmap":["R21","R48"],"issue":1100,"stakes_tiers":{"green":"[Truncated]","amber":"[Truncated]","red":"[Truncated]"},"escalation":{"writes":"confirm-each","route":"f14"},"cost_measurement":{"system":"UsageTotals","sub_limit_key":"homematic"}}} |
Homematic
Use this skill for Homematic IP Home Control Unit (HCU) state inspection and
guarded smart-home control planning. The primary v1 integration target is the
official Homematic IP Connect API, which exposes HCU plugin communication over
WebSocket. Treat CCU/RaspberryMatic and Homematic IP Access Point cloud support
as separate compatibility paths until their protocols are implemented and
tested.
This v1 targets remote HCU Connect API clients. The HTTPS port 6969 auth
helpers implement the remote-client enrollment flow. Installed HCU plugin
containers instead receive their token from the HCU container environment and
mounted /TOKEN file; this helper does not implement container installation.
Safety Rules
- Start with
plan, summarize-fixture, plugin-ready, get-state, or
get-system-state.
- For HCU setup, generate gateway
http-request payloads with the helper.
Never ask the operator to paste activation keys or auth tokens into chat.
- For HCU WebSocket operations, use helper
websocket-message output as the
source of truth for connection headers, message type, path, stakes tier, and
approval requirement.
- For a local operator-owned read-only smoke test,
run-websocket can open
the HCU WebSocket directly using HOMEMATIC_HCU_AUTH_TOKEN from the helper
environment. Do not pass that token as an argument. Use gateway-managed
execution for any amber/red operation.
- Reads are green but still privacy-sensitive because home occupancy, alarms,
temperatures, shutters, and energy state can reveal living patterns.
- Mutating device or group actions are amber unless they affect alarms,
security zones, locks, or safety state; those are red.
- Do not execute a write unless the operator granted the exact helper-reported
requiredGrant. Include device/group ids, channel index, target value,
rollback, and expected physical effect in the approval text.
- Do not use shell
curl, ad hoc WebSocket scripts, or cleartext headers when
the gateway tool or helper output can express the request.
Command Contract
Show helper usage:
node skills/homematic/homematic.cjs --help
Plan an explicit operation. The model should choose from the documented helper
operations instead of asking the helper to parse user prose:
node skills/homematic/homematic.cjs --format json plan get-state
node skills/homematic/homematic.cjs --format json plan set-set-point-temperature
