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

Build HCU auth setup requests. The helper uses <secret:HOMEMATIC_HCU_ACTIVATION_KEY> and <secret:HOMEMATIC_HCU_AUTH_TOKEN> placeholders so the gateway resolves stored secrets server-side.

node skills/homematic/homematic.cjs --format json http-request auth-token \
  --hcu-url https://hcu1-1234.local \
  --plugin-id com.example.hybridclaw.homematic

node skills/homematic/homematic.cjs --format json http-request confirm-token \
  --hcu-url https://hcu1-1234.local

Prepare read-only HCU Connect API messages:

node skills/homematic/homematic.cjs --format json websocket-message plugin-ready \
  --hcu-url https://hcu1-1234.local

node skills/homematic/homematic.cjs --format json websocket-message get-state \
  --hcu-url https://hcu1-1234.local

node skills/homematic/homematic.cjs --format json websocket-message get-system-state \
  --hcu-url https://hcu1-1234.local

node skills/homematic/homematic.cjs --format json --hmip-system-events websocket-message get-state \
  --hcu-url https://hcu1-1234.local

Run a local HCU WebSocket read. This is for operator-owned smoke tests where the helper environment can see the stored token value; normal agent flows should prefer generated payloads and gateway-managed secrets. Use --insecure-local-tls only for operator-owned local/private HCU hosts with self-signed certificates.

HOMEMATIC_HCU_AUTH_TOKEN="<token>" \
  node skills/homematic/homematic.cjs --format json run-websocket get-state \
  --hcu-url https://hcu1-1234.local

Generate policy material for local HCU network access and SecretRef routing:

node skills/homematic/homematic.cjs --format json policy-rules \
  --hcu-url https://hcu1-1234.local \
  --agent main

Prepare guarded write messages:

First produce an approval plan. After explicit operator confirmation, run the exact approvedCommand unchanged.

node skills/homematic/homematic.cjs --format json approval-plan set-switch-state \
  --hcu-url https://hcu1-1234.local \
  --device-id 3014F711A000000000001234 \
  --channel-index 1 \
  --on true

node skills/homematic/homematic.cjs --format json websocket-message set-switch-state \
  --hcu-url https://hcu1-1234.local \
  --device-id 3014F711A000000000001234 \
  --channel-index 1 \
  --on true \
  --operator-grant approve-homematic-write

node skills/homematic/homematic.cjs --format json websocket-message set-set-point-temperature \
  --hcu-url https://hcu1-1234.local \
  --group-id 00000000-1111-2222-3333-444444444444 \
  --temperature 20.5 \
  --operator-grant approve-homematic-write

node skills/homematic/homematic.cjs --format json websocket-message set-shutter-level \
  --hcu-url https://hcu1-1234.local \
  --device-id 3014F711A000000000001234 \
  --channel-index 1 \
  --level 0.25 \
  --operator-grant approve-homematic-write

node skills/homematic/homematic.cjs --format json websocket-message acknowledge-safety-alarm \
  --hcu-url https://hcu1-1234.local \
  --operator-grant approve-homematic-security-write

Summarize a saved HCU state fixture without contacting hardware:

node skills/homematic/homematic.cjs --format json summarize-fixture \
  --fixture skills/homematic/fixtures/hcu-state.json

The helper returns auditEvents payloads for planned and live read/control operations. These are structured for the F2 audit rail and intentionally carry SecretRef ids, never secret values.