fix: vereinheitliche die JSON-Antwortstruktur für CC1101-Parameter und verbessere Timeout-Konstanten

Author: sidey79

.roo/mcp.json

@@ -1 +1 @@
-{"mcpServers":{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/workspaces/PySignalduino"],"alwaysAllow":["edit_file","read_text_file","search_files","read_multiple_files"]},"git":{"command":"uvx","args":["mcp-server-git","--repository","/workspaces/PySignalduino"],"alwaysAllow":["git_diff_unstaged","git_checkout"]}}}
+{"mcpServers":{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/workspaces/PySignalduino"],"alwaysAllow":["edit_file","read_text_file","search_files","read_multiple_files","create_directory","list_directory","directory_tree"]},"git":{"command":"uvx","args":["mcp-server-git","--repository","/workspaces/PySignalduino"],"alwaysAllow":["git_diff_unstaged","git_checkout"]}}}

docs/01_user_guide/mqtt_api.adoc

@@ -136,35 +136,35 @@ GET-Befehle benötigen eine leere Payload (`{}`) oder nur eine `req_id`.
 | CC1101 Konfigurationsregister-Dump als gekapselter String.
 
 | `get/cc1101/patable`
-| `"C3E = C0 C1 C2 C3 C4 C5 C6 C7"`
+| `{"pa_table_hex": "C3E = C0 C1 C2 C3 C4 C5 C6 C7"}`
 | CC1101 PA-Tabelle.
 
 | `get/cc1101/register`
-| `"C00 = 29"`
+| `{"register_value": "C00 = 29"}`
 | Liest den Wert eines einzelnen CC1101-Registers (Adresse 0x00). Der Befehl nimmt keinen Wert in der Payload entgegen und liest standardmäßig Register 0x00.
 
 | `get/cc1101/frequency`
-| `{"frequency_mhz": 868.3500}`
+| `{"frequency": 868.3500}`
 | Aktuelle RF-Frequenz in MHz.
 
 | `get/cc1101/bandwidth`
-| `102.0`
+| `{"bandwidth": 102.0}`
 | Aktuelle IF-Bandbreite in kHz.
 
 | `get/cc1101/rampl`
-| `30`
+| `{"rampl": 30}`
 | Aktuelle Empfängerverstärkung (LNA Gain) in dB. Mögliche Werte: `24, 27, 30, 33, 36, 38, 40, 42`.
 
 | `get/cc1101/sensitivity`
-| `12`
+| `{"sensitivity": 12}`
 | Aktuelle Empfindlichkeit in dB. Mögliche Werte: `4, 8, 12, 16`.
 
 | `get/cc1101/datarate`
-| `4.8`
+| `{"datarate": 4.8}`
 | Aktuelle Datenrate in kBaud.
 
 | `get/cc1101/settings`
-| `{"frequency_mhz": 868.35, "bandwidth": 102.0, "rampl": 30, "sens": 12, "datarate": 4.8}`
+| `{"frequency": 868.35, "bandwidth": 102.0, "rampl": 30, "sensitivity": 12, "datarate": 4.8}`
 | Aggregierte Abfrage aller CC1101-Haupteinstellungen.
 |===
 

docs/architecture/decisions/ADR-005-mqtt-cc1101-response-consistency.adoc

@@ -0,0 +1,49 @@
+= ADR 005: Vereinheitlichung der MQTT-Antwortstruktur für CC1101-Parameter
+:doctype: article :encoding: utf-8 :lang: de :status: Proposed :decided-at: 2026-01-07 :decided-by: Roo
+:toc: left
+
+[[kontext]]
+== Kontext
+
+Aktuell weichen die JSON-Antwortstrukturen für die Abfrage einzelner CC1101-Parameter via MQTT (z.B. Topic `get/cc1101/bandwidth`) von der Struktur der Gesamt-Abfrage (Topic `get/cc1101/settings`) ab.
+
+*   **Aktuelle Einzelabfrage (angenommen):** `get/cc1101/bandwidth` -> `{"bandwidth": "X kHz"}`
+*   **Aktuelle Gesamtabfrage (angenommen):** `get/cc1101/settings` -> `{"cc1101": {"bandwidth": "X kHz", "rampl": "Y dbm", ...}}`
+
+Diese Inkonsistenz erschwert die automatisierte Verarbeitung der Antworten, da Clients je nach Abfragetyp unterschiedliche JSON-Pfade parsen müssen. Ziel ist eine konsistente Struktur, bei der die JSON-Knotennamen für die einzelnen Parameter in beiden Abfragetypen identisch sind.
+
+[[entscheidung]]
+== Entscheidung
+
+Die JSON-Antwortstruktur für alle CC1101-Parameter-Abfragen wird vereinheitlicht. Die Schlüsselnamen der einzelnen Parameter in der JSON-Antwort werden in beiden Abfragetypen (Einzelparameter und Gesamt-Settings) identisch verwendet. Es wird entschieden, die Schlüssel der Einzelparameter ohne umschließendes Wrapper-Objekt zu verwenden.
+
+*   **Antwort auf `get/cc1101/parameter` (z.B. `get/cc1101/bandwidth`):**
+    ```json
+    {"bandwidth": "X kHz"}
+    ```
+*   **Antwort auf `get/cc1101/settings`:**
+    ```json
+    {
+      "bandwidth": "X kHz",
+      "rampl": "Y dbm",
+      "sensitivity": "Z",
+      "datarate": "A kbps"
+    }
+    ```
+Die `settings`-Antwort ist somit eine direkte Aggregation der Einzelparameter-Antworten.
+
+[[konsequenzen]]
+== Konsequenzen
+
+=== Positive Konsequenzen
+*   **Konsistenz:** Vereinfacht das Parsen für MQTT-Clients, da die logischen Parameternamen (z.B. `bandwidth`) immer als JSON-Schlüssel auf der obersten Ebene der jeweiligen Antwort verwendet werden.
+*   **Wartbarkeit:** Reduziert die Komplexität in der Implementierung, da die Logik zur Generierung der Parameterdaten wiederverwendet werden kann.
+
+=== Negative Konsequenzen
+*   **Breaking Change:** Bestehende Clients, die sich auf eine Wrapper-Struktur wie `{"cc1101": {...}}` bei der Gesamt-Abfrage (`get/cc1101/settings`) verlassen, müssen angepasst werden.
+*   **Migration:** Die Server-Logik für die MQTT-Antworten in der PySignalduino-Implementierung muss entsprechend geändert werden.
+
+[[alternativen]]
+== Alternativen
+*   **Alternative A: Wrapper in Einzelabfragen beibehalten:** Man könnte die Einzelabfrage um den CC1101-Wrapper erweitern (z.B. `get/cc1101/bandwidth` -> `{"cc1101": {"bandwidth": "X kHz"}}`). Dies wurde abgelehnt, da es unnötige Verschachtelung für Einzelwerte einführt und die Lesbarkeit des Payloads verschlechtert.
+*   **Alternative B: Einzelabfragen als reiner Wert:** Die Antwort könnte nur den reinen Wert zurückgeben (z.B. `get/cc1101/bandwidth` -> `"X kHz"`). Dies wurde abgelehnt, da es das JSON-Format verlässt und der Parametername im Payload verloren ginge, was die Eindeutigkeit erschwert.

signalduino/commands.py

@@ -8,6 +8,7 @@
 
 from jsonschema import validate, ValidationError
 from signalduino.exceptions import CommandValidationError, SignalduinoCommandTimeout
+from .constants import SDUINO_CMD_TIMEOUT
 
 if TYPE_CHECKING:
     # Importiere SignalduinoController nur für Type Hinting zur Kompilierzeit
@@ -39,11 +40,11 @@ def _parse_decoder_config(self, response: str) -> Dict[str, int]:
                     pass 
         return config
 
-    async def get_version(self, timeout: float = 2.0) -> str:
+    async def get_version(self, timeout: float = SDUINO_CMD_TIMEOUT) -> 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) -> int:
+    async def get_free_ram(self, timeout: float = SDUINO_CMD_TIMEOUT) -> int:
         """Free RAM (R)"""
         # Firmware typically responds with a numeric value (e.g., "1234")
         response_pattern = re.compile(r'^(\d+)$')
@@ -54,7 +55,7 @@ async def get_free_ram(self, timeout: float = 2.0) -> int:
             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:
+    async def get_uptime(self, timeout: float = SDUINO_CMD_TIMEOUT) -> int:
         """System uptime (t)"""
         # Firmware typically responds with a numeric value (e.g., "1234")
         response_pattern = re.compile(r'^(\d+)$')
@@ -65,17 +66,17 @@ async def get_uptime(self, timeout: float = 2.0) -> int:
             return int(match.group(1))
         raise ValueError(f"Unexpected response format for Uptime: {response}")
 
-    async def get_cmds(self, timeout: float = 2.0) -> str:
+    async def get_cmds(self, timeout: float = SDUINO_CMD_TIMEOUT) -> str:
         """Available commands (?)"""
         return await self._send_command(command="?", expect_response=True, timeout=timeout)
 
-    async def ping(self, timeout: float = 2.0) -> str:
+    async def ping(self, timeout: float = SDUINO_CMD_TIMEOUT) -> str:
         """Ping (P)"""
         return await self._send_command(command="P", expect_response=True, timeout=timeout)
 
-    async def get_config(self, timeout: float = 2.0) -> Dict[str, int]:
+    async def get_config(self, timeout: float = SDUINO_CMD_TIMEOUT) -> Dict[str, int]:
         """Decoder configuration (CG) - Returns parsed dictionary."""
-        config_pattern = re.compile(r'^MS=[01];MU=[01];MC=[01];Mred=[01](;M[A-Za-z0-9]+=[01])*$')
+        config_pattern = re.compile(r'^\s*([A-Za-z0-9]+=\d+;?)+\s*$', re.IGNORECASE)
         response = await self._send_command(
             command="CG",
             expect_response=True,
@@ -84,19 +85,20 @@ async def get_config(self, timeout: float = 2.0) -> Dict[str, int]:
         )
         return self._parse_decoder_config(response)
 
-    async def get_ccconf(self, timeout: float = 2.0) -> Dict[str, str]:
+    async def get_ccconf(self, timeout: float = SDUINO_CMD_TIMEOUT) -> 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
-        response = await self._send_command(command="C0DnF", expect_response=True, timeout=timeout, response_pattern=re.compile(r'C0Dn11\s*=\s*[a-f0-9]+', re.IGNORECASE))
+        response = await self._send_command(command="C0DnF", expect_response=True, timeout=timeout, response_pattern=re.compile(r'^\s*C0D\w*\s*=\s*.*$', re.IGNORECASE))
         # 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:
+    async def get_ccpatable(self, timeout: float = SDUINO_CMD_TIMEOUT) -> Dict[str, str]:
         """CC1101 PA table (C3E)"""
         # Response-Pattern aus 00_SIGNALduino.pm, Zeile 88
-        return await self._send_command(command="C3E", expect_response=True, timeout=timeout, response_pattern=re.compile(r'C3E\s*=\s*.*'))
+        response = await self._send_command(command="C3E", expect_response=True, timeout=timeout, response_pattern=re.compile(r'^\s*C3E\s*=\s*.*\s*$', re.IGNORECASE))
+        return {"pa_table_hex": response}
 
-    async def factory_reset(self, timeout: float = 5.0) -> Dict[str, str]:
+    async def factory_reset(self, timeout: float = SDUINO_CMD_TIMEOUT) -> Dict[str, str]:
         """Sets EEPROM defaults, effectively a factory reset (e).
 
         This command does not send a response unless debug mode is active. We treat the command
@@ -113,33 +115,35 @@ async def get_cc1101_settings(self, payload: Optional[Dict[str, Any]] = None) ->
         """
         # Alle benötigten Getter existieren bereits in SignalduinoCommands
         freq_result = await self.get_frequency(payload)
-        bandwidth = await self.get_bandwidth(payload)
-        rampl = await self.get_rampl(payload)
-        sens = await self.get_sensitivity(payload)
-        datarate = await self.get_data_rate(payload)
+        bandwidth_result = await self.get_bandwidth(payload)
+        rampl_result = await self.get_rampl(payload)
+        sens_result = await self.get_sensitivity(payload)
+        datarate_result = await self.get_data_rate(payload)
 
         return {
-            # Flatten the frequency structure
-            "frequency_mhz": freq_result["frequency_mhz"],
-            "bandwidth": bandwidth,
-            "rampl": rampl,
-            "sens": sens,
-            "datarate": datarate,
+            "frequency_mhz": freq_result["frequency"],
+            "bandwidth": bandwidth_result["bandwidth"],
+            "rampl": rampl_result["rampl"],
+            "sensitivity": sens_result["sensitivity"],
+            "datarate": datarate_result["datarate"],
         }
 
     # --- CC1101 Hardware Status GET-Methoden (Basierend auf 00_SIGNALduino.pm) ---
 
     async def _read_register_value(self, register_address: int) -> int:
         """Liest einen CC1101-Registerwert und gibt ihn als Integer zurück."""
-        response = await self.read_cc1101_register(register_address)
-        # Stellt sicher, dass wir nur den Wert nach 'C[A-Fa-f0-9]{2} = ' extrahieren
-        match = re.search(r'C[A-Fa-f0-9]{2}\s*=\s*([0-9A-Fa-f]+)', response, re.IGNORECASE)
+        response_dict = await self.read_cc1101_register(register_address)
+        response = response_dict["register_value"]
+        
+        # Stellt sicher, dass wir nur den Wert nach 'C[A-Fa-f0-9]{2}\s*=\s*([0-9A-Fa-f]+)' extrahieren
+        # Hinzufügen von \s* um die Werte herum, um Whitespace-Toleranz zu erhöhen.
+        match = re.search(r'C[A-Fa-f0-9]{2}\s*=\s*([0-9A-Fa-f]+)\s*', response, re.IGNORECASE)
         if match:
             return int(match.group(1), 16)
         # Fängt auch den Fall 'ccreg 00:' (default-Antwort) oder andere unerwartete Antworten ab
         raise ValueError(f"Unexpected response format for CC1101 register read: {response}")
 
-    async def get_bandwidth(self, payload: Optional[Dict[str, Any]] = None) -> float:
+    async def get_bandwidth(self, payload: Optional[Dict[str, Any]] = None) -> Dict[str, float]:
         """Liest die CC1101 Bandbreitenregister (MDMCFG4/0x10) und berechnet die Bandbreite in kHz."""
         r10 = await self._read_register_value(0x10) # MDMCFG4
 
@@ -150,9 +154,9 @@ async def get_bandwidth(self, payload: Optional[Dict[str, Any]] = None) -> float
         # Frequenz (FXOSC) ist 26 MHz (26000 kHz)
         bandwidth_khz = 26000.0 / (8.0 * (4.0 + mant_b) * (1 << exp_b))
 
-        return round(bandwidth_khz, 3)
+        return {"bandwidth": round(bandwidth_khz, 3)}
 
-    async def get_rampl(self, payload: Optional[Dict[str, Any]] = None) -> int:
+    async def get_rampl(self, payload: Optional[Dict[str, Any]] = None) -> Dict[str, int]:
         """Liest die CC1101 Verstärkungsregister (AGCCTRL0/0x1B) und gibt die Verstärkung in dB zurück."""
         r1b = await self._read_register_value(0x1B) # AGCCTRL0
 
@@ -164,23 +168,25 @@ async def get_rampl(self, payload: Optional[Dict[str, Any]] = None) -> int:
         index = r1b & 7
 
         if index < len(ampllist):
-            return ampllist[index]
+            rampl_db = ampllist[index]
         else:
             # Dies sollte nicht passieren, wenn die CC1101-Registerwerte korrekt sind
             logger.warning("Invalid AGC_LNA_GAIN setting found in 0x1B: %s", index)
-            return -1 # Fehlerwert
+            rampl_db = -1 # Fehlerwert
+            
+        return {"rampl": rampl_db}
 
-    async def get_sensitivity(self, payload: Optional[Dict[str, Any]] = None) -> int:
+    async def get_sensitivity(self, payload: Optional[Dict[str, Any]] = None) -> Dict[str, int]:
         """Liest die CC1101 Empfindlichkeitsregister (RSSIAGC/0x1D) und gibt die Empfindlichkeit in dB zurück."""
         r1d = await self._read_register_value(0x1D) # RSSIAGC (0x1D)
 
         # Sens (dB) = 4 + 4 * (r1d & 3)
         # Die unteren 2 Bits enthalten den LNA-Modus (LNA_PD_BUF)
         sens_db = 4 + 4 * (r1d & 3)
 
-        return sens_db
+        return {"sensitivity": sens_db}
 
-    async def get_data_rate(self, payload: Optional[Dict[str, Any]] = None) -> float:
+    async def get_data_rate(self, payload: Optional[Dict[str, Any]] = None) -> Dict[str, float]:
         """Liest die CC1101 Datenratenregister (MDMCFG4/0x10 und MDMCFG3/0x11) und berechnet die Datenrate in kBaud."""
         r10 = await self._read_register_value(0x10) # MDMCFG4
         r11 = await self._read_register_value(0x11) # MDMCFG3
@@ -201,7 +207,7 @@ async def get_data_rate(self, payload: Optional[Dict[str, Any]] = None) -> float
         # Umrechnung in kBaud (kiloBaud = kiloBits pro Sekunde)
         data_rate_kbaud = data_rate_hz / 1000.0
 
-        return round(data_rate_kbaud, 2)
+        return {"datarate": round(data_rate_kbaud, 2)}
 
     def _calculate_datarate_registers(self, datarate_kbaud: float) -> tuple[int, int]:
         """
@@ -260,11 +266,17 @@ def _calculate_datarate_registers(self, datarate_kbaud: float) -> tuple[int, int
 
         return best_drate_e, best_drate_m
 
-    async def read_cc1101_register(self, register_address: int, timeout: float = 2.0) -> str:
+    async def read_cc1101_register(self, register_address: int, timeout: float = SDUINO_CMD_TIMEOUT) -> Dict[str, str]:
         """Read CC1101 register (C<reg>)"""
         hex_addr = f"{register_address:02X}"
         # Response-Pattern: ccreg 00: oder Cxx = yy (aus 00_SIGNALduino.pm, Zeile 87)
-        return await self._send_command(command=f"C{hex_addr}", expect_response=True, timeout=timeout, response_pattern=re.compile(r'C[a-f0-9]{2}\s*=\s*[a-f0-9]+|ccreg 00:', re.IGNORECASE))
+        # Die Regex muss an den Anfang und das Ende der Zeile gebunden werden (re.match wird verwendet)
+        # ^(C[a-f0-9]{2}\s*=\s*[a-f0-9]+|ccreg 00:.*)\s*$
+        # Hinweis: *Der Controller verwendet re.match*, was implizit ^ bindet. 
+        # Wir müssen den Regex also an das Ende binden, um Leerzeichen zu erlauben.
+        response_pattern = re.compile(r'^\s*(C[a-f0-9]{2}\s*=\s*[a-f0-9]+|ccreg [a-f0-9]{2}:.*)\s*$', re.IGNORECASE)
+        response = await self._send_command(command=f"C{hex_addr}", expect_response=True, timeout=timeout, response_pattern=response_pattern)
+        return {"register_value": response}
 
     async def _get_frequency_registers(self) -> int:
         """Liest die CC1101 Frequenzregister (FREQ2, FREQ1, FREQ0) und kombiniert sie zu einem 24-Bit-Wert (F_REG)."""
@@ -276,24 +288,24 @@ async def _get_frequency_registers(self) -> int:
 
         # Funktion zum Extrahieren des Hex-Werts aus der Antwort: Cxx = <hex>
         def extract_hex_value(response: str) -> int:
-            # Stellt sicher, dass wir nur den Wert nach 'C[A-Fa-f0-9]{2} = ' extrahieren
-            match = re.search(r'C[A-Fa-f0-9]{2}\s=\s([0-9A-Fa-f]+)$', response)
+            # Stellt sicher, dass wir nur den Wert nach 'C[A-Fa-f0-9]{2}\s=\s([0-9A-Fa-f]+)$' extrahieren
+            match = re.search(r'C[A-Fa-f0-9]{2}\s*=\s*([0-9A-Fa-f]+)\s*$', response)
             if match:
                 return int(match.group(1), 16)
             # Fängt auch den Fall 'ccreg 00:' (default-Antwort) oder andere unerwartete Antworten ab
             raise ValueError(f"Unexpected response format for CC1101 register read: {response}")
 
         # FREQ2 (0D)
         response2 = await self.read_cc1101_register(FREQ2)
-        freq2 = extract_hex_value(response2)
+        freq2 = extract_hex_value(response2["register_value"])
 
         # FREQ1 (0E)
         response1 = await self.read_cc1101_register(FREQ1)
-        freq1 = extract_hex_value(response1)
+        freq1 = extract_hex_value(response1["register_value"])
 
         # FREQ0 (0F)
         response0 = await self.read_cc1101_register(FREQ0)
-        freq0 = extract_hex_value(response0)
+        freq0 = extract_hex_value(response0["register_value"])
 
         # Die Register bilden eine 24-Bit-Zahl: (FREQ2 << 16) | (FREQ1 << 8) | FREQ0
         f_reg = (freq2 << 16) | (freq1 << 8) | freq0
@@ -317,14 +329,14 @@ async def get_frequency(self, payload: Optional[Dict[str, Any]] = None) -> Dict[
 
         # Rückgabe des gekapselten und auf 4 Dezimalstellen gerundeten Wertes, wie in tests/test_mqtt.py erwartet.
         return {
-            "frequency_mhz": round(frequency_mhz, 4)
+            "frequency": round(frequency_mhz, 4)
         }
 
-    async def send_raw_message(self, command: str, timeout: float = 2.0) -> str:
+    async def send_raw_message(self, command: str, timeout: float = SDUINO_CMD_TIMEOUT) -> str:
         """Send raw message (M...)"""
         return await self._send_command(command=command, expect_response=True, timeout=timeout)
 
-    async def send_message(self, message: str, timeout: float = 2.0) -> None:
+    async def send_message(self, message: str, timeout: float = SDUINO_CMD_TIMEOUT) -> None:
         """Send a pre-encoded message (P...#R...). This is typically used for 'set raw' commands where the message is already fully formatted.
         
         NOTE: This sends the message AS IS, without any wrapping like 'set raw '.