Fix: docs revised

Author: sidey79

.devcontainer/fhem-data/fhem_signalduino_example.cfg

@@ -25,12 +25,16 @@ attr WEB stylesheetPrefix dark
 define eventTypes eventTypes ./log/eventTypes.txt
 setuuid eventTypes 695e9c21-f33f-c986-9ac3-190c47641a98acb9
 
+
+# tag::broker_config[]
 # 4. Define the MQTT Client (Broker Connection)
 # 'mqtt' is the hostname of the broker service in docker-compose.yml
 define mqtt_broker MQTT2_CLIENT mqtt:1883
 setuuid mqtt_broker 695e9c21-f33f-c986-e617-d7301881c4685bc6
 attr mqtt_broker autocreate simple
+# end::broker_config[]
 
+# tag::device_config[]
 # 5. Define the SignalDuino MQTT Device
 define PySignalDuino MQTT2_DEVICE
 setuuid PySignalDuino 695e9c21-f33f-c986-4f81-a9f0ab37b6bcedf8
@@ -75,6 +79,7 @@ attr PySignalDuino setList raw:textField signalduino/v1/commands/set/raw $EVTPAR
   # Maintenance commands \
   factory_reset:noArg signalduino/v1/commands/set/factory_reset
 attr PySignalDuino stateFormat state
+# end::device_config[]
 # Map JSON payload to readings
 # Define setter commands
 

.github/workflows/docs.yml

@@ -31,7 +31,10 @@ jobs:
       - name: run asciidoctor with Kroki extension
         # Registriere die Kroki-Extension (-r asciidoctor-kroki) und aktiviere sie (-a kroki=). 
         # Mermaid-Diagramme werden mit dem Kroki-Server gerendert.
-        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= {} \;
+        # Verwendung von -R docs, um die Verzeichnisstruktur unter build/site/html beizubehalten
+        run: |
+          shopt -s globstar
+          asciidoctor -R docs -D build/site/html -a docinfo=shared -a toc=left -a toclevels=2 -r asciidoctor-kroki -a kroki= docs/**/*.adoc
       
       - name: Setup Python for Sitemap Generation
         uses: actions/setup-python@v5

docs/01_user_guide/index.adoc

@@ -42,7 +42,37 @@ PySignalduino folgt einer modular aufgebauten Architektur:
 
 [source,plantuml]
 ----
-include::../../docs/diagrams/architecture.puml[]
+@startuml
+skinparam componentStyle uml2
+
+package "PySignalduino Core" {
+    [Controller] as ctrl
+    [Command API] as cmd
+    [Parser Layer] as parser
+    [Transport Layer] as transport
+    [Protocol Lib] as proto
+    [MQTT Client] as mqtt
+}
+
+node "Hardware" {
+    [SIGNALDuino] as hw
+}
+
+cloud "Infrastructure" {
+    [MQTT Broker] as broker
+}
+
+ctrl -down-> transport : manages
+ctrl -right-> parser : feeds raw data
+parser -right-> proto : uses for decoding
+ctrl -up-> mqtt : publishes events
+ctrl -left-> cmd : uses
+cmd -down-> transport : sends commands
+
+transport <--> hw : Serial / TCP
+mqtt <--> broker : WiFi / LAN
+
+@enduml
 ----
 
 Die Hauptkomponenten sind:
@@ -78,6 +108,6 @@ Für einen schnellen Einstieg folgen Sie diesen Schritten:
 
 Ausführliche Anleitungen finden Sie in den folgenden Kapiteln.
 
-include::installation.adoc[]
-include::usage.adoc[]
-include::mqtt_api.adoc[]
+include::installation.adoc[leveloffset=+1]
+include::usage.adoc[leveloffset=+1]
+include::mqtt_api.adoc[leveloffset=+1]

docs/01_user_guide/installation.adoc

@@ -88,4 +88,4 @@ Nach der Installation können Sie:
 
 * Die xref:#_schnellstart[Schnellstart-Anleitung] befolgen.
 * Die xref:#_konfiguration[Konfiguration über Umgebungsvariablen] einrichten.
-* Die xref:#_mqtt_integration[MQTT-Integration] testen.
+* Die xref:#_mqtt_integration[MQTT-Integration] testen.

docs/01_user_guide/mqtt_api.adoc

