Skip to content

Commit 32a75d3

Browse files
author
sidey79
committed
feat: Update documentation to enhance clarity and include Architecture Decision Records
1 parent a1d69fd commit 32a75d3

File tree

5 files changed

+106
-236
lines changed

5 files changed

+106
-236
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ jobs:
3131
- name: run asciidoctor with Kroki extension
3232
# Registriere die Kroki-Extension (-r asciidoctor-kroki) und aktiviere sie (-a kroki=).
3333
# Mermaid-Diagramme werden mit dem Kroki-Server gerendert.
34-
run: asciidoctor -R docs -D build/site/html -a docinfo=shared -a toc=left -a toclevels=2 -r asciidoctor-kroki -a kroki= 'docs/index.adoc'
34+
run: find docs -type f -name "*.adoc" -exec asciidoctor -D build/site/html -a docinfo=shared -a toc=left -a toclevels=2 -r asciidoctor-kroki -a kroki= {} \;
3535

3636
- name: Setup Python for Sitemap Generation
3737
uses: actions/setup-python@v5

‎README.adoc‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
= PySignalduino – Asynchrone MQTT-Bridge für SIGNALDuino
2+
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+
5+
=== Entwicklungsstatus
6+
7+
[NOTE]
8+
.Entwicklungsstatus
9+
====
10+
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.
11+
====
12+
13+
=== PySignalduino vs. Original
14+
PySignalduino ist keine direkte Portierung, sondern eine Neuimplementierung mit folgenden Unterschieden:
15+
* *Asynchrone Verarbeitung*:: Statt Threads wird `asyncio` verwendet.
16+
* *MQTT-Integration*:: Eingebaute MQTT-Bridge für nahtlose Integration in IoT-Ökosysteme.
17+
* *Moderne Python-Praktiken*:: Typisierung, strukturierte Logging, Konfiguration über Umgebungsvariablen.
18+
19+
== Controller-Code und Firmware
20+
21+
Die SIGNALDuino-Firmware (Microcontroller-Code) wird in einem separaten Repository entwickelt:
22+
23+
* *GitHub Repository*:: https://github.com/RFD-FHEM/SIGNALDuino
24+
* *Aktuelle Version*:: v4.0.0
25+
* *Unterstützte Hardware*::
26+
** Arduino Nano mit CC1101
27+
** ESP32-basierte Boards (z.B. ESP32-DevKitC)
28+
** Maple Mini (STM32)
29+
* *Build-Anleitungen*:: Das Repository enthält PlatformIO-Konfigurationen und Arduino-IDE-Projektdateien für einfache Kompilierung.
30+
31+
== Hauptmerkmale
32+
33+
* **Vollständig asynchron** – Basierend auf `asyncio` für hohe Performance und einfache Integration in asynchrone Anwendungen.
34+
* **MQTT-Integration** – Automatisches Publizieren dekodierter Nachrichten in konfigurierbare Topics und Empfang von Steuerbefehlen (z.B. `version`, `set`, `mqtt`).
35+
* **Unterstützte Transporte** – Serielle Verbindung (über `pyserial-asyncio`) und TCP-Verbindung.
36+
* **Umfangreiche Protokollbibliothek** – Portierung der originalen FHEM‑SIGNALDuino‑Protokolle mit `SDProtocols` und `SDProtocolData`.
37+
* **Konfiguration über Umgebungsvariablen** – Einfache Einrichtung ohne Codeänderungen.
38+
* **Ausführbares Hauptprogramm** – `main.py` bietet eine sofort einsatzbereite Lösung mit Logging, Signalbehandlung und Timeout‑Steuerung.
39+
* **Komprimierte Datenübertragung** – Effiziente Payload‑Kompression für MQTT‑Nachrichten.
40+
41+
== Demo
42+
43+
=== MQTT-CLI-Integration
44+
45+
image::docs/pysignalduino_cli.apng[PySignalduino CLI Demo]
46+
47+
=== FHEMweb-Integration
48+
49+
image::docs/pysignalduino_fhemweb.apng[PySignalduino FHEMweb Demo]
50+
51+
\n
52+
== Projektstruktur
53+
54+
[source,text]
55+
----
56+
PySignalduino/
57+
├── signalduino/ # Hauptpaket
58+
│ ├── controller.py # Asynchroner Controller
59+
│ ├── mqtt.py # MQTT‑Publisher/Subscriber
60+
│ ├── transport.py # Serielle/TCP‑Transporte (asyncio)
61+
│ ├── commands.py # Befehlsimplementierung
62+
│ └── ...
63+
├── sd_protocols/ # Protokollbibliothek (SDProtocols)
64+
├── tests/ # Umfangreiche Testsuite
65+
├── docs/ # Dokumentation (AsciiDoc)
66+
├── main.py # Ausführbares Hauptprogramm
67+
├── pyproject.toml # Paketkonfiguration
68+
└── requirements*.txt # Abhängigkeiten
69+
----
70+
71+
\n
72+
== Dokumentation
73+
74+
Die vollständige Dokumentation und alle Anleitungen finden Sie auf der Hauptseite:
75+
76+
* xref:docs/index.adoc[Zur vollständigen PySignalduino Dokumentation]
77+
78+
== SEO & Sitemap
79+
80+
Die Dokumentation wird automatisch mit einer dynamischen Sitemap (`sitemap.xml`) und branch‑spezifischen `robots.txt`‑Dateien versehen, um die Auffindbarkeit in Suchmaschinen zu verbessern.
81+
82+
* *Sitemap‑Generierung*:: Das Skript xref:tools/generate_sitemap.py[tools/generate_sitemap.py] scannt den Build‑Output, weist Prioritäten und Update‑Frequenzen zu und generiert eine valide XML‑Sitemap gemäß sitemaps.org.
83+
* *Branch‑spezifische URLs*:: Für die Branches `main`, `preview` und `develop` werden unterschiedliche Base‑URLs verwendet.
84+
* *Integration in CI/CD*:: Der GitHub Actions Workflow link:.github/workflows/docs.yml[.github/workflows/docs.yml] generiert die Sitemap automatisch nach jedem Build und passt die `robots.txt` entsprechend an.
85+
86+
Weitere Details zur Architektur finden Sie im xref:docs/02_developer_guide/architecture.adoc#dokumentations-infrastruktur-sitemap--seo[Architektur‑Dokument].
87+
88+
== Lizenz
89+
90+
Dieses Projekt steht unter der MIT‑Lizenz – siehe xref:LICENSE[LICENSE] für Details.
91+
92+
== Danksagung
93+
94+
Basierend auf der originalen FHEM‑SIGNALDuino‑Implementierung von [@Sidey79](https://github.com/Sidey79) und der Community.

‎README.md‎

Lines changed: 0 additions & 230 deletions
This file was deleted.

‎docs/01_user_guide/installation.adoc‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,6 @@ Details finden Sie in der [DevContainer-Dokumentation](devcontainer_env.md).
8686

8787
Nach der Installation können Sie:
8888

89-
1. Die [Schnellstart-Anleitung](../index.adoc#_schnellstart) befolgen.
90-
2. Die [Konfiguration über Umgebungsvariablen](../usage.adoc#_konfiguration) einrichten.
91-
3. Die [MQTT-Integration](../usage.adoc#_mqtt_integration) testen.
89+
* Die xref:#_schnellstart[Schnellstart-Anleitung] befolgen.
90+
* Die xref:#_konfiguration[Konfiguration über Umgebungsvariablen] einrichten.
91+
* Die xref:#_mqtt_integration[MQTT-Integration] testen.

‎docs/02_developer_guide/architecture.adoc‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -95,8 +95,14 @@ Alle Requests (Commands) und Responses (Responses/Errors) verwenden eine standar
9595
----
9696

9797
=== Wichtige Architekturentscheidungen
98-
* link:../architecture/decisions/adr-001-mqtt-topic-structure.md[ADR-001: MQTT Topic Struktur und Versionierung]
99-
* link:../architecture/decisions/adr-002-command-dispatcher.md[ADR-002: Command Dispatcher Pattern und JSON-Schema-Validierung]
98+
Die vollständigen Architecture Decision Records (ADR) sind hier aufgelistet und werden im Dokument eingebettet:
99+
100+
// ADRs 001 bis 005 werden direkt eingebunden
101+
include::../architecture/decisions/ADR-001-mqtt-get-frequency.adoc[leveloffset=+1]
102+
include::../architecture/decisions/ADR-002-mqtt-command-dispatcher.adoc[leveloffset=+1]
103+
include::../architecture/decisions/ADR-003-cc1101-parameter-set-logic.adoc[leveloffset=+1]
104+
include::../architecture/decisions/ADR-004-mqtt-response-parsing.adoc[leveloffset=+1]
105+
include::../architecture/decisions/ADR-005-mqtt-cc1101-response-consistency.adoc[leveloffset=+1]
100106

101107
== Komponentendiagramm (Übersicht)
102108

0 commit comments

Comments
 (0)