feat: Implement MQTT command interface for various commands with tests

Author: sidey79

docs/architecture/decisions/adr-001-mqtt-topic-structure.md

@@ -0,0 +1,32 @@
+# ADR 001: MQTT Topic Struktur und Versionierung
+
+## Kontext
+
+Die vorhandene MQTT-Integration in PySignalduino verfügt über eine minimale Topic-Struktur für Telemetrie, aber keine konsistente, versionierte Befehlsschnittstelle. Für die Implementierung einer konsistenten API für alle Firmware-Parameter ist eine klare Struktur und Versionierung erforderlich, um Zukunftsfähigkeit und Wartbarkeit zu gewährleisten.
+
+## Entscheidung
+
+Wir führen eine hierarchische und versionierte Topic-Struktur für Befehle, Antworten und Statusmeldungen ein.
+
+**Struktur:** `signalduino/<version>/<type>/<target>/<parameter>`
+
+**Beispiele:**
+*   **Befehle (Commands):** `signalduino/v1/commands/set/cc1101/frequency`
+*   **Antworten (Responses):** `signalduino/v1/responses/get/system/version`
+*   **Fehler (Errors):** `signalduino/v1/errors/set/cc1101/frequency`
+*   **Status (State):** `signalduino/v1/state/device/uptime`
+
+## Begründung
+
+1.  **Versionierung (`v1`):** Durch die Topic-Versionierung können wir später Breaking Changes einführen (z.B. `v2`) und ältere Clients über einen längeren Zeitraum unterstützen, ohne die gesamte Infrastruktur sofort anpassen zu müssen.
+2.  **Hierarchie (`commands`/`responses`/`errors`):** Die klare Trennung von Request- und Response-Topics vereinfacht die clientseitige Implementierung und ermöglicht eine präzise Konfiguration von MQTT-ACLs (Access Control Lists). Clients müssen nur Topics abonnieren, die für ihre Rolle relevant sind (z.B. nur `responses` und `errors`).
+3.  **Konsistenz (`get`/`set`/`command`):** Das Paradigma spiegelt die gängige Praxis in modernen APIs (REST, IoT) wider und bietet eine intuitive Steuerung für alle Firmware-Parameter.
+
+## Konsequenzen
+
+*   **Code-Änderungen:** Der MQTT-Client in PySignalduino muss so erweitert werden, dass er Befehle auf diesen spezifischen Topics abonniert und eingehende Payloads entsprechend dem `type` (`get`/`set`/`command`) an einen Command Dispatcher weiterleitet.
+*   **Kompatibilität:** Es besteht keine Abwärtskompatibilität zur bisherigen minimalen MQTT-Integration. Da diese jedoch ohnehin unstrukturiert und unvollständig war, wird dies als akzeptabler Breaking Change im Zuge der Implementierung der V1-API angesehen.
+*   **Dokumentation:** Alle Clients und die Benutzerdokumentation müssen auf diese neue Topic-Struktur umgestellt werden.
+
+---
+[Fortsetzung in ADR-002]

docs/architecture/decisions/adr-002-command-dispatcher.md

