Minimal viable Product

.devcontainer/.devcontainer.env.sample

@@ -0,0 +1,40 @@
+# MQTT Broker Konfiguration
+# Die Adresse des MQTT Brokers (z.B. Mosquitto).
+MQTT_HOST=localhost
+
+# Der Port des MQTT Brokers (Standard: 1883).
+MQTT_PORT=1883
+
+# Der Benutzername für die Authentifizierung am MQTT Broker.
+# Optional: Leer lassen, wenn keine Authentifizierung erforderlich ist.
+MQTT_USERNAME=
+
+# Das Passwort für die Authentifizierung am MQTT Broker.
+# Optional: Leer lassen, wenn keine Authentifizierung erforderlich ist.
+MQTT_PASSWORD=
+
+# Das Basis-Topic für Signalduino Nachrichten.
+# Nachrichten werden unter $MQTT_TOPIC/<protokoll_id> veröffentlicht.
+# Befehle werden unter $MQTT_TOPIC/commands/# erwartet.
+MQTT_TOPIC=signalduino/messages
+
+# Signalduino Verbindungseinstellungen (für direkte Verwendung in main.py)
+# Wähle entweder eine serielle Verbindung ODER eine TCP-Verbindung.
+
+# Serieller Port für die Verbindung zum Signalduino (z.B. /dev/ttyUSB0).
+# Wird verwendet, wenn das Skript mit --serial gestartet wird oder um Standardwerte zu setzen.
+SIGNALDUINO_SERIAL_PORT=/dev/ttyUSB0
+
+# Baudrate für die serielle Verbindung (Standard: 57600).
+SIGNALDUINO_BAUD=57600
+
+# TCP Host für die Verbindung zum Signalduino über Netzwerk (z.B. ESP-Link).
+# Wird verwendet, wenn das Skript mit --tcp gestartet wird.
+SIGNALDUINO_TCP_HOST=192.168.1.10
+
+# TCP Port für die Verbindung zum Signalduino (Standard: 23).
+SIGNALDUINO_TCP_PORT=23
+
+# Logging Level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+# Steuert die Ausführlichkeit der Log-Ausgaben.
+LOG_LEVEL=INFO

.devcontainer/devcontainer.json

@@ -0,0 +1,33 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/python
+{
+	"name": "Python 3",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "mcr.microsoft.com/devcontainers/python:2-3-bookworm",
+	"features": {
+		//"ghcr.io/hspaans/devcontainer-features/pytest:2": {}
+	},
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	"postCreateCommand": "pip3 install --user -r requirements-dev.txt  -r requirements.txt || exit 0",
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"RooVeterinaryInc.roo-cline"
+			]
+		}
+	},
+	"runArgs": ["--env-file", ".devcontainer/devcontainer.env"]
+
+	// Configure tool-specific properties.
+	// "customizations": {},
+
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}

.github/workflows/test-pr.yml

@@ -19,8 +19,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -r requirements.txt
-        pip install pytest-cov
+        pip install -r requirements.txt -r requirements-dev.txt
 
     - name: Run tests with coverage
       run: |

.gitignore

@@ -1,4 +1,8 @@
 pycache/
 *.pyc
 .venv/
-.env/
+.env/
+temp_repo/
+SIGNALDuino-Firmware/
+.devcontainer/devcontainer.env
+.devcontainer/.devcontainer.env

.vscode/settings.json

@@ -40,5 +40,10 @@
                 }
             }
         ]
-    }
+    },
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
 }

.vscode/tasks.json

@@ -0,0 +1,13 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "run main program",
+            "type": "shell",
+            "command": "python3 main.py",
+            "problemMatcher": []
+        }
+    ]
+}

AGENTS.md

@@ -7,4 +7,43 @@ This file provides guidance to agents when working with code in this repository.
 - **TFA Protocol Gotcha:** `mcBit2TFA` implements duplicate message detection by chunking the *entire* received bitstream, not just the expected message length.
 - **Grothe Constraint:** `mcBit2Grothe` enforces an *exact* 32-bit length, overriding general length checks.
 - **Test Mocking:** MC Parser tests mock `mock_protocols.demodulate` to simulate the output of the protocol layer, not `demodulate_mc` directly.
