Skip to content

Commit 8be04d0

Browse files
author
sidey79
committed
feat: fhem container in devcontainer environment with basic configuration
1 parent 188de18 commit 8be04d0

File tree

6 files changed

+185
-0
lines changed

6 files changed

+185
-0
lines changed

‎.devcontainer/devcontainer.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
12
// For format details, see https://aka.ms/devcontainer.json. For config options, see the
23
// README at: https://github.com/devcontainers/templates/tree/main/src/python
34
{

‎.devcontainer/docker-compose.yml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,18 @@ services:
2929
- ./mosquitto/log:/mosquitto/log
3030
command: mosquitto -c /mosquitto/config/mosquitto.conf
3131
restart: unless-stopped
32+
33+
fhem:
34+
image: ghcr.io/fhem/fhem-minimal-docker:5-bookworm
35+
container_name: fhem-dev-server
36+
ports:
37+
- '38083:8083' # Expose FHEM web interface on port 38083
38+
environment:
39+
- CONFIGTYPE=fhem_signalduino_example.cfg
40+
- FHEM_PERM_DIR=0777
41+
- FHEM_PERM_FILES=0777
42+
volumes:
43+
- ./fhem-data:/opt/fhem
44+
depends_on:
45+
- mqtt
46+
restart: unless-stopped

‎.devcontainer/fhem-data/fhem_signalduino_example.cfg‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# FHEM Configuration for PySignalduino Dev Environment
2+
#
3+
# This file is loaded by the FHEM container via CONFIGTYPE environment variable.
4+
5+
attr global logfile ./log/fhem-%Y-%m.log
6+
attr global modpath .
7+
attr global statefile ./log/fhem.save
8+
attr global verbose 3
9+
10+
# 1. Define FHEMWEB instance to access FHEM via Browser (Port 8083)
11+
define WEB FHEMWEB 8083 global
12+
attr WEB editConfig 1
13+
attr WEB stylesheetPrefix dark
14+
15+
# 2. Define Telnet for command line access (Optional)
16+
#define telnetPort telnet 7072 global
17+
18+
# 3. Basic Event Handling
19+
define eventTypes eventTypes ./log/eventTypes.txt
20+
21+
# 4. Define the MQTT Client (Broker Connection)
22+
# 'mqtt' is the hostname of the broker service in docker-compose.yml
23+
define mqtt_broker MQTT2_CLIENT mqtt:1883
24+
attr mqtt_broker autocreate simple
25+
26+
# 5. Define the SignalDuino MQTT Device
27+
define PySignalDuino MQTT2_DEVICE
28+
attr PySignalDuino IODev mqtt_broker
29+
# Map JSON payload to readings
30+
attr PySignalDuino readingList \
31+
signalduino/v1/state/messages:.* { json2nameValue($EVENT, 'MSG_',$JSONMAP) }\
32+
signalduino/v1/responses:.* { json2nameValue($EVENT, 'RESP_') }\
33+
signalduino/v1/errors:.* { json2nameValue($EVENT, 'ERR_') }
34+
# Define setter commands
35+
attr PySignalDuino setList \
36+
raw:textField signalduino/v1/commands/set/raw $EVTPART1 \
37+
cc1101_reg:textField signalduino/v1/commands/set/cc1101_reg $EVTPART1 \
38+
# System GET commands (noArg) \
39+
version:noArg signalduino/v1/commands/get/system/version \
40+
freeram:noArg signalduino/v1/commands/get/system/freeram \
41+
uptime:noArg signalduino/v1/commands/get/system/uptime \
42+
# Decoder state commands \
43+
decoder_state:noArg signalduino/v1/commands/get/config/decoder \
44+
decoder_ms_enable:noArg signalduino/v1/commands/set/config/decoder_ms_enable \
45+
decoder_ms_disable:noArg signalduino/v1/commands/set/config/decoder_ms_disable \
46+
decoder_mu_enable:noArg signalduino/v1/commands/set/config/decoder_mu_enable \
47+
decoder_mu_disable:noArg signalduino/v1/commands/set/config/decoder_mu_disable \
48+
decoder_mc_enable:noArg signalduino/v1/commands/set/config/decoder_mc_enable \
49+
decoder_mc_disable:noArg signalduino/v1/commands/set/config/decoder_mc_disable \
50+
# CC1101 GET commands (noArg) \
51+
cc_config:noArg signalduino/v1/commands/get/cc1101/config \
52+
cc_patable_get:noArg signalduino/v1/commands/get/cc1101/patable \
53+
cc_register:noArg signalduino/v1/commands/get/cc1101/register \
54+
cc_freq_get:noArg signalduino/v1/commands/get/cc1101/frequency \
55+
cc_bandwidth_get:noArg signalduino/v1/commands/get/cc1101/bandwidth \
56+
cc_rampl_get:noArg signalduino/v1/commands/get/cc1101/rampl \
57+
cc_sensitivity_get:noArg signalduino/v1/commands/get/cc1101/sensitivity \
58+
cc_datarate_get:noArg signalduino/v1/commands/get/cc1101/datarate \
59+
cc_settings_get:noArg signalduino/v1/commands/get/cc1101/settings \
60+
# CC1101 SET commands \
61+
cc_frequency_set:textField signalduino/v1/commands/set/cc1101/frequency $EVTPART1 \
62+
cc_rampl_set:select,24,27,30,33,36,38,40,42 signalduino/v1/commands/set/cc1101/rampl $EVTPART1 \
63+
cc_sensitivity_set:select,4,8,12,16 signalduino/v1/commands/set/cc1101/sensitivity $EVTPART1 \
64+
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 \
65+
cc_bandwidth_set:textField signalduino/v1/commands/set/cc1101/bandwidth $EVTPART1 \
66+
cc_datarate_set:textField signalduino/v1/commands/set/cc1101/datarate $EVTPART1 \
67+
cc_deviation_set:textField signalduino/v1/commands/set/cc1101/deviation $EVTPART1 \
68+
# Maintenance commands \
69+
factory_reset:noArg signalduino/v1/commands/set/factory_reset
70+
attr PySignalDuino stateFormat state
71+
72+
# Logfile for SignalDuino
73+
define FileLog_PySignalDuino FileLog ./log/PySignalDuino-%Y.log PySignalDuino
74+
attr FileLog_PySignalDuino logtype text
75+
define Logfile FileLog /opt/fhem/log/fhem-%Y-%m-%d.log Logfile

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,7 @@ SIGNALDuino-Firmware/
88
.devcontainer/.devcontainer.env
99
.devcontainer/mosquitto/data/
1010
.devcontainer/mosquitto/log/
11+
.devcontainer/fhem-data/*
12+
!.devcontainer/fhem-data/fhem_signalduino_example.cfg
13+
1114
.roo/mcp.json

‎docs/01_user_guide/mqtt_api.adoc‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -303,3 +303,37 @@ Dieser Befehl sendet eine vorab encodierte Nachricht an das Signalduino-Gerät,
303303
| Nein
304304
| Optionale Frequenz in MHz (`F<val>`).
305305
|===
306+
307+
[[_fhem_integration]]
308+
== FHEM Integration
309+
310+
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.
311+
312+
=== Beispielkonfiguration
313+
314+
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.
315+
316+
[source,fhem]
317+
----
318+
# 1. Verbindung zum Broker herstellen (falls noch nicht vorhanden)
319+
define mqtt_broker MQTT2_CLIENT mqtt:1883
320+
attr mqtt_broker autocreate simple
321+
322+
# 2. PySignalduino Device definieren
323+
define PySignalDuino MQTT2_DEVICE
324+
attr PySignalDuino IODev mqtt_broker
325+
326+
# 3. Readings für empfangene Nachrichten extrahieren
327+
# Wandelt JSON-Payload automatisch in Readings um
328+
attr PySignalDuino readingList signalduino/v1/state/messages:.* { json2nameValue($EVENT, '', $JSONMAP) }
329+
330+
# 4. Senden von Befehlen ermöglichen
331+
attr PySignalDuino setList raw:textField signalduino/v1/commands/set/raw $EVTPART1 \
332+
cc1101_reg:textField signalduino/v1/commands/set/cc1101_reg $EVTPART1 \
333+
version:noArg signalduino/v1/commands/get/system/version
334+
----
335+
336+
=== Wichtige Hinweise
337+
338+
* **Topics:** Stellen Sie sicher, dass das `readingList` Attribut dem in PySignalduino konfigurierten `MQTT_TOPIC` entspricht (Standard: `signalduino/v1/state/messages`).
339+
* **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‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Architekturproposal: FHEM-Integration über MQTT
2+
3+
## Zusammenfassung
4+
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.
5+
6+
## Datenfluss-Diagramm
7+
8+
```mermaid
9+
flowchart TD
10+
A[SignalDuino Hardware] -->|Seriell/TCP| B(PySignalduino Anwendung);
11+
12+
subgraph MQTT Broker (z.B. Mosquitto)
13+
M(MQTT Broker);
14+
end
15+
16+
B -->|Publish (signalduino/messages/decoded/...)| M;
17+
B <--|Subscribe (signalduino/commands/#)| M;
18+
19+
C(FHEM Server) -->|Verbindet sich mit| M;
20+
C <--|Abonniert Topics| M;
21+
C -->|Sendet Steuerbefehle| M;
22+
23+
M -->|Topic: signalduino/messages/#| D[FHEM MQTT_DEVICE Modul];
24+
D -->|Internal FHEM Logic| C;
25+
C -->|Befehle publizieren| M;
26+
M -->|Topic: signalduino/commands/#| B;
27+
28+
style B fill:#f9f,stroke:#333
29+
style C fill:#ccf,stroke:#333
30+
style M fill:#ffa,stroke:#333
31+
32+
%% Datenfluss
33+
subgraph Datenfluss
34+
direction LR
35+
S1[PySignalduino publiziert] --> S2{MQTT Broker} --> S3[FHEM abonniert];
36+
end
37+
38+
%% Befehlsfluss
39+
subgraph Befehlsfluss
40+
direction LR
41+
S4[FHEM Steuerbefehl] --> S5{MQTT Broker} --> S6[PySignalduino Subscriber];
42+
end
43+
44+
B --> Datenfluss;
45+
B <-- Befehlsfluss;
46+
C --> Datenfluss;
47+
C <-- Befehlsfluss;
48+
```
49+
50+
## Implementierungsplan (TODO-Liste)
51+
Da die PySignalduino-Implementierung bereits vorhanden ist, konzentriert sich der Implementierungsplan auf die Erstellung von Dokumentation und Beispielen.
52+
53+
[x] Architektur-Entscheidung dokumentiert: Verwendung eines externen MQTT-Brokers für FHEM-Integration
54+
[x] Devcontainer-Konfiguration geprüft und als ausreichend befunden.
55+
[-] Mermaid-Diagramm zur Visualisierung des Datenflusses (PySignalduino <-> MQTT Broker <-> FHEM) erstellt.
56+
[ ] FHEM-spezifische Konfigurationsbeispiele in `docs/01_user_guide/mqtt.adoc` ergänzen.
57+
[ ] Plan dem Benutzer zur Genehmigung vorlegen und Moduswechsel zu 'code' vorschlagen.

0 commit comments

Comments
 (0)