Use Async IO instead of threads

AGENTS.md

@@ -11,4 +11,39 @@ This file provides guidance to agents when working with code in this repository.
 
 ## Verification Execution
 - Das Hauptprogramm für Verifizierungen sollte wie folgt gestartet werden:
-  `python3 main.py --timeout 1`
+  `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.

docs/01_user_guide/installation.adoc

@@ -1,25 +1,83 @@
 = Installation
 
 == Voraussetzungen
+
 * Python 3.8 oder höher
 * pip (Python Package Installer)
+* Ein SIGNALDuino-Gerät mit serieller oder TCP-Verbindung
+* Optional: Ein MQTT-Broker (z.B. Mosquitto) für die MQTT-Integration
+
+== Abhängigkeiten
+
+PySignalduino benötigt folgende Python-Pakete:
+
+* `pyserial` – Serielle Kommunikation
+* `pyserial-asyncio` – Asynchrone serielle Unterstützung
+* `aiomqtt` – Asynchroner MQTT-Client (ersetzt `paho-mqtt` in der asynchronen Version)
+* `python-dotenv` – Laden von Umgebungsvariablen aus `.env`-Dateien
+* `requests` – HTTP-Anfragen (für Firmware-Download)
 
-== Installation via pip
+Diese Abhängigkeiten werden automatisch installiert, wenn Sie das Paket mit `pip install -e .` installieren.
 
-Am einfachsten installieren Sie PySignalduino direkt aus dem Repository:
+== Installation via pip (empfohlen)
+
+Die einfachste Methode ist die Installation aus dem geklonten Repository im Entwicklermodus:
 
 [source,bash]
 ----
-git clone https://github.com/Ein-Einfaches-Beispiel/PySignalduino.git
-cd PySignalduino
-pip install -r requirements.txt
+include::../examples/bash/install_via_pip.sh[]
 ----
 
+Dadurch wird das Paket `signalduino-mqtt` in Ihrer Python-Umgebung installiert und alle Runtime-Abhängigkeiten werden erfüllt.
+
+== Alternative: Installation nur der Abhängigkeiten
+
+Falls Sie das Paket nicht installieren, sondern nur die Abhängigkeiten nutzen möchten (z.B. für Skripte im Projektverzeichnis):
+
+[source,bash]
+----
+include::../examples/bash/install_requirements.sh[]
+----
+
+Die Datei `requirements.txt` enthält die gleichen Pakete wie oben aufgelistet.
+
 == Entwicklungsumgebung einrichten
 
-Für Entwickler empfehlen wir die Installation der zusätzlichen Abhängigkeiten (z.B. für Tests):
+Für Beiträge zum Projekt oder zum Ausführen der Tests installieren Sie zusätzlich die Entwicklungsabhängigkeiten:
 
 [source,bash]
 ----
-pip install -r requirements-dev.txt
-----
+include::../examples/bash/install_dev_requirements.sh[]
+----
+
+Dies installiert:
+
+* `pytest` – Testframework
+* `pytest-mock` – Mocking-Unterstützung
+* `pytest-asyncio` – Asynchrone Testunterstützung
+* `pytest-cov` – Coverage-Berichte
+
+== Verifikation der Installation
+
+Überprüfen Sie, ob die Installation erfolgreich war, indem Sie die Hilfe des Hauptprogramms aufrufen:
+
+[source,bash]
+----
+include::../examples/bash/verify_installation.sh[]
+----
+
+Sie sollten eine Ausgabe mit allen verfügbaren Kommandozeilenoptionen sehen.
+
+== Docker / DevContainer
+
+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).
+
+== Nächste Schritte
+
+Nach der Installation können Sie:
+
+1. Die [Schnellstart-Anleitung](../index.adoc#_schnellstart) befolgen.
+2. Die [Konfiguration über Umgebungsvariablen](../usage.adoc#_konfiguration) einrichten.
+3. Die [MQTT-Integration](../usage.adoc#_mqtt_integration) testen.