@@ -1,13 +1,15 @@
-= MQTT API Reference
-:doctype: book :icons: font :toc: left :toclevels: 2
+:doctype: book
+:icons: font
+:toc: left
+:toclevels: 2
 :sectnums:
 
 [[_mqtt_introduction]]
-== Einführung
+= Einführung
 
 Die MQTT-Schnittstelle ermöglicht die Steuerung des PySignalduino-Gateways und den Empfang von dekodierten Nachrichten. Alle Befehle und Antworten verwenden das JSON-Format.
 
-=== Topics und Struktur
+== Topics und Struktur
 
 Der **Standard-Topic** für alle MQTT-Operationen ist `signalduino/v1`. 
 Dieser Wert kann über die Umgebungsvariable `MQTT_TOPIC` oder den CLI-Parameter `--mqtt-topic` angepasst werden. Wenn nur der Basis-Topic (z.B. `foo`) gesetzt wird, ist der finale Topic immer versionsspezifisch: `foo/v1`.
@@ -316,21 +318,10 @@ Eine vollständige Beispielkonfiguration finden Sie in der Datei `.devcontainer/
 [source,fhem]
 ----
 # 1. Verbindung zum Broker herstellen (falls noch nicht vorhanden)
-define mqtt_broker MQTT2_CLIENT mqtt:1883
-attr mqtt_broker autocreate simple
+include::../../.devcontainer/fhem-data/fhem_signalduino_example.cfg[tags=broker_config]
 
 # 2. PySignalduino Device definieren
-define PySignalDuino MQTT2_DEVICE
-attr PySignalDuino IODev mqtt_broker
-
-# 3. Readings für empfangene Nachrichten extrahieren
-# Wandelt JSON-Payload automatisch in Readings um
-attr PySignalDuino readingList signalduino/v1/state/messages:.* { json2nameValue($EVENT, '', $JSONMAP) }
-
-# 4. Senden von Befehlen ermöglichen
-attr PySignalDuino setList raw:textField signalduino/v1/commands/set/raw $EVTPART1 \
-cc1101_reg:textField signalduino/v1/commands/set/cc1101_reg $EVTPART1 \
-version:noArg signalduino/v1/commands/get/system/version
+include::../../.devcontainer/fhem-data/fhem_signalduino_example.cfg[tags=device_config]
 ----
 
 === Wichtige Hinweise

docs/01_user_guide/usage.adoc

@@ -1,6 +1,4 @@
-= Verwendung und Konfiguration
-
-== Grundlegende Nutzung
+=== Grundlegende Nutzung
 
 Die Hauptklasse `SDProtocols` stellt die Schnittstelle zur Protokollverarbeitung bereit.
 
@@ -9,11 +7,11 @@ Die Hauptklasse `SDProtocols` stellt die Schnittstelle zur Protokollverarbeitung
 include::../../sd_protocols/sd_protocols.py[lines=25..47]
 ----
 
-== Integration
+=== Integration
 
 PySignalduino ist als Bibliothek konzipiert, die beispielsweise in MQTT-Bridges oder Home-Automation-Skripten verwendet werden kann. Sie übernimmt die Erkennung und Dekodierung der Rohdaten.
 
-=== Logging
+==== Logging
 
 Für Debugging-Zwecke können Sie eine eigene Callback-Funktion registrieren:
 
@@ -22,11 +20,11 @@ Für Debugging-Zwecke können Sie eine eigene Callback-Funktion registrieren:
 include::../../sd_protocols/sd_protocols.py[lines=162..170]
 ----
 
-=== MQTT Integration
+==== MQTT Integration
 
 PySignalduino bietet eine integrierte MQTT-Integration über die Klasse `MqttPublisher`. Diese ermöglicht das Veröffentlichen dekodierter Nachrichten an einen MQTT-Broker und das Empfangen von Befehlen über MQTT-Topics.
 
-==== Einrichtung und Konfiguration
+===== Einrichtung und Konfiguration
 
 Die MQTT-Verbindung wird automatisch initialisiert, wenn die Umgebungsvariable `MQTT_HOST` gesetzt ist. Folgende Umgebungsvariablen können konfiguriert werden:
 
@@ -44,31 +42,31 @@ Der `MqttPublisher` wird innerhalb des `SignalduinoController` verwendet und ste
 include::../../main.py[lines=55..84]
 ----
 
-==== MQTT-Topics
+===== MQTT-Topics
 
 * `{topic}/messages` – JSON‑kodierte dekodierte Nachrichten (DecodedMessage)
 * `{topic}/commands/#` – Topic für eingehende Befehle (Wildcard-Subscription)
 * `{topic}/responses` – Antworten auf GET-Befehle, inkl. `get/cc1101/frequency`.
 * `{topic}/errors` – Fehlerantworten.
 * `{topic}/status` – Heartbeat‑ und Statusmeldungen (optional)
 
