feat: fix mqtt timeouts by improving response parsing for cc1101 and config commands (ADR-004)

Author: sidey79

docs/01_user_guide/mqtt_api.adoc

@@ -65,6 +65,47 @@ Eine erfolgreiche Response auf `signalduino/v1/responses` hat folgende Struktur:
 }
 ----
 
+[[_cli_tool]]
+== CLI Tool zur Steuerung (`tools/sd_mqtt_cli.py`)
+
+Das Skript `tools/sd_mqtt_cli.py` dient als einfaches Python-Kommandozeilen-Tool, um Befehle an das PySignalduino MQTT-Gateway zu senden und die Antworten zu empfangen.
+
+=== Installation und Ausführung
+
+Das Tool benötigt die `paho-mqtt` Abhängigkeit, die in der `requirements-dev.txt` enthalten ist.
+
+[source,bash]
+----
+pip install paho-mqtt
+python3 tools/sd_mqtt_cli.py --help
+----
+
+=== Verfügbare Kommandos
+
+|===
+| Kommando | Beschreibung | Beispiel
+
+| `reset`
+| Führt einen Factory Reset durch (`set/factory_reset`).
+| `python3 tools/sd_mqtt_cli.py reset`
+
+| `get all-settings`
+| Fragt alle wichtigen CC1101-Einstellungen in einer aggregierten Nachricht ab.
+| `python3 tools/sd_mqtt_cli.py get all-settings`
+
+| `get hardware-status --parameter <param>`
+| Fragt einen spezifischen CC1101-Parameter ab. Parameter: `frequency`, `bandwidth`, `rampl`, `sensitivity`, `datarate`.
+| `python3 tools/sd_mqtt_cli.py get hardware-status --parameter frequency`
+
+| `get system-status --parameter <param>`
+| **NEU:** Fragt einen spezifischen System-Parameter ab. Parameter: `version`, `freeram`, `uptime`.
+| `python3 tools/sd_mqtt_cli.py get system-status --parameter freeram`
+
+| `poll`
+| **NEU:** Fragt nacheinander alle verfügbaren System- und CC1101-Parameter ab. Nützlich zur Diagnose des aktuellen Gerätezustands.
+| `python3 tools/sd_mqtt_cli.py poll`
+|===
+
 [[_get_commands]]
 == GET Commands (Status und Konfiguration abrufen)
 
@@ -79,20 +120,20 @@ GET-Befehle benötigen eine leere Payload (`{}`) oder nur eine `req_id`.
 | Firmware-Version.
 
 | `get/system/freeram`
-| `"1234"`
-| Verfügbarer RAM-Speicher.
+| `1234`
+| Verfügbarer RAM-Speicher (`int`).
 
 | `get/system/uptime`
-| `"56789"`
-| System-Laufzeit.
+| `56789`
+| System-Laufzeit (`int`).
 
 | `get/config/decoder`
-| `"MS=1;MU=1;MC=1;MN=1"`
-| Aktuelle Decoder-Konfiguration (aktivierte Protokollfamilien).
+| `{"MS": 1, "MU": 1, "MC": 1, "MN": 1}`
+| Aktuelle Decoder-Konfiguration (aktivierte Protokollfamilien) als geparstes Dictionary.
 
 | `get/cc1101/config`
-| `"C0D11=0F"`
-| CC1101 Konfigurationsregister-Dump.
+| `{"cc1101_config_string": "C0D11=0F"}`
+| CC1101 Konfigurationsregister-Dump als gekapselter String.
 
 | `get/cc1101/patable`
 | `"C3E = C0 C1 C2 C3 C4 C5 C6 C7"`

docs/architecture/decisions/ADR-004-mqtt-response-parsing.adoc

