You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: AGENTS.md
+198-1Lines changed: 198 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,6 +12,8 @@ This file provides guidance to agents when working with code in this repository.
12
12
## Verification Execution
13
13
- Das Hauptprogramm für Verifizierungen sollte wie folgt gestartet werden:
14
14
`python3 main.py --timeout 1`
15
+
oder um eine längere Laufzeit zu analysieren:
16
+
`python3 main.py --timeout 30`
15
17
16
18
## Mandatory Documentation and Test Maintenance
17
19
@@ -46,4 +48,199 @@ Diese Richtlinie gilt für alle AI-Agenten, die Code oder Systemkonfigurationen
46
48
-[ ] Gesamte Testsuite (`pytest`) ohne Fehler durchgelaufen
47
49
-[ ] Änderungen mit den Projekt‑Konventionen konsistent
48
50
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.
51
+
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.
52
+
53
+
## Architecture-First Development Process
54
+
55
+
Dieser Abschnitt definiert den verbindlichen Arbeitsablauf für die Entwicklung neuer Funktionen im PySignalduino-Projekt. Der zentrale Grundsatz lautet: **Jede neue Funktion beginnt mit einer vorausschauenden Erweiterung der Architekturdokumentation.** Diese dokumentierte Architektur dient als die einzige verbindliche Spezifikation und der primäre Leitfaden für alle nachfolgenden Implementierungsschritte.
56
+
57
+
### Grundprinzipien
58
+
59
+
1.**Architektur vor Code:** Design-Entscheidungen müssen zuerst in der Dokumentation reflektiert und abgestimmt werden, bevor jeglicher Code geschrieben wird.
60
+
2.**Dokumentation als Single Source of Truth:** Die Architekturdokumentation ist die autoritative Referenz für alle Implementierungsentscheidungen.
61
+
3.**Traceability:** Jede Code-Änderung muss auf eine spezifische Architekturentscheidung zurückführbar sein.
62
+
4.**Compliance-Checks:** Implementierungen müssen regelmäßig auf Konformität mit der dokumentierten Architektur überprüft werden.
63
+
64
+
### Vier-Phasen-Prozess
65
+
66
+
#### Phase 1: Architekturdefinition mit verbindlichem Architekturproposal
67
+
-**Ziel:** Erstellung eines vollständigen Architekturproposals, das alle Design-Entscheidungen dokumentiert
68
+
-**Aktivitäten:**
69
+
- Anforderungsanalyse und Scope-Definition
70
+
- Erstellung von Architekturdiagrammen (Mermaid, PlantUML)
71
+
- Definition von Schnittstellen und Datenmodellen
72
+
- Risikoanalyse und Alternativenbewertung
73
+
- Erstellung eines Architecture Decision Record (ADR)
74
+
-**Deliverables:**
75
+
- Architekturproposal im AsciiDoc-Format
76
+
- Mermaid-Diagramme für Komponenten- und Sequenzabläufe
77
+
- ADR im `docs/architecture/decisions/` Verzeichnis
78
+
- Review-Protokoll mit Genehmigung durch Architecture Owner
79
+
80
+
#### Phase 2: Implementierungsplanung basierend auf genehmigter Architektur
81
+
-**Ziel:** Detaillierte Planung der Implementierungsschritte unter strikter Einhaltung der Architektur
82
+
-**Aktivitäten:**
83
+
- Aufteilung in konkrete Arbeitspakete (Tasks)
84
+
- Definition von Akzeptanzkriterien für jede Komponente
85
+
- Planung von Teststrategien (Unit, Integration, System)
86
+
- Ressourcen- und Zeitplanung
87
+
- Erstellung von Mockups/Prototypen für kritische Pfade
88
+
-**Deliverables:**
89
+
- Implementierungsplan mit Task-Breakdown
90
+
- Testplan mit Coverage-Zielen
91
+
- Prototypen für Risikokomponenten
92
+
- Genehmigung durch Feature Developer und Reviewer
93
+
94
+
#### Phase 3: Implementierung mit strikter Konformität zur Architektur
95
+
-**Ziel:** Code-Entwicklung unter ständiger Referenzierung der Architekturdokumentation
96
+
-**Aktivitäten:**
97
+
- Iterative Entwicklung gemäß Implementierungsplan
98
+
- Regelmäßige Architektur-Compliance-Checks
99
+
- Dokumentation von Abweichungen und deren Begründung
100
+
- Kontinuierliche Integration und Code-Reviews
101
+
- Anpassung der Dokumentation bei notwendigen Änderungen
G -->|Ja| H[ADR für Änderung<br/>oder Rückführung]
223
+
H --> E
224
+
G -->|Nein| I[Phase 4: Validation & Integration]
225
+
I --> J{Alle Tests bestanden<br/>und Compliance ok?}
226
+
J -->|Ja| K[Merge & Deployment]
227
+
J -->|Nein| I
228
+
229
+
subgraph "Architektur-Governance"
230
+
L[Architecture Owner Review]
231
+
M[ADR Management]
232
+
N[Compliance Monitoring]
233
+
end
234
+
235
+
B --> L
236
+
D --> L
237
+
I --> L
238
+
H --> M
239
+
F --> N
240
+
```
241
+
242
+
### Verbindlichkeit
243
+
244
+
Dieser Architecture-First Development Process ist für **alle** neuen Funktionen und wesentlichen Änderungen verbindlich. Ausnahmen sind nur bei kritischen Bugfixes erlaubt und müssen durch einen Emergency-ADR dokumentiert werden. Jede Abweichung vom Prozess muss vom Architecture Owner genehmigt werden.
245
+
246
+
Die Einhaltung dieses Prozesses gewährleistet, dass Design-Entscheidungen bewusst getroffen, dokumentiert und nachvollziehbar sind, was die langfristige Wartbarkeit, Skalierbarkeit und Qualität des PySignalduino-Projekts sicherstellt.
Copy file name to clipboardExpand all lines: README.md
+43Lines changed: 43 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,49 @@
2
2
3
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.
4
4
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:
Copy file name to clipboardExpand all lines: docs/01_user_guide/index.adoc
+75Lines changed: 75 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,5 +3,80 @@
3
3
4
4
Der Benutzer-Leitfaden enthält Anweisungen zur Installation, Konfiguration und grundlegenden Verwendung von PySignalduino.
5
5
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:
Copy file name to clipboardExpand all lines: docs/01_user_guide/usage.adoc
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -210,6 +210,8 @@ Die Log-Ausgabe zeigt den Status von Transport, Parser und MQTT.
210
210
211
211
=== Bekannte Probleme und Workarounds
212
212
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
+
213
215
* **`aiomqtt`-Versionen:** Verwenden Sie `aiomqtt>=2.0.0`. Ältere Versionen können Inkompatibilitäten aufweisen.
214
216
* **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.
215
217
* **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.
Copy file name to clipboardExpand all lines: docs/02_developer_guide/contribution.adoc
+5Lines changed: 5 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,10 @@
1
1
= Beitrag leisten (Contributing)
2
2
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.
0 commit comments