-==== Heartbeat-Funktionalität
+===== Heartbeat-Funktionalität
 
 Der Publisher sendet regelmäßig einen Heartbeat („online“) unter `{topic}/status`, solange die Verbindung besteht.
 Bei Verbindungsabbruch wird „offline“ gepublished.
 
-==== Beispiel: Manuelle Nutzung des MqttPublisher
+===== Beispiel: Manuelle Nutzung des MqttPublisher
 
 [source,python]
 ----
 include::../../tests/test_mqtt.py[lines=112..116]
 ----
 
-=== Command Interface
+==== Command Interface
 
 PySignalduino stellt eine umfangreiche Befehls-API zur Steuerung des SIGNALDuino-Firmware-Geräts bereit. Die Klasse `SignalduinoCommands` kapselt alle verfügbaren seriellen Befehle und bietet eine asynchrone Schnittstelle.
 
-==== Verfügbare Befehle
+===== Verfügbare Befehle
 
 Die folgenden Befehle werden unterstützt (Auswahl):
 
@@ -105,13 +103,13 @@ Die folgenden Befehle werden unterstützt (Auswahl):
   * `send_xfsk(params)` – xFSK senden (SN...)
   * `send_message(message)` – Vorkodierte Nachricht senden
 
-==== Persistenz-Funktionalität
+===== Persistenz-Funktionalität
 
 Befehle, die die Hardware-Konfiguration ändern (z.
 B. `write_register`, `set_patable`), werden in der Regel im EEPROM des SIGNALDuino persistent gespeichert.
 Die Persistenz wird durch die Firmware gewährleistet; PySignalduino sendet lediglich die entsprechenden Kommandos.
 
-==== Nutzung über MQTT
+===== Nutzung über MQTT
 
 Wenn MQTT aktiviert ist, können Befehle über das Topic `{base_topic}/commands/{command}` gesendet werden. Die Basis für Antworten ist `{base_topic}/responses` (Erfolg) oder `{base_topic}/errors` (Fehler). Das `base_topic` ist standardmäßig `signalduino/v1`.
 
@@ -186,27 +184,25 @@ mosquitto_pub -h localhost -t "signalduino/v1/commands/get/system/version" -m '{
 # Antwort empfängst du auf signalduino/v1/responses
 ----
 
-==== Code-Beispiel: Direkte Nutzung der Command-API
-
-==== Code-Beispiel: Direkte Nutzung der Command-API
+===== Code-Beispiel: Direkte Nutzung der Command-API
 
 [source,python]
 ----
 include::../../tests/test_controller.py[lines=120..130]
 ----
 
-==== Beispiel: Asynchrone Context-Manager Nutzung
+===== Beispiel: Asynchrone Context-Manager Nutzung
 
 [source,python]
 ----
 include::../../main.py[lines=55..84]
 ----
 
-== API-Referenz (Auszug)
+=== API-Referenz (Auszug)
 
 Die folgenden Klassen und Schnittstellen sind für die Integration besonders relevant:
 
-=== MqttPublisher
+==== MqttPublisher
 
 Die Klasse `signalduino.mqtt.MqttPublisher` bietet eine asynchrone Context-Manager-Schnittstelle zur Kommunikation mit einem MQTT-Broker.
 
@@ -218,15 +214,15 @@ Die Klasse `signalduino.mqtt.MqttPublisher` bietet eine asynchrone Context-Manag
 
 * **Context-Manager:** `async with MqttPublisher() as publisher:`
 
-=== SignalduinoCommands
+==== SignalduinoCommands
 
 Die Klasse `signalduino.commands.SignalduinoCommands` kapselt alle seriellen Befehle für die SIGNALDuino-Firmware.
 
 * **Initialisierung:** Erfordert eine asynchrone Sendefunktion (wird normalerweise vom `SignalduinoController` bereitgestellt)
 * **Alle Methoden sind asynchron** (`async def`) und geben entweder `str` (Antwort) zurück oder `None` (keine Antwort erwartet)
 * **Umfang:** Systembefehle, Konfiguration, Senden von Nachrichten (siehe Abschnitt „Command Interface“)
 
