feat: fhem container in devcontainer environment with basic configuration

Author: sidey79

.devcontainer/devcontainer.json

@@ -1,3 +1,4 @@
+
 // 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
 {
@@ -9,17 +10,9 @@
 	// Features to add to the dev container. More info: https://containers.dev/features.
 	// "features": {},
 	"features": {
-		"ghcr.io/devcontainers/features/node:1": {
-			"nodeGypDependencies": true,
-			"installYarnUsingApt": true,
-			"version": "lts",
-			"pnpmVersion": "latest",
-			"nvmVersion": "latest"
-		},
-		"ghcr.io/devcontainer-community/devcontainer-features/astral.sh-uv:1": {
-			"shellautocompletion": true,
-			"version": "latest"
-		}
+		"ghcr.io/devcontainers/features/node:1": {},
+		"ghcr.io/devcontainer-community/devcontainer-features/astral.sh-uv:1": {},
+		"ghcr.io/braun-daniel/devcontainer-features/asciidoc:1": {}
 		//"ghcr.io/hspaans/devcontainer-features/pytest:2": {}
 	},
 	// Use 'forwardPorts' to make a list of ports inside the container available locally.

.devcontainer/docker-compose.yml

@@ -29,3 +29,18 @@ services:
        - ./mosquitto/log:/mosquitto/log
     command: mosquitto -c /mosquitto/config/mosquitto.conf
     restart: unless-stopped
+  
+  fhem:
+    image: ghcr.io/fhem/fhem-minimal-docker:5-bookworm
+    container_name: fhem-dev-server
+    ports:
+      - '38083:8083' # Expose FHEM web interface on port 38083
+    environment:
+      - CONFIGTYPE=fhem_signalduino_example.cfg
+      - FHEM_PERM_DIR=0777
+      - FHEM_PERM_FILES=0777
+    volumes:
+      - ./fhem-data:/opt/fhem
+    depends_on:
+      - mqtt
+    restart: unless-stopped

.devcontainer/fhem-data/fhem_signalduino_example.cfg

@@ -0,0 +1,86 @@
+attr global userattr cmdIcon devStateIcon:textField-long devStateStyle icon sortby webCmd webCmdLabel:textField-long widgetOverride
+attr global autosave 0
+attr global logfile log/fhem-%Y-%m-%d.log
+attr global modpath .
+attr global nofork 0
+attr global pidfilename log/fhem.pid
+attr global statefile ./log/fhem.save
+attr global updateInBackground 1
+attr global verbose 3
+# FHEM Configuration for PySignalduino Dev Environment
+#
+# This file is loaded by the FHEM container via CONFIGTYPE environment variable.
+
+
+# 1. Define FHEMWEB instance to access FHEM via Browser (Port 8083)
+define WEB FHEMWEB 8083 global
+setuuid WEB 695e9c21-f33f-c986-956a-7e26fc9adfc69728
+attr WEB editConfig 1
+attr WEB stylesheetPrefix dark
+
+# 2. Define Telnet for command line access (Optional)
+#define telnetPort telnet 7072 global
+
+# 3. Basic Event Handling
+define eventTypes eventTypes ./log/eventTypes.txt
+setuuid eventTypes 695e9c21-f33f-c986-9ac3-190c47641a98acb9
+
+# 4. Define the MQTT Client (Broker Connection)
+# 'mqtt' is the hostname of the broker service in docker-compose.yml
+define mqtt_broker MQTT2_CLIENT mqtt:1883
+setuuid mqtt_broker 695e9c21-f33f-c986-e617-d7301881c4685bc6
+attr mqtt_broker autocreate simple
+
+# 5. Define the SignalDuino MQTT Device
+define PySignalDuino MQTT2_DEVICE
+setuuid PySignalDuino 695e9c21-f33f-c986-4f81-a9f0ab37b6bcedf8
+attr PySignalDuino IODev mqtt_broker
+attr PySignalDuino readingList signalduino/v1/state/messages:.* { json2nameValue($EVENT, 'MSG_',$JSONMAP) }\
+  signalduino/v1/responses:.* { json2nameValue($EVENT, 'RESP_') }\
+  signalduino/v1/errors:.* { json2nameValue($EVENT, 'ERR_') }
+attr PySignalDuino setList raw:textField signalduino/v1/commands/set/raw $EVTPART1 \
+  cc1101_reg:textField signalduino/v1/commands/set/cc1101_reg $EVTPART1 \
+  # System GET commands (noArg) \
+  version:noArg signalduino/v1/commands/get/system/version \
+  freeram:noArg signalduino/v1/commands/get/system/freeram \
+  uptime:noArg signalduino/v1/commands/get/system/uptime \
+  # Decoder state commands \
+  decoder_state:noArg signalduino/v1/commands/get/config/decoder \
+  decoder_ms_enable:noArg signalduino/v1/commands/set/config/decoder_ms_enable \
+  decoder_ms_disable:noArg signalduino/v1/commands/set/config/decoder_ms_disable \
+  decoder_mu_enable:noArg signalduino/v1/commands/set/config/decoder_mu_enable \
+  decoder_mu_disable:noArg signalduino/v1/commands/set/config/decoder_mu_disable \
+  decoder_mc_enable:noArg signalduino/v1/commands/set/config/decoder_mc_enable \
+  decoder_mc_disable:noArg signalduino/v1/commands/set/config/decoder_mc_disable \
+  # CC1101 GET commands (noArg) \
+  cc_config:noArg signalduino/v1/commands/get/cc1101/config \
+  cc_patable_get:noArg signalduino/v1/commands/get/cc1101/patable \
+  cc_register:noArg signalduino/v1/commands/get/cc1101/register \
+  cc_freq_get:noArg signalduino/v1/commands/get/cc1101/frequency \
+  cc_bandwidth_get:noArg signalduino/v1/commands/get/cc1101/bandwidth \
+  cc_rampl_get:noArg signalduino/v1/commands/get/cc1101/rampl \
+  cc_sensitivity_get:noArg signalduino/v1/commands/get/cc1101/sensitivity \
+  cc_datarate_get:noArg signalduino/v1/commands/get/cc1101/datarate \
+  cc_settings_get:noArg signalduino/v1/commands/get/cc1101/settings \
+  cc_deviation_get:noArg signalduino/v1/commands/get/cc1101/deviation\
+  # CC1101 SET commands \
+  cc_frequency_set:textField signalduino/v1/commands/set/cc1101/frequency $EVTPART1 \
+  cc_rampl_set:select,24,27,30,33,36,38,40,42 signalduino/v1/commands/set/cc1101/rampl $EVTPART1 \
+  cc_sensitivity_set:select,4,8,12,16 signalduino/v1/commands/set/cc1101/sensitivity $EVTPART1 \
+  cc_patable_set:select,-30_dBm,-20_dBm,-15_dBm,-10_dBm,-5_dBm,0_dBm,5_dBm,7_dBm,10_dBm signalduino/v1/commands/set/cc1101/patable $EVTPART1 \
+  cc_bandwidth_set:textField signalduino/v1/commands/set/cc1101/bandwidth $EVTPART1 \
+  cc_datarate_set:textField signalduino/v1/commands/set/cc1101/datarate $EVTPART1 \
+  cc_deviation_set:textField signalduino/v1/commands/set/cc1101/deviation $EVTPART1 \
+\
+  # Maintenance commands \
+  factory_reset:noArg signalduino/v1/commands/set/factory_reset
+attr PySignalDuino stateFormat state
+# Map JSON payload to readings
+# Define setter commands
+
+# Logfile for SignalDuino
+define FileLog_PySignalDuino FileLog ./log/PySignalDuino-%Y.log PySignalDuino
+setuuid FileLog_PySignalDuino 695e9c21-f33f-c986-1981-abe9a5a366b3c989
+attr FileLog_PySignalDuino logtype text
+define Logfile FileLog /opt/fhem/log/fhem-%Y-%m-%d.log Logfile
+setuuid Logfile 695e9c21-f33f-c986-cfda-4915c3e60c145721

.gitignore

@@ -8,4 +8,7 @@ SIGNALDuino-Firmware/
 .devcontainer/.devcontainer.env
 .devcontainer/mosquitto/data/
 .devcontainer/mosquitto/log/
+.devcontainer/fhem-data/*
+!.devcontainer/fhem-data/fhem_signalduino_example.cfg
+
 .roo/mcp.json

docs/01_user_guide/mqtt_api.adoc

@@ -140,8 +140,8 @@ GET-Befehle benötigen eine leere Payload (`{}`) oder nur eine `req_id`.
 | CC1101 PA-Tabelle.
 
 | `get/cc1101/register`
-| `{"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.
+| `{"register_name": "IOCFG2", "address_hex": "00", "register_value": "C00 = 29"}`
+| Liest den Wert eines einzelnen CC1101-Registers. *Erfordert den Registernamen* im `value`-Feld der Payload (z.B. `{"value": "IOCFG2"}`).
 
 | `get/cc1101/frequency`
 | `{"frequency": 868.3500}`
@@ -303,3 +303,37 @@ Dieser Befehl sendet eine vorab encodierte Nachricht an das Signalduino-Gerät,
 | Nein
 | Optionale Frequenz in MHz (`F<val>`).
 |===
+
+[[_fhem_integration]]
+== FHEM Integration
+
+PySignalduino lässt sich nahtlos in FHEM integrieren, indem ein MQTT-Broker als Vermittler genutzt wird. Die empfohlene Methode ist die Verwendung des FHEM-Moduls `MQTT2_CLIENT` zur Verbindung mit dem Broker und `MQTT2_DEVICE` zur Repräsentation des Signalduino.
+
+=== Beispielkonfiguration
+
+Eine vollständige Beispielkonfiguration finden Sie in der Datei `.devcontainer/fhem-data/fhem_signalduino_example.cfg`. Im DevContainer wird diese Datei automatisch als FHEM-Konfiguration geladen, sodass `PySignalDuino` sofort verfügbar ist.
+
+[source,fhem]
+----
+# 1. Verbindung zum Broker herstellen (falls noch nicht vorhanden)
+define mqtt_broker MQTT2_CLIENT mqtt:1883
+attr mqtt_broker autocreate simple
+
+# 2. PySignalduino Device definieren
+define PySignalDuino MQTT2_DEVICE
+attr PySignalDuino IODev mqtt_broker
+
+# 3. Readings für empfangene Nachrichten extrahieren
+# Wandelt JSON-Payload automatisch in Readings um
+attr PySignalDuino readingList signalduino/v1/state/messages:.* { json2nameValue($EVENT, '', $JSONMAP) }
+
+# 4. Senden von Befehlen ermöglichen
+attr PySignalDuino setList raw:textField signalduino/v1/commands/set/raw $EVTPART1 \
+cc1101_reg:textField signalduino/v1/commands/set/cc1101_reg $EVTPART1 \
+version:noArg signalduino/v1/commands/get/system/version
+----
+
+=== Wichtige Hinweise
+
+*   **Topics:** Stellen Sie sicher, dass das `readingList` Attribut dem in PySignalduino konfigurierten `MQTT_TOPIC` entspricht (Standard: `signalduino/v1/state/messages`).
+*   **JSON Parsing:** Die Funktion `json2nameValue` in FHEM ist ideal, um die flachen JSON-Objekte von PySignalduino direkt in FHEM Readings umzuwandeln.

plans/fhem_mqtt_integration_plan.md

@@ -0,0 +1,57 @@
+# Architekturproposal: FHEM-Integration über MQTT
+
+## Zusammenfassung
+Die empfohlene Architektur für die Anbindung von PySignalduino an FHEM basiert auf der Nutzung eines zentralen MQTT-Brokers. PySignalduino agiert als MQTT-Publisher und Subscriber, während FHEM über das `MQTT_DEVICE` Modul die Daten von PySignalduino konsumiert und Steuerbefehle zurücksendet.
+
+## Datenfluss-Diagramm
+
+```mermaid
+flowchart TD
+    A[SignalDuino Hardware] -->|Seriell/TCP| B(PySignalduino Anwendung);
+    
+    subgraph MQTT Broker (z.B. Mosquitto)
+        M(MQTT Broker);
+    end
+    
+    B -->|Publish (signalduino/messages/decoded/...)| M;
+    B <--|Subscribe (signalduino/commands/#)| M;
+    
+    C(FHEM Server) -->|Verbindet sich mit| M;
+    C <--|Abonniert Topics| M;
+    C -->|Sendet Steuerbefehle| M;
+    
+    M -->|Topic: signalduino/messages/#| D[FHEM MQTT_DEVICE Modul];
+    D -->|Internal FHEM Logic| C;
+    C -->|Befehle publizieren| M;
+    M -->|Topic: signalduino/commands/#| B;
+    
+    style B fill:#f9f,stroke:#333
+    style C fill:#ccf,stroke:#333
+    style M fill:#ffa,stroke:#333
+    
+    %% Datenfluss
+    subgraph Datenfluss
+        direction LR
+        S1[PySignalduino publiziert] --> S2{MQTT Broker} --> S3[FHEM abonniert];
+    end
+    
+    %% Befehlsfluss
+    subgraph Befehlsfluss
+        direction LR
+        S4[FHEM Steuerbefehl] --> S5{MQTT Broker} --> S6[PySignalduino Subscriber];
+    end
+
+    B --> Datenfluss;
+    B <-- Befehlsfluss;
+    C --> Datenfluss;
+    C <-- Befehlsfluss;
+```
+
+## Implementierungsplan (TODO-Liste)
+Da die PySignalduino-Implementierung bereits vorhanden ist, konzentriert sich der Implementierungsplan auf die Erstellung von Dokumentation und Beispielen.
+
+[x] Architektur-Entscheidung dokumentiert: Verwendung eines externen MQTT-Brokers für FHEM-Integration
+[x] Devcontainer-Konfiguration geprüft und als ausreichend befunden.
+[-] Mermaid-Diagramm zur Visualisierung des Datenflusses (PySignalduino <-> MQTT Broker <-> FHEM) erstellt.
+[ ] FHEM-spezifische Konfigurationsbeispiele in `docs/01_user_guide/mqtt.adoc` ergänzen.
+[ ] Plan dem Benutzer zur Genehmigung vorlegen und Moduswechsel zu 'code' vorschlagen.

signalduino/commands.py

@@ -16,6 +16,21 @@
 
 logger = logging.getLogger(__name__)
 
+CC1101_REGISTER_MAP: Dict[str, int] = {
+    # Configuration Registers
+    "IOCFG2": 0x00, "IOCFG1": 0x01, "IOCFG0": 0x02, "FIFOTHR": 0x03, 
+    "PKTLEN": 0x06, "PKTCTRL1": 0x07, "PKTCTRL0": 0x08, "ADDR": 0x09, 
+    "CHANNR": 0x0A, "FSCTRL1": 0x0B, "FSCTRL0": 0x0C, "FREQ2": 0x0D, 
+    "FREQ1": 0x0E, "FREQ0": 0x0F, "MDMCFG4": 0x10, "MDMCFG3": 0x11, 
+    "MDMCFG2": 0x12, "MDMCFG1": 0x13, "MDMCFG0": 0x14, "DEVIATN": 0x15, 
+    "MCSM1": 0x16, "MCSM0": 0x17, "FOCCFG": 0x19, "BSCFG": 0x1A, 
+    "AGCCTRL2": 0x1B, "AGCCTRL1": 0x1C, "AGCCTRL0": 0x1D, "FSCAL3": 0x1F, 
+    "FSCAL2": 0x20, "FSCAL1": 0x21, "FSCAL0": 0x22, "FSTEST": 0x23, 
+    "PTEST": 0x25, "LTEST": 0x26, "PATABLE": 0x3E,
+    # Status Registers
+    "PARTNUM": 0x30, "VERSION": 0x31, "MARCSTATE": 0x35, "LQI": 0x38, "RSSI": 0x39
+}
+
 # --- BEREICH 1: SignalduinoCommands (Implementierung der seriellen Befehle) ---
 
 class SignalduinoCommands:
@@ -132,7 +147,7 @@ async def get_cc1101_settings(self, payload: Optional[Dict[str, Any]] = None) ->
 
     async def _read_register_value(self, register_address: int) -> int:
         """Liest einen CC1101-Registerwert und gibt ihn als Integer zurück."""
-        response_dict = await self.read_cc1101_register(register_address)
+        response_dict = await self._read_cc1101_register_by_address(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
@@ -266,18 +281,41 @@ 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 = SDUINO_CMD_TIMEOUT) -> Dict[str, str]:
-        """Read CC1101 register (C<reg>)"""
+    async def _read_cc1101_register_by_address(self, register_address: int, timeout: float = SDUINO_CMD_TIMEOUT) -> Dict[str, str]:
+        """Liest CC1101-Register über die numerische Adresse (C<reg>) und gibt die rohe Antwort zurück."""
         hex_addr = f"{register_address:02X}"
         # Response-Pattern: ccreg 00: oder Cxx = yy (aus 00_SIGNALduino.pm, Zeile 87)
-        # 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 _read_cc1101_register_by_name(self, register_name: str, timeout: float = SDUINO_CMD_TIMEOUT) -> Dict[str, Any]:
+        """Internal: Read CC1101 register by name (e.g., 'IOCFG2')."""
+        register_name = register_name.upper()
+        register_address = CC1101_REGISTER_MAP.get(register_name)
+        if register_address is None:
+            raise CommandValidationError(f"Unknown CC1101 register name: {register_name}")
+
+        response_dict = await self._read_cc1101_register_by_address(register_address, timeout)
+        
+        # Füge den Registernamen und die Adresse zur Antwort hinzu
+        response_dict["register_name"] = register_name
+        response_dict["address_hex"] = f"{register_address:02X}"
+        
+        return response_dict
+
+    async def read_cc1101_register(self, payload: Dict[str, Any], timeout: float = SDUINO_CMD_TIMEOUT) -> Dict[str, Any]:
+        """
+        MqttCommand: Reads a CC1101 register by name provided in the MQTT payload's 'value' field.
+        The name must be a key from CC1101_REGISTER_MAP.
+        """
+        register_name = payload.get("value")
+        if not register_name:
+            raise CommandValidationError("Payload for read_cc1101_register must contain 'value' with the register name.")
+            
+        # Ruft die interne Methode auf
+        return await self._read_cc1101_register_by_name(str(register_name), timeout=timeout)
+
     async def _get_frequency_registers(self) -> int:
         """Liest die CC1101 Frequenzregister (FREQ2, FREQ1, FREQ0) und kombiniert sie zu einem 24-Bit-Wert (F_REG)."""
 
@@ -296,15 +334,15 @@ def extract_hex_value(response: str) -> int:
             raise ValueError(f"Unexpected response format for CC1101 register read: {response}")
 
         # FREQ2 (0D)
-        response2 = await self.read_cc1101_register(FREQ2)
+        response2 = await self._read_cc1101_register_by_address(FREQ2)
         freq2 = extract_hex_value(response2["register_value"])
 
         # FREQ1 (0E)
-        response1 = await self.read_cc1101_register(FREQ1)
+        response1 = await self._read_cc1101_register_by_address(FREQ1)
         freq1 = extract_hex_value(response1["register_value"])
 
         # FREQ0 (0F)
-        response0 = await self.read_cc1101_register(FREQ0)
+        response0 = await self._read_cc1101_register_by_address(FREQ0)
         freq0 = extract_hex_value(response0["register_value"])
 
         # Die Register bilden eine 24-Bit-Zahl: (FREQ2 << 16) | (FREQ1 << 8) | FREQ0
@@ -524,6 +562,12 @@ def create_value_schema(value_schema: Dict[str, Any]) -> Dict[str, Any]:
     "description": "Frequency Deviation in kHz (float)."
 })
 
+CC1101_REGISTER_SCHEMA = create_value_schema({
+    "type": "string",
+    "pattern": r"^[A-Z0-9]{4,8}$", # Registername wie IOCFG2, MCSM0, etc.
+    "description": "CC1101 register name (e.g., 'IOCFG2', 'MCSM0')."
+})
+
 # --- SEND MSG SCHEMA (PHASE 2) ---
 SEND_MSG_SCHEMA = {
     "type": "object",
@@ -556,7 +600,7 @@ def create_value_schema(value_schema: Dict[str, Any]) -> Dict[str, Any]:
     '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/register': { 'method': 'read_cc1101_register', 'schema': CC1101_REGISTER_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/controller.py

@@ -166,6 +166,10 @@ async def get_cc1101_settings(self, payload: Dict[str, Any]) -> Dict[str, Any]:
         """Delegates to SignalduinoCommands to get all key CC1101 settings."""
         return await self.commands.get_cc1101_settings(payload)
 
+    async def read_cc1101_register(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Reads a specific CC1101 register value by name (e.g., 'IOCFG2')."""
+        return await self.commands.read_cc1101_register(payload, timeout=SDUINO_CMD_TIMEOUT)
+
     async def send_command(
         self,
         command: str,