@@ -0,0 +1,57 @@
+= ADR-004: Strukturiertes Parsing serieller Antworten für MQTT GET-Befehle
+:revdate: 2026-01-06
+:author: Roo
+
+== 1. Kontext
+
+Die MQTT-Befehle `get/cc1101/*` (z.B. `get/cc1101/config`) und `get/config/decoder` schlagen mit Timeouts fehl, obwohl die serielle Kommunikation mit der SIGNALDuino-Firmware die Antworten empfängt. Die Ursache liegt darin, dass der `MqttCommandDispatcher` eine strukturierte JSON-Payload (ein Python-Dictionary) als `data`-Feld in der MQTT-Antwort erwartet. Die zugrundeliegenden `SignalduinoCommands` Methoden geben jedoch in diesen Fällen den *rohen* String der seriellen Firmware-Antwort zurück.
+
+Der `MqttCommandDispatcher` kann diese String-Antworten nicht direkt in das JSON-Antwortformat umwandeln, was zu einem Abbruch der Verarbeitung und damit zum Timeout führt.
+
+Betroffene Befehle und ihre Rohantwortformate:
+*   `get/config/decoder` (CG): `MS=1;MU=1;MC=1;Mred=1\n`
+*   `get/cc1101/config` (C0DnF): `C0Dn11=<Hex-Wert>\n`
+
+Zusätzlich müssen alle `get` Befehle, die einen rohen String zurückgeben, angepasst werden, um die Konsistenz des MQTT-API zu gewährleisten.
+
+== 2. Entscheidung
+
+Wir werden die `SignalduinoCommands` Methoden, die serielle GET-Befehle ausführen, so modifizieren, dass sie die rohe Firmware-Antwort parsen und ein konsistentes Python-Dictionary (`Dict[str, Any]`) zurückgeben. Dieses Dictionary wird dann vom `MqttCommandDispatcher` als JSON-Payload im `data`-Feld der MQTT-Antwort verwendet.
+
+Dies stellt sicher, dass alle erfolgreichen `GET` Anfragen über MQTT eine strukturierte und maschinenlesbare JSON-Antwort erhalten und die Timeouts vermieden werden.
+
+=== Detaillierte Logik-Anpassungen
+
+1.  **`get_config` (CG):**
+    *   Wird eine private Hilfsfunktion `_parse_decoder_config(response: str) -> Dict[str, int]` in [`signalduino/commands.py`](signalduino/commands.py) implementiert.
+    *   Diese Funktion parst den `key=value;` String in ein Dictionary (z.B. `{'MS': 1, 'MU': 1, 'MC': 1, 'Mred': 1}`).
+    *   Der Rückgabetyp von `get_config` wird von `str` auf `Dict[str, int]` geändert.
+
+2.  **`get_ccconf` (C0DnF):**
+    *   Diese Methode gibt einen String wie `C0Dn11=<Hex-Wert>` zurück.
+    *   Die Methode wird angepasst, um die rohe String-Antwort in ein Dictionary zu kapseln, z.B. `{'cc1101_config_string': response_string}`.
+    *   Der Rückgabetyp von `get_ccconf` wird von `str` auf `Dict[str, str]` geändert.
+
+3.  **Weitere einfache GET-Befehle:**
+    *   Methoden wie `get_version`, `get_free_ram`, `get_uptime` geben bereits einen geparsten Wert zurück (String oder Int), der korrekt gekapselt wird. Diese Methoden bleiben unverändert, da sie bereits einen strukturierten Wert zurückgeben, der indirekt im `data`-Feld des MQTT-Payloads landet.
+
+== 3. Konsequenzen
+
+=== Positive
+*   **Behebung der Timeouts:** Die MQTT GET-Befehle für Konfigurationen werden korrekt beantwortet und die Timeouts behoben.
+*   **API-Konsistenz:** Alle MQTT `GET` Antworten liefern nun eine konsistente, JSON-serialisierbare Struktur.
+*   **Wartbarkeit:** Der Code wird robuster, da das Parsing der seriellen Antwort in der `commands.py`-Schicht zentralisiert ist.
+
+=== Negative
+*   **Refactoring:** Es müssen kleinere Refactorings in [`signalduino/commands.py`](signalduino/commands.py) durchgeführt werden, um die Rückgabetypen der Methoden anzupassen.
+*   **Tests/Dokumentation:** Die zugehörigen Unittests in [`tests/test_mqtt_commands.py`](tests/test_mqtt_commands.py) und die MQTT API Dokumentation in [`docs/01_user_guide/mqtt_api.adoc`](docs/01_user_guide/mqtt_api.adoc) müssen aktualisiert werden.
+
+== 4. Alternativen
+
+1.  **Alternative 1: Parsing im `MqttCommandDispatcher`:** Die Rohergebnisse als `str` beibehalten und das Parsen spezifischer Befehlsantworten direkt im `MqttCommandDispatcher` durchführen.
+    *   *Nachteil:* Vermischt die Zuständigkeiten. Der Dispatcher sollte nur das Routing und die Validierung übernehmen, während die `SignalduinoCommands` die Logik für die Kommunikation und das Parsen der Firmware-spezifischen Antworten enthalten sollten.
+    *   *Abgelehnt* wegen schlechter Architektur und Verstoß gegen das Single Responsibility Principle.
+
+2.  **Alternative 2: Globaler, einfacher String-Wrapper im Dispatcher:** Jede String-Antwort global in ein einfaches Dictionary wie `{'response': <String>}` verpacken.
+    *   *Nachteil:* Führt zu einer inkonsistenten API, da einige Befehle (wie `get/config/decoder`) semantisch reiche, parsbare Daten liefern, die als roher String versteckt wären.
+    *   *Abgelehnt* zugunsten einer semantisch korrekten, strukturierten Antwort.

