Configuration Reference¶

The authoritative reference for every setting OpenCCU-Loom reads at startup: where configuration comes from, how the bootstrap and database tiers interact, and the keys, types, defaults, and environment overrides for each block.

How configuration is layered¶

OpenCCU-Loom resolves configuration from three sources, applied in this order (later wins):

1. Compiled-in defaults — every field has a safe default.
2. YAML config file (config.yaml) — read at startup.
3. Environment variables (OPENCCU_LOOM_*) — a curated overlay.

On top of that, most settings are also editable at runtime through the web Config UI; those edits are stored in the SQLite database and win over the YAML on the next start.

Config file discovery¶

When you start the daemon with openccu-loom run and omit --config, it probes these locations in order and uses the first file that exists:

If none exists the daemon runs on built-in defaults and logs no config file found, running with defaults. An explicit --config <path> always wins over discovery.

openccu-loom run --config /etc/openccu-loom/config.yaml

A minimal config.yaml¶

data_dir: /var/lib/openccu-loom
locale: en

centrals:
  - name: home
    host: 172.18.4.29
    username: Admin
    password: "your-ccu-password"
    interfaces: [HmIP-RF, BidCos-RF]

north:
  rest:
    listen: ":8119"

For the complete annotated set of every key, see example.config.full.yaml in the repository, and example.config.yaml for a shorter starter file.

Environment overlays¶

A narrow set of environment variables overrides the matching YAML field. They are useful for container deployments where the image carries the YAML and a handful of values are per-deployment. Variables that are unset leave the YAML value intact.

The daemon also reads an optional .env file from the working directory (or the path named by env_file: in the config) at startup. Real process-environment values always win over .env entries. See example.env for the full annotated list.

services:
  openccu-loom:
    image: ghcr.io/sukramj/openccu-loom:latest
    environment:
      OPENCCU_LOOM_DATA_DIR: /data
      OPENCCU_LOOM_CALLBACK_HOST: 192.0.2.10
    volumes:
      - openccu-loom-data:/data

export OPENCCU_LOOM_DATA_DIR=/var/lib/openccu-loom
export OPENCCU_LOOM_CALLBACK_HOST=192.0.2.10
openccu-loom run --config /etc/openccu-loom/config.yaml

Secrets¶

Secret-classed fields are encrypted at rest in the database with AES-256-GCM and stored with the prefix enc:v1:. The master key is resolved hybrid:

1. OPENCCU_LOOM_SECRET_KEY — a base64-encoded 32-byte key. Wins when present. Generate one with openssl rand -base64 32.
2. Otherwise an auto-generated key file at <data_dir>/secret.key (created with mode 0600 on first start).

If no key can be resolved or written, the daemon logs a warning and stores secret values in plaintext rather than refusing to boot.

Fields treated as secrets include centrals[].password, north.rest.auth.users, north.rest.auth.tokens, north.rest.auth.oidc.client_secret, north.mqtt.password, and the Matter commissioning passcode/salt and DAC key path.

Configuration blocks¶

Defaults shown are the compiled-in values. Keys marked secret are encrypted at rest. The env column lists the overlay variable when one exists.

locale¶

UI/label language. Catalogues ship for en and de.

data_dir¶

Directory for the SQLite database (<data_dir>/openccu-loom.db), the auto-generated secret.key, and other on-disk state. This is a bootstrap-tier field — set it in YAML/environment.

logging¶

level is one of debug, info, warn, error. format is one of json, text, text-color. overrides maps a dot-separated subsystem path to a level, for static boot-time overrides; runtime overrides are installed (with a TTL) via the diagnostics API.

callback¶

The XML-RPC and BIN-RPC callback servers that receive push events from the CCU. The host/ports here must be reachable from the CCU.

port is the XML-RPC callback (HmIP/BidCos); bin_port is the BIN-RPC callback (CUxD). A value of 0 means the OS assigns an ephemeral port. port_range (e.g. "30000-30099") applies to the XML-RPC listener and takes precedence over port: when it is set the listener binds the first free port inside the range and port is not used. A malformed range is rejected when the config is saved, not only at the next boot. public_host overrides the host advertised to the CCU when the daemon is behind NAT. The effective port is re-advertised to the CCU on every reconnect, so dynamic ports survive restarts.

max_connections caps the number of concurrent connections each callback listener accepts (0 uses the default of 64) — a guard against a misbehaving or hostile peer exhausting file descriptors. restrict_source_ips, when true, makes the listeners accept callbacks only from the configured CCU IPs (plus loopback); leave it false unless every CCU address is static and known.

north.rest and authentication¶