-=== Asynchrone Context-Manager-Schnittstelle
+==== Asynchrone Context-Manager-Schnittstelle
 
 Sowohl `SignalduinoController` als auch `MqttPublisher` und die Transportklassen (`TcpTransport`, `SerialTransport`) implementieren das asynchrone Context-Manager-Protokoll (`__aenter__`/`__aexit__`). Dies gewährleistet eine sichere Ressourcenverwaltung (Verbindungsauf‑/abbau, Hintergrundtasks).
 
@@ -237,37 +233,37 @@ Beispiel für verschachtelte Context-Manager:
 include::../../main.py[lines=55..84]
 ----
 
-=== Weitere Klassen
+==== Weitere Klassen
 
 * `SignalduinoController` – Zentrale Steuerungsklasse, koordiniert Transport, Parser, MQTT und Befehle
 * `TcpTransport`, `SerialTransport` – Asynchrone Transportimplementierungen für TCP bzw. serielle Verbindungen
 * `DecodedMessage`, `RawFrame` – Datentypen für dekodierte Nachrichten und Rohframes
 
 Eine vollständige API-Dokumentation kann mit `pydoc` oder mittels Sphinx generiert werden.
 
-== Troubleshooting
+=== Troubleshooting
 
 Dieser Abschnitt beschreibt häufige Probleme und deren Lösungen.
 
-=== MQTT-Verbindungsprobleme
+==== MQTT-Verbindungsprobleme
 
 * **Keine Verbindung zum Broker:** Stellen Sie sicher, dass die Umgebungsvariablen `MQTT_HOST` und `MQTT_PORT` korrekt gesetzt sind. Der Broker muss erreichbar sein und keine Authentifizierung erfordern (oder Benutzername/Passwort müssen gesetzt sein).
 * **Verbindung bricht ab:** Überprüfen Sie die Netzwerkverbindung und Broker-Konfiguration. Der MQTT-Client (`aiomqtt`) versucht automatisch, die Verbindung wiederherzustellen. Falls die Verbindung dauerhaft abbricht, prüfen Sie Firewall-Einstellungen und Broker-Logs.
 * **MQTT-Nachrichten werden nicht empfangen:** Stellen Sie sicher, dass das Topic `{topic}/commands/#` abonniert ist. Der Command-Listener startet automatisch, wenn MQTT aktiviert ist. Überprüfen Sie die Log-Ausgabe auf Fehler.
 
-=== Asyncio-spezifische Probleme
+==== Asyncio-spezifische Probleme
 
 * **`RuntimeError: no running event loop`:** Tritt auf, wenn asyncio-Funktionen außerhalb eines laufenden Event-Loops aufgerufen werden. Stellen Sie sicher, dass Ihr Code innerhalb einer asyncio-Coroutine läuft und `asyncio.run()` verwendet wird. Verwenden Sie `async with` für Context-Manager.
 * **Tasks hängen oder werden nicht abgebrochen:** Alle Hintergrundtasks sollten auf das `_stop_event` reagieren. Bei manuell erstellten Tasks müssen Sie `asyncio.CancelledError` abfangen und Ressourcen freigeben.
 * **Deadlocks in Queues:** Wenn eine Queue voll ist und kein Consumer mehr liest, kann `await queue.put()` blockieren. Stellen Sie sicher, dass die Consumer-Tasks laufen und die Queue nicht überfüllt wird. Verwenden Sie `asyncio.wait_for` mit Timeout.
 
-=== Verbindungsprobleme zum SIGNALDuino-Gerät
+==== Verbindungsprobleme zum SIGNALDuino-Gerät
 
 * **Keine Antwort auf Befehle:** Überprüfen Sie die serielle oder TCP-Verbindung. Stellen Sie sicher, dass das Gerät eingeschaltet ist und die korrekte Baudrate (115200) verwendet wird. Testen Sie mit einem Terminal-Programm, ob das Gerät auf `V` (Version) antwortet.
 * **Timeout-Errors:** Die Standard-Timeout für Befehle beträgt 2 Sekunden. Bei langsamen Verbindungen kann dies erhöht werden. Falls Timeouts trotzdem auftreten, könnte die Verbindung instabil sein.
 * **Parser erkennt keine Protokolle:** Überprüfen Sie, ob die Rohdaten im erwarteten Format ankommen (z.B. `+MU;...`). Stellen Sie sicher, dass die Protokolldefinitionen (`protocols.json`) geladen werden und das Protokoll aktiviert ist.
 
