Using the Web UI¶

OpenCCU-Loom ships a browser-based Config UI for inspecting your CCUs, browsing devices, changing values, and configuring devices — no command line needed. This page is a tour of what you can do there.

Opening the UI¶

By default the web UI listens on port 8119. In a browser on the same network, open:

http://<host-running-openccu-loom>:8119/

First run¶

The very first time you open the UI, there is no account yet. You are sent to the first-run setup page at /setup, where you create the initial administrator account.

http://<host>:8119/setup

After that, future visits go through the login page at /login.

Logging in¶

OpenCCU-Loom supports several sign-in methods (local accounts, sessions, and optionally OIDC single sign-on). Which ones are available depends on how the daemon was configured. For the details of accounts, roles, and OIDC, see Authentication.

What the UI lets you do¶

The app is organised into views. The main ones, and the everyday tasks they cover:

Not every view appears on every system:

• Log viewer and Backups are shown to administrators only.
• Programs, System variables, Groups and Backups appear only while at least one connected system offers the feature — an openccu-lite system, for example, has no programs or system variables.
• Energy and Diagrams appear only when measurement history is enabled.
• Matter appears only when the Matter bridge is enabled.

An administrator can also hide views under Settings → Navigation & views. Devices, Settings and About can never be hidden.

The sections below cover the tasks most users do.

Browsing devices, channels, and parameters¶

Open the Devices view to see every device OpenCCU-Loom has discovered across all configured CCUs. If you run more than one CCU, devices are grouped by their CCU name (the central_name).

Selecting a device opens its detail view, where you can:

1. See the device's channels.
2. Open a channel to list its data points (parameters such as STATE, LEVEL, TEMPERATURE).
3. Read the current value of each data point.

If you are unsure what "device", "channel", and "data point" mean, read Core concepts first.

Adding devices¶

Pair a new device with Add device in the Devices view: pick the interface, open the pairing window, and put the device into pairing mode.

A newly paired device is not handed to your other systems straight away. OpenCCU-Loom holds it in two steps, which you find in the add-device dialog and in the New devices view. The view is offered on every system — a CCU, an OpenCCU and an openccu-lite box alike; on a CCU it also lists the devices waiting in the CCU's own inbox.

1. Accept. The device is listed as awaiting acceptance. Accepting it builds it in OpenCCU-Loom: its channels and data points appear. The dialog asks for its name and its rooms and functions right away, so they are set as it is built.
2. Release. The device is now listed as awaiting release. It is fully usable in the web UI and the API, but MQTT / Home Assistant discovery, the Matter bridge and outbound webhooks do not see it yet. Releasing it publishes it to all of them.

Accept and release does both in one go and is the usual choice once the name and the assignments are entered. Choose Accept alone when you want to configure more on the device page before it is published; the device then waits under awaiting release in the dialog and in the New devices view, each with a Release button. If the accept works but the release does not, the device stays withheld and is listed as awaiting release, so you can release it once the cause is fixed. Assigning the device to a heating group is offered in the accept dialog of the New devices view.

A device that only a CCU's own inbox holds (with the hold switched off) is built and published by the accept itself; there is nothing to release.

The order matters because the systems behind those bridges keep the identity they see first: Home Assistant keeps the entity ids of the name a device was discovered with, and a Matter controller keeps its endpoint. Releasing last means they see the name you chose, not the factory name.

The hold only applies to devices paired while OpenCCU-Loom is running. Devices it already knows — your whole installation after an upgrade, or the devices of a CCU you add — are never held.

To publish new devices immediately instead, switch off Hold new devices until released in the Advanced behaviour section of the central (Settings → CCUs, edit the CCU), or set it in the configuration file:

centrals:
  - name: my-ccu
    behavior:
      delay_new_device_creation: false

Switching the hold off also releases every device that is waiting. The setting is described in the configuration reference.

Changing a value¶

For writable parameters, the UI gives you a control (a toggle, a slider, an input field) to set a new value. When you confirm, OpenCCU-Loom sends the change to the CCU and the device reacts.