The REST + WebSocket server. This is the API surface and the backend for the SPA.

Authentication lives under north.rest.auth:

Two further login sources delegate authentication elsewhere. CCU-delegated login (ADR 0043) validates the login form against a CCU's own user database and maps the CCU UserLevel onto a Loom role — so a break-glass local admin always remains a fallback:

HA Ingress passthrough (ADR 0044) trusts a request proxied by the Home Assistant Supervisor as an admin without a local login. It is a deliberate, supervised-only auth bypass; a genuine token or session always wins over it:

Authentication setup (Basic, Session, API tokens, OIDC, CCU-delegated login, and HA Ingress passthrough) is covered in detail on the auth admin page (docs/admin/auth.md).

north.ui¶

north.ui.enabled gates only the minimal no-JS server-rendered diagnostic surface — /health and /about — that stays reachable when the Svelte SPA cannot load. Login, logout, OIDC, and the first-run onboarding wizard all live in the Svelte SPA (ADR 0045), served on the REST listener (:8119 by default); there is no server-rendered HTMX login or /setup template.

north.ui.listen has been removed — the diagnostic surface shares the REST listener, so there is no separate UI bind address. Delete the key (and the OPENCCU_LOOM_UI_LISTEN env var) from existing configs.

north.mqtt¶

The MQTT bridge (Home Assistant Discovery and/or raw topic planes).

broker_url is required when enabled is true; accepted schemes are tcp, mqtt, tls, ssl, mqtts (or a bare host:port). For the topic layout see the MQTT topic schema.

retain_cleanup_window_ms is how long (500–30000 ms; 0 = 2000) the bridge waits at boot for the broker to deliver retained messages before evicting stale discovery/legacy topics — raise it on high-latency brokers.

north.matter¶

The native-Go Matter bridge. Disabled by default; opt-in.

The default vendor/product IDs are development values from the test block — never ship them in production. Matter pairing and commissioning are covered on the Matter user page (docs/user/matter.md).

• expose_secondary_channels (expert, ADR 0049) controls the one-endpoint-per-device folding. Default false: a physical device projects a single Matter endpoint from its primary channel. Turn it on to also fan out a device's secondary actor / status channels as extra endpoints (they otherwise appear as duplicates in Apple/Google Home). Matter-only — MQTT, HA-Discovery and REST/WS always carry every channel.
• enable_time_sync (expert) mounts the TimeSynchronization cluster (0x0038) on the Root endpoint. Leave it off unless a controller needs it: Apple Home's HAP service mapper may reject the bridge at pairing when an unexpected RootNode cluster is present. Re-pair after changing it.
• dev_rotate_unique_ids (expert, dev/test only) mixes a per-boot salt into every endpoint's Matter UniqueID. Enabling it in production breaks accessory recognition — controllers must re-link every device after each restart. Keep the default false.
• case.node_id / case.fabric_id pin the operational node/fabric identity; node_id = 0 disables CASE. attestation.dac_path, pai_path, and cd_path point at production Device Attestation material (DAC + PAI + CD). When all resolve, the bridge presents that material to commissioners; otherwise it uses an ephemeral development DAC that only validates under chip-tool's --bypass-attestation-verifier. The DAC private key path (attestation.dac_key_path) and the commissioning passcode/salt are secrets encrypted at rest.
• mdns_advertise selects the mDNS advertiser: zeroconf (default, publishes the commissionable records) or noop (in-memory only, no multicast — a hermetic-test opt-out; QR-scan pairing cannot work in this mode).

north.mcp¶

The Model Context Protocol server for LLM agents. Disabled by default; read-only even when enabled until allow_writes is also set.

The MCP transport is mounted on the existing REST listener. See the MCP client guide.

north.webhook¶

A bidirectional HTTP bridge, both directions disabled by default. Outbound POSTs a signed JSON payload to an operator URL on datapoint / system-status / incident events. Inbound mounts REST routes (POST /api/v1/webhook/value, POST /api/v1/webhook/program) that external systems call to set a datapoint or trigger a program; these are real device writes, so they carry full authorization weight. Both directions are wired once at boot — toggling is restart-required.

secret is the shared key for the X-OpenCCU-Signature HMAC-SHA256 body signature (empty = no signature header). events and centrals are allowlists (empty = all); parameter_glob further filters datapoint events by parameter name. inbound.token is an optional bearer token accepted in addition to the normal REST auth chain, so a header-only caller (e.g. a doorbell) can POST without a session.

north.discovery.mdns¶

LAN self-advertisement so zeroconf-aware clients (e.g. Home Assistant) can auto-discover the daemon.