-- **Bit Conversion:** `_convert_mc_hex_to_bits` handles `polarity_invert` and firmware version toggling for polarity.
+- **Bit Conversion:** `_convert_mc_hex_to_bits` handles `polarity_invert` and firmware version toggling for polarity.
+
+## Verification Execution
+- Das Hauptprogramm für Verifizierungen sollte wie folgt gestartet werden:
+  `python3 main.py --timeout 1`
+
+## Mandatory Documentation and Test Maintenance
+
+Diese Richtlinie gilt für alle AI-Agenten, die Code oder Systemkonfigurationen in diesem Repository ändern. Jede Änderung **muss** eine vollständige Analyse der Auswirkungen auf die zugehörige Dokumentation und die Testsuite umfassen.
+
+### 1. Dokumentationspflicht
+- **Synchronisierung:** Die Dokumentation muss synchron zu allen vorgenommenen Änderungen aktualisiert werden, um deren Genauigkeit und Vollständigkeit sicherzustellen.
+- **Bereiche:** Betroffene Dokumentationsbereiche umfassen:
+  - `docs/`‑Verzeichnis (AsciiDoc‑Dateien)
+  - Inline‑Kommentare und Docstrings
+  - README.md und andere Markdown‑Dateien
+  - API‑Referenzen und Benutzerhandbücher
+- **Prüfung:** Vor dem Abschluss einer Änderung ist zu verifizieren, dass alle dokumentationsrelevanten Aspekte berücksichtigt wurden.
+
+### 2. Test‑Pflicht
+- **Bestehende Tests:** Die bestehenden Tests sind zu überprüfen und anzupassen, um die geänderten Funktionalitäten korrekt abzudecken.
+- **Neue Tests:** Bei Bedarf sind neue Tests zu erstellen, um eine vollständige Testabdeckung der neuen oder modifizierten Logik zu gewährleisten.
+- **Test‑Verzeichnis:** Alle Tests befinden sich im `tests/`‑Verzeichnis und müssen nach der Änderung weiterhin erfolgreich ausführbar sein.
+- **Test‑Ausführung:** Vor dem Commit ist die Testsuite mit `pytest` (oder dem projektspezifischen Testrunner) auszuführen, um Regressionen auszuschließen.
+
+### 3. Verbindlichkeit
+- Diese Praxis ist für **jede** Änderung verbindlich und nicht verhandelbar.
+- Ein Commit, der die Dokumentation oder Tests nicht entsprechend anpasst, ist unzulässig.
+- Agenten müssen sicherstellen, dass ihre Änderungen den etablierten Qualitätsstandards des Projekts entsprechen.
+
+### 4. Checkliste vor dem Commit
+- [ ] Dokumentation im `docs/`‑Verzeichnis aktualisiert
+- [ ] Inline‑Kommentare und Docstrings angepasst
+- [ ] README.md und andere Markdown‑Dateien geprüft
+- [ ] Bestehende Tests angepasst und erfolgreich ausgeführt
+- [ ] Neue Tests für geänderte/neue Logik erstellt
+- [ ] Gesamte Testsuite (`pytest`) ohne Fehler durchgelaufen
+- [ ] Änderungen mit den Projekt‑Konventionen konsistent
+
+Diese Richtlinie gewährleistet, dass Code‑Änderungen nicht isoliert, sondern im Kontext des gesamten Projekts betrachtet werden und die langfristige Wartbarkeit sowie die Zuverlässigkeit der Software erhalten bleibt.

README.md

@@ -1,15 +1,167 @@
-# SignalDuino MQTT Bridge
+# PySignalduino – Asynchrone MQTT-Bridge für SIGNALDuino
 
