Skip to content

Commit bbbca53

Browse files
sidey79sidey79
authored
Merge pull request #3 from RFD-FHEM/codespace-redesigned-doodle-vjjx9wgjr4c5p5
Minimal viable Product
2 parents c912ad0 + 1fb773b commit bbbca53

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

68 files changed

+6307
-517
lines changed

‎.devcontainer/.devcontainer.env.sample‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# MQTT Broker Konfiguration
2+
# Die Adresse des MQTT Brokers (z.B. Mosquitto).
3+
MQTT_HOST=localhost
4+
5+
# Der Port des MQTT Brokers (Standard: 1883).
6+
MQTT_PORT=1883
7+
8+
# Der Benutzername für die Authentifizierung am MQTT Broker.
9+
# Optional: Leer lassen, wenn keine Authentifizierung erforderlich ist.
10+
MQTT_USERNAME=
11+
12+
# Das Passwort für die Authentifizierung am MQTT Broker.
13+
# Optional: Leer lassen, wenn keine Authentifizierung erforderlich ist.
14+
MQTT_PASSWORD=
15+
16+
# Das Basis-Topic für Signalduino Nachrichten.
17+
# Nachrichten werden unter $MQTT_TOPIC/<protokoll_id> veröffentlicht.
18+
# Befehle werden unter $MQTT_TOPIC/commands/# erwartet.
19+
MQTT_TOPIC=signalduino/messages
20+
21+
# Signalduino Verbindungseinstellungen (für direkte Verwendung in main.py)
22+
# Wähle entweder eine serielle Verbindung ODER eine TCP-Verbindung.
23+
24+
# Serieller Port für die Verbindung zum Signalduino (z.B. /dev/ttyUSB0).
25+
# Wird verwendet, wenn das Skript mit --serial gestartet wird oder um Standardwerte zu setzen.
26+
SIGNALDUINO_SERIAL_PORT=/dev/ttyUSB0
27+
28+
# Baudrate für die serielle Verbindung (Standard: 57600).
29+
SIGNALDUINO_BAUD=57600
30+
31+
# TCP Host für die Verbindung zum Signalduino über Netzwerk (z.B. ESP-Link).
32+
# Wird verwendet, wenn das Skript mit --tcp gestartet wird.
33+
SIGNALDUINO_TCP_HOST=192.168.1.10
34+
35+
# TCP Port für die Verbindung zum Signalduino (Standard: 23).
36+
SIGNALDUINO_TCP_PORT=23
37+
38+
# Logging Level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
39+
# Steuert die Ausführlichkeit der Log-Ausgaben.
40+
LOG_LEVEL=INFO

‎.devcontainer/devcontainer.json‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
// For format details, see https://aka.ms/devcontainer.json. For config options, see the
2+
// README at: https://github.com/devcontainers/templates/tree/main/src/python
3+
{
4+
"name": "Python 3",
5+
// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
6+
"image": "mcr.microsoft.com/devcontainers/python:2-3-bookworm",
7+
"features": {
8+
//"ghcr.io/hspaans/devcontainer-features/pytest:2": {}
9+
},
10+
11+
// Features to add to the dev container. More info: https://containers.dev/features.
12+
// "features": {},
13+
14+
// Use 'forwardPorts' to make a list of ports inside the container available locally.
15+
// "forwardPorts": [],
16+
17+
// Use 'postCreateCommand' to run commands after the container is created.
18+
"postCreateCommand": "pip3 install --user -r requirements-dev.txt -r requirements.txt || exit 0",
19+
"customizations": {
20+
"vscode": {
21+
"extensions": [
22+
"RooVeterinaryInc.roo-cline"
23+
]
24+
}
25+
},
26+
"runArgs": ["--env-file", ".devcontainer/devcontainer.env"]
27+
28+
// Configure tool-specific properties.
29+
// "customizations": {},
30+
31+
// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
32+
// "remoteUser": "root"
33+
}

‎.github/workflows/test-pr.yml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,7 @@ jobs:
1919
- name: Install dependencies
2020
run: |
2121
python -m pip install --upgrade pip
22-
pip install -r requirements.txt
23-
pip install pytest-cov
22+
pip install -r requirements.txt -r requirements-dev.txt
2423
2524
- name: Run tests with coverage
2625
run: |

‎.gitignore‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
pycache/
22
*.pyc
33
.venv/
4-
.env/
4+
.env/
5+
temp_repo/
6+
SIGNALDuino-Firmware/
7+
.devcontainer/devcontainer.env
8+
.devcontainer/.devcontainer.env

‎.vscode/settings.json‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,5 +40,10 @@
4040
}
4141
}
4242
]
43-
}
43+
},
44+
"python.testing.pytestArgs": [
45+
"tests"
46+
],
47+
"python.testing.unittestEnabled": false,
48+
"python.testing.pytestEnabled": true
4449
}

