/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
      `node skills/homematic/homematic.cjs http-request auth-token` and
      `confirm-token`, then set the confirmed Connect API auth token as
      `HOMEMATIC_HCU_AUTH_TOKEN` through browser admin at
      `/admin/secrets`; if browser admin is unavailable,
      use `/secret set HOMEMATIC_HCU_AUTH_TOKEN "<token>"` in browser `/chat`
      or TUI; local console fallback:
      `hybridclaw secret set HOMEMATIC_HCU_AUTH_TOKEN "<token>"`.
  - 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
      long enough to enroll the Connect API client as
      `HOMEMATIC_HCU_ACTIVATION_KEY` through browser admin at
      `/admin/secrets`; if browser admin is unavailable,
      use `/secret set HOMEMATIC_HCU_ACTIVATION_KEY "<activation-key>"` in
      browser `/chat` or TUI; local console fallback:
      `hybridclaw secret set HOMEMATIC_HCU_ACTIVATION_KEY "<activation-key>"`.
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:
        - plan
        - fixture-summary
        - hcu-get-state
        - hcu-get-system-state
        - plugin-ready
      amber:
        - auth-token
        - confirm-token
        - switch-control
        - thermostat-control
        - shutter-control
        - scene-trigger
      red:
        - safety-alarm-acknowledge
    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

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