-Dieses Projekt ist eine Python-Portierung der SIGNALDuino-Protokolle aus FHEM.
-Es stellt die Protokolle als Dictionary bereit und bietet eine objektorientierte
-Schnittstelle (`SDProtocols`).
+Dieses Projekt ist eine moderne Python-Implementierung der SIGNALDuino-Protokolle mit vollständiger **asyncio**-Unterstützung und integrierter **MQTT-Bridge**. Es ermöglicht die Kommunikation mit SIGNALDuino-Hardware (über serielle Schnittstelle oder TCP) und veröffentlicht empfangene Signale sowie empfängt Steuerbefehle über MQTT.
 
-## Struktur
-- `sd_protocols/` – Kernmodule
-- `examples/` – Demo-Skripte
-- `tests/` – Unit-Tests mit pytest
+## Hauptmerkmale
+
+*   **Vollständig asynchron** – Basierend auf `asyncio` für hohe Performance und einfache Integration in asynchrone Anwendungen.
+*   **MQTT-Integration** – Automatisches Publizieren dekodierter Nachrichten in konfigurierbare Topics und Empfang von Steuerbefehlen (z.B. `version`, `set`, `mqtt`).
+*   **Unterstützte Transporte** – Serielle Verbindung (über `pyserial-asyncio`) und TCP-Verbindung.
+*   **Umfangreiche Protokollbibliothek** – Portierung der originalen FHEM‑SIGNALDuino‑Protokolle mit `SDProtocols` und `SDProtocolData`.
+*   **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.
+*   **Komprimierte Datenübertragung** – Effiziente Payload‑Kompression für MQTT‑Nachrichten.
+
+## Installation
+
+### Voraussetzungen
+
+*   Python 3.8 oder höher
+*   pip (Python-Paketmanager)
+
+### Paketinstallation
+
+1.  Repository klonen:
+    ```bash
+    git clone https://github.com/.../PySignalduino.git
+    cd PySignalduino
+    ```
+
+2.  Abhängigkeiten installieren (empfohlen in einer virtuellen Umgebung):
+    ```bash
+    pip install -e .
+    ```
+
+    Dies installiert das Paket im Entwicklermodus inklusive aller Runtime‑Abhängigkeiten:
+    *   `pyserial`
+    *   `pyserial-asyncio`
+    *   `aiomqtt` (asynchrone MQTT‑Client‑Bibliothek)
+    *   `python-dotenv`
+    *   `requests`
+
+3.  Für Entwicklung und Tests zusätzlich:
+    ```bash
+    pip install -r requirements-dev.txt
+    ```
+
+## Schnellstart
+
+1.  **Umgebungsvariablen setzen** (optional). Erstelle eine `.env`‑Datei im Projektverzeichnis:
+    ```bash
+    SIGNALDUINO_SERIAL_PORT=/dev/ttyUSB0
+    MQTT_HOST=localhost
+    LOG_LEVEL=INFO
+    ```
+
+2.  **Programm starten**:
+    ```bash
+    python3 main.py --serial /dev/ttyUSB0 --mqtt-host localhost
+    ```
+
+    Oder nutze die Umgebungsvariablen:
+    ```bash
+    python3 main.py
+    ```
+
+3.  **Ausgabe beobachten**. Das Programm verbindet sich mit dem SIGNALDuino, initialisiert die Protokolle und beginnt mit dem Empfang. Dekodierte Nachrichten werden im Log ausgegeben und – sofern MQTT konfiguriert ist – an den Broker gesendet.
+
+## Konfiguration
+
+### Umgebungsvariablen
+
+| Variable | Beschreibung | Beispiel |
+|----------|--------------|----------|
+| `SIGNALDUINO_SERIAL_PORT` | Serieller Port (z.B. `/dev/ttyUSB0`) | `/dev/ttyACM0` |
+| `SIGNALDUINO_BAUD` | Baudrate (Standard: `57600`) | `115200` |
+| `SIGNALDUINO_TCP_HOST` | TCP‑Host (alternativ zu Serial) | `192.168.1.10` |
+| `SIGNALDUINO_TCP_PORT` | TCP‑Port (Standard: `23`) | `23` |
+| `MQTT_HOST` | MQTT‑Broker‑Host | `mqtt.eclipseprojects.io` |
+| `MQTT_PORT` | MQTT‑Broker‑Port (Standard: `1883`) | `1883` |
+| `MQTT_USERNAME` | Benutzername für MQTT‑Authentifizierung | `user` |
+| `MQTT_PASSWORD` | Passwort für MQTT‑Authentifizierung | `pass` |
+| `MQTT_TOPIC` | Basis‑Topic für Publikation/Subscription | `signalduino/` |
+| `LOG_LEVEL` | Logging‑Level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | `DEBUG` |
+
+### Kommandozeilenargumente
+
+Alle Umgebungsvariablen können auch als Argumente übergeben werden (sie haben Vorrang). Eine vollständige Liste erhält man mit:
 