signalduino/commands.py

@@ -24,17 +24,46 @@ def __init__(self, send_command: Callable[..., Awaitable[Any]], mqtt_topic_root:
         self._send_command = send_command
         self.mqtt_topic_root = mqtt_topic_root
 
+    def _parse_decoder_config(self, response: str) -> Dict[str, int]:
+        """Parses the 'MS=1;MU=1;MC=1;Mred=1' firmware response into a dictionary of integers."""
+        config: Dict[str, int] = {}
+        for item in response.strip().split(';'):
+            if '=' in item:
+                key, val = item.split('=', 1)
+                try:
+                    # Wir gehen davon aus, dass die Werte boolesch (0 oder 1) sind.
+                    config[key.strip()] = int(val.strip())
+                except ValueError:
+                    logger.warning("Could not parse decoder config value '%s' for key '%s' as integer.", val, key)
+                    # Falls Parsing fehlschlägt, ignorieren wir den Wert, um Typkonsistenz zu wahren.
+                    pass 
+        return config
+        
     async def get_version(self, timeout: float = 2.0) -> str:
         """Firmware version (V)"""
         return await self._send_command(command="V", expect_response=True, timeout=timeout)
 
-    async def get_free_ram(self, timeout: float = 2.0) -> str:
+    async def get_free_ram(self, timeout: float = 2.0) -> int:
         """Free RAM (R)"""
-        return await self._send_command(command="R", expect_response=True, timeout=timeout)
+        # Firmware typically responds with a numeric value (e.g., "1234")
+        response_pattern = re.compile(r'^(\d+)$')
+        response = await self._send_command(command="R", expect_response=True, timeout=timeout, response_pattern=response_pattern)
 
-    async def get_uptime(self, timeout: float = 2.0) -> str:
+        match = response_pattern.match(response.strip())
+        if match:
+            return int(match.group(1))
+        raise ValueError(f"Unexpected response format for Free RAM: {response}")
+
+    async def get_uptime(self, timeout: float = 2.0) -> int:
         """System uptime (t)"""
-        return await self._send_command(command="t", expect_response=True, timeout=timeout)
+        # Firmware typically responds with a numeric value (e.g., "1234")
+        response_pattern = re.compile(r'^(\d+)$')
+        response = await self._send_command(command="t", expect_response=True, timeout=timeout, response_pattern=response_pattern)
+        
+        match = response_pattern.match(response.strip())
+        if match:
+            return int(match.group(1))
+        raise ValueError(f"Unexpected response format for Uptime: {response}")
 
     async def get_cmds(self, timeout: float = 2.0) -> str:
         """Available commands (?)"""
@@ -44,15 +73,18 @@ async def ping(self, timeout: float = 2.0) -> str:
         """Ping (P)"""
         return await self._send_command(command="P", expect_response=True, timeout=timeout)
 
-    async def get_config(self, timeout: float = 2.0) -> str:
-        """Decoder configuration (CG)"""
-        return await self._send_command(command="CG", expect_response=True, timeout=timeout)
+    async def get_config(self, timeout: float = 2.0) -> Dict[str, int]:
+        """Decoder configuration (CG) - Returns parsed dictionary."""
+        response = await self._send_command(command="CG", expect_response=True, timeout=timeout)
+        return self._parse_decoder_config(response)
 
-    async def get_ccconf(self, timeout: float = 2.0) -> str:
-        """CC1101 configuration registers (C0DnF)"""
+    async def get_ccconf(self, timeout: float = 2.0) -> Dict[str, str]:
+        """CC1101 configuration registers (C0DnF). Returns a dictionary with the raw string."""
         # Response-Pattern aus 00_SIGNALduino.pm, Zeile 86, angepasst an Python regex
-        return await self._send_command(command="C0DnF", expect_response=True, timeout=timeout, response_pattern=re.compile(r'C0Dn11=[A-F0-9a-f]+'))
-    
+        response = await self._send_command(command="C0DnF", expect_response=True, timeout=timeout, response_pattern=re.compile(r'C0Dn11=[A-F0-9a-f]+'))
+        # Kapselt den rohen String, um die MQTT-Antwort konsistent als Dict zurückzugeben
+        return {"cc1101_config_string": response}
+        
     async def get_ccpatable(self, timeout: float = 2.0) -> str:
         """CC1101 PA table (C3E)"""
         # Response-Pattern aus 00_SIGNALduino.pm, Zeile 88
@@ -501,12 +533,12 @@ def create_value_schema(value_schema: Dict[str, Any]) -> Dict[str, Any]:
 COMMAND_MAP: Dict[str, Dict[str, Any]] = {
     # Phase 1: Einfache GET-Befehle (Core)
     'get/system/version': { 'method': 'get_version', 'schema': BASE_SCHEMA, 'description': 'Firmware version (V)' },
-    'get/system/freeram': { 'method': 'get_freeram', 'schema': BASE_SCHEMA, 'description': 'Free RAM (R)' },
+    'get/system/freeram': { 'method': 'get_free_ram', 'schema': BASE_SCHEMA, 'description': 'Free RAM (R)' },
     'get/system/uptime': { 'method': 'get_uptime', 'schema': BASE_SCHEMA, 'description': 'System uptime (t)' },
-    'get/config/decoder': { 'method': 'get_config_decoder', 'schema': BASE_SCHEMA, 'description': 'Decoder configuration (CG)' },
-    'get/cc1101/config': { 'method': 'get_cc1101_config', 'schema': BASE_SCHEMA, 'description': 'CC1101 configuration registers (C0DnF)' },
-    'get/cc1101/patable': { 'method': 'get_cc1101_patable', 'schema': BASE_SCHEMA, 'description': 'CC1101 PA table (C3E)' },
-    'get/cc1101/register': { 'method': 'get_cc1101_register', 'schema': BASE_SCHEMA, 'description': 'Read CC1101 register (C<reg>)' },
+    'get/config/decoder': { 'method': 'get_config', 'schema': BASE_SCHEMA, 'description': 'Decoder configuration (CG)' },
+    'get/cc1101/config': { 'method': 'get_ccconf', 'schema': BASE_SCHEMA, 'description': 'CC1101 configuration registers (C0DnF)' },
+    'get/cc1101/patable': { 'method': 'get_ccpatable', 'schema': BASE_SCHEMA, 'description': 'CC1101 PA table (C3E)' },
+    'get/cc1101/register': { 'method': 'read_cc1101_register', 'schema': BASE_SCHEMA, 'description': 'Read CC1101 register (C<reg>)' },
     'get/cc1101/frequency': { 'method': 'get_frequency', 'schema': BASE_SCHEMA, 'description': 'CC1101 current RF frequency' },
     'get/cc1101/settings': { 'method': 'get_cc1101_settings', 'schema': BASE_SCHEMA, 'description': 'CC1101 key configuration settings (freq, bw, rampl, sens, dr)' },
 

signalduino/constants.py

@@ -4,7 +4,7 @@
 SDUINO_INIT_WAIT_XQ = 1.5
 SDUINO_INIT_WAIT = 2.0
 SDUINO_INIT_MAXRETRY = 3
-SDUINO_CMD_TIMEOUT = 10.0
+SDUINO_CMD_TIMEOUT = 15.0
 SDUINO_KEEPALIVE_TIMEOUT = 60
 SDUINO_KEEPALIVE_MAXRETRY = 3
 SDUINO_WRITEQUEUE_NEXT = 0.3

signalduino/controller.py

@@ -89,12 +89,32 @@ async def get_version(self, payload: Dict[str, Any]) -> str:
         # commands.get_version ist eine asynchrone Methode in SignalduinoCommands, die 'V' sendet.
         return await self.commands.get_version()
 
+    async def get_free_ram(self, payload: Dict[str, Any]) -> int:
+        """Delegates to SignalduinoCommands to get the free RAM (R)."""
+        return await self.commands.get_free_ram()
+
+    async def get_uptime(self, payload: Dict[str, Any]) -> int:
+        """Delegates to SignalduinoCommands to get the system uptime (t)."""
+        return await self.commands.get_uptime()
+
+    async def get_config(self, payload: Dict[str, Any]) -> Dict[str, int]:
+        """Delegates to SignalduinoCommands to get the decoder configuration (CG)."""
+        return await self.commands.get_config()
+        
+    async def get_ccconf(self, payload: Dict[str, Any]) -> Dict[str, str]:
+        """Delegates to SignalduinoCommands to get the CC1101 config registers (C0DnF)."""
+        return await self.commands.get_ccconf()
+
+    async def get_ccpatable(self, payload: Dict[str, Any]) -> str:
+        """Delegates to SignalduinoCommands to get the CC1101 PA table (C3E)."""
+        return await self.commands.get_ccpatable()
+
     async def get_frequency(self, payload: Dict[str, Any]) -> Dict[str, Any]:
         """Delegates to SignalduinoCommands to get the current CC1101 frequency."""
         # Der Payload wird vom MqttCommandDispatcher übergeben, aber von commands.get_frequency ignoriert.
         return await self.commands.get_frequency(payload)
 
-    async def factory_reset(self, payload: Dict[str, Any]) -> str:
+    async def factory_reset(self, payload: Dict[str, Any]) -> Dict[str, str]:
         """Delegates to SignalduinoCommands to execute a factory reset (e)."""
         # Payload wird zur Validierung akzeptiert, aber ignoriert.
         return await self.commands.factory_reset()