‎.vscode/tasks.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
// See https://go.microsoft.com/fwlink/?LinkId=733558
3+
// for the documentation about the tasks.json format
4+
"version": "2.0.0",
5+
"tasks": [
6+
{
7+
"label": "run main program",
8+
"type": "shell",
9+
"command": "python3 main.py",
10+
"problemMatcher": []
11+
}
12+
]
13+
}

‎AGENTS.md‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,43 @@ This file provides guidance to agents when working with code in this repository.
77
- **TFA Protocol Gotcha:** `mcBit2TFA` implements duplicate message detection by chunking the *entire* received bitstream, not just the expected message length.
88
- **Grothe Constraint:** `mcBit2Grothe` enforces an *exact* 32-bit length, overriding general length checks.
99
- **Test Mocking:** MC Parser tests mock `mock_protocols.demodulate` to simulate the output of the protocol layer, not `demodulate_mc` directly.
10-
- **Bit Conversion:** `_convert_mc_hex_to_bits` handles `polarity_invert` and firmware version toggling for polarity.
10+
- **Bit Conversion:** `_convert_mc_hex_to_bits` handles `polarity_invert` and firmware version toggling for polarity.
11+
12+
## Verification Execution
13+
- Das Hauptprogramm für Verifizierungen sollte wie folgt gestartet werden:
14+
`python3 main.py --timeout 1`
15+
16+
## Mandatory Documentation and Test Maintenance
17+
18+
Diese Richtlinie gilt für alle AI-Agenten, die Code oder Systemkonfigurationen in diesem Repository ändern. Jede Änderung **muss** eine vollständige Analyse der Auswirkungen auf die zugehörige Dokumentation und die Testsuite umfassen.
19+
20+
### 1. Dokumentationspflicht
21+
- **Synchronisierung:** Die Dokumentation muss synchron zu allen vorgenommenen Änderungen aktualisiert werden, um deren Genauigkeit und Vollständigkeit sicherzustellen.
22+
- **Bereiche:** Betroffene Dokumentationsbereiche umfassen:
23+
- `docs/`‑Verzeichnis (AsciiDoc‑Dateien)
24+
- Inline‑Kommentare und Docstrings
25+
- README.md und andere Markdown‑Dateien
26+
- API‑Referenzen und Benutzerhandbücher
27+
- **Prüfung:** Vor dem Abschluss einer Änderung ist zu verifizieren, dass alle dokumentationsrelevanten Aspekte berücksichtigt wurden.
28+
29+
### 2. Test‑Pflicht
30+
- **Bestehende Tests:** Die bestehenden Tests sind zu überprüfen und anzupassen, um die geänderten Funktionalitäten korrekt abzudecken.
31+
- **Neue Tests:** Bei Bedarf sind neue Tests zu erstellen, um eine vollständige Testabdeckung der neuen oder modifizierten Logik zu gewährleisten.
32+
- **Test‑Verzeichnis:** Alle Tests befinden sich im `tests/`‑Verzeichnis und müssen nach der Änderung weiterhin erfolgreich ausführbar sein.
33+
- **Test‑Ausführung:** Vor dem Commit ist die Testsuite mit `pytest` (oder dem projektspezifischen Testrunner) auszuführen, um Regressionen auszuschließen.
34+
35+
### 3. Verbindlichkeit
36+
- Diese Praxis ist für **jede** Änderung verbindlich und nicht verhandelbar.
37+
- Ein Commit, der die Dokumentation oder Tests nicht entsprechend anpasst, ist unzulässig.
38+
- Agenten müssen sicherstellen, dass ihre Änderungen den etablierten Qualitätsstandards des Projekts entsprechen.
39+
40+
### 4. Checkliste vor dem Commit
41+
- [ ] Dokumentation im `docs/`‑Verzeichnis aktualisiert
42+
- [ ] Inline‑Kommentare und Docstrings angepasst
43+
- [ ] README.md und andere Markdown‑Dateien geprüft
44+
- [ ] Bestehende Tests angepasst und erfolgreich ausgeführt
45+
- [ ] Neue Tests für geänderte/neue Logik erstellt
46+
- [ ] Gesamte Testsuite (`pytest`) ohne Fehler durchgelaufen
47+
- [ ] Änderungen mit den Projekt‑Konventionen konsistent
48+
49+
Diese Richtlinie gewährleistet, dass Code‑Änderungen nicht isoliert, sondern im Kontext des gesamten Projekts betrachtet werden und die langfristige Wartbarkeit sowie die Zuverlässigkeit der Software erhalten bleibt.

‎README.md‎