-## Tests ausführen
 ```bash
-pip install -r requirements.txt
-pytest
+python3 main.py --help
+```
+
+Wichtige Optionen:
+*   `--serial PORT` – Serieller Port
+*   `--tcp HOST` – TCP‑Host
+*   `--mqtt-host HOST` – MQTT‑Broker
+*   `--mqtt-topic TOPIC` – Basis‑Topic
+*   `--timeout SECONDS` – Automatisches Beenden nach N Sekunden
+*   `--log-level LEVEL` – Logging‑Level
+
+## MQTT‑Integration
+
+### Publizierte Topics
+
+*   `{basis_topic}/decoded` – JSON‑Nachricht jedes dekodierten Signals.
+*   `{basis_topic}/raw` – Rohdaten (falls aktiviert).
+*   `{basis_topic}/status` – Statusmeldungen (Verbunden/Getrennt/Fehler).
+
+### Abonnierte Topics (Befehle)
+
+*   `{basis_topic}/cmd/version` – Liefert die Firmware‑Version des SIGNALDuino.
+*   `{basis_topic}/cmd/set` – Sendet einen `set`‑Befehl an den SIGNALDuino.
+*   `{basis_topic}/cmd/mqtt` – Steuert die MQTT‑Integration (z.B. Kompression an/aus).
+
+Die genauen Payload‑Formate und weitere Befehle sind in der [Befehlsreferenz](docs/03_protocol_reference/commands.adoc) dokumentiert.
+
+## Projektstruktur
+
+```
+PySignalduino/
+├── signalduino/              # Hauptpaket
+│   ├── controller.py         # Asynchroner Controller
+│   ├── mqtt.py               # MQTT‑Publisher/Subscriber
+│   ├── transport.py          # Serielle/TCP‑Transporte (asyncio)
+│   ├── commands.py           # Befehlsimplementierung
+│   └── ...
+├── sd_protocols/             # Protokollbibliothek (SDProtocols)
+├── tests/                    # Umfangreiche Testsuite
+├── docs/                     # Dokumentation (AsciiDoc)
+├── main.py                   # Ausführbares Hauptprogramm
+├── pyproject.toml            # Paketkonfiguration
+└── requirements*.txt         # Abhängigkeiten
+```
+
+## Entwicklung
+
+### Tests ausführen
+
+```bash
+pytest
+```
+
+Für Tests mit Coverage‑Bericht:
+
+```bash
+pytest --cov=signalduino --cov=sd_protocols
+```
+
+### Beitragen
+
+Beiträge sind willkommen! Bitte erstelle einen Pull‑Request oder öffne ein Issue im Repository.
+
+## Dokumentation
+
+*   [Installationsanleitung](docs/01_user_guide/installation.adoc)
+*   [Benutzerhandbuch](docs/01_user_guide/usage.adoc)
+*   [Asyncio‑Migrationsleitfaden](docs/ASYNCIO_MIGRATION.md)
+*   [Protokollreferenz](docs/03_protocol_reference/protocol_details.adoc)
+*   [Befehlsreferenz](docs/01_user_guide/usage.adoc#_command_interface)
+
+## Lizenz
+
+Dieses Projekt steht unter der MIT‑Lizenz – siehe [LICENSE](LICENSE) für Details.
+
+## Danksagung
+
+Basierend auf der originalen FHEM‑SIGNALDuino‑Implementierung von [@Sidey79](https://github.com/Sidey79) und der Community.