homematic

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

1. Start with plan, summarize-fixture, plugin-ready, get-state, or get-system-state.
2. For HCU setup, generate gateway http-request payloads with the helper. Never ask the operator to paste activation keys or auth tokens into chat.
3. 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.
4. 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.
5. Reads are green but still privacy-sensitive because home occupancy, alarms, temperatures, shutters, and energy state can reveal living patterns.
6. Mutating device or group actions are amber unless they affect alarms, security zones, locks, or safety state; those are red.
7. 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.
8. 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