Lines changed: 163 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,167 @@
1-
# SignalDuino MQTT Bridge
1+
# PySignalduino – Asynchrone MQTT-Bridge für SIGNALDuino
22

3-
Dieses Projekt ist eine Python-Portierung der SIGNALDuino-Protokolle aus FHEM.
4-
Es stellt die Protokolle als Dictionary bereit und bietet eine objektorientierte
5-
Schnittstelle (`SDProtocols`).
3+
Dieses Projekt ist eine moderne Python-Implementierung der SIGNALDuino-Protokolle mit vollständiger **asyncio**-Unterstützung und integrierter **MQTT-Bridge**. Es ermöglicht die Kommunikation mit SIGNALDuino-Hardware (über serielle Schnittstelle oder TCP) und veröffentlicht empfangene Signale sowie empfängt Steuerbefehle über MQTT.
64

7-
## Struktur
8-
- `sd_protocols/` – Kernmodule
9-
- `examples/` – Demo-Skripte
10-
- `tests/` – Unit-Tests mit pytest
5+
## Hauptmerkmale
6+
7+
* **Vollständig asynchron** – Basierend auf `asyncio` für hohe Performance und einfache Integration in asynchrone Anwendungen.
8+
* **MQTT-Integration** – Automatisches Publizieren dekodierter Nachrichten in konfigurierbare Topics und Empfang von Steuerbefehlen (z.B. `version`, `set`, `mqtt`).
9+
* **Unterstützte Transporte** – Serielle Verbindung (über `pyserial-asyncio`) und TCP-Verbindung.
10+
* **Umfangreiche Protokollbibliothek** – Portierung der originalen FHEM‑SIGNALDuino‑Protokolle mit `SDProtocols` und `SDProtocolData`.
11+
* **Konfiguration über Umgebungsvariablen** – Einfache Einrichtung ohne Codeänderungen.
12+
* **Ausführbares Hauptprogramm** – `main.py` bietet eine sofort einsatzbereite Lösung mit Logging, Signalbehandlung und Timeout‑Steuerung.
13+
* **Komprimierte Datenübertragung** – Effiziente Payload‑Kompression für MQTT‑Nachrichten.
14+
15+
## Installation
16+
17+
### Voraussetzungen
18+
19+
* Python 3.8 oder höher
20+
* pip (Python-Paketmanager)
21+
22+
### Paketinstallation
23+
24+
1. Repository klonen:
25+
```bash
26+
git clone https://github.com/.../PySignalduino.git
27+
cd PySignalduino
28+
```
29+
30+
2. Abhängigkeiten installieren (empfohlen in einer virtuellen Umgebung):
31+
```bash
32+
pip install -e .
33+
```
34+
35+
Dies installiert das Paket im Entwicklermodus inklusive aller Runtime‑Abhängigkeiten:
36+
* `pyserial`
37+
* `pyserial-asyncio`
38+
* `aiomqtt` (asynchrone MQTT‑Client‑Bibliothek)
39+
* `python-dotenv`
40+
* `requests`
41+
42+
3. Für Entwicklung und Tests zusätzlich:
43+
```bash
44+
pip install -r requirements-dev.txt
45+
```
46+
47+
## Schnellstart
48+
49+
1. **Umgebungsvariablen setzen** (optional). Erstelle eine `.env`‑Datei im Projektverzeichnis:
50+
```bash
51+
SIGNALDUINO_SERIAL_PORT=/dev/ttyUSB0
52+
MQTT_HOST=localhost
53+
LOG_LEVEL=INFO
54+
```
55+
56+
2. **Programm starten**:
57+
```bash
58+
python3 main.py --serial /dev/ttyUSB0 --mqtt-host localhost
59+
```
60+
61+
Oder nutze die Umgebungsvariablen:
62+
```bash
63+
python3 main.py
64+
```
65+
66+
3. **Ausgabe beobachten**. Das Programm verbindet sich mit dem SIGNALDuino, initialisiert die Protokolle und beginnt mit dem Empfang. Dekodierte Nachrichten werden im Log ausgegeben und – sofern MQTT konfiguriert ist – an den Broker gesendet.
67+
68+
## Konfiguration
69+
70+
### Umgebungsvariablen
71+
72+
| Variable | Beschreibung | Beispiel |
73+
|----------|--------------|----------|
74+
| `SIGNALDUINO_SERIAL_PORT` | Serieller Port (z.B. `/dev/ttyUSB0`) | `/dev/ttyACM0` |
75+
| `SIGNALDUINO_BAUD` | Baudrate (Standard: `57600`) | `115200` |
76+
| `SIGNALDUINO_TCP_HOST` | TCP‑Host (alternativ zu Serial) | `192.168.1.10` |
77+
| `SIGNALDUINO_TCP_PORT` | TCP‑Port (Standard: `23`) | `23` |
78+
| `MQTT_HOST` | MQTT‑Broker‑Host | `mqtt.eclipseprojects.io` |
79+
| `MQTT_PORT` | MQTT‑Broker‑Port (Standard: `1883`) | `1883` |
80+
| `MQTT_USERNAME` | Benutzername für MQTT‑Authentifizierung | `user` |
81+
| `MQTT_PASSWORD` | Passwort für MQTT‑Authentifizierung | `pass` |
82+
| `MQTT_TOPIC` | Basis‑Topic für Publikation/Subscription | `signalduino/` |
83+
| `LOG_LEVEL` | Logging‑Level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | `DEBUG` |
84+
85+
### Kommandozeilenargumente
86+
87+
Alle Umgebungsvariablen können auch als Argumente übergeben werden (sie haben Vorrang). Eine vollständige Liste erhält man mit:
1188

