Skip to content

Commit 6978943

Browse files
sidey79sidey79
committed
feat: improve some docs
1 parent 80ffc54 commit 6978943

7 files changed

Lines changed: 174 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ This file provides guidance to agents when working with code in this repository.
1212
## Verification Execution
1313
- Das Hauptprogramm für Verifizierungen sollte wie folgt gestartet werden:
1414
`python3 main.py --timeout 1`
15+
oder um eine längere Laufzeit zu analysieren:
16+
`python3 main.py --timeout 30`
1517

1618
## Mandatory Documentation and Test Maintenance
1719

‎README.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,49 @@
22

33
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.
44

5+
## Projektgeschichte
6+
7+
PySignalduino ist Teil des **RFD-FHEM**-Ökosystems, das ursprünglich als Perl-basierte Lösung für die Hausautomationssoftware FHEM begann. Die Entwicklung lässt sich in folgende Meilensteine unterteilen:
8+
9+
### Ursprung: RFD-FHEM und SIGNALDuino
10+
- **2010er Jahre**: Die RFD-FHEM-Community entwickelte Hardware- und Softwarelösungen für die Funkkommunikation mit 433/868 MHz Geräten.
11+
- **SIGNALDuino-Hardware**: Ein Arduino-basierter Transceiver mit CC1101 Funkmodul, der als kostengünstige Alternative zu kommerziellen Lösungen entstand.
12+
- **Perl-Implementierung**: Die ursprüngliche Protokollimplementierung erfolgte in Perl als FHEM-Modul `00_SIGNALduino.pm`.
13+
14+
### Migration zu Python
15+
- **2020er Jahre**: Mit der wachsenden Popularität von Python und MQTT entstand der Bedarf nach einer moderneren, asynchronen Lösung.
16+
- **PySignalduino**: Diese Bibliothek portiert die Perl-Protokolle (`SD_Protocols.pm`, `SD_ProtocolData.pm`) in eine native Python-Implementierung.
17+
- **Asynchrone Architektur**: Vollständige `asyncio`-Integration für bessere Performance und einfachere Integration in moderne IoT-Systeme.
18+
19+
### Community-Entwicklung
20+
- **Open Source**: Das Projekt wird von einer aktiven Community auf GitHub gepflegt und weiterentwickelt.
21+
- **Firmware-Entwicklung**: Die SIGNALDuino-Firmware wird parallel im Repository [RFD-FHEM/SIGNALDuino](https://github.com/RFD-FHEM/SIGNALDuino) entwickelt.
22+
- **Version 3.5.0**: Die aktuelle Firmware-Version bietet erweiterte Funktionen wie WiFi-Unterstützung für ESP32-basierte Boards.
23+
24+
### Entwicklungsstatus
25+
26+
> **⚠️ Entwicklungsstatus**
27+
>
28+
> PySignalduino befindet sich noch in aktiver Entwicklung und hat noch kein offizielles Release veröffentlicht. Die API kann sich zwischen Versionen ändern. Entwickler sollten bei der Verwendung Vorsicht walten lassen und auf mögliche Breaking Changes vorbereitet sein.
29+
30+
### PySignalduino vs. Original
31+
PySignalduino ist keine direkte Portierung, sondern eine Neuimplementierung mit folgenden Unterschieden:
32+
- **Asynchrone Verarbeitung**: Statt Threads wird `asyncio` verwendet.
33+
- **MQTT-Integration**: Eingebaute MQTT-Bridge für nahtlose Integration in IoT-Ökosysteme.
34+
- **Moderne Python-Praktiken**: Typisierung, strukturierte Logging, Konfiguration über Umgebungsvariablen.
35+
36+
## Controller-Code und Firmware
37+
38+
Die SIGNALDuino-Firmware (Microcontroller-Code) wird in einem separaten Repository entwickelt:
39+
40+
- **GitHub Repository**: https://github.com/RFD-FHEM/SIGNALDuino
41+
- **Aktuelle Version**: v3.5.0
42+
- **Unterstützte Hardware**:
43+
- Arduino Nano mit CC1101
44+
- ESP32-basierte Boards (z.B. ESP32-DevKitC)
45+
- Maple Mini (STM32)
46+
- **Build-Anleitungen**: Das Repository enthält PlatformIO-Konfigurationen und Arduino-IDE-Projektdateien für einfache Kompilierung.
47+
548
## Hauptmerkmale
649

750
* **Vollständig asynchron** – Basierend auf `asyncio` für hohe Performance und einfache Integration in asynchrone Anwendungen.

‎docs/01_user_guide/index.adoc‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,80 @@
33

44
Der Benutzer-Leitfaden enthält Anweisungen zur Installation, Konfiguration und grundlegenden Verwendung von PySignalduino.
55

6+
== Was ist PySignalduino?
7+
8+
PySignalduino ist eine moderne Python-Bibliothek zur Kommunikation mit **SIGNALDuino**-Hardware – einem Arduino-basierten Transceiver für 433/868 MHz Funkkommunikation. Die Bibliothek bietet:
9+
10+
* **Asynchrone Verarbeitung**: Vollständige `asyncio`-Integration für nicht-blockierende Operationen.
11+
* **MQTT-Bridge**: Eingebaute MQTT-Unterstützung für nahtlose Integration in Smart-Home-Systeme.
12+
* **Protokollbibliothek**: Portierung der originalen FHEM‑SIGNALDuino‑Protokolle (`SD_Protocols.pm`, `SD_ProtocolData.pm`) in Python.
13+
* **Moderne Transporte**: Unterstützung für serielle und TCP-Verbindungen.
14+
15+
=== Unterschied zum Original
16+
PySignalduino ist keine direkte Portierung des Perl‑FHEM‑Moduls, sondern eine Neuimplementierung mit folgenden Schwerpunkten:
17+
18+
* **Asynchrone Architektur**: Statt Threads wird `asyncio` verwendet, was bessere Skalierbarkeit und einfachere Integration in asynchrone Anwendungen ermöglicht.
19+
* **Typisierung**: Vollständige Typ‑Annotations für bessere Code‑Qualität und IDE‑Unterstützung.
20+
* **Konfiguration über Umgebungsvariablen**: Einfache Einrichtung ohne Codeänderungen.
21+
* **Umfangreiche Testsuite**: Hohe Testabdeckung zur Gewährleistung der Stabilität.
22+
23+
=== Entwicklungsstatus
24+
25+
[WARNING]
26+
====
27+
**Entwicklungsstatus**
28+
29+
PySignalduino befindet sich noch in aktiver Entwicklung und hat noch kein offizielles Release veröffentlicht. Die API kann sich zwischen Versionen ändern. Entwickler sollten bei der Verwendung Vorsicht walten lassen und auf mögliche Breaking Changes vorbereitet sein.
30+
====
31+
32+
=== Zielgruppe
33+
PySignalduino richtet sich an:
34+
35+
* **Entwickler**, die SIGNALDuino‑Hardware in Python‑Projekte integrieren möchten.
36+
* **Smart‑Home‑Enthusiasten**, die eine MQTT‑Bridge für ihre Funkgeräte benötigen.
37+
* **Integratoren**, die bestehende FHEM‑Installationen um moderne Python‑Komponenten erweitern wollen.
38+
39+
== Architektur-Übersicht
40+
41+
PySignalduino folgt einer modular aufgebauten Architektur:
42+
43+
[source,plantuml]
44+
----
45+
include::../../docs/diagrams/architecture.puml[]
46+
----
47+
48+
Die Hauptkomponenten sind:
49+
50+
1. **Transport Layer** (`signalduino.transport`):
51+
* `SerialTransport` – Asynchrone serielle Kommunikation über `pyserial-asyncio`.
52+
* `TcpTransport` – TCP‑Socket‑Verbindung.
53+
54+
2. **Parser Layer** (`signalduino.parser`):
55+
* `MCParser`, `MNParser`, `MSParser`, `MUParser` – Verarbeitung der verschiedenen SIGNALDuino‑Nachrichtentypen.
56+
57+
3. **Protokollbibliothek** (`sd_protocols`):
58+
* `SDProtocols` – Hauptklasse für Protokollerkennung und ‑dekodierung.
59+
* `SDProtocolData` – Datenstrukturen für Protokolldefinitionen.
60+
61+
4. **Controller** (`signalduino.controller`):
62+
* `SignalduinoController` – Zentrale Steuerungsklasse, koordiniert Transport, Parser und MQTT.
63+
64+
5. **MQTT‑Integration** (`signalduino.mqtt`):
65+
* `MqttPublisher` – Asynchroner MQTT‑Client für Publikation und Subscription.
66+
67+
6. **Befehls‑API** (`signalduino.commands`):
68+
* `SignalduinoCommands` – Umfassende Schnittstelle zur Steuerung der SIGNALDuino‑Firmware.
69+
70+
== Schnellstart
71+
72+
Für einen schnellen Einstieg folgen Sie diesen Schritten:
73+
74+
1. **Installation**: Siehe link:installation.adoc[Installationsanleitung].
75+
2. **Konfiguration**: Setzen Sie die erforderlichen Umgebungsvariablen (z.B. `SIGNALDUINO_SERIAL_PORT`, `MQTT_HOST`).
76+
3. **Programm starten**: Führen Sie `python3 main.py` aus.
77+
4. **MQTT‑Nachrichten überwachen**: Abonnieren Sie das Topic `signalduino/messages`, um dekodierte Signale zu empfangen.
78+
79+
Ausführliche Anleitungen finden Sie in den folgenden Kapiteln.
80+
681
include::installation.adoc[]
782
include::usage.adoc[]

‎docs/01_user_guide/installation.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
= Installation
22

3+
[NOTE]
4+
====
5+
PySignalduino ist noch in Entwicklung. Es gibt bisher keine stabile Version – nutzen Sie die Software mit entsprechender Vorsicht.
6+
====
7+
38
== Voraussetzungen
49

510
* Python 3.8 oder höher

‎docs/01_user_guide/usage.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -210,6 +210,8 @@ Die Log-Ausgabe zeigt den Status von Transport, Parser und MQTT.
210210

211211
=== Bekannte Probleme und Workarounds
212212

213+
* **Entwicklungsstatus**: Da PySignalduino noch in aktiver Entwicklung ist, können sich Verhalten und API zwischen Commits ändern. Bei unerwartetem Verhalten prüfen Sie bitte die aktuelle Codebasis und melden Sie Issues auf GitHub.
214+
213215
* **`aiomqtt`-Versionen:** Verwenden Sie `aiomqtt>=2.0.0`. Ältere Versionen können Inkompatibilitäten aufweisen.
214216
* **Windows und asyncio:** Unter Windows kann es bei seriellen Verbindungen zu Problemen mit asyncio kommen. Verwenden Sie `asyncio.ProactorEventLoop` oder weichen Sie auf TCP-Transport aus.
215217
* **Memory Leaks:** Bei langem Betrieb können asyncio-Tasks Speicher verbrauchen. Stellen Sie sicher, dass abgeschlossene Tasks garbage-collected werden. Verwenden Sie `asyncio.create_task` mit Referenzen, um Tasks später abbrechen zu können.

‎docs/02_developer_guide/contribution.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
= Beitrag leisten (Contributing)
22

3+
[NOTE]
4+
====
5+
Da PySignalduino noch in aktiver Entwicklung ist, können sich Code-Strukturen und APIs schnell ändern. Bitte synchronisieren Sie Ihren Fork regelmäßig mit dem upstream-Repository.
6+
====
7+
38
Beiträge zum Projekt sind willkommen!
49

510
== Workflow

‎docs/index.adoc‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,48 @@ Die verfügbare Hardware-Basis reicht von einfachen Arduino/nanoCUL-Lösungen bi
1919

2020
image::images/signalduino_uebersicht.png[SIGNALduino Übersicht - Hardware und Funktion]
2121

22+
[[section-historie]]
23+
== Projektgeschichte und Entwicklung
24+
25+
Das SIGNALduino-Projekt entstand in der **RFD-FHEM**-Community als Open-Source-Initiative zur kostengünstigen Funkkommunikation im Smart-Home-Bereich.
26+
27+
=== Ursprung und Meilensteine
28+
- **2010er Jahre**: Entwicklung erster Arduino-basierter Transceiver mit CC1101-Chips für 433/868 MHz.
29+
- **Perl-Ära**: Die Protokollimplementierung erfolgte zunächst als FHEM-Modul `00_SIGNALduino.pm` in Perl.
30+
- **Community-Wachstum**: Eine aktive Entwickler- und Anwendergemeinschaft trieb die Erweiterung der unterstützten Protokolle voran.
31+
32+
=== Migration zu Python
33+
- **PySignalduino**: Mit dem Aufkommen moderner IoT-Architekturen wurde eine Python-Implementierung notwendig.
34+
- **Asynchrone Verarbeitung**: PySignalduino nutzt `asyncio` für effiziente, nicht-blockierende Verarbeitung.
35+
- **MQTT-Integration**: Eingebaute MQTT-Bridge für nahtlose Integration in moderne Smart-Home-Systeme.
36+
37+
=== Firmware-Entwicklung
38+
Die SIGNALDuino-Firmware wird kontinuierlich im separaten Repository weiterentwickelt:
39+
40+
- **GitHub Repository**: https://github.com/RFD-FHEM/SIGNALDuino
41+
- **Aktuelle Version**: v3.5.0 (Stand Dezember 2025)
42+
- **Unterstützte Plattformen**:
43+
* Arduino Nano mit CC1101
44+
* ESP32 (mit WiFi-Unterstützung)
45+
* STM32 (Maple Mini)
46+
- **Build-System**: PlatformIO und Arduino-IDE Projekte sind im Repository enthalten.
47+
48+
=== PySignalduino vs. Original
49+
PySignalduino ist keine direkte Portierung, sondern eine Neuimplementierung mit folgenden Schwerpunkten:
50+
- **Moderne Python-Praktiken**: Typisierung, strukturierte Logging, Konfiguration über Umgebungsvariablen.
51+
- **Erweiterte Transporte**: Unterstützung für serielle und TCP-Verbindungen.
52+
- **Testabdeckung**: Umfangreiche Testsuite zur Gewährleistung der Codequalität.
53+
54+
[[section-status]]
55+
== Entwicklungsstatus
56+
57+
[WARNING]
58+
====
59+
**Entwicklungsstatus**
60+
61+
PySignalduino befindet sich noch in aktiver Entwicklung und hat noch kein offizielles Release veröffentlicht. Die API kann sich zwischen Versionen ändern. Entwickler sollten bei der Verwendung Vorsicht walten lassen und auf mögliche Breaking Changes vorbereitet sein.
62+
====
63+
2264
[[section-protokolle]]
2365
== Unterstützte Protokolle
2466

0 commit comments

Comments
 (0)