openccu-loom-client
Status: Beta — transport, event bus, domain store, the full daemon
REST surface (HA-relevant + admin/ops), and the aiohomematic compat
namespace are in place (see "Status of the wire contract" below).
Async Python REST + WebSocket client for the openccu-loom daemon.
An alternative backend for the homematicip_local Home-Assistant
custom component — coexisting with aiohomematic rather than replacing
it. Instead of direct XML-RPC/JSON-RPC, it mediates CCU contact through
the openccu-loom daemon. Reusing aiohomematic at runtime (routing-key
algorithm, protocols, selected model code) is a deliberate part of this
strategy: it shares one contract between two backends and avoids silent
drift. The compat/aiohomematic/ namespace shim is how the backend is
plugged in today; CLAUDE.md carries the reasoning behind that form.
Architecture
Wire types are generated into openccu_loom_client/wire/ (Pydantic
models + enum catalogue, from the daemon's assets/openapi.yaml,
assets/wsapi.json and assets/schemas/enums.json). They shipped as the
separate openccu-loom-types distribution until 2026.9; that package is
now a thin alias that requires this one, and nothing needs to depend on it.
Everything under wire/ is machine output; everything else here is
hand-written:
transport/http.py— async REST client (aiohttp), RFC 9457problem+jsonparsing, retry/backoff.transport/ws.py— WebSocket loop with subscribe/unsubscribe, heartbeat, resume-after-reconnect viaseq/sincecursor per ADR-0022.client.py—LoomClientfacade: snapshot bootstrap, event bus, in-memory store, and the operation modules (devices,datapoints,custom_data_points,hub,system,schedules,links).compat/aiohomematic/— namespace shim so existinghomematicip_localimports keep working during the cutover. This includes aLoomCentralAdapterthat presents aiohomematic'sCentralUnit+ coordinator surface, and a categorised data-point model (genericDp*, hubSysvarDp*/ProgramDp*, customCustomDp*for light/cover/climate/lock/siren/valve/switch) withunique_id/category/registeredbookkeeping. A refresh bridge fans the daemon's value/sysvar/custom events into the singleDataPointStateChangedEvent(keyed byunique_id) HA entities subscribe to.
Connecting through an openccu-lite box
An openccu-lite box can serve the daemon through its own web server at
https://<box>/addons/loom/, behind a session gate that lets nothing
through without a box login. Set LoomConfig.box_ingress to go that way:
from openccu_loom_client import BearerAuth, BoxIngressConfig, LoomConfig
config = LoomConfig(
host="openccu-lite.local", # the box
auth=BearerAuth(token="<daemon API token>"),
box_ingress=BoxIngressConfig(username="admin", password="<box password>"),
)
The client logs in to the box (POST /api/auth/v1/login) on connect and
carries the box session as ?sid= on every REST request and every WebSocket
(re)connect; when the gate turns a request away it logs in again and retries
once, then raises LoomBoxGateError (LoomBoxLoginError when the login
itself is refused). The box session only opens the gate — the daemon still
authenticates the request through auth. In this mode tls describes the
box's listener, BoxIngressConfig.port defaults to 443 (80 without TLS),
path_prefix to /addons/loom, and LoomConfig.port is unused.
Status of the wire contract
The daemon's external-client contract is tracked in
notes/reference/external-client-asks.md
in the daemon repo. All push-event
payloads needed by Home Assistant (DataPointValueChanged,
CustomDataPointStateChanged, CentralStateChanged,
SystemStatusChanged, SysvarChanged, ProgramExecuted,
InstallModeChanged, DeviceCreated, DeviceRemoved) ship typed and
are bound in the event registry.
The full daemon REST surface is wrapped — typed end-to-end against the generated wire models:
- HA-relevant: devices/channels/data-points, paramsets, batch reads, custom data points, programs and sysvars (incl. create / metadata-patch / lifecycle), alarm/service messages (incl. ack), install-mode, interfaces, rooms/functions, firmware updates, calculated data points, climate schedules / week-profiles, and direct/central links.
- Admin / ops: auth + API-token provisioning (
client.auth), users (client.users), centrals (client.centrals), config management (client.config_admin), diagnostics / log-levels / capture / RPC-recording / metrics / values-cache / MQTT-reload / audit (client.diagnostics), backups incl. importing an externally produced.sbk(client.backup), CCU maintenance — reboot / power off / safe mode / recovery mode / astro position (client.system), edit-lock sessions (client.sessions), the Matter bridge (client.matter), and parameter visibility (client.visibility).
The schedule, link and calculated-data-point schemas live in the
daemon's openapi.yaml (components.schemas) and are regenerated into
openccu_loom_client/wire/, so they are typed rather than free-form
dicts.
Two broadcasts that were once daemon-side gaps are now live and bound:
datapoint.optimistic_rolled_back— broadcast by the daemon, consumed asDataPointOptimisticRolledBackEventand bridged to the HA-facingOptimisticRollbackEvent. Local synthesis from RESTset_valuefailures remains available as a fallback.- Device trigger / keypress events — emitted on the
device.{address}.channels.{channel}.triggertopic and bound toDeviceTriggerEvent; the HA event-group surface is served byquery_facade.get_event_groups.
Development
python3.14 -m venv venv
source venv/bin/activate
pip install -e '.[dev]'
pytest
Parts of openccu-loom-client are developed with agentic AI assistance, primarily Claude Code. Submitted issues are also triaged and analysed with agentic help. Every change is still reviewed by a human maintainer and has to pass the project's tests before it lands — the AI accelerates the work, it does not replace the review gate.
Contributing
AI-assisted contributions are welcome, but you must review, understand
and stand behind everything you submit — see
AI_POLICY.md for the rules.
License
MIT. See LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for openccu-loom-client 2026.10.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| openccu_loom_client-2026.10.1.tar.gz | 332.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| openccu_loom_client-2026.10.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 701.1 kB
Release files / openccu_loom_client-2026.10.1.tar.gz
| Download URL | openccu_loom_client-2026.10.1.tar.gz |
|---|---|
| Size | 332.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5783dc142cbe9ecf315a8ce91fd1b3f3f4e547937f953319c252b816fa85838e
|
|
BLAKE2b-256 checksum How to use checksums |
25db8ecae2610eadb6090eab85f04384a4a5454641a16f3f92486b6375b53f46
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logRelease files / openccu_loom_client-2026.10.1-py3-none-any.whl
| Download URL | openccu_loom_client-2026.10.1-py3-none-any.whl |
|---|---|
| Size | 368.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
881dcc49b5f951c92c89d93b76146896ab7ef00aee91735b04c848a66122bb21
|
|
BLAKE2b-256 checksum How to use checksums |
87f5175b434ff9bb0463e9996f60f5b93d1bcc2cbc5defd83a9c96c2883a3312
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency log