Behind the scenes this is a single write to the parameter (PUT /api/v1/devices/{address}/channels/{channel}/data-points/{parameter}/value); you do not need to call it yourself — the control does it for you.

Configuring a device (paramsets)¶

Beyond live values, many devices have configuration parameters (the device's settings, as opposed to its current state). On a device's Configure tab, Device and channel parameters shows them on one page, laid out like the CCU WebUI's Geräte-/Kanalparameter: the device parameters first, then one block per channel (Ch. 1, Ch. 2, …). A channel block also holds the channel's name, rooms, functions and visibility flags. The device parameters and the first channel are open; every other channel loads its parameters from the device when you open its block.

Edits are collected across the whole page. A save bar at the bottom counts them, and Apply writes every changed channel; a channel that fails is named, the rest is written. Cancel discards all of them.

Expert mode (the switch at the top of the page, the same as in Settings) also shows untranslated parameters and the raw CCU name of each parameter.

You can also export a channel's configuration and import it again from the ⋯ menu of its block, which is handy for copying settings between similar devices.

Direct links¶

Direct links lists every direct link between two channels, headed Sender | Link | Receiver as in the CCU WebUI, and can group the list by sender or by receiver. A device's own links are on its Configure → Direct links tab.

• New link walks through three steps: the first link partner (any device's channel that can be linked), a compatible second partner, then a name and a description.
• Edit opens the link's profile settings: the sender's and the receiver's settings, each led by a profile (for example Switch on / off). A profile shows only the settings it leaves open; Expert shows every link parameter, with short and long keypress side by side. Apply writes both sides together.

Showing hidden parameters (un-ignore)¶

Some parameters are hidden by default to keep views clean — see parameter visibility. Settings → Advanced → Hidden parameters lists what is currently hidden and lets you switch individual parameters back on.

The list shows one row per parameter, not one row per device. A large installation hides only a few dozen distinct parameters, but each of them occurs on many device models and channels — so the row is the parameter, and you open it to choose where it applies.

1. Open Settings and pick the Hidden parameters tab.
2. Find the parameter you need — type part of its name, its translated label, or a device model into the search box.
3. Switch it on with the checkbox at the start of the row. That enables it for every device.
4. To be more selective, expand the row with the chevron on the right and tick a single device model, or a single channel of that model.
5. Click Save.

If you cannot find a parameter¶

Most hidden parameters are internal plumbing — diagnostic bits, service values the CCU marks as internal, and the individual cells of week profiles. Those categories start collapsed, so the list opens on the parameters that are usually worth a decision.

A line under the filter tells you how many rows are currently hidden and offers Show all. You can also click the category chips to filter to exactly the categories you want; each chip shows how many parameters it holds.

The category on each row names the rule that hid the parameter:

Three-state checkboxes¶

A row's checkbox has three states: empty (off), checked (on for every device), and a dash (on for some device models or channels only). The right-hand column tells you which — All devices, or how many scopes are active.

Patterns without a matching parameter¶

If you previously enabled a parameter that no device in your installation carries any more — a device you removed, or a hand-typed entry with a typo — it appears in a separate Patterns without a matching parameter list at the bottom instead of disappearing. Saving never drops those silently; remove them yourself with the ✕ button.

Once un-ignored, the parameter shows up in the device's data-point list and is published to MQTT, REST, and the other north-bound bridges like any other data point.

Charts and measurement history¶

The device detail view has a History tab that charts a data point's recorded values over time — handy for seeing how a temperature, humidity, or power reading moved across a day or week.

Measurement history is opt-in: nothing is recorded until you enable it (persistence.history in the configuration). Once on, the daemon stores samples in a separate history.db and the History tab plots them; before that the tab has nothing to show.

Health and diagnostics¶

The Diagnostics view shows the daemon's overall health and connection status to each CCU and interface — useful when a device seems unresponsive or a CCU dropped offline. There is also a server-rendered /health page if you only need a quick up/down check.

For deeper operational topics (log levels, captures, metrics), see Observability.

Where to go next¶

• Getting started — install and first run.
• Authentication — accounts, roles, and OIDC.
• Core concepts — the device model in plain language.
• Multi-CCU — running several CCUs at once.