The advertised port mirrors north.rest.listen. Disable for security-sensitive deployments where LAN visibility is unwanted.

north.discovery.ssdp¶

Active SSDP / UPnP discovery of Homematic / OpenCCU central units on the LAN (ADR 0046). When enabled the daemon periodically multicasts an M-SEARCH, follows each responder's basic_dev.cgi, and surfaces matching CCUs in the UI so the operator can adopt or ignore them.

This is a read-only LAN scan — a multicast probe only; no data about the daemon leaves the LAN, and it simply finds nothing where multicast is unavailable (some container networks). It is on by default; disable it if unsolicited multicast probes are unwanted.

centrals[]¶

One entry per configured CCU. OpenCCU-Loom is multi-CCU from day one; see the multi-CCU guide.

interfaces accepts a short list of names or a long form with per- interface overrides:

centrals:
  - name: home
    host: 172.18.4.29
    username: Admin
    password: "your-ccu-password"
    interfaces:
      - HmIP-RF
      - name: BidCos-RF
        port: 2001
        rpc_type: xmlrpc
      - name: CUxD          # CUxD is reached over BIN-RPC

rpc_type is xmlrpc or binrpc (empty derives it from the interface name). json_rpc_port defaults to 80 (plain) or 443 (TLS); set it when the CCU sits behind a non-standard proxy. Set tls_insecure_skip_verify only against a self-signed CCU on a trusted network. check_connection_interval of 0 uses the 30s default; a negative value disables the background connection check.

Each central also carries an optional behavior: sub-block of expert per-central toggles that shape how devices and hub entities are modelled. All are hot-reloadable and default to sensible values:

persistence¶

Tuning for the SQLite-backed caches. The VALUES cache (persistence.values_cache, ADR 0019) persists wire-DP values so they survive a restart; it is on by default. The measurement-history recorder (persistence.history, ADR 0040) is opt-in: enabling it opens a dedicated history.db, records numeric VALUES samples, drives the SPA charts (GET /history), and can optionally push each sample to an external time-series store.

Sysvar and program markers¶

The marker lists do not decide whether a system variable or program is imported — everything the CCU exposes is imported. They decide how an entry arrives in a consumer such as Home Assistant:

An entry matching any configured marker arrives enabled; every other entry arrives disabled and is switched on per entity. With no markers configured, everything is imported and everything arrives disabled.

The reference stack also recognises an MQTT marker, which steers a hand-off this daemon does not need — its MQTT bridge publishes every hub entity regardless — so the CCU editor does not offer it. A stored value is dropped when the editor opens; the token is still stripped from the CCU description so it never shows up in an entity name.

include_internal_sysvars / include_internal_programs are the equivalent switch for operators who configure no markers at all; either they or the INTERNAL marker suffice.

history.retention bounds raw samples (clamped up to a 1h floor); retention_hourly and retention_daily bound the two rollup tiers. include/exclude are parameter-name globs (exclude wins). The export token is never inline — the daemon reads it from the env var named by export.token_env.

energy_price_per_kwh makes the energy view show costs next to consumption. Leave it at 0 to show no costs at all — a tariff of zero would render every amount as 0.00, which reads as "free" rather than "not configured". energy_currency only labels those amounts; nothing is ever converted.

reliability¶

Overrides for the reliability stack (retry / throttle). Both fields default to 0, meaning "use the compiled-in behaviour"; set them only to pin a specific timing (e.g. on heavily-loaded BidCos-RF).

ccu_data¶

Optional filesystem overrides for the openccu-data metadata archives (parameter translations and easymode profiles). Both are empty by default — the daemon uses the embedded archives and falls back to raw parameter / model names if a path is set but cannot be read.

backup¶

Automatic, scheduled CCU backups. Off by default (a backup touches the CCU and produces files, so it is opt-in); manual backups via the REST/UI surface work regardless. Both fields are hot-reloaded.

keep_last prunes the oldest scheduled backups per central beyond the given count after each successful run.

security¶

When false (default and recommended) the daemon refuses to persist a central's password in cleartext — it must be encryptable with the master key (see Secrets). Set it true only in a throwaway/dev environment where no at-rest key is available; the password is then stored in plaintext in the database.

Validating a config file¶

Use the admin CLI to check a file before deploying it:

hmcli config validate /etc/openccu-loom/config.yaml

See also¶

• Backup & restore — and why secret.key must travel with the database.
• Troubleshooting — callback reachability, lockouts, lost keys.
• Security guide — at-rest encryption and hardening.
• Multi-CCU guide — running several CCUs from one daemon.
• REST + WebSocket API reference (docs/integrations/rest-ws.md).