From 04b42e7c46909ac3cbb2a3784ec1de920c8286fc Mon Sep 17 00:00:00 2001 From: volschin Date: Tue, 17 Nov 2026 13:00:38 +0100 Subject: [PATCH] feat: add native USB actuator gateway with Home Assistant discovery --- .github/workflows/test-pr.yml | 38 ++- .gitignore | 1 + README.adoc | 3 +- docker/homeassistant/Dockerfile | 20 ++ docker/homeassistant/Dockerfile.dockerignore | 6 + docker/homeassistant/requirements.txt | 16 + docs/01_user_guide/homeassistant_gateway.adoc | 144 +++++++++ docs/01_user_guide/installation.adoc | 5 + ...DR-008-homeassistant-actuator-gateway.adoc | 33 ++ .../diagrams/homeassistant-usb-components.mmd | 9 + .../diagrams/homeassistant-usb-discovery.mmd | 18 ++ .../proposals/homeassistant_usb_gateway.adoc | 90 ++++++ pyproject.toml | 18 +- requirements-dev.txt | 1 + signalduino/actuators.py | 101 +++++++ signalduino/controller.py | 43 +-- signalduino/decoders/custom/__init__.py | 2 + signalduino/decoders/custom/actuators.py | 78 +++++ signalduino/homeassistant/__init__.py | 1 + signalduino/homeassistant/__main__.py | 5 + signalduino/homeassistant/bridge.py | 174 +++++++++++ signalduino/homeassistant/health.py | 18 ++ signalduino/homeassistant/runtime.py | 286 ++++++++++++++++++ signalduino/output/__init__.py | 1 + signalduino/output/homeassistant.py | 43 +++ signalduino/transport.py | 39 ++- tests/data/actuators.json | 57 ++++ tests/homeassistant/__init__.py | 1 + tests/homeassistant/test_bridge.py | 145 +++++++++ tests/homeassistant/test_integration.py | 207 +++++++++++++ tests/homeassistant/test_radio.py | 139 +++++++++ tests/homeassistant/test_runtime.py | 112 +++++++ tests/homeassistant/test_upstream.py | 96 ++++++ tests/test_decoder_registry.py | 6 + tests/test_homeassistant_output.py | 17 ++ 35 files changed, 1937 insertions(+), 36 deletions(-) create mode 100644 docker/homeassistant/Dockerfile create mode 100644 docker/homeassistant/Dockerfile.dockerignore create mode 100644 docker/homeassistant/requirements.txt create mode 100644 docs/01_user_guide/homeassistant_gateway.adoc create mode 100644 docs/architecture/decisions/ADR-008-homeassistant-actuator-gateway.adoc create mode 100644 docs/architecture/diagrams/homeassistant-usb-components.mmd create mode 100644 docs/architecture/diagrams/homeassistant-usb-discovery.mmd create mode 100644 docs/architecture/proposals/homeassistant_usb_gateway.adoc create mode 100644 signalduino/actuators.py create mode 100644 signalduino/decoders/custom/actuators.py create mode 100644 signalduino/homeassistant/__init__.py create mode 100644 signalduino/homeassistant/__main__.py create mode 100644 signalduino/homeassistant/bridge.py create mode 100644 signalduino/homeassistant/health.py create mode 100644 signalduino/homeassistant/runtime.py create mode 100644 signalduino/output/__init__.py create mode 100644 signalduino/output/homeassistant.py create mode 100644 tests/data/actuators.json create mode 100644 tests/homeassistant/__init__.py create mode 100644 tests/homeassistant/test_bridge.py create mode 100644 tests/homeassistant/test_integration.py create mode 100644 tests/homeassistant/test_radio.py create mode 100644 tests/homeassistant/test_runtime.py create mode 100644 tests/homeassistant/test_upstream.py create mode 100644 tests/test_homeassistant_output.py diff --git a/.github/workflows/test-pr.yml b/.github/workflows/test-pr.yml index 49c3079..3886b2d 100644 --- a/.github/workflows/test-pr.yml +++ b/.github/workflows/test-pr.yml @@ -2,7 +2,7 @@ name: Unittest on Pull Request on: pull_request: - branches: [ main ] + branches: [ main, feat/sensor-decoding ] jobs: test: @@ -33,3 +33,39 @@ jobs: name: codecov-umbrella fail_ci_if_error: true token: ${{ secrets.CODECOV_TOKEN }} + + homeassistant-container: + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 + with: + persist-credentials: false + - name: Verify installed gateway with isolated MQTT and pseudo-terminal serial + shell: bash + run: | + set -euo pipefail + docker build -f docker/homeassistant/Dockerfile -t pysignalduino-ha:test . + test_name="pysignalduino-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" + trap 'docker rm -f "$test_name-mqtt" >/dev/null 2>&1 || true; docker network rm "$test_name" >/dev/null 2>&1 || true' EXIT + docker network create "$test_name" + docker run -d --name "$test_name-mqtt" --network "$test_name" \ + docker.io/library/eclipse-mosquitto:2.1.2-alpine@sha256:75d6662dee52c947dc9dd9c29f1d8d7ffef78ddaf38001caa09755681e8bbc98 \ + /bin/sh -ec 'mosquitto_passwd -b -c /tmp/passwords restricted test-password; printf "listener 1883\nallow_anonymous true\npassword_file /tmp/passwords\nacl_file /tmp/acl\n" > /tmp/test.conf; printf "topic readwrite #\nuser restricted\ntopic write permitted\ntopic write permitted/availability\n" > /tmp/acl; chown mosquitto:mosquitto /tmp/test.conf /tmp/passwords /tmp/acl; chmod 600 /tmp/test.conf /tmp/passwords /tmp/acl; exec mosquitto -c /tmp/test.conf' + ready=false + for attempt in {1..20}; do + if docker exec "$test_name-mqtt" mosquitto_pub -h 127.0.0.1 -t readiness -m ready >/dev/null 2>&1; then + ready=true + break + fi + sleep 1 + done + "$ready" + broker_ip="$(docker inspect --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$test_name-mqtt")" + test -n "$broker_ip" + docker run --rm --network "$test_name" --env MQTT_TEST_HOST="$broker_ip" \ + --read-only --tmpfs /tmp:rw,nosuid,nodev,size=16m --cap-drop=ALL \ + --security-opt=no-new-privileges:true \ + --mount type=bind,src="$GITHUB_WORKSPACE/tests",dst=/tests,readonly \ + pysignalduino-ha:test python -m unittest discover -s /tests/homeassistant -q diff --git a/.gitignore b/.gitignore index 7e572d4..9afcf0f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ pycache/ *.pyc +*.egg-info/ .venv/ .env/ temp_repo/ diff --git a/README.adoc b/README.adoc index 8502f34..4b7e507 100644 --- a/README.adoc +++ b/README.adoc @@ -37,6 +37,7 @@ Die SIGNALDuino-Firmware (Microcontroller-Code) wird in einem separaten Reposito * **Umfangreiche Protokollbibliothek** – Portierung der originalen FHEM‑SIGNALDuino‑Protokolle über `SDProtocols`; die Protokolldefinitionen liegen in `sd_protocols/protocols.json`. * **Konfiguration über Umgebungsvariablen** – Einfache Einrichtung ohne Codeänderungen. * **Ausführbares Hauptprogramm** – `main.py` bietet eine sofort einsatzbereite Lösung mit Logging, Signalbehandlung und Timeout‑Steuerung. +* **Optionales Home-Assistant-Gateway** – `python -m signalduino.homeassistant` lernt IT-v3-Schalter und A-OK-AC114-Cover über empfangene Funktelegramme und MQTT-Discovery. xref:docs/01_user_guide/homeassistant_gateway.adoc[Installation, Docker-Betrieb und Protokollgrenzen]. * **Komprimierte Datenübertragung** – Effiziente Payload‑Kompression für MQTT‑Nachrichten. == Demo @@ -90,4 +91,4 @@ Dieses Projekt steht unter der MIT‑Lizenz – siehe xref:LICENSE[LICENSE] für == Danksagung -Basierend auf der originalen FHEM‑SIGNALDuino‑Implementierung von [@Sidey79](https://github.com/Sidey79) und der Community. \ No newline at end of file +Basierend auf der originalen FHEM‑SIGNALDuino‑Implementierung von [@Sidey79](https://github.com/Sidey79) und der Community. diff --git a/docker/homeassistant/Dockerfile b/docker/homeassistant/Dockerfile new file mode 100644 index 0000000..a8fb611 --- /dev/null +++ b/docker/homeassistant/Dockerfile @@ -0,0 +1,20 @@ +FROM docker.io/library/python:3.14.8-alpine3.24@sha256:f6a589d43c42b9e7f7dc67a12d37132491f362859a5d750607710cc56da3bc72 AS builder +COPY docker/homeassistant/requirements.txt /tmp/requirements.txt +RUN pip install --no-cache-dir setuptools==84.2.1 \ + && pip install --no-cache-dir --prefix /install -r /tmp/requirements.txt +WORKDIR /usr/src/pysignalduino +COPY pyproject.toml README.adoc LICENSE ./ +COPY signalduino ./signalduino +COPY sd_protocols ./sd_protocols +RUN pip install --no-cache-dir --no-deps --no-build-isolation --prefix /install . + +FROM docker.io/library/python:3.14.8-alpine3.24@sha256:f6a589d43c42b9e7f7dc67a12d37132491f362859a5d750607710cc56da3bc72 +LABEL org.opencontainers.image.source="https://github.com/RFD-FHEM/PySignalduino" \ + org.opencontainers.image.description="USB MQTT actuator gateway with Home Assistant discovery" \ + org.opencontainers.image.licenses="GPL-3.0-only" +COPY --from=builder /install/ /usr/local/ +ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1 +USER 1000:1000 +EXPOSE 8000 +HEALTHCHECK --interval=15s --timeout=3s --start-period=30s --retries=3 CMD ["python", "-m", "signalduino.homeassistant.health"] +CMD ["python", "-m", "signalduino.homeassistant"] diff --git a/docker/homeassistant/Dockerfile.dockerignore b/docker/homeassistant/Dockerfile.dockerignore new file mode 100644 index 0000000..c27efd6 --- /dev/null +++ b/docker/homeassistant/Dockerfile.dockerignore @@ -0,0 +1,6 @@ +.git +.devcontainer +.env* +**/__pycache__ +**/*.pyc +*.egg-info diff --git a/docker/homeassistant/requirements.txt b/docker/homeassistant/requirements.txt new file mode 100644 index 0000000..53cbcef --- /dev/null +++ b/docker/homeassistant/requirements.txt @@ -0,0 +1,16 @@ +aiomqtt==2.5.1 +attrs==26.1.0 +certifi==2026.10.23 +charset-normalizer==3.5.2 +idna==3.20 +jsonschema==4.26.0 +jsonschema-specifications==2025.9.1 +paho-mqtt==2.2.0 +prometheus-client==0.26.0 +pyserial==3.5 +pyserial-asyncio==0.6 +python-dotenv==1.2.4 +referencing==0.37.0 +requests==2.34.2 +rpds-py==2026.9.1 +urllib3==2.8.0 diff --git a/docs/01_user_guide/homeassistant_gateway.adoc b/docs/01_user_guide/homeassistant_gateway.adoc new file mode 100644 index 0000000..f6cf294 --- /dev/null +++ b/docs/01_user_guide/homeassistant_gateway.adoc @@ -0,0 +1,144 @@ += Home Assistant USB actuator gateway +:sectlinks: +:toc: + +== Supported devices and automatic discovery + +The opt-in gateway learns Intertechno v3 (protocol 17) switches and A-OK +AC114-01B (protocol 56) covers from valid received telegrams. Operate an existing +remote to provide a telegram. No FHEM process, API, definition list or preloaded +production addresses are needed. Other SD_UT models and IT v1 are not claimed +as supported. Other stage-one messages remain diagnostic events. + +Both protocols are one-way. State is inferred from an observed command, not +physical receiver acknowledgement or measured position. For outgoing OPEN/CLOSE, +HA immediately assumes open/closed through its native optimistic behavior, +before firmware or physical confirmation. Received telegrams update +opening/closing/stopped action state, with no invented +position percentage, travel time or battery value. HA maps stopped according +to its native optimistic-cover behavior. + +== Installation and selected entry point + +The gateway targets Python 3.12 or newer, has additional dependencies and uses MQTT5: + +[source,bash] +---- +pip install '.[homeassistant]' +export SERIAL_PORT=/dev/serial/by-id/YOUR_VERIFIED_DEVICE +export MQTT_BROKER_HOSTNAME=mqtt.example.net +export MQTT_BROKER_USERNAME_FILE=/private/mqtt-username +export MQTT_BROKER_PASSWORD_FILE=/private/mqtt-password +python -m signalduino.homeassistant +---- + +The existing `main.py` raw/FHEM entry point remains available. Do not set +`MQTT_HOST` for this gateway: that would select upstream's separate publisher. +The qualified hardware is a Radino/ATmega32U4 with CC1101 and SIGNALduino 4.0.0, +57600 baud. Startup preserves RF frequency, PA table and decoder flags. + +Settings are `SERIAL_PORT` (default `/dev/signalduino`), `SERIAL_BAUD` (57600), +`MQTT_BROKER_HOSTNAME` (localhost), `MQTT_BROKER_PORT` (1883), +`MQTT_BROKER_USERNAME`, `MQTT_BROKER_PASSWORD` (both also accept `_FILE`), +`MQTT_CLIENT_ID` (pysignalduino-mqtt), `MQTT_TOPIC` (signalduino) and +`MQTT_DISCOVERY_PREFIX` (homeassistant). Give each active instance a distinct +client identity and topic tree. Keep secret files owner-only and readable by +the runtime UID. TCP MQTT uses the broker's authenticated LAN contract; TLS is +not configured by this gateway. + +== Docker + +Build from the repository root: + +[source,bash] +---- +docker build -f docker/homeassistant/Dockerfile -t pysignalduino-ha:local . +docker run -d --name pysignalduino-ha \ + --read-only --tmpfs /tmp:rw,nosuid,nodev,size=16m \ + --cap-drop=ALL --security-opt=no-new-privileges:true \ + --device=/dev/serial/by-id/YOUR_VERIFIED_DEVICE:/dev/signalduino:rw \ + --group-add YOUR_SERIAL_DEVICE_GROUP_ID \ + --env MQTT_BROKER_HOSTNAME=mqtt.example.net \ + --env MQTT_BROKER_USERNAME_FILE=/run/secrets/username \ + --env MQTT_BROKER_PASSWORD_FILE=/run/secrets/password \ + --mount type=bind,src=/private/mqtt-username,dst=/run/secrets/username,readonly \ + --mount type=bind,src=/private/mqtt-password,dst=/run/secrets/password,readonly \ + -p 127.0.0.1:18008:8000 pysignalduino-ha:local +---- + +The image runs as UID/GID 1000. Inspect the device's actual group; do not use a +privileged container or mount every USB device. An Arduino Micro USB descriptor +is not globally unique: select and verify exactly one physical device. Only +one controller may own it. Recreate the container after physical USB replug so +Docker allocates the newly resolved device. An in-process reconnect cannot +refresh the Docker device cgroup. + +Python 3.14.8/Alpine 3.24 is digest-pinned, with fully pinned image dependencies. +Alpine and Trixie passed the same downstream tests and actual USB/MQTT handshake; +available musl wheels removed any compiler/glibc requirement. Comparison images +were about 23.5 MB and 46.5 MB respectively. These are comparison measurements, +not a size guarantee for this upstream build. No image publication is added. + +== MQTT persistence and access + +For the default prefixes, a dedicated native broker principal needs: + +[source,text] +---- +topic readwrite signalduino/# +topic write homeassistant/switch/signalduino/+/config +topic write homeassistant/cover/signalduino/+/config +topic read homeassistant/status +---- + +Stable identity includes protocol, complete address and channel/group. The +broker retains validated descriptors at `signalduino/devices//config` +and HA discovery. Its native persistence/backup contract owns recovery. Restore +the broker or relearn devices from remotes; no gateway database/PVC is needed. +HA birth republishes discovery, and restart restores routing without inventing +RF reception. The gateway learns at most 256 supported identities per process; +registry JSON is limited to 512 bytes and malformed input cannot stop learning. + +State and diagnostic events are non-retained at +`signalduino/devices//state` and `signalduino/events`. Commands at +`signalduino/devices//set` accept ON/OFF or OPEN/CLOSE/STOP. Never retain +commands. MQTT5 options reject cached and live retained commands; unknown and +malformed targets/actions are rejected. No toggle, pairing, register-write, +frequency, factory-reset or firmware commands are exposed by MQTT. The selected +serial device itself still grants full RF/configuration authority. + +== Health and recovery + +Logs go to stdout/stderr. `/metrics` on port 8000 exposes serial/MQTT connectivity, +firmware heartbeat, decoded frames, learned devices, errors and acknowledged +transmissions. A transmission counter means firmware acknowledgement only. + +Health uses a successful native firmware heartbeat every 15 seconds while MQTT +is connected; its monotonic receipt expires after 45 seconds. Quiet radio traffic +is healthy. Docker checks `python -m signalduino.homeassistant.health`. +`signalduino/availability` is retained online/offline with LWT and clean shutdown. +Serial/broker failures close resources and reconnect with 1–30 second backoff. +Negative PUBACKs fail the session and trigger native MQTT5 disconnect-with-Will +so a denied cleanup publication cannot leave retained online availability. + +Stop this container to release USB. Preserve broker discovery/registry for +ordinary rollback. Retiring a device requires its exact registry/discovery +topics and native HA entries; never clear wildcard retained data or edit HA +`.storage`. Firmware backup/rollback is independent from this application. + +== Verification scope + +Tests live under `tests/`, including pseudo-terminal native USB, independent +FHEM/A-OK vectors, discovery, malformed input, retained commands, negative PUBACK, +registry restart and HA birth. Run the full suite in the documented devcontainer. +Set `MQTT_TEST_HOST` to an isolated Mosquitto configured like the container CI +fixture to run its three broker integration cases; never point them at a live +broker. The CI image job runs them with an isolated pinned broker and read-only, +non-root runtime. + +The downstream implementation was also tested with actual Radino RF reception +and HA 2026.11.2: a real A-OK telegram created a device/cover automatically; +received state and stable IDs after stop/restart were verified. Physical IT +reception and production actuator commands remain unverified. The upstream port +has its own native/package/container checks; downstream evidence is not presented +as new over-the-air reception by a different build. diff --git a/docs/01_user_guide/installation.adoc b/docs/01_user_guide/installation.adoc index daef3d1..bbdf21a 100644 --- a/docs/01_user_guide/installation.adoc +++ b/docs/01_user_guide/installation.adoc @@ -79,6 +79,11 @@ Sie sollten eine Ausgabe mit allen verfügbaren Kommandozeilenoptionen sehen. == Docker / DevContainer +Für das optionale USB-Gateway mit Home-Assistant-MQTT-Discovery siehe +xref:homeassistant_gateway.adoc[Home Assistant actuator gateway]. Es verwendet +den nativen Decoder und eine eigene Startoption; das bestehende Hauptprogramm +bleibt verfügbar. + Für eine konsistente Entwicklungsumgebung steht eine DevContainer-Konfiguration bereit. Öffnen Sie das Projekt in Visual Studio Code mit der Remote-Containers-Erweiterung, um automatisch alle Abhängigkeiten in einem isolierten Container zu installieren. Details finden Sie in der [DevContainer-Dokumentation](devcontainer_env.md). diff --git a/docs/architecture/decisions/ADR-008-homeassistant-actuator-gateway.adoc b/docs/architecture/decisions/ADR-008-homeassistant-actuator-gateway.adoc new file mode 100644 index 0000000..575eff2 --- /dev/null +++ b/docs/architecture/decisions/ADR-008-homeassistant-actuator-gateway.adoc @@ -0,0 +1,33 @@ += ADR 008: Opt-in Home Assistant actuator gateway +:doctype: article +:lang: en +:status: Proposed +:decided-by: Pending architecture-owner review + +== Context + +ADR-006 defines native payload interpretation and pure output adapters. IT v3 +and A-OK add one-way actuators whose last motion command must not be treated as +measured position or replayed after reconnect. ADR-007 remains reserved by the +existing raw-command feature branch. + +== Proposed decision + +Extend ADR-006 through native custom decoders, a pure Home Assistant output +formatter and a separately selected gateway. Preserve the existing raw/FHEM +entry point. Persist only validated learned routing descriptors and discovery +in the broker; publish actuator action state as non-retained. The explicit +gateway topic tree keeps this behavior independent from the existing canonical +sensor-state topics. + +See xref:../proposals/homeassistant_usb_gateway.adoc[the implementation proposal] +for interfaces, diagrams, permissions and acceptance evidence. + +== Consequences and alternatives + +Users can reuse USB SIGNALduino hardware directly with HA MQTT discovery. +Default library/CLI behavior and native stage-one payloads remain available. +The optional runtime adds a small MQTT dependency on an explicitly qualified +aiomqtt version because negative PUBACK handling uses its callback boundary. +Retaining inferred motion state would fabricate freshness; embedding decoders +in the publisher would couple protocol semantics to a particular output. diff --git a/docs/architecture/diagrams/homeassistant-usb-components.mmd b/docs/architecture/diagrams/homeassistant-usb-components.mmd new file mode 100644 index 0000000..8b72586 --- /dev/null +++ b/docs/architecture/diagrams/homeassistant-usb-components.mmd @@ -0,0 +1,9 @@ +flowchart LR + USB[Selected SIGNALduino USB] --> Controller[Native controller / parser] + Controller --> Decoders[Native actuator decoders] + Decoders --> Event[SensorEvent] + Event --> Gateway[Opt-in HA gateway] + Gateway --> Formatter[Pure discovery formatter] + Gateway <--> Broker[MQTT broker / retained registry] + Broker <--> HA[Home Assistant MQTT discovery] + Gateway --> Metrics[Prometheus / heartbeat health] diff --git a/docs/architecture/diagrams/homeassistant-usb-discovery.mmd b/docs/architecture/diagrams/homeassistant-usb-discovery.mmd new file mode 100644 index 0000000..7108fbb --- /dev/null +++ b/docs/architecture/diagrams/homeassistant-usb-discovery.mmd @@ -0,0 +1,18 @@ +sequenceDiagram + participant R as Remote + participant S as SIGNALduino + participant G as HA gateway + participant M as MQTT broker + participant H as Home Assistant + R->>S: Real RF telegram + S->>G: Native raw frame + G->>G: Parse and validate native SensorEvent + G->>M: Retain descriptor and discovery + M->>H: Automatically create switch / cover + G->>M: Non-retained inferred action state + M->>H: Update action state + G->>M: Offline during shutdown + M->>H: Unavailable + G->>M: Subscribe after restart + M->>G: Retained validated descriptor + G->>M: Rediscovery and online, no invented RF event diff --git a/docs/architecture/proposals/homeassistant_usb_gateway.adoc b/docs/architecture/proposals/homeassistant_usb_gateway.adoc new file mode 100644 index 0000000..fdcacc2 --- /dev/null +++ b/docs/architecture/proposals/homeassistant_usb_gateway.adoc @@ -0,0 +1,90 @@ += Proposal: USB gateway for Home Assistant switches and covers +:doctype: article +:lang: en +:status: Proposed; architecture-owner review requested + +== Scope and architecture + +This implements the actuator use case of accepted ADR-006 on top of PR #15 +(`d7820836633111ae3c1bf332fcc5b8a6498029f3`). Existing FHEM/raw MQTT operation +keeps its entry point. The opt-in gateway runs as +`python -m signalduino.homeassistant`, with one explicitly selected USB device. +It reuses the native controller, parser, decoder registry and `SensorEvent`. + +Custom IT v3/protocol 17 and A-OK AC114-01B/protocol 56 decoders belong in +`signalduino/decoders/custom/`; validated actuator identities and native SR +encoding belong in `signalduino/actuators.py`. The pure discovery formatter in +`signalduino/output/homeassistant.py` has no MQTT client. Gateway orchestration +under `signalduino/homeassistant/` owns publication, subscriptions and lifecycle. + +[mermaid] +---- +include::../diagrams/homeassistant-usb-components.mmd[] +---- + +[mermaid] +---- +include::../diagrams/homeassistant-usb-discovery.mmd[] +---- + +== Interfaces and behavior + +* Native stage two returns `SensorEvent` with model, address, channel/group, + action and received pulse clock. Invalid checksums, headers, sizes and + non-movement A-OK commands return no event through native error isolation. +* `descriptor(event)` and `validate_descriptor(dict)` produce the retained + minimal routing identity; `identity(dict)` includes the complete channel + bitmap/group; `encode(dict, action)` produces one bounded native SR command. +* `discovery_config(device, root, version)` returns a pure `(domain, config)` + pair. Switches expose ON/OFF; covers expose OPEN/CLOSE/STOP. +* `Bridge` publishes retained discovery/descriptors, non-retained RF events and + inferred action state. It restores descriptors and republishes discovery on + HA birth without fabricating reception. It rejects retained, unknown and + malformed commands. Exactly one process owns the serial device. +* The gateway uses MQTT5, heartbeat-based health, LWT/offline, bounded reconnect, + stdout logging and Prometheus metrics. A denied PUBACK fails the session; + native MQTT5 disconnect-with-Will prevents retained false-online state. + +These protocols are one-way. An observed or transmitted action does not prove +receiver position or physical acknowledgement. No percentage/travel-time or +battery capability is invented. Silent devices are learned by operating their +existing remote, never from a hardcoded list of addresses. + +== Security, retention and alternatives + +The container runs as UID/GID 1000 with read-only root, dropped capabilities and +one selected serial device. File-based credentials avoid command-line secrets. +The device grants full serial/RF authority; typed MQTT commands are an API +boundary, not receive-only hardware enforcement. Native broker ACLs scope +gateway topics and the discovery node. No serial proxy, FHEM runtime, filesystem +database, firmware update or automatic RF reconfiguration is added. + +The broker owns retained routing/discovery persistence. Command and inferred +motion state are deliberately not retained: this actuator gateway must not +replay a stale movement or present an old movement as a fresh observation. +This is the actuator-specific extension described in proposed ADR-008. + +An independent demodulator would duplicate upstream's pulse definitions; +embedding actuator semantics in the MQTT transport would violate ADR-006. +The selected decoder/pure-output/orchestrator split reuses the existing native +boundaries. Alpine uses available musl wheels and passed real USB/MQTT tests; +no glibc requirement was found. + +== Implementation and verification plan + +. Complete native serial transport, distribution data and cancellation cleanup; + deliver every demodulated result. +. Register native actuator decoders; port the reviewed descriptor/encoder and + discovery formatter without changing the wire protocol or existing CLI. +. Package the opt-in gateway and non-root Alpine container; document settings, + ACLs, persistence and hardware recovery. +. Run native pytest in the documented devcontainer, pseudo-terminal and real + isolated-Mosquitto regressions, installed-wheel and container checks. + +The downstream implementation has passed 389 upstream tests and 24 gateway +tests. Real SIGNALduino 4.0.0/Radino reception automatically created an A-OK +MQTT cover in Home Assistant 2026.11.2; stopping the gateway made it unavailable, +and restarting preserved device/entity IDs through retained descriptors. +IT decoding/encoding/discovery has automated coverage; physical IT reception +and production actuator-command transmission were not performed. The upstream +port is revalidated separately; owner approval is requested through the draft PR. diff --git a/pyproject.toml b/pyproject.toml index 50c8a5f..1d99aa5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,15 +11,27 @@ dependencies = [ "requests", "pyserial-asyncio", "aiomqtt", - "python-dotenv" + "python-dotenv", + "jsonschema" +] + +[project.optional-dependencies] +homeassistant = [ + "aiomqtt==2.5.1", + "paho-mqtt==2.2.0", + "prometheus-client==0.26.0" ] [tool.setuptools.packages.find] -include = ["signalduino", "sd_protocols"] +include = ["signalduino*", "sd_protocols*"] + +[tool.setuptools.package-data] +sd_protocols = ["protocols.json"] +"signalduino.decoders" = ["spec_schema.json", "specs/*.json"] [tool.pytest.ini_options] testpaths = ["tests"] timeout = 30 [tool.pytest-asyncio] -mode = "auto" \ No newline at end of file +mode = "auto" diff --git a/requirements-dev.txt b/requirements-dev.txt index bdf5664..f6ff994 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -4,3 +4,4 @@ pytest-asyncio pytest-cov jsonschema pytest-timeout +-e .[homeassistant] diff --git a/signalduino/actuators.py b/signalduino/actuators.py new file mode 100644 index 0000000..cfb9d8e --- /dev/null +++ b/signalduino/actuators.py @@ -0,0 +1,101 @@ +"""Validated IT/A-OK routing identities and native transmit encoding.""" + +import re + +from sd_protocols import SDProtocols + +from .decoders import SensorDecoder + +PROTOCOLS = SDProtocols() + +DECODER = SensorDecoder() + + +def decode(message): + """Use upstream routing/error isolation, returning only valid device events.""" + return DECODER.decode(message) + + +def descriptor(event): + result = {key: event.values[key] for key in ("address", "channel", "clock")} + result["protocol"] = event.protocol_id + if event.protocol_id == "17": + result["group"] = event.values["group"] + return validate_descriptor(result) + + +def validate_descriptor(device): + """Validate retained broker data as carefully as a new radio identity.""" + if not isinstance(device, dict) or device.get("protocol") not in ("17", "56"): + raise ValueError("Unsupported device descriptor") + it = device["protocol"] == "17" + expected = {"protocol", "address", "channel", "clock"} | ( + {"group"} if it else set() + ) + if set(device) != expected: + raise ValueError("Unexpected descriptor fields") + if not isinstance(device["address"], str) or not re.fullmatch( + "[0-9a-f]{7}" if it else "[0-9a-f]{6}", device["address"] + ): + raise ValueError("Invalid radio address") + if it and int(device["address"], 16) >= 1 << 26: + raise ValueError("IT address outside 26-bit range") + if type(device["channel"]) is not int or not (0 if it else 1) <= device[ + "channel" + ] <= (15 if it else 65535): + raise ValueError("Invalid channel") + if type(device["clock"]) is not int or not 100 <= device["clock"] <= 1000: + raise ValueError("Invalid pulse clock") + if it and (type(device["group"]) is not int or device["group"] not in (0, 1)): + raise ValueError("Invalid group bit") + return dict(device) + + +def identity(device): + device = validate_descriptor(device) + prefix = f"signalduino_{device['protocol']}_{device['address']}_" + if device["protocol"] == "17": + return prefix + f"{device['group']}_{device['channel']:x}" + return prefix + f"{device['channel']:04x}" + + +def encode(device, action): + """Encode supported actions into the firmware's native bounded SR command.""" + device = validate_descriptor(device) + pid = device["protocol"] + if pid == "17": + if action not in ("ON", "OFF"): + raise ValueError("IT accepts ON or OFF") + bits = ( + f"{int(device['address'],16):026b}{device['group']}" + f"{int(action == 'ON')}{device['channel']:04b}" + ) + start = PROTOCOLS.get_property(pid, "sync") + end = PROTOCOLS.get_property(pid, "end") + else: + code = {"OPEN": 0x0B, "CLOSE": 0x43, "STOP": 0x23}.get(action) + if code is None: + raise ValueError("A-OK accepts OPEN, CLOSE or STOP") + body = ( + bytes.fromhex(device["address"]) + + device["channel"].to_bytes(2, "big") + + bytes([code]) + ) + raw = b"\xa3" + body + bytes([sum(body) & 255]) + bits = "".join(f"{value:08b}" for value in raw) + "1" + start = PROTOCOLS.get_property(pid, "start") + end = PROTOCOLS.get_property(pid, "pause") + clock = device["clock"] + pulses = [round(clock * p) for p in start] + for bit in bits: + pulses.extend( + round(clock * p) + for p in PROTOCOLS.get_property(pid, "one" if bit == "1" else "zero") + ) + pulses.extend(round(clock * p) for p in end) + patterns = list(dict.fromkeys(pulses)) + if len(patterns) > 8: + raise ValueError("Firmware pattern limit exceeded") + data = "".join(str(patterns.index(p)) for p in pulses) + fields = ";".join(f"P{i}={p}" for i, p in enumerate(patterns)) + return f"SR;R=5;{fields};D={data};" diff --git a/signalduino/controller.py b/signalduino/controller.py index 552a7a2..8d8683e 100644 --- a/signalduino/controller.py +++ b/signalduino/controller.py @@ -206,18 +206,25 @@ async def send_command( return None async def __aenter__(self) -> "SignalduinoController": - await self.transport.open() - if self.mqtt_publisher: - try: - await self.mqtt_publisher.__aenter__() - except MqttError as exc: - self.logger.warning("Konnte keine Verbindung zum MQTT-Broker herstellen: %s", exc) try: - await self.initialize() # Wichtig: Initialisierung nach dem Öffnen des Transports und Publishers - except SignalduinoConnectionError as exc: - self.logger.error("Verbindungsfehler während der Initialisierung, setze fort: %s", exc) - - return self + await self.transport.open() + if self.mqtt_publisher: + try: + await self.mqtt_publisher.__aenter__() + except MqttError as exc: + self.logger.warning("Konnte keine Verbindung zum MQTT-Broker herstellen: %s", exc) + try: + await self.initialize() + except SignalduinoConnectionError as exc: + # Preserve the upstream context contract; the HA driver verifies + # cached firmware identity and worker health before going online. + self.logger.error("Verbindungsfehler während der Initialisierung, setze fort: %s", exc) + return self + except BaseException as error: + # Context managers do not call __aexit__ if __aenter__ fails. + # In particular cancellation must release the exclusive serial port. + await self.__aexit__(type(error), error, error.__traceback__) + raise async def __aexit__(self, exc_type, exc_val, exc_tb) -> None: self._stop_event.set() @@ -250,11 +257,13 @@ async def _parser_task(self) -> None: # Führe die rechenintensive Parsing-Logik in einem separaten Thread aus. # Dadurch wird die asyncio-Event-Schleife nicht blockiert. decoded = await asyncio.to_thread(self.parser.parse_line, line) - if decoded and self.message_callback: - await self.message_callback(decoded[0]) - if self.mqtt_publisher and decoded: - # Verwende die neue MqttPublisher.publish(message: DecodedMessage) Signatur - await self.mqtt_publisher.publish(decoded[0]) + # A single RF burst can contain several decoded messages. + # PR #14 also processes every result, using its alternate model. + for message in decoded: + if self.message_callback: + await self.message_callback(message) + if self.mqtt_publisher: + await self.mqtt_publisher.publish(message) await self._handle_as_command_response(line) # Ensure a minimal yield time for other tasks when the queue is rapidly processed. @@ -464,4 +473,4 @@ async def _publish_status_heartbeat(self) -> None: "version": self.init_version_response, "connected": not self.transport.closed() } - await self.mqtt_publisher.publish_simple("status/heartbeat", json.dumps(status)) \ No newline at end of file + await self.mqtt_publisher.publish_simple("status/heartbeat", json.dumps(status)) diff --git a/signalduino/decoders/custom/__init__.py b/signalduino/decoders/custom/__init__.py index 3606519..3bfa37e 100644 --- a/signalduino/decoders/custom/__init__.py +++ b/signalduino/decoders/custom/__init__.py @@ -16,3 +16,5 @@ def decode_bresser_5in1(message): and is imported here so the registry picks it up. A custom decoder takes precedence over a specification with the same protocol id. """ + +from . import actuators # noqa: F401 - register native actuator decoders diff --git a/signalduino/decoders/custom/actuators.py b/signalduino/decoders/custom/actuators.py new file mode 100644 index 0000000..f8e57b2 --- /dev/null +++ b/signalduino/decoders/custom/actuators.py @@ -0,0 +1,78 @@ +"""IT v3 and A-OK AC114-01B stage-two decoders (ADR-006).""" + +import re + +from ...types import SensorEvent +from ..pipeline import DecodeError +from ..registry import register_decoder + +AOK_ACTIONS = {0x0B: "up", 0x23: "stop", 0x43: "down"} + + +@register_decoder("17") +def _intertechno(message): + bits = message.metadata.get("bits") + if not bits: + if not re.fullmatch(r"i[0-9a-fA-F]{8}00", message.payload): + raise DecodeError("Invalid IT v3 payload") + bits = f"{int(message.payload[1:9], 16):032b}" + if not re.fullmatch("[01]{32}", bits): + raise DecodeError("Invalid IT v3 bit length") + address = f"{int(bits[:26], 2):07x}" + group = int(bits[26], 2) + state = "on" if bits[27] == "1" else "off" + channel = int(bits[28:], 2) + values = { + "address": address, + "group": group, + "channel": channel, + "state": state, + "clock": round(float(message.metadata.get("clock", 275))), + } + return _event( + message, + "Intertechno v3", + address, + f"signalduino_17_{address}_{group}_{channel:x}", + values, + ) + + +@register_decoder("56") +def _aok(message): + if not re.fullmatch(r"P56#[0-9a-fA-F]{17}", message.payload): + raise DecodeError("Invalid A-OK payload") + raw = bytes.fromhex(message.payload[4:20]) + if raw[0] != 0xA3 or message.payload[-1].lower() != "8": + raise DecodeError("Invalid A-OK header or trailing marker") + if sum(raw[1:7]) & 255 != raw[7]: + raise DecodeError("Invalid A-OK checksum") + if raw[6] not in AOK_ACTIONS: + raise DecodeError("Not an A-OK movement/stop telegram") + channel = int.from_bytes(raw[4:6], "big") + if channel == 0: + raise DecodeError("A-OK telegram selects no channel") + address = raw[1:4].hex() + values = { + "address": address, + "channel": channel, + "state": AOK_ACTIONS[raw[6]], + "clock": round(float(message.metadata.get("clock", 200))), + } + return _event( + message, "AC114-01B", address, f"signalduino_56_{address}_{channel:04x}", values + ) + + +def _event(message, model, address, identity, values): + return SensorEvent( + protocol_id=message.protocol_id, + model=model, + sensor_type="switch" if message.protocol_id == "17" else "cover", + device_id=identity, + sensor_id=address, + channel=values["channel"], + values=values, + dmsg=message.payload, + rssi=message.raw.rssi, + ) diff --git a/signalduino/homeassistant/__init__.py b/signalduino/homeassistant/__init__.py new file mode 100644 index 0000000..92680c9 --- /dev/null +++ b/signalduino/homeassistant/__init__.py @@ -0,0 +1 @@ +"""Opt-in USB/MQTT actuator gateway for Home Assistant.""" diff --git a/signalduino/homeassistant/__main__.py b/signalduino/homeassistant/__main__.py new file mode 100644 index 0000000..ae7670a --- /dev/null +++ b/signalduino/homeassistant/__main__.py @@ -0,0 +1,5 @@ +"""Run with python -m signalduino.homeassistant.""" + +from .runtime import main + +main() diff --git a/signalduino/homeassistant/bridge.py b/signalduino/homeassistant/bridge.py new file mode 100644 index 0000000..6edd1cb --- /dev/null +++ b/signalduino/homeassistant/bridge.py @@ -0,0 +1,174 @@ +"""Home Assistant output adapter; radio decoding stays in PySignalduino.""" + +import json +import logging +import time +from datetime import UTC, datetime +from importlib.metadata import version + +from prometheus_client import CollectorRegistry, Counter, Gauge + +from .. import actuators as radio +from ..output.homeassistant import discovery_config + +LOG = logging.getLogger(__name__) +VERSION = version("signalduino-mqtt") + + +class Metrics: + def __init__(self): + self.registry = CollectorRegistry() + self.serial = Gauge( + "signalduino_serial_connected", + "Firmware heartbeat is healthy", + registry=self.registry, + ) + self.mqtt = Gauge( + "signalduino_mqtt_connected", + "MQTT session is connected", + registry=self.registry, + ) + self.heartbeat = Gauge( + "signalduino_last_heartbeat_timestamp_seconds", + "Last firmware heartbeat", + registry=self.registry, + ) + self.devices = Gauge( + "signalduino_devices", + "Known supported radio identities", + registry=self.registry, + ) + self.frames = Counter( + "signalduino_received_frames", + "Native decoded RF frames", + registry=self.registry, + ) + self.errors = Counter( + "signalduino_errors", + "Failed publish, serial or command operations", + registry=self.registry, + ) + self.sent = Counter( + "signalduino_sent_commands", + "Firmware-acknowledged transmissions, not physical acknowledgements", + registry=self.registry, + ) + + +class Bridge: + def __init__( + self, client, send, metrics, root="signalduino", discovery="homeassistant" + ): + self.client = client + self.send = send + self.metrics = metrics + self.root = root + self.discovery = discovery + self.devices = {} + self.recent = {} + + async def publish(self, topic, payload, retain=False): + try: + await self.client.publish(topic, json.dumps(payload), qos=1, retain=retain) + except Exception: + self.metrics.errors.inc() + raise + + async def discover(self, device): + identity = radio.identity(device) + domain, config = discovery_config(device, self.root, VERSION) + # The native discovery node level permits a broker ACL scoped to this + # driver without granting write access to every HA switch or cover. + await self.publish( + f"{self.discovery}/{domain}/signalduino/{identity}/config", + config, + retain=True, + ) + + async def receive(self, message): + self.metrics.frames.inc() + now = datetime.now(UTC).isoformat() + await self.publish( + f"{self.root}/events", + { + "protocol_id": message.protocol_id, + "payload": message.payload, + "received_at": now, + }, + ) + event = radio.decode(message) + if event is None: + return + try: + device = radio.descriptor(event) + identity = radio.identity(device) + except (ValueError, TypeError, KeyError): + LOG.warning("Ignoring invalid decoded device identity") + return + if identity not in self.devices: + if len(self.devices) >= 256: + LOG.warning("Learned-device limit reached") + return + await self.publish( + f"{self.root}/devices/{identity}/config", device, retain=True + ) + await self.discover(device) + self.devices[identity] = device + self.metrics.devices.set(len(self.devices)) + LOG.info("Learned %s", identity) + state = event.values["state"] + previous = self.recent.get(identity) + clock = time.monotonic() + if previous and previous[0] == state and clock - previous[1] < 0.4: + return + self.recent[identity] = (state, clock) + ha_state = ( + state.upper() + if device["protocol"] == "17" + else {"up": "opening", "down": "closing", "stop": "stopped"}[state] + ) + await self.publish( + f"{self.root}/devices/{identity}/state", + { + "state": ha_state, + "action": state, + "source": "received", + "received_at": now, + "rssi": event.rssi, + }, + ) + + async def handle(self, topic, payload, retain): + if topic == f"{self.discovery}/status" and payload == b"online": + for device in tuple(self.devices.values()): + await self.discover(device) + return + prefix = f"{self.root}/devices/" + if not topic.startswith(prefix): + return + tail = topic[len(prefix) :].split("/") + if len(tail) != 2: + return + identity, operation = tail + try: + if operation == "config": + if len(payload) > 512: + raise ValueError("Device descriptor exceeds 512 bytes") + device = radio.validate_descriptor(json.loads(payload)) + if identity != radio.identity(device): + raise ValueError("Registry identity mismatch") + if identity not in self.devices: + if len(self.devices) >= 256: + raise ValueError("Learned-device limit reached") + await self.discover(device) + self.devices[identity] = device + self.metrics.devices.set(len(self.devices)) + elif operation == "set": + if retain or identity not in self.devices: + raise ValueError("Retained or unknown device command") + command = radio.encode(self.devices[identity], payload.decode("ascii")) + await self.send(command) + self.metrics.sent.inc() + except (ValueError, KeyError, TypeError, UnicodeError, RecursionError): + self.metrics.errors.inc() + LOG.warning("Rejected invalid %s message for %s", operation, identity) diff --git a/signalduino/homeassistant/health.py b/signalduino/homeassistant/health.py new file mode 100644 index 0000000..df1ce9b --- /dev/null +++ b/signalduino/homeassistant/health.py @@ -0,0 +1,18 @@ +"""Connectivity receipt; quiet RF traffic is not an unhealthy gateway.""" + +import time +from pathlib import Path + +HEALTH_FILE = Path("/tmp/signalduino-health") + + +def healthy(): + try: + age = time.monotonic() - float(HEALTH_FILE.read_text()) + return 0 <= age < 45 + except (OSError, ValueError): + return False + + +if __name__ == "__main__": + raise SystemExit(0 if healthy() else 1) diff --git a/signalduino/homeassistant/runtime.py b/signalduino/homeassistant/runtime.py new file mode 100644 index 0000000..901788f --- /dev/null +++ b/signalduino/homeassistant/runtime.py @@ -0,0 +1,286 @@ +"""Exclusive USB/MQTT lifecycle around PySignalduino's native controller.""" + +import asyncio +import logging +import os +import re +import signal +import time +from dataclasses import dataclass, field +from pathlib import Path + +import aiomqtt +from paho.mqtt.packettypes import PacketTypes +from paho.mqtt.reasoncodes import ReasonCode +from paho.mqtt.subscribeoptions import SubscribeOptions +from prometheus_client import start_http_server + +from signalduino.controller import SignalduinoController +from signalduino.exceptions import SignalduinoError +from signalduino.transport import SerialTransport + +from . import health +from .bridge import Bridge, Metrics + +LOG = logging.getLogger(__name__) + + +class MqttClient(aiomqtt.Client): + """Propagate MQTT5 negative PUBACKs that aiomqtt 2.5.1 discards. + + Keep aiomqtt's native connection/event machinery. A denied publish poisons + this session so concurrent publications cannot falsely refresh health. + """ + + def __init__(self, *args, **kwargs): + self._publish_error = None + super().__init__(*args, **kwargs) + + def _on_publish(self, client, userdata, mid, reason_code, properties): + if reason_code.is_failure: + self._publish_error = aiomqtt.MqttCodeError(reason_code) + super()._on_publish(client, userdata, mid, reason_code, properties) + + async def publish(self, *args, **kwargs): + if self._publish_error: + raise self._publish_error + await super().publish(*args, **kwargs) + if self._publish_error: + raise self._publish_error + + async def __aexit__(self, exc_type, exc, tb): + if self._publish_error and self._client.is_connected(): + # A poisoned session cannot publish cleanup's offline message. A + # normal DISCONNECT would suppress its Will and leave HA online. + # MQTT5 explicitly supports graceful disconnect WITH Will delivery. + self._client.disconnect( + reasoncode=ReasonCode(PacketTypes.DISCONNECT, identifier=4) + ) + try: + await self._wait_for(self._disconnected, timeout=2) + except aiomqtt.MqttError: + pass + await super().__aexit__(exc_type, exc, tb) + + +def secret(name): + value, filename = os.environ.get(name), os.environ.get(name + "_FILE") + if value is not None and filename: + raise ValueError(f"Choose {name} or {name}_FILE") + return Path(filename).read_text().rstrip("\r\n") if filename else value + + +@dataclass(frozen=True) +class Settings: + serial_port: str + baud: int + host: str + port: int + username: str | None = field(repr=False) + password: str | None = field(repr=False) + root: str + discovery: str + client_id: str + + @classmethod + def from_env(cls): + root = os.environ.get("MQTT_TOPIC", "signalduino") + discovery = os.environ.get("MQTT_DISCOVERY_PREFIX", "homeassistant") + for prefix in (root, discovery): + if not re.fullmatch(r"[A-Za-z0-9_-]+(?:/[A-Za-z0-9_-]+)*", prefix): + raise ValueError( + "MQTT prefixes must not contain wildcards or empty levels" + ) + if ( + root == discovery + or root.startswith(discovery + "/") + or discovery.startswith(root + "/") + ): + raise ValueError( + "Driver and Home Assistant topic prefixes must be separate" + ) + baud = int(os.environ.get("SERIAL_BAUD", "57600")) + if baud != 57600: + raise ValueError("This qualified SIGNALduino configuration uses 57600 baud") + port = int(os.environ.get("MQTT_BROKER_PORT", "1883")) + if not 1 <= port <= 65535: + raise ValueError("Invalid MQTT port") + # Never let upstream instantiate its separate, incompatible MQTT publisher. + if os.environ.get("MQTT_HOST"): + raise ValueError("Use MQTT_BROKER_HOSTNAME, not upstream MQTT_HOST") + return cls( + os.environ.get("SERIAL_PORT", "/dev/signalduino"), + baud, + os.environ.get("MQTT_BROKER_HOSTNAME", "localhost"), + port, + secret("MQTT_BROKER_USERNAME"), + secret("MQTT_BROKER_PASSWORD"), + root, + discovery, + os.environ.get("MQTT_CLIENT_ID", "pysignalduino-mqtt"), + ) + + +async def check_serial(controller, metrics): + if ( + not controller.get_cached_version() + or "SIGNALduino" not in controller.get_cached_version() + ): + raise ConnectionError("Firmware initialization did not complete") + if any(task.done() for task in controller._main_tasks[:3]): + raise ConnectionError("Native serial reader/parser/writer stopped") + response = await controller.send_command( + "P", expect_response=True, response_pattern=re.compile(r"^OK\s*$"), timeout=5 + ) + if response.strip() != "OK": + raise ConnectionError("Firmware heartbeat failed") + metrics.serial.set(1) + metrics.heartbeat.set_to_current_time() + health.HEALTH_FILE.write_text(str(time.monotonic())) + + +async def heartbeat(controller, metrics): + while True: + await check_serial(controller, metrics) + await asyncio.sleep(15) + + +async def mqtt_messages(client, driver): + async for message in client.messages: + await driver.handle(str(message.topic), message.payload, message.retain) + raise ConnectionError("MQTT incoming stream ended") + + +async def session(settings, metrics): + availability = f"{settings.root}/availability" + client = MqttClient( + hostname=settings.host, + port=settings.port, + username=settings.username, + password=settings.password, + identifier=settings.client_id, + protocol=aiomqtt.ProtocolVersion.V5, + clean_start=True, + keepalive=30, + timeout=10, + max_queued_incoming_messages=512, + will=aiomqtt.Will(availability, "offline", qos=1, retain=True), + ) + metrics.devices.set(0) + try: + async with client: + metrics.mqtt.set(1) + lock = asyncio.Lock() + controller = SignalduinoController( + SerialTransport(settings.serial_port, settings.baud) + ) + + async def send(command): + async with lock: + await controller.send_command( + command, + expect_response=True, + response_pattern=re.compile(r"^SR;"), + timeout=10, + ) + + driver = Bridge(client, send, metrics, settings.root, settings.discovery) + controller.message_callback = driver.receive + # Registry and commands are separate subscriptions. MQTT5 preserves the + # retain flag even for live delivery; old retained commands are never sent. + await client.subscribe(f"{settings.root}/devices/+/config", qos=1) + await client.subscribe( + f"{settings.root}/devices/+/set", + options=SubscribeOptions( + qos=1, retainAsPublished=True, retainHandling=2 + ), + ) + await client.subscribe(f"{settings.discovery}/status", qos=1) + try: + async with controller: + await check_serial(controller, metrics) + await client.publish(availability, "online", qos=1, retain=True) + LOG.info("Gateway online: %s", controller.get_cached_version()) + tasks = [ + asyncio.create_task(heartbeat(controller, metrics)), + asyncio.create_task(mqtt_messages(client, driver)), + ] + try: + done, _ = await asyncio.wait( + tasks, return_when=asyncio.FIRST_COMPLETED + ) + for task in done: + task.result() + raise ConnectionError("Gateway worker ended unexpectedly") + finally: + for task in tasks: + task.cancel() + await asyncio.gather(*tasks, return_exceptions=True) + finally: + try: + await asyncio.wait_for( + client.publish(availability, "offline", qos=1, retain=True), 2 + ) + except (aiomqtt.MqttError, TimeoutError): + pass + finally: + metrics.serial.set(0) + metrics.mqtt.set(0) + health.HEALTH_FILE.unlink(missing_ok=True) + + +async def reconnect(settings, metrics): + delay = 1 + while True: + started = time.monotonic() + try: + await session(settings, metrics) + except ( + OSError, + TimeoutError, + ConnectionError, + aiomqtt.MqttError, + SignalduinoError, + ) as error: + metrics.errors.inc() + # Exception payloads from brokers can include configuration; log type only. + LOG.warning( + "Gateway session lost (%s); reconnect in %ss", + type(error).__name__, + delay, + ) + if time.monotonic() - started > 60: + delay = 1 + await asyncio.sleep(delay) + delay = min(delay * 2, 30) + + +async def run(): + settings = Settings.from_env() + metrics = Metrics() + health.HEALTH_FILE.unlink(missing_ok=True) + start_http_server(8000, registry=metrics.registry) + stop = asyncio.Event() + loop = asyncio.get_running_loop() + for sig in (signal.SIGTERM, signal.SIGINT): + loop.add_signal_handler(sig, stop.set) + worker = asyncio.create_task(reconnect(settings, metrics)) + stopping = asyncio.create_task(stop.wait()) + try: + done, _ = await asyncio.wait( + [worker, stopping], return_when=asyncio.FIRST_COMPLETED + ) + for task in done: + task.result() + finally: + worker.cancel() + stopping.cancel() + await asyncio.gather(worker, stopping, return_exceptions=True) + + +def main(): + """Run the explicitly selected Home Assistant USB gateway.""" + logging.basicConfig( + level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s" + ) + asyncio.run(run()) diff --git a/signalduino/output/__init__.py b/signalduino/output/__init__.py new file mode 100644 index 0000000..9ca107b --- /dev/null +++ b/signalduino/output/__init__.py @@ -0,0 +1 @@ +"""Pure output formatters for native decoded events (ADR-006).""" diff --git a/signalduino/output/homeassistant.py b/signalduino/output/homeassistant.py new file mode 100644 index 0000000..95570d3 --- /dev/null +++ b/signalduino/output/homeassistant.py @@ -0,0 +1,43 @@ +"""Pure Home Assistant discovery configuration for supported actuators.""" + +from .. import actuators as radio + + +def discovery_config(device, root="signalduino", version="0.1.0"): + """Return (domain, config), without publishing or changing device state.""" + device = radio.validate_descriptor(device) + identity = radio.identity(device) + domain = "switch" if device["protocol"] == "17" else "cover" + stem = f"{root}/devices/{identity}" + model = "Intertechno v3" if domain == "switch" else "AC114-01B" + config = { + "name": None, + "unique_id": identity, + "command_topic": f"{stem}/set", + "state_topic": f"{stem}/state", + "value_template": "{{ value_json.state }}", + "availability_topic": f"{root}/availability", + "optimistic": True, + "device": { + "identifiers": [identity], + "name": f"{model} {device['address']} / {device['channel']:x}", + "model": model, + }, + "origin": { + "name": "pysignalduino-mqtt", + "sw_version": version, + "support_url": "https://github.com/RFD-FHEM/PySignalduino", + }, + } + if domain == "switch": + config.update(payload_on="ON", payload_off="OFF") + else: + config.update( + payload_open="OPEN", + payload_close="CLOSE", + payload_stop="STOP", + state_opening="opening", + state_closing="closing", + state_stopped="stopped", + ) + return domain, config diff --git a/signalduino/transport.py b/signalduino/transport.py index fa445ed..1f1cf80 100644 --- a/signalduino/transport.py +++ b/signalduino/transport.py @@ -43,35 +43,46 @@ def closed(self) -> bool: # pragma: no cover - interface class SerialTransport(BaseTransport): - """Placeholder for asynchronous serial transport.""" + """Exclusive serial transport using pyserial-asyncio streams.""" def __init__(self, port: str, baudrate: int = 115200, read_timeout: float = 0.5): self.port = port self.baudrate = baudrate self.read_timeout = read_timeout - self._serial: Any = None # Placeholder für asynchrones Serial-Objekt + self._reader = None + self._writer = None async def open(self) -> None: - # Hier wäre die Logik für `async_serial.to_serial_port()` oder ähnliches - raise NotImplementedError("Asynchronous serial transport is not implemented yet.") + import serial_asyncio + self._reader, self._writer = await serial_asyncio.open_serial_connection( + url=self.port, baudrate=self.baudrate, exclusive=True, limit=8192 + ) async def close(self) -> None: - # Hier wäre die Logik für das Schließen des asynchronen Ports - pass + if self._writer: + self._writer.close() + try: + await self._writer.wait_closed() + finally: + self._writer = None + self._reader = None async def write_line(self, data: str) -> None: - # Platzhalter: Müsste zu `await self._writer.write(payload)` werden - await asyncio.sleep(0) # Nicht-blockierende Wartezeit - raise NotImplementedError("Asynchronous serial transport is not implemented yet.") + if self.closed(): + raise SignalduinoConnectionError("Serial port is closed") + self._writer.write((data + '\n').encode('latin-1')) + await self._writer.drain() async def readline(self) -> Optional[str]: - # Platzhalter: Müsste zu `await self._reader.readline()` werden - # Simuliere das Warten auf eine Zeile (blockiert effektiv) - await asyncio.Future() # Hängt die Coroutine auf - raise NotImplementedError("Asynchronous serial transport is not implemented yet.") + if self.closed(): + raise SignalduinoConnectionError("Serial port is closed") + raw = await self._reader.readline() + if not raw: + raise SignalduinoConnectionError("Serial port disconnected") + return raw.decode('latin-1').strip() def closed(self) -> bool: - return self._serial is None + return self._writer is None or self._writer.is_closing() class TCPTransport(BaseTransport): diff --git a/tests/data/actuators.json b/tests/data/actuators.json new file mode 100644 index 0000000..37d35ec --- /dev/null +++ b/tests/data/actuators.json @@ -0,0 +1,57 @@ +{ + "source": "RFD-FHEM/RFFHEM t/FHEM/14_SD_UT/testData.json and documented Intertechno v3 pulse mapping", + "vectors": [ + { + "comment": "Celexon Motorleinwand", + "dmsg": "P56#A300587B010043178", + "rmsg": "MU;P0=5036;P1=-624;P2=591;P3=-227;P4=187;P5=-5048;D=0123412341414123234141414141414141412341232341414141232323234123234141414141414123414141414141414141234141414123234141412341232323250123412341414123234141414141414141412341232341414141232323234123234141414141414123414141414141414141234141414123234141412;CP=4;O;", + "readings": { + "LastAction": "receive", + "deviceCode": "00587B", + "state": "down" + }, + "internals": { + "DEF": "AC114_01B 00587B", + "NAME": "AC114_01B_00587B" + } + }, + { + "comment": "Remote control AC114-01B", + "dmsg": "P56#A347969601000B7F8", + "rmsg": "MU;P0=-16412;P1=5195;P2=-598;P3=585;P4=-208;P5=192;D=01234523452525234345234525252343434345252345234345234525234523434525252525252525234525252525252525252525252345234345234343434343434341234523452525234345234525252343434345252345234345234525234523434525252525252525234525252525252525252525252345234345234343;CP=5;R=105;O;", + "readings": { + "LastAction": "receive", + "deviceCode": "479696", + "state": "up" + }, + "internals": { + "DEF": "AC114_01B 479696", + "NAME": "AC114_01B_479696" + } + }, + { + "comment": "remote control AC114-01B", + "dmsg": "P56#A3479696010023978", + "rmsg": "MU;P0=-2341;P1=5206;P2=-571;P3=591;P4=-211;P5=207;D=01234523452525234345234525252343434345252345234345234525234523434525252525252525234525252525252525252523452525234343452523452343434341234523452525234345234525252343434345252345234345234525234523434525252525252525234525252525252525252523452525234343452523;CP=5;R=107;O;", + "readings": { + "LastAction": "receive", + "deviceCode": "479696", + "state": "stop" + }, + "internals": { + "DEF": "AC114_01B 479696", + "NAME": "AC114_01B_479696" + } + }, + { + "comment": "Hand-encoded Intertechno v3 off: FHEM IT_V3_bf26361 address/group/unit", + "rmsg": "MS;P0=275;P1=-275;P2=-1375;P3=-2750;P4=-11000;D=030102010201020201010202010201020102010201020101020102020101020102020102010102010201020201020101020201020101020102010201020102020104;CP=0;SP=3;R=100;", + "protocol_id": "17", + "bits": "00010111111001001100011011000001", + "address": "05F931B", + "channel": 1, + "group": 0, + "state": "off" + } + ] +} diff --git a/tests/homeassistant/__init__.py b/tests/homeassistant/__init__.py new file mode 100644 index 0000000..a39138b --- /dev/null +++ b/tests/homeassistant/__init__.py @@ -0,0 +1 @@ +"""USB, actuator and MQTT gateway regressions.""" diff --git a/tests/homeassistant/test_bridge.py b/tests/homeassistant/test_bridge.py new file mode 100644 index 0000000..1c28f59 --- /dev/null +++ b/tests/homeassistant/test_bridge.py @@ -0,0 +1,145 @@ +import json +import unittest +from pathlib import Path + +from signalduino.homeassistant import bridge +from signalduino.parser import SignalParser + + +class Publisher: + """External MQTT boundary; messages are checked as a HA consumer sees them.""" + + def __init__(self): + self.messages = [] + + async def publish(self, topic, payload, qos=0, retain=False): + self.messages.append( + ( + topic, + json.loads(payload) if payload.startswith("{") else payload, + qos, + retain, + ) + ) + + +class BridgeTests(unittest.IsolatedAsyncioTestCase): + async def asyncSetUp(self): + self.publisher = Publisher() + self.sent = [] + + async def send(command): + self.sent.append(command) + + self.driver = bridge.Bridge(self.publisher, send, bridge.Metrics()) + vectors = json.loads( + (Path(__file__).parents[1] / "data" / "actuators.json").read_text() + )["vectors"] + self.messages = [ + m + for v in vectors + for m in SignalParser().parse_line("\x02" + v["rmsg"] + "\x03") + ] + + async def test_received_devices_create_retained_switch_and_cover_discovery(self): + for message in self.messages: + await self.driver.receive(message) + configs = { + t: p + for t, p, q, r in self.publisher.messages + if t.startswith("homeassistant/") + } + cover = configs[ + "homeassistant/cover/signalduino/signalduino_56_479696_0100/config" + ] + switch = configs[ + "homeassistant/switch/signalduino/signalduino_17_05f931b_0_1/config" + ] + self.assertEqual(cover["device"]["identifiers"], ["signalduino_56_479696_0100"]) + self.assertTrue(cover["optimistic"]) + self.assertNotIn("position_topic", cover) + self.assertEqual( + switch["command_topic"], + "signalduino/devices/signalduino_17_05f931b_0_1/set", + ) + self.assertTrue( + all( + q == 1 and r + for t, p, q, r in self.publisher.messages + if t.startswith("homeassistant/") + ) + ) + self.assertTrue( + all(not r for t, p, q, r in self.publisher.messages if t.endswith("/state")) + ) + + async def test_restart_registry_and_ha_birth_keep_identity_without_fake_state(self): + device = {"protocol": "56", "address": "479696", "channel": 256, "clock": 200} + topic = "signalduino/devices/signalduino_56_479696_0100/config" + await self.driver.handle(topic, json.dumps(device).encode(), True) + await self.driver.handle("homeassistant/status", b"online", False) + configs = [ + p + for t, p, q, r in self.publisher.messages + if t.startswith("homeassistant/") + ] + self.assertEqual(len(configs), 2) + self.assertEqual(configs[0]["unique_id"], configs[1]["unique_id"]) + self.assertFalse( + any(t.endswith("/state") for t, p, q, r in self.publisher.messages) + ) + + async def test_retained_unknown_and_invalid_commands_never_transmit(self): + device = {"protocol": "56", "address": "479696", "channel": 256, "clock": 200} + stem = "signalduino/devices/signalduino_56_479696_0100/" + await self.driver.handle(stem + "config", json.dumps(device).encode(), True) + await self.driver.handle(stem + "set", b"OPEN", True) + await self.driver.handle(stem + "set", b"PROGRAM", False) + await self.driver.handle("signalduino/devices/unknown/set", b"OPEN", False) + self.assertEqual(self.sent, []) + await self.driver.handle(stem + "set", b"STOP", False) + self.assertEqual(len(self.sent), 1) + self.assertTrue(self.sent[0].startswith("SR;R=5;")) + + async def test_malformed_registry_cannot_stop_subsequent_device_learning(self): + device = {"protocol": "56", "address": "479696", "channel": 256, "clock": 200} + identity = "signalduino_56_479696_0100" + topic = f"signalduino/devices/{identity}/config" + poison = b'{"protocol":' + b"[" * 100000 + b"0" + b"]" * 100000 + b"}" + await self.driver.handle(topic, poison, True) + self.assertEqual(self.driver.devices, {}) + self.assertEqual(self.publisher.messages, []) + await self.driver.handle(topic, json.dumps(device).encode(), True) + self.assertEqual(self.driver.devices[identity], device) + self.assertEqual(len(self.publisher.messages), 1) + + async def test_mismatched_registry_topic_cannot_create_or_control_device(self): + device = {"protocol": "56", "address": "479696", "channel": 256, "clock": 200} + await self.driver.handle( + "signalduino/devices/not_the_address/config", + json.dumps(device).encode(), + True, + ) + self.assertEqual(self.driver.devices, {}) + self.assertEqual(self.publisher.messages, []) + + async def test_repeated_rf_burst_does_not_duplicate_discovery(self): + for _ in range(3): + await self.driver.receive(self.messages[-1]) + configs = [ + t + for t, p, q, r in self.publisher.messages + if t.startswith("homeassistant/") + ] + self.assertEqual( + configs, + ["homeassistant/switch/signalduino/signalduino_17_05f931b_0_1/config"], + ) + states = [p for t, p, q, r in self.publisher.messages if t.endswith("/state")] + self.assertEqual(len(states), 1) + self.assertEqual(states[0]["state"], "OFF") + self.assertEqual(states[0]["source"], "received") + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/homeassistant/test_integration.py b/tests/homeassistant/test_integration.py new file mode 100644 index 0000000..f2b2cac --- /dev/null +++ b/tests/homeassistant/test_integration.py @@ -0,0 +1,207 @@ +"""Real isolated Mosquitto and native serial pipeline; never production RF.""" + +import asyncio +import json +import os +import tempfile +import unittest +import uuid +from pathlib import Path +from unittest.mock import patch + +import aiomqtt + +from signalduino.homeassistant import health +from signalduino.homeassistant import runtime as main +from signalduino.homeassistant.bridge import Metrics + + +@unittest.skipUnless( + os.environ.get("MQTT_TEST_HOST"), "isolated MQTT test broker not configured" +) +class MqttIntegration(unittest.IsolatedAsyncioTestCase): + async def test_failed_publication_still_replaces_retained_online_with_offline(self): + host = os.environ["MQTT_TEST_HOST"] + topic = "permitted/availability" + async with aiomqtt.Client(host) as observer: + await observer.publish(topic, None, qos=1, retain=True) + await observer.subscribe(topic, qos=1) + async with main.MqttClient( + host, + username="restricted", + password="test-password", + protocol=aiomqtt.ProtocolVersion.V5, + will=aiomqtt.Will(topic, "offline", qos=1, retain=True), + ) as client: + await client.publish(topic, "online", qos=1, retain=True) + async with asyncio.timeout(3): + async for message in observer.messages: + if message.payload == b"online": + break + with self.assertRaises(aiomqtt.MqttError): + await client.publish( + "forbidden/discovery", "{}", qos=1, retain=True + ) + # Match the runtime's best-effort cleanup after a poisoned session. + with self.assertRaises(aiomqtt.MqttError): + await client.publish(topic, "offline", qos=1, retain=True) + async with asyncio.timeout(3): + async for message in observer.messages: + if message.payload == b"offline": + break + async with aiomqtt.Client(host) as fresh: + await fresh.subscribe(topic, qos=1) + async with asyncio.timeout(3): + async for message in fresh.messages: + self.assertEqual(message.payload, b"offline") + self.assertTrue(message.retain) + break + + async def test_broker_puback_denial_is_an_error(self): + async with main.MqttClient( + os.environ["MQTT_TEST_HOST"], + username="restricted", + password="test-password", + protocol=aiomqtt.ProtocolVersion.V5, + ) as client: + with self.assertRaises(aiomqtt.MqttError): + await client.publish("forbidden/discovery", "{}", qos=1, retain=True) + + async def test_real_runtime_discovers_and_retained_commands_never_reach_serial( + self, + ): + host = os.environ["MQTT_TEST_HOST"] + root = "sdtest_" + uuid.uuid4().hex[:8] + discovery = root + "_ha" + master, slave = os.openpty() + os.set_blocking(master, False) + commands = [] + + async def firmware(): + buffer = b"" + while True: + try: + buffer += os.read(master, 8192) + except BlockingIOError: + pass + while b"\n" in buffer: + command, buffer = buffer.split(b"\n", 1) + commands.append(command) + if command == b"V": + os.write(master, b"V 4.0.0 SIGNALduino cc1101\r\n") + elif command == b"P": + os.write(master, b"OK\r\n") + elif command.startswith(b"SR;"): + os.write(master, command + b"\r\n") + await asyncio.sleep(0.005) + + async def until(client, predicate): + async with asyncio.timeout(12): + async for message in client.messages: + if predicate(message): + return message + + emulator = asyncio.create_task(firmware()) + session = None + settings = main.Settings( + os.ttyname(slave), 57600, host, 1883, None, None, root, discovery, root + ) + metrics = Metrics() + vectors = json.loads( + (Path(__file__).parents[1] / "data" / "actuators.json").read_text() + )["vectors"] + identity = "signalduino_56_479696_0100" + cfg = f"{discovery}/cover/signalduino/{identity}/config" + state = f"{root}/devices/{identity}/state" + command_topic = f"{root}/devices/{identity}/set" + registry = f"{root}/devices/{identity}/config" + try: + async with aiomqtt.Client(host) as observer: + await observer.subscribe(f"{root}/#", qos=1) + await observer.subscribe(f"{discovery}/#", qos=1) + # Cached commands must not be delivered to a new driver session. + await observer.publish(command_topic, "OPEN", qos=1, retain=True) + with tempfile.TemporaryDirectory() as tmp, patch.object( + health, "HEALTH_FILE", Path(tmp) / "health" + ): + session = asyncio.create_task(main.session(settings, metrics)) + await until( + observer, + lambda m: str(m.topic) == f"{root}/availability" + and m.payload == b"online", + ) + os.write( + master, + ("\x02" + vectors[1]["rmsg"] + "\x03\n").encode("latin-1"), + ) + message = await until(observer, lambda m: str(m.topic) == cfg) + self.assertEqual(json.loads(message.payload)["unique_id"], identity) + await until(observer, lambda m: str(m.topic) == state) + self.assertTrue(health.healthy()) + # MQTT5 must preserve RETAIN on live delivery as well. + await observer.publish(command_topic, "CLOSE", qos=1, retain=True) + await asyncio.sleep(0.1) + self.assertFalse(any(c.startswith(b"SR;") for c in commands)) + await observer.publish(command_topic, "STOP", qos=1, retain=False) + async with asyncio.timeout(5): + while metrics.sent._value.get() != 1: + await asyncio.sleep(0.01) + self.assertEqual(sum(c.startswith(b"SR;") for c in commands), 1) + async with aiomqtt.Client(host) as retained: + await retained.subscribe(cfg, qos=1) + remembered = await until( + retained, lambda m: str(m.topic) == cfg + ) + self.assertTrue(remembered.retain) + await retained.subscribe(registry, qos=1) + remembered = await until( + retained, lambda m: str(m.topic) == registry + ) + self.assertEqual( + json.loads(remembered.payload)["address"], "479696" + ) + # State must not survive for a fresh subscriber. + await retained.subscribe(state, qos=1) + with self.assertRaises(TimeoutError): + await asyncio.wait_for( + anext(retained.messages.__aiter__()), 0.15 + ) + session.cancel() + await asyncio.gather(session, return_exceptions=True) + await until( + observer, + lambda m: str(m.topic) == f"{root}/availability" + and m.payload == b"offline", + ) + self.assertFalse(health.healthy()) + commands.clear() + session = asyncio.create_task(main.session(settings, metrics)) + restored = set() + async with asyncio.timeout(12): + async for message in observer.messages: + if str(message.topic) == cfg: + restored.add("config") + if ( + str(message.topic) == f"{root}/availability" + and message.payload == b"online" + ): + restored.add("online") + if restored == {"config", "online"}: + break + await observer.publish(f"{discovery}/status", "online", qos=1) + message = await until(observer, lambda m: str(m.topic) == cfg) + self.assertEqual(json.loads(message.payload)["unique_id"], identity) + self.assertFalse(any(c.startswith(b"SR;") for c in commands)) + self.assertFalse(any(c[:1] in (b"W", b"e", b"x") for c in commands)) + finally: + if session: + session.cancel() + await asyncio.gather(session, return_exceptions=True) + emulator.cancel() + await asyncio.gather(emulator, return_exceptions=True) + os.close(master) + os.close(slave) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/homeassistant/test_radio.py b/tests/homeassistant/test_radio.py new file mode 100644 index 0000000..7967204 --- /dev/null +++ b/tests/homeassistant/test_radio.py @@ -0,0 +1,139 @@ +import json +import unittest +from pathlib import Path + +from signalduino import actuators as radio +from signalduino.parser import SignalParser +from signalduino.types import DecodedMessage, RawFrame + + +class RadioTests(unittest.TestCase): + def setUp(self): + self.parser = SignalParser() + self.vectors = json.loads( + (Path(__file__).parents[1] / "data" / "actuators.json").read_text() + )["vectors"] + + def test_native_fhem_vectors_create_correct_devices(self): + for vector in self.vectors: + with self.subTest(vector=vector["comment"]): + events = [ + radio.decode(m) + for m in self.parser.parse_line("\x02" + vector["rmsg"] + "\x03") + ] + events = [e for e in events if e] + self.assertTrue(events) + event = events[0] + expected = vector.get("readings", {}).get("state", vector.get("state")) + self.assertEqual(event.values["state"], expected) + device = radio.descriptor(event) + if event.protocol_id == "56": + self.assertEqual( + device["address"], vector["readings"]["deviceCode"].lower() + ) + self.assertEqual(device["channel"], 256) + else: + self.assertEqual(device["address"], "05f931b") + self.assertEqual(device["channel"], 1) + self.assertEqual(device["group"], 0) + + def test_aok_rejects_bad_checksum_marker_header_and_secondary_command(self): + for payload in [ + "A347969601000B7E8", + "A347969601000B7F0", + "A247969601000B7F8", + "A3479696010024988", + "A34796", + "ZZ", + ]: + with self.subTest(payload=payload): + msg = DecodedMessage("56", "P56#" + payload, RawFrame("")) + self.assertIsNone(radio.decode(msg)) + + def test_full_aok_channel_bitmap_is_identity(self): + # Checksum = 0x47+0x96+0x96+0x02+0x00+0x0b = 0x80. + first = radio.decode( + DecodedMessage("56", "P56#A347969601000B7F8", RawFrame("")) + ) + second = radio.decode( + DecodedMessage("56", "P56#A347969602000B808", RawFrame("")) + ) + self.assertNotEqual(first.device_id, second.device_id) + + def test_unknown_protocol_or_malformed_it_has_no_device(self): + for protocol, payload in [ + ("999", "123"), + ("17", "i1234"), + ("17", "iFFFFFFFF000"), + ("17", "iBAD"), + ]: + self.assertIsNone( + radio.decode(DecodedMessage(protocol, payload, RawFrame(""))) + ) + + def test_send_aok_matches_independent_65_bit_reference(self): + d = {"protocol": "56", "address": "479696", "channel": 256, "clock": 200} + command = radio.encode(d, "OPEN") + pulses = self.pulses(command) + self.assertEqual(pulses[:2], [5000, -600]) + pairs = [tuple(pulses[i : i + 2]) for i in range(2, len(pulses) - 1, 2)] + bits = "".join({(600, -200): "1", (200, -600): "0"}[pair] for pair in pairs) + self.assertEqual( + bits, "10100011010001111001011010010110000000010000000000001011011111111" + ) + self.assertEqual(pulses[-1], -5000) + + def test_send_intertechno_uses_full_address_group_and_unit(self): + d = { + "protocol": "17", + "address": "05f931b", + "channel": 1, + "group": 0, + "clock": 275, + } + pulses = self.pulses(radio.encode(d, "ON")) + self.assertEqual(pulses[:2], [275, -2750]) + bits = "".join( + {(275, -275, 275, -1375): "0", (275, -1375, 275, -275): "1"}[ + tuple(pulses[i : i + 4]) + ] + for i in range(2, len(pulses) - 2, 4) + ) + self.assertEqual(bits, "00010111111001001100011011010001") + self.assertEqual(pulses[-2:], [275, -11000]) + + def test_registry_and_commands_reject_injection_and_out_of_range_data(self): + valid = { + "protocol": "17", + "address": "05f931b", + "channel": 1, + "group": 0, + "clock": 275, + } + for patch in [ + {"address": "../bad"}, + {"protocol": "17/other"}, + {"channel": 16}, + {"clock": -1}, + {"group": 2}, + ]: + with self.assertRaises(ValueError): + radio.validate_descriptor(valid | patch) + for command in ["PROGRAM", "ON\nW0000", "", "toggle"]: + with self.assertRaises(ValueError): + radio.encode(valid, command) + + @staticmethod + def pulses(command): + parts = command.split(";") + if parts[0] != "SR" or "R=5" not in parts: + raise AssertionError("Not a bounded native SR command") + mapping = { + part[1]: int(part.split("=")[1]) for part in parts if part.startswith("P") + } + data = next(part[2:] for part in parts if part.startswith("D=")) + return [mapping[i] for i in data] + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/homeassistant/test_runtime.py b/tests/homeassistant/test_runtime.py new file mode 100644 index 0000000..b51ce37 --- /dev/null +++ b/tests/homeassistant/test_runtime.py @@ -0,0 +1,112 @@ +import asyncio +import os +import tempfile +import unittest +from pathlib import Path +from unittest.mock import patch + +from signalduino.controller import SignalduinoController +from signalduino.exceptions import SignalduinoCommandTimeout +from signalduino.homeassistant import health +from signalduino.homeassistant import runtime as main +from signalduino.homeassistant.bridge import Metrics +from signalduino.transport import SerialTransport + + +class RuntimeTests(unittest.TestCase): + def test_credentials_from_file_do_not_enter_repr(self): + with tempfile.TemporaryDirectory() as tmp: + p = Path(tmp) / "password" + p.write_text("secret-test-value\n") + with patch.dict( + os.environ, {"MQTT_BROKER_PASSWORD_FILE": str(p)}, clear=True + ): + settings = main.Settings.from_env() + self.assertEqual(settings.password, "secret-test-value") + self.assertNotIn("secret-test-value", repr(settings)) + + def test_topic_wildcards_and_conflicting_secret_inputs_are_rejected(self): + for env in [ + {"MQTT_TOPIC": "signalduino/#"}, + {"MQTT_TOPIC": "homeassistant"}, + {"MQTT_BROKER_PASSWORD": "one", "MQTT_BROKER_PASSWORD_FILE": "/secret"}, + ]: + with patch.dict(os.environ, env, clear=True), self.assertRaises(ValueError): + main.Settings.from_env() + + def test_health_rejects_stale_future_and_malformed_receipts(self): + with tempfile.TemporaryDirectory() as tmp: + p = Path(tmp) / "health" + with patch.object(health, "HEALTH_FILE", p), patch.object( + health.time, "monotonic", return_value=100 + ): + for value, want in [ + ("90", True), + ("0", False), + ("101", False), + ("nan", False), + ("garbage", False), + ]: + p.write_text(value) + self.assertEqual(health.healthy(), want) + + +class FirmwareHeartbeat(unittest.IsolatedAsyncioTestCase): + async def test_native_timeout_reconnects_instead_of_killing_driver(self): + attempts = [] + + async def failed_session(settings, metrics): + attempts.append(1) + if len(attempts) == 2: + raise asyncio.CancelledError() + raise SignalduinoCommandTimeout("no response") + + async def no_wait(delay): + pass + + with patch.object(main, "session", failed_session), patch.object( + main.asyncio, "sleep", no_wait + ), self.assertRaises(asyncio.CancelledError): + await main.reconnect(None, Metrics()) + self.assertEqual(len(attempts), 2) + + async def test_real_native_serial_heartbeat_updates_health_without_rf(self): + master, slave = os.openpty() + os.set_blocking(master, False) + + async def firmware(): + buffer = b"" + while True: + try: + buffer += os.read(master, 4096) + except BlockingIOError: + pass + while b"\n" in buffer: + command, buffer = buffer.split(b"\n", 1) + if command == b"V": + os.write(master, b"V 4.0.0 SIGNALduino cc1101\r\n") + elif command == b"P": + os.write(master, b"OK\r\n") + await asyncio.sleep(0.005) + + task = asyncio.create_task(firmware()) + metrics = Metrics() + with tempfile.TemporaryDirectory() as tmp, patch.object( + health, "HEALTH_FILE", Path(tmp) / "health" + ): + try: + async with SignalduinoController( + SerialTransport(os.ttyname(slave), 57600) + ) as controller: + await main.check_serial(controller, metrics) + self.assertTrue(health.healthy()) + self.assertEqual(metrics.serial._value.get(), 1) + finally: + task.cancel() + await asyncio.gather(task, return_exceptions=True) + os.close(master) + os.close(slave) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/homeassistant/test_upstream.py b/tests/homeassistant/test_upstream.py new file mode 100644 index 0000000..69e5d4c --- /dev/null +++ b/tests/homeassistant/test_upstream.py @@ -0,0 +1,96 @@ +"""Regressions for native USB transport, initialization and parser delivery.""" + +import asyncio +import json +import os +import unittest +from pathlib import Path +from types import SimpleNamespace + +from signalduino.controller import SignalduinoController +from signalduino.parser import SignalParser +from signalduino.transport import SerialTransport +from signalduino.types import DecodedMessage, RawFrame + + +class NativeParsing(unittest.TestCase): + def test_fhem_aok_and_intertechno_vectors_reach_native_decoder(self): + parser = SignalParser() + vectors = json.loads( + (Path(__file__).parents[1] / "data" / "actuators.json").read_text() + )["vectors"] + for vector in vectors: + with self.subTest(vector=vector["comment"]): + messages = parser.parse_line("\x02" + vector["rmsg"] + "\x03") + expected = vector.get("protocol_id", "56") + matches = [m for m in messages if m.protocol_id == expected] + self.assertTrue(matches, "Native parser lost the target protocol") + if "dmsg" in vector: + self.assertEqual(matches[0].payload.upper(), vector["dmsg"].upper()) + self.assertTrue(matches[0].metadata["bits"]) + + +class NativeAsync(unittest.IsolatedAsyncioTestCase): + async def test_cancelled_initialization_closes_serial_and_background_tasks(self): + master, slave = os.openpty() + transport = SerialTransport(os.ttyname(slave), baudrate=57600) + controller = SignalduinoController(transport) + try: + with self.assertRaises(TimeoutError): + await asyncio.wait_for(controller.__aenter__(), 0.05) + self.assertTrue(transport.closed()) + self.assertTrue(all(t.done() for t in controller._main_tasks)) + finally: + await controller.__aexit__(None, None, None) + os.close(master) + os.close(slave) + + async def test_serial_roundtrip_and_close(self): + master, slave = os.openpty() + transport = SerialTransport(os.ttyname(slave), baudrate=57600) + try: + await transport.open() + self.assertFalse(transport.closed()) + await transport.write_line("V") + command = await asyncio.wait_for(asyncio.to_thread(os.read, master, 128), 2) + self.assertEqual(command, b"V\n") + os.write(master, b"V 4.0.0 SIGNALduino\r\n") + self.assertEqual( + await asyncio.wait_for(transport.readline(), 2), "V 4.0.0 SIGNALduino" + ) + await transport.close() + self.assertTrue(transport.closed()) + finally: + await transport.close() + os.close(master) + os.close(slave) + + async def test_controller_delivers_every_demodulated_result(self): + messages = [ + DecodedMessage(str(pid), "test", RawFrame("test")) for pid in (17, 56) + ] + observed = [] + complete = asyncio.Event() + + async def receive(message): + observed.append(message.protocol_id) + if len(observed) == 2: + complete.set() + + controller = SignalduinoController( + transport=None, + parser=SimpleNamespace(parse_line=lambda line: messages), + message_callback=receive, + ) + task = asyncio.create_task(controller._parser_task()) + try: + await controller._raw_message_queue.put("test") + await asyncio.wait_for(complete.wait(), 0.5) + self.assertEqual(observed, ["17", "56"]) + finally: + task.cancel() + await asyncio.gather(task, return_exceptions=True) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_decoder_registry.py b/tests/test_decoder_registry.py index 38d9658..3b60ed6 100644 --- a/tests/test_decoder_registry.py +++ b/tests/test_decoder_registry.py @@ -107,6 +107,12 @@ def test_unknown_variant_adds_nothing(self, spec): class TestRegistryLoading: + @pytest.fixture(autouse=True) + def specifications_only(self, monkeypatch): + """Synthetic spec counts must not depend on shipped custom decoders.""" + from signalduino.decoders import registry as registry_module + monkeypatch.setattr(registry_module, "registered_custom", lambda: {}) + def test_loads_specifications_from_a_directory(self, tmp_path): write_spec(tmp_path, "test_999.json", MINIMAL_SPEC) registry = DecoderRegistry(specs_dir=tmp_path) diff --git a/tests/test_homeassistant_output.py b/tests/test_homeassistant_output.py new file mode 100644 index 0000000..c8fd7df --- /dev/null +++ b/tests/test_homeassistant_output.py @@ -0,0 +1,17 @@ +"""The native output adapter formats discovery without a broker or side effects.""" + +from signalduino.output.homeassistant import discovery_config + + +def test_cover_discovery_is_pure_and_includes_the_complete_channel_bitmap(): + device = {"protocol": "56", "address": "479696", "channel": 256, "clock": 200} + original = dict(device) + domain, config = discovery_config(device, "signalduino", "0.1.0") + assert device == original + assert domain == "cover" + assert config["unique_id"] == "signalduino_56_479696_0100" + assert ( + config["command_topic"] == "signalduino/devices/signalduino_56_479696_0100/set" + ) + assert config["optimistic"] is True + assert "position_topic" not in config