openccu-loom-client
Status: WIP / Alpha — 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 come from the sister package
openccu-loom-types
(Pydantic models + enum catalogue, generated from the daemon's
assets/openapi.yaml and assets/schemas/enums.json). This package
adds:
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.
Status of the wire contract
The daemon's external-client contract is tracked in
notes/reference/external-client-asks.md
in the daemon repo. As of openccu-loom-types==0.1.24, 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
openccu-loom-types:
- 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-types (currently 0.1.24), 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
Release files for openccu-loom-client 2026.8.7
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.8.7.tar.gz | 215.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| openccu_loom_client-2026.8.7-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 470.7 kB
Release files / openccu_loom_client-2026.8.7.tar.gz
| Download URL | openccu_loom_client-2026.8.7.tar.gz |
|---|---|
| Size | 215.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e5372e0f511a6a609962c61b5692581972c63b3dfce6d950fbcef9f9bf7de6cc
|
|
BLAKE2b-256 checksum How to use checksums |
0814fb922bc4e57be57215c8fe2db8118e94ecd9097f5c1bbf3fb7263a30c8aa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.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 Aug 8, 2026.
Transparency logRelease files / openccu_loom_client-2026.8.7-py3-none-any.whl
| Download URL | openccu_loom_client-2026.8.7-py3-none-any.whl |
|---|---|
| Size | 255.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8e1371ba51498b0c2d72d8896a0868d4bf36075d550183569d2efca4a14c6921
|
|
BLAKE2b-256 checksum How to use checksums |
07757799db146c4431b42fde622e09638831ba2f61838d0d5e39afbca6a5c901
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.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 Aug 8, 2026.
Transparency log