-=== Logging und Debugging
+==== Logging und Debugging
 
 Aktivieren Sie Debug-Logging, um detaillierte Informationen zu erhalten:
 
@@ -278,12 +274,12 @@ include::../../main.py[lines=21..30]
 
 Die Log-Ausgabe zeigt den Status von Transport, Parser und MQTT.
 
-=== Bekannte Probleme und Workarounds
+==== Bekannte Probleme und Workarounds
 
 * **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.
 
 * **`aiomqtt`-Versionen:** Verwenden Sie `aiomqtt>=2.0.0`. Ältere Versionen können Inkompatibilitäten aufweisen.
 * **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.
 * **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.
 
-Bei weiteren Problemen öffnen Sie bitte ein Issue auf GitHub mit den relevanten Logs und Konfigurationsdetails.
+Bei weiteren Problemen öffnen Sie bitte ein Issue auf GitHub mit den relevanten Logs und Konfigurationsdetails.

docs/02_developer_guide/architecture.adoc

@@ -1,5 +1,3 @@
-= Architektur
-
 == Übersicht
 
 PySignalduino ist modular aufgebaut und trennt die Protokolldefinitionen (JSON) strikt von der Verarbeitungslogik (Python).

docs/02_developer_guide/contribution.adoc

@@ -1,4 +1,3 @@
-= Beitrag leisten (Contributing)
 
 [NOTE]
 ====

docs/03_protocol_reference/protocol_details.adoc

@@ -1,4 +1,3 @@
-= Protokolldetails
 
 PySignalduino unterstützt eine Vielzahl von Funkprotokollen im 433 MHz und 868 MHz Bereich.
 

docs/architecture/decisions/ADR-001-mqtt-get-frequency.adoc

@@ -6,7 +6,7 @@
 
 Angenommen.
 
-[[context]]
+[#adr-context]
 == Kontext
 
 Das PySignalduino-Projekt benötigt eine Methode, um die aktuell im CC1101-Transceiver eingestellte Funkfrequenz über das MQTT-Interface abzufragen, hauptsächlich für Diagnose- und Statuszwecke.
@@ -19,7 +19,7 @@ $$f_{RF} = \frac{F_{XOSC}}{2^{16}} \times F_{REG}$$
 Bei $F_{XOSC} = 26 \, \text{MHz}$ ergibt sich:
 $$f_{RF} = \frac{26}{65536} \times F_{REG} \, \text{MHz}$$
 
-[[decision]]
+[#adr-decision]
 == Entscheidung
 
 Wir implementieren den `get/frequency` Befehl als Teil der `MqttHandler`- und `Commands`-Klassen.
@@ -31,15 +31,15 @@ Wir implementieren den `get/frequency` Befehl als Teil der `MqttHandler`- und `C
     *   Wir implementieren die Berechnung in `signalduino/commands.py` (z.B. `get_frequency()`), um die Abhängigkeit der Hardware vom Command Layer zu kapseln.
     *   Das Ergebnis wird auf 4 Dezimalstellen gerundet (in MHz), um eine hohe Genauigkeit bei der Anzeige zu gewährleisten.
 
-[[consequences]]
+[#adr-consequences]
 == Konsequenzen
 
 *   *Positiv*: Benutzer können die eingestellte Frequenz einfach über MQTT abfragen, was die Diagnose erleichtert.
 *   *Positiv*: Die Verwendung der offiziellen CC1101-Formel und der 26 MHz Oszillatorfrequenz gewährleistet Korrektheit und Konsistenz.
 *   *Negativ*: Es müssen neue Methoden in `signalduino/hardware.py`, `signalduino/commands.py` und `signalduino/mqtt.py` implementiert werden.
 *   *Negativ*: Die Hardware-Klasse muss um die Logik zum Lesen der drei Register erweitert werden, möglicherweise durch eine neue Abstraktionsebene, falls dies in Zukunft für andere Dreifachregister notwendig wird.
 
-[[alternatives]]
+[#adr-alternatives]
 == Alternativen
 
 *   *Alternative 1: Berechnung auf der Hardware-Ebene:*