One daemon between your Homematic CCUs and the rest of your smart home.

OpenCCU-Loom

OpenCCU-Loom is a standalone Go daemon that talks to Homematic and
HomematicIP CCUs (CCU2, CCU3, RaspberryMatic, OpenCCU) over XML-RPC,
BIN-RPC and JSON-RPC — and exposes them through MQTT, a REST +
WebSocket API, a web Config UI, a native Matter bridge and an MCP
server. It runs several CCUs at once, administers them (pairing,
firmware, links, programs, system variables, groups), records
measurement history, and ships a complete local alarm system.

Single static binary, no CGo, no cloud, no Home Assistant required —
though it integrates with Home Assistant through MQTT Discovery,
Matter, and two ready-made add-ons.

Features

North-bound bridges

• MQTT — Home Assistant Discovery and a raw topic plane in
  parallel, bidirectional control via /set topics, localized entity
  names. Pure-Go MQTT 5.0 client (3.1.1 selectable).
  → docs/mqtt-topic-schema.md
• REST + WebSocket — OpenAPI 3.1 contract, RFC 9457 problem+json,
  Idempotency-Key middleware, resumable WebSocket subscriptions with
  typed broadcasts. → assets/openapi.yaml,
  assets/wsapi.json
• Config UI — Svelte 5 SPA (Tailwind 4, embedded via go:embed) as
  the primary surface: login, OIDC and first-run onboarding all live in
  the SPA. Fully localized (en + de), light/dark, and a Home-Assistant-
  native visual skin. → docs/user/web-ui.md
• Matter — native-Go bridge (no CHIP SDK): PASE/CASE, full
  Read/Write/Invoke/Subscribe/TimedRequest, generic measurement and
  bridge-core cluster servers, and projections for switch / light /
  cover / climate / lock / siren / valve / button / text-display. One
  Matter endpoint per physical device. Default off.
  → docs/user/matter.md
• MCP — Model Context Protocol server so AI clients can read (and,
  optionally, write) the device model.
  → ADR 0025
• Webhooks — outbound HTTP fan-out for device, hub and alarm events.

CCU connectivity

• Multi-CCU from day one — one daemon, many CCUs, every store,
  coordinator and topic scoped by central. No "the one CCU" anywhere.
  → docs/user/multi-ccu.md
• Push everywhere, no polling — XML-RPC + JSON-RPC for HmIP-RF,
  BidCos-RF, BidCos-Wired, HmIP-Wired and VirtualDevices; native
  BIN-RPC for CUxD, including our own BIN-RPC callback server.
• Hot-plug — newly paired devices appear without a restart;
  readiness-gated bring-up waits for a co-booting CCU instead of
  serving half a device tree.
• Reliability layer — circuit breaker, retry, throttle, request
  coalescer and ping/pong per interface, with recorded default values
  pinned by contract tests.
• Device model — generated device profiles plus custom data points
  (light, cover, climate, lock, siren, …), calculated and combined data
  points, week profiles / schedules, and hub entities (system
  variables, programs, service messages).

CCU administration

Everything below is driven from the Config UI and the REST/WS API —
no detour through the CCU WebUI:

• Devices — pairing inbox with first-time configuration, install
  mode, HmIP teach-in via SGTIN + key (no internet needed), wired-bus
  search, guided device replace, delete with factory-reset and
  dependency check, per-device communication test, rename device and
  channel, restore stored configuration.
• Channels — MASTER paramset editor with session-based editing,
  undo/redo and presets, "determine" for determinable values, AES
  secured transmission, team assignment, and per-channel visibility /
  operation lock.
• Links — global direct-links overview, create / rename / delete /
  test, plus central links (press-event forwarding) with live active
  state.
• Groups — Homematic heating groups: list, create, edit, delete,
  member picker at scale.
• Programs & system variables — run (optionally only when the
  condition holds), delete, rename, create alarm and logic variables,
  edit value lists, assign channels, and see where a variable is used
  before deleting it.