@@ -0,0 +1,32 @@
+# ADR 002: Command Dispatcher Pattern und JSON-Schema-Validierung
+
+## Kontext
+
+Die Verarbeitung eingehender MQTT-Befehle erfordert Robustheit, Skalierbarkeit und strenge Eingabeverifizierung, insbesondere da die Befehle direkt in serielle Kommandos für die Firmware übersetzt werden, was kritische Hardware-Einstellungen beeinflussen kann (z.B. CC1101-Register). Ein direktes Mapping von Topic zu Funktion ist unflexibel und anfällig für ungültige Eingaben.
+
+## Entscheidung
+
+Wir implementieren einen dedizierten **Command Dispatcher** als zentrale Komponente zwischen der MQTT-Schnittstelle und dem `SignalduinoController`. Jeder eingehende Befehl wird vor der Ausführung einer strikten **JSON-Schema-Validierung** unterzogen.
+
+**Workflow des Dispatchers:**
+1.  MQTT-Interface empfängt Payload.
+2.  Dispatcher extrahiert `command_name`, `target`, `type` und `req_id`.
+3.  Dispatcher übergibt Payload an den **Input Validator**.
+4.  Der Validator verwendet ein dem `command_name` zugeordnetes JSON-Schema, um die `value` und `parameters` zu prüfen.
+5.  Nur bei erfolgreicher Validierung wird der Befehl an den **Command Executor** weitergeleitet.
+
+## Begründung
+
+1.  **Sicherheit und Stabilität:** Die JSON-Schema-Validierung garantiert, dass nur erwartete Datenformate und Wertebereiche an den Core-Controller und letztlich an die serielle Schnittstelle gelangen. Dies verhindert Pufferüberläufe oder die Einstellung illegaler Hardware-Werte.
+2.  **Entkopplung:** Der Command Dispatcher entkoppelt die MQTT-Topics von den internen Python-Methoden. Topic-Änderungen erfordern keine Anpassung der Business-Logik.
+3.  **Flexibilität:** Das Muster ermöglicht eine einfache Erweiterung um neue Befehle und Befehls-Typen (z.B. zukünftige `batch`-Befehle) ohne Modifikation der Kernlogik.
+4.  **Strukturierte Fehlerbehandlung:** Validierungsfehler können sofort mit einem HTTP 400-ähnlichen Status (Bad Request) beantwortet werden, bevor Ressourcen für die serielle Kommunikation verschwendet werden.
+
+## Konsequenzen
+
+*   **Neue Komponenten:** Es müssen die Komponenten `Command Dispatcher` und `Input Validator` (mit Integration einer JSON-Schema-Bibliothek wie `jsonschema`) implementiert werden.
+*   **Wartungsaufwand:** Für jeden neuen Befehl muss ein entsprechendes JSON-Schema definiert und gewartet werden. Dies ist ein akzeptabler Aufwand im Austausch für erhöhte Robustheit und Sicherheit.
+*   **Abhängigkeiten:** Die externe Abhängigkeit zu einer JSON-Schema-Validierungsbibliothek wird hinzugefügt.
+
+---
+[Ende der ADRs für diese Architekturphase]

docs/architecture/proposals/mqtt_command_interface.adoc