12-
## Tests ausführen
1389
```bash
14-
pip install -r requirements.txt
15-
pytest
90+
python3 main.py --help
91+
```
92+
93+
Wichtige Optionen:
94+
* `--serial PORT` – Serieller Port
95+
* `--tcp HOST` – TCP‑Host
96+
* `--mqtt-host HOST` – MQTT‑Broker
97+
* `--mqtt-topic TOPIC` – Basis‑Topic
98+
* `--timeout SECONDS` – Automatisches Beenden nach N Sekunden
99+
* `--log-level LEVEL` – Logging‑Level
100+
101+
## MQTT‑Integration
102+
103+
### Publizierte Topics
104+
105+
* `{basis_topic}/decoded` – JSON‑Nachricht jedes dekodierten Signals.
106+
* `{basis_topic}/raw` – Rohdaten (falls aktiviert).
107+
* `{basis_topic}/status` – Statusmeldungen (Verbunden/Getrennt/Fehler).
108+
109+
### Abonnierte Topics (Befehle)
110+
111+
* `{basis_topic}/cmd/version` – Liefert die Firmware‑Version des SIGNALDuino.
112+
* `{basis_topic}/cmd/set` – Sendet einen `set`‑Befehl an den SIGNALDuino.
113+
* `{basis_topic}/cmd/mqtt` – Steuert die MQTT‑Integration (z.B. Kompression an/aus).
114+
115+
Die genauen Payload‑Formate und weitere Befehle sind in der [Befehlsreferenz](docs/03_protocol_reference/commands.adoc) dokumentiert.
116+
117+
## Projektstruktur
118+
119+
```
120+
PySignalduino/
121+
├── signalduino/ # Hauptpaket
122+
│ ├── controller.py # Asynchroner Controller
123+
│ ├── mqtt.py # MQTT‑Publisher/Subscriber
124+
│ ├── transport.py # Serielle/TCP‑Transporte (asyncio)
125+
│ ├── commands.py # Befehlsimplementierung
126+
│ └── ...
127+
├── sd_protocols/ # Protokollbibliothek (SDProtocols)
128+
├── tests/ # Umfangreiche Testsuite
129+
├── docs/ # Dokumentation (AsciiDoc)
130+
├── main.py # Ausführbares Hauptprogramm
131+
├── pyproject.toml # Paketkonfiguration
132+
└── requirements*.txt # Abhängigkeiten
133+
```
134+
135+
## Entwicklung
136+
137+
### Tests ausführen
138+
139+
```bash
140+
pytest
141+
```
142+
143+
Für Tests mit Coverage‑Bericht:
144+
145+
```bash
146+
pytest --cov=signalduino --cov=sd_protocols
147+
```
148+
149+
### Beitragen
150+
151+
Beiträge sind willkommen! Bitte erstelle einen Pull‑Request oder öffne ein Issue im Repository.
152+
153+
## Dokumentation
154+
155+
* [Installationsanleitung](docs/01_user_guide/installation.adoc)
156+
* [Benutzerhandbuch](docs/01_user_guide/usage.adoc)
157+
* [Asyncio‑Migrationsleitfaden](docs/ASYNCIO_MIGRATION.md)
158+
* [Protokollreferenz](docs/03_protocol_reference/protocol_details.adoc)
159+
* [Befehlsreferenz](docs/01_user_guide/usage.adoc#_command_interface)
160+
161+
## Lizenz
162+
163+
Dieses Projekt steht unter der MIT‑Lizenz – siehe [LICENSE](LICENSE) für Details.
164+
165+
## Danksagung
166+
167+
Basierend auf der originalen FHEM‑SIGNALDuino‑Implementierung von [@Sidey79](https://github.com/Sidey79) und der Community.

0 commit comments

Comments
 (0)