• Rooms, functions & areas — assign per channel, and group CCU
  rooms into operator-defined areas (floors, outbuildings) that filter
  every device list and picker.
• Fleet health — firmware updates with duty-cycle warning, signal
  quality, per-radio-interface duty cycle and carrier sense,
  diagnostics artefacts, service-message acknowledge/suppress, backups,
  CCU reboot, and a cache clear + re-pull.

Alarm system

A complete, local-first alarm system in the daemon — no cloud, no CCU
program spaghetti: zones with arm/disarm and delays, sensors with hold
time and cross-zoning, capability-derived outputs (sirens with tone /
pattern / sound file, sysvar mirrors, notifications), guided keyfob
bindings (e.g. HmIP-KRCA), PIN codes, journal, walk test and a
re-runnable setup wizard. Surfaces as a Home Assistant
alarm_control_panel over MQTT.
→ docs/alarm-user-guide.md

Data & insight

• Measurement history — opt-in recorder with per-datapoint toggle,
  persisted to SQLite, rendered as in-SPA charts.
• Diagrams & energy — named multi-series diagrams with a guided
  series editor, plus a dedicated energy view.
• Audit log — every configuration change appended and queryable.
• Metrics & tracing — Prometheus collectors and an OTLP span
  exporter.

Operations & security

• Authentication — HTTP Basic, Bearer tokens, session cookies with
  CSRF, OpenID Connect (PKCE, JWKS-verified RS256, role mapping),
  CCU-delegated login (ADR 0043)
  and Home Assistant Ingress passthrough
  (ADR 0044).
  Role-based authorization across every north-bound surface
  (ADR 0051).
• Runtime configuration — almost every knob is editable in the SPA
  and takes effect without hand-editing YAML (see below).
• Discovery — the daemon announces itself via mDNS and finds CCUs
  on the network via SSDP.
• Packaging — single static binary (CGO_ENABLED=0) for Linux
  amd64 / arm64 / armv7, a multi-arch Docker image, two Home Assistant
  add-ons (daemon + remote ingress proxy), and a CCU/RaspberryMatic
  add-on that updates itself
  (ADR 0057).

Status

All north-bound bridges work end-to-end against a real CCU and against
the godevccu simulator. CHANGELOG.md is the
authoritative release history — it carries the current version rather
than this page, which would re-drift every release; the shipped build
reports its own version and REST APIVersion on /about and
GET /api/v1/info. notes/plans/roadmap.md
covers what is next.

Maturity: beta — the feature set is complete and in daily productive
use, but it has not been hardened across a wide range of installations
yet. Expect bugs, keep a CCU backup, and note that the daemon can not
only read your CCU but also change it (pairing, deleting, writing
paramsets).

The Matter bridge is alpha — considerably younger than the rest and
the least proven part. It is off by default; switching it on is an
explicit test decision, not something to build load-bearing automations
on. Production-grade Matter attestation additionally requires
vendor-supplied DAC/PAI/CD bundles configured by the operator; the
bundled CSA Test PAA chain is fine for development and for
Apple- / Google- / chip-tool-driven testing.

Quickstart

Docker

docker run -d --restart unless-stopped \
  -p 8119:8119 -p 8120:8120 -p 8129:8129 \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  -v openccu-loom-data:/app/var \
  ghcr.io/sukramj/openccu-loom:latest run --config /app/config.yaml

--restart unless-stopped (already set in docker-compose.yaml) is
what makes the Config UI's Restart action work: the daemon exits,
Docker brings the container back.

Binary

make build
./bin/openccu-loom run --config config.yaml

Home Assistant add-ons

Add https://github.com/SukramJ/openccu-loom as a repository under
Settings → Add-ons → Add-on Store → ⋮ → Repositories, then install
OpenCCU-Loom. The Config UI appears as a sidebar panel (Ingress)
and on :8119; state persists in the add-on's /data. A second add-on,
OpenCCU-Loom Remote (ADR 0054),
proxies a daemon running elsewhere into the same sidebar.
→ packaging/ha-addon/README.md

CCU / RaspberryMatic add-on

Runs the daemon directly on the CCU, defaults to CCU-delegated login,
and can update itself from the project's GitHub releases.
→ packaging/ccu-addon/README.md

First run

1. Start the daemon with no user configured.
2. Open http://localhost:8119/ — the SPA renders the onboarding
   wizard and creates the first admin.
3. Add your CCUs, then enable the bridges you want.

The full walkthrough is docs/getting-started.md
and docs/user-guide.md.

Configuration model

Configuration lives in three tiers so the SPA can drive almost
everything at runtime:

The daemon overlays the live tier on top of the YAML: an empty database
starts from the YAML (that's the seed), SPA edits win from then on, and
DELETE /api/v1/config/sections/{section} reverts a section to its YAML
fallback — so GitOps + restart stays a valid workflow.
example.config.yaml is intentionally short;
GET /api/v1/config/schema returns the complete field schema with each
field's classification (basic / expert / secret) — the same endpoint the
SPA builds its editors from.

Passwords never have to touch config.yaml. Type them into the SPA
(stored encrypted at rest, redacted from backups unless
--include-secrets is passed), or keep them in your own secret store
and reference the variable name — centrals[].password_env per CCU,
OPENCCU_LOOM_MQTT_PASSWORD, OPENCCU_LOOM_OIDC_CLIENT_SECRET.
Docker env_file: and Kubernetes envFrom: work the same way; details
and the plaintext escape hatch for test rigs are in
docs/user-guide.md and
docs/SECURITY.md.

Why "OpenCCU-Loom"?

OpenCCU (openccu.de) is the cloud-free,
Buildroot-based smart-home OS for the HomematicIP CCU that this project
extends — and, via openccu-data,
the upstream the daemon's embedded metadata is derived from.

A loom is the bundled cable harness running through a car or an
aircraft: many conductors, one routed path. That is the daemon's job —
many CCU wire protocols come in on one side, the standard north-bound
protocols come out on the other. The mark shows that cross-section.

Relationship to Home Assistant

OpenCCU-Loom does not need Home Assistant, and Home Assistant does not
need OpenCCU-Loom — they overlap, so the useful question is which one
owns the CCU connection and how devices travel from there.

• HA only, one CCU, everything fine? Keep Homematic(IP) Local
  talking to the CCU directly; the daemon adds nothing.
• Want one CCU connection, several CCUs as one fleet, CCU
  administration outside the CCU WebUI, a local alarm system or
  measurement history? Let the daemon own the CCU and feed HA over
  MQTT Discovery.
• Only a third system (Node-RED, InfluxDB, evcc, …) needs the data?
  Run the daemon with the raw topic plane and Discovery off —
  no HA entities, no duplicates.
• Matter mainly pays off without HA; with HA you would usually
  publish to Apple/Google/Alexa from HA itself.
• The Homematic(IP) Local loom backend (integration talks REST/WS
  to the daemon) is wired but not yet user-selectable — a preview.

MQTT Discovery, the loom backend and the Matter bridge each create their
own HA entities, so exactly one of them per device. Wherever that
lands, the recommended place to run the daemon is on the CCU
(CCU / RaspberryMatic add-on): the chatty XML-RPC/BIN-RPC hop stays on
loopback, callback addressing resolves itself, and HA restarts stop
touching the Homematic side. The full scenario catalogue, combination
matrix, anti-patterns and migration paths are in
docs/user/home-assistant.md.

Relationship to aiohomematic

OpenCCU-Loom began as a Go port of
aiohomematic and now
develops independently. aiohomematic remains the Python library
powering the Home Assistant integration Homematic(IP) Local — and the
reference implementation for CCU-side semantics, cross-checked by a
scoped model-snapshot regression gate. It is a reference, not a
dependency, and no longer a parity target.

On the Matter side the gold standard is
matter.js HEAD: cluster
IDs, revisions, constraints and wire shape are mirrored from it and
locked by parity tests.

Building

make build        # ./bin/openccu-loom
make test         # unit + contract tests
make integration  # godevccu + Mosquitto (Mosquitto needs Docker)
make lint         # golangci-lint (zero findings required)
make docker       # multi-arch image via buildx

Prerequisites: Go 1.26+, golangci-lint v2, gofumpt, goreleaser,
Docker (+ buildx) for the Mosquitto-backed integration tests.
Integration runs use godevccu,
a pure-Go CCU simulator consumed as a regular module dependency — no
Python toolchain required. Four structural pillars guard against
architecture drift — reachability (make reachability), wiring pin
tests, wire snapshots (make wire-snapshots) and E2E smoke
(make e2e).

Documentation

• docs/getting-started.md — install and
  first CCU in a few minutes.
• docs/user-guide.md — the operator manual;
  docs/user/ covers concepts, the web UI, multi-CCU
  and Matter.
• docs/user/home-assistant.md — which
  integration path to run when Home Assistant is in the picture, and
  which combinations are mutually exclusive.
• SPECIFICATION.md — design intent, hard
  constraints, resolved decisions; docs/adr/ — the
  architecture decisions behind them, e.g. Matter
  (0012), MQTT topics
  (0011) and
  multi-CCU (0002).
• docs/SECURITY.md — threat model and audit
  checklist; docs/caching.md — every cache layer
  and its boot-time radio cost.
• docs/external-clients/ — the wire
  contract for Python / TypeScript / Rust clients; start at the
  topic hierarchy.
• CLAUDE.md — entry point for fresh contributors and
  AI assistants.

Contributing

CONTRIBUTING.md covers local setup, PR
expectations and the release workflow. Please open an issue first so we
agree on scope — especially for changes to the wire layer or the device
profile catalogue. AI_POLICY.md sets the rules for
AI-assisted contributions: AI as a tool is welcome, autonomous agent
submissions are not. Parts of OpenCCU-Loom are developed with agentic AI
assistance, primarily Claude Code
— but every change is reviewed by a human maintainer and has to pass the
full test, contract and parity suites before it lands.

License

The source code is MIT, aligned with the rest of the
aiohomematic ecosystem.

The binary distribution additionally ships CCU metadata archives
sourced from openccu-data via
the versioned go-openccu-data
module (ADR 0053). Those
archives are governed by the eQ-3 HomeMatic Software License — free
for private and non-commercial use; commercial redistribution requires
written permission from eQ-3 AG. See
the module's NOTICE.md
and ADR 0003. Operators with
commercial use-cases can point cfg.CCUData.{translations_path,easymode_path}
at self-licensed equivalents — the daemon degrades gracefully.

Third-party prior art and module dependencies with their licenses and
verbatim copyright notices are recorded in
THIRD-PARTY-NOTICES.md; full license texts
live under licenses/.

Acknowledgements

Narrative credits are in docs/attribution.md.
With particular thanks:

• aiohomematic (MIT) — the
  reference implementation for wire behaviour and the device profile
  catalogue, by SukramJ and Daniel Perna; plus
  aiohomematic-config
  (MIT) for the form-schema, grouping and label logic in the Config UI.
• pydevccu (MIT, Daniel
  Perna & SukramJ) — the CCU simulator that
  godevccu is a Go port of.
• matter.js (Apache-2.0) —
  the gold standard for the entire Matter bridge.
• homematicip-local-frontend
  (MIT) and the Home Assistant frontend
  (Apache-2.0) — UI interaction and control-primitive references.
• The Homematic / HomematicIP community and eQ-3, for the devices and
  the protocol knowledge that make any of this possible.