@@ -0,0 +1,91 @@
+= Architekturproposal: Erweiterung der MQTT-Schnittstelle um Firmware-Befehle
+:revdate: 2025-12-21
+:page-layout: proposal
+:sectnums:
+:toc: left
+:toc-title: Inhalt
+
+<<<
+
+== 1. Einleitung und Zielsetzung
+
+Dieses Architekturproposal definiert die Integration von direkten Firmware-Steuerungsbefehlen (`set raw`, `set cc1101_reg`) in die `PySignalduino` MQTT-API (V1), basierend auf den etablierten Architekturentscheidungen in ADR-001 und ADR-002. Ziel ist es, die volle Funktionalität der seriellen Schnittstelle über MQTT verfügbar zu machen.
+
+== 2. Betroffene Komponenten
+
+*   `signalduino/mqtt.py`: Muss Abonnements für die neuen Command-Topics registrieren.
+*   `signalduino/controller.py`: Muss um die Logik zur Ausführung dieser Befehle erweitert werden.
+*   `Command Dispatcher` (gemäß ADR-002): Neue Routen und JSON-Schemas für die Validierung müssen hinzugefügt werden.
+
+== 3. Definition der MQTT-Kommandos
+
+Die neuen Befehle folgen der in ADR-001 definierten Struktur: `signalduino/v1/commands/set/<target>/<parameter>`. Das Payload-Format ist strikt JSON und wird durch den Command Dispatcher validiert.
+
+=== 3.1. `set raw` (Senden von rohen Firmware-Befehlen)
+
+|===
+| Thema | `signalduino/v1/commands/set/firmware/raw`
+| Payload-Format | JSON
+| Payload-Schema (Teilauszug) | Objekt mit `value` (String, z.B. C11)
+| Beispiel Payload | `{"value": "C11"}`
+| Beschreibung | Leitet den String im Feld `value` direkt als seriellen Befehl an die Firmware weiter.
+|===
+
+=== 3.2. `set cc1101_reg` (Setzen eines CC1101-Registers)
+
+Dieser Befehl ermöglicht das Setzen eines spezifischen CC1101-Registers.
+
+|===
+| Thema | `signalduino/v1/commands/set/cc1101/register`
+| Payload-Format | JSON
+| Payload-Schema (Teilauszug) | Objekt mit `address` (Hex-String, 2 Zeichen) und `value` (Hex-String, 2 Zeichen)
+| Beispiel Payload | `{"address": "0D", "value": "2E"}`
+| Beschreibung | Setzt das CC1101-Register an der Adresse `address` auf den Wert `value`. Alle Werte müssen als Hex-Strings (z.B. "0D") übergeben werden.
+|===
+
+== 4. Architekturentscheidung und Begründung
+
+Basierend auf den Anforderungen wird die folgende Entscheidung getroffen und in das Projekt-ADR-System integriert:
+
+[IMPORTANT]
+====
+**Titel:** Integration der Firmware-Steuerbefehle (`raw`, `cc1101_reg`) in die V1 MQTT-API
+
+**Kontext:** Um PySignalduino zu einem vollständigen Backend für Steuerungs-Frontends (wie FHEM) zu machen, ist es erforderlich, die direkten Steuerungsmöglichkeiten der seriellen Schnittstelle (z.B. Frequenz- und Registermanipulation) über die standardisierte MQTT-API anzubieten.
+
+**Entscheidung:**
+Die Befehle `set raw` und `set cc1101_reg` werden unter den in Abschnitt 3.1 und 3.2 definierten Topics und Payloads in die MQTT-Schnittstelle integriert. Die strikte **JSON-Schema-Validierung** wird für beide Befehle implementiert.
+
+**Begründung:**
+*   **Vollständigkeit:** Diese Befehle schließen eine kritische Lücke im Funktionsumfang der MQTT-API im Vergleich zur seriellen Schnittstelle.
+*   **Sicherheit:** Die direkte Manipulation der CC1101-Hardware erfordert höchste Sorgfalt. Die in ADR-002 beschlossene **JSON-Schema-Validierung** ist für diese Befehle zwingend erforderlich, um sicherzustellen, dass nur gültige Adressen und Werte an die Firmware gesendet werden.
+*   **Konsistenz:** Durch die Verwendung der `signalduino/v1/commands/set` Topic-Hierarchie wird die Konsistenz mit dem Rest der API gewahrt.
+
+**Konsequenzen:**
+*   Es müssen zwei neue JSON-Schemas für die Validierung erstellt werden.
+*   Der `Command Dispatcher` muss erweitert werden, um diese Befehle zu routen.
+*   Die Kernfunktionalität muss in `signalduino/controller.py` implementiert werden.
+====
+
+== 5. Compliance-Checks (Mermaid)
+
+Der erweiterte Workflow visualisiert die Verarbeitung eines CC1101-Registersatzbefehls:
+
+[mermaid, flowchart, "CC1101 Register Set Workflow"]
+----
+flowchart TD
+    A[MQTT Client sendet set cc1101_reg] --> B{Topic: signalduino/v1/commands/set/cc1101/register}
+    B --> C[MQTT Interface empfängt Payload]
+    C --> D[Command Dispatcher]
+    D --> E{Input Validator (JSON Schema)}
+    E -- Validierung fehlgeschlagen --> F[Error Response Topic publish]
+    E -- Validierung erfolgreich --> G[SignalduinoController.execute_command]
+    G --> H[Controller generiert serielle Raw-Befehle]
+    H --> I[Transport Layer sendet an Hardware]
+    I --> J{Hardware (SIGNALduino)}
+    J --> K[Hardware setzt CC1101 Register]
+----
+
+== 6. Nächste Schritte (Phase 2)
+
+Nach Genehmigung dieses Proposals folgt die Implementierungsplanung (Phase 2) mit der Erstellung der JSON-Schemas und der genauen Definition der `Controller`-Methoden.

plans/mqtt_command_interface_architecture.md

@@ -0,0 +1,64 @@
+# Architekturproposal: Erweiterung der MQTT-Schnittstelle um Firmware-Befehle
+
+**Datum:** 2025-12-21
+**Basis:** ADR-001 (Topic-Struktur), ADR-002 (Command Dispatcher)
+
+## 1. Einleitung und Zielsetzung
+
+Dieses Architekturproposal definiert die Integration von direkten Firmware-Steuerungsbefehlen (`set raw`, `set cc1101_reg`) in die `PySignalduino` MQTT-API (V1). Ziel ist es, die volle Funktionalität der seriellen Schnittstelle über MQTT verfügbar zu machen.
+
+## 2. Definition der MQTT-Kommandos
+
+Die neuen Befehle folgen der in ADR-001 definierten Struktur: `signalduino/v1/commands/set/<target>/<parameter>`. Das Payload-Format ist strikt JSON und wird durch den Command Dispatcher validiert.
+
+### 2.1. `set raw` (Senden von rohen Firmware-Befehlen)
+
+| Schlüssel | Wert |
+| :--- | :--- |
+| **Topic** | `signalduino/v1/commands/set/firmware/raw` |
+| **Payload-Format** | JSON |
+| **Payload-Schema (Teilauszug)** | Objekt mit `value` (String, z.B. C11) |
+| **Beispiel Payload** | `{"value": "C11"}` |
+| **Beschreibung** | Leitet den String im Feld `value` direkt als seriellen Befehl an die Firmware weiter. |
+
+### 2.2. `set cc1101_reg` (Setzen eines CC1101-Registers)
+
+| Schlüssel | Wert |
+| :--- | :--- |
+| **Topic** | `signalduino/v1/commands/set/cc1101/register` |
+| **Payload-Format** | JSON |
+| **Payload-Schema (Teilauszug)** | Objekt mit `address` (Hex-String, 2 Zeichen) und `value` (Hex-String, 2 Zeichen) |
+| **Beispiel Payload** | `{"address": "0D", "value": "2E"}` |
+| **Beschreibung** | Setzt das CC1101-Register an der Adresse `address` auf den Wert `value`. Alle Werte müssen als Hex-Strings (z.B. "0D") übergeben werden. |
+
+## 3. Architekturentscheidung (ADR-Auszug)
+
+> **Titel:** Integration der Firmware-Steuerbefehle (`raw`, `cc1101_reg`) in die V1 MQTT-API
+> 
+> **Kontext:** Um PySignalduino zu einem vollständigen Backend für Steuerungs-Frontends (wie FHEM) zu machen, ist es erforderlich, die direkten Steuerungsmöglichkeiten der seriellen Schnittstelle (z.B. Frequenz- und Registermanipulation) über die standardisierte MQTT-API anzubieten.
+> 
+> **Entscheidung:**
+> Die Befehle `set raw` und `set cc1101_reg` werden unter den in Abschnitt 2.1 und 2.2 definierten Topics und Payloads in die MQTT-Schnittstelle integriert. Die strikte **JSON-Schema-Validierung** wird für beide Befehle implementiert.
+> 
+> **Begründung:**
+> 1. **Vollständigkeit:** Diese Befehle schließen eine kritische Lücke im Funktionsumfang der MQTT-API im Vergleich zur seriellen Schnittstelle.
+> 2. **Sicherheit:** Die direkte Manipulation der CC1101-Hardware erfordert höchste Sorgfalt. Die in ADR-002 beschlossene JSON-Schema-Validierung ist für diese Befehle zwingend erforderlich, um sicherzustellen, dass nur gültige Adressen und Werte an die Firmware gesendet werden.
+> 3. **Konsistenz:** Durch die Verwendung der `signalduino/v1/commands/set` Topic-Hierarchie wird die Konsistenz mit dem Rest der API gewahrt.
+
+## 4. Compliance-Checks (Mermaid)
+
+Der erweiterte Workflow visualisiert die Verarbeitung eines CC1101-Registersatzbefehls.
+
+```mermaid
+flowchart TD
+    A[MQTT Client sendet set cc1101_reg] --> B{Topic: signalduino/v1/commands/set/cc1101/register}
+    B --> C[MQTT Interface empfängt Payload]
+    C --> D[Command Dispatcher]
+    D --> E{Input Validator (JSON Schema)}
+    E -- Validierung fehlgeschlagen --> F[Error Response Topic publish]
+    E -- Validierung erfolgreich --> G[SignalduinoController.execute_command]
+    G --> H[Controller generiert serielle Raw-Befehle]
+    H --> I[Transport Layer sendet an Hardware]
+    I --> J{Hardware (SIGNALduino)}
+    J --> K[Hardware setzt CC1101 Register]
+```