Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 37 additions & 1 deletion .github/workflows/test-pr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ name: Unittest on Pull Request

on:
pull_request:
branches: [ main ]
branches: [ main, feat/sensor-decoding ]

jobs:
test:
Expand Down Expand Up @@ -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
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
pycache/
*.pyc
*.egg-info/
.venv/
.env/
temp_repo/
Expand Down
3 changes: 2 additions & 1 deletion README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Basierend auf der originalen FHEM‑SIGNALDuino‑Implementierung von [@Sidey79](https://github.com/Sidey79) und der Community.
20 changes: 20 additions & 0 deletions docker/homeassistant/Dockerfile
Original file line number Diff line number Diff line change
@@ -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"]
6 changes: 6 additions & 0 deletions docker/homeassistant/Dockerfile.dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
.git
.devcontainer
.env*
**/__pycache__
**/*.pyc
*.egg-info
16 changes: 16 additions & 0 deletions docker/homeassistant/requirements.txt
Original file line number Diff line number Diff line change
@@ -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
144 changes: 144 additions & 0 deletions docs/01_user_guide/homeassistant_gateway.adoc
Original file line number Diff line number Diff line change
@@ -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/<identity>/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/<identity>/state` and `signalduino/events`. Commands at
`signalduino/devices/<identity>/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.
5 changes: 5 additions & 0 deletions docs/01_user_guide/installation.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
9 changes: 9 additions & 0 deletions docs/architecture/diagrams/homeassistant-usb-components.mmd
Original file line number Diff line number Diff line change
@@ -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]
18 changes: 18 additions & 0 deletions docs/architecture/diagrams/homeassistant-usb-discovery.mmd
Original file line number Diff line number Diff line change
@@ -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
Loading