diff --git a/.devcontainer/.devcontainer.env.sample b/.devcontainer/.devcontainer.env.sample index c01a14b..12d3c19 100644 --- a/.devcontainer/.devcontainer.env.sample +++ b/.devcontainer/.devcontainer.env.sample @@ -13,10 +13,11 @@ MQTT_USERNAME= # Optional: Leer lassen, wenn keine Authentifizierung erforderlich ist. MQTT_PASSWORD= -# Das Basis-Topic für Signalduino Nachrichten. -# Nachrichten werden unter $MQTT_TOPIC/ veröffentlicht. -# Befehle werden unter $MQTT_TOPIC/commands/# erwartet. -MQTT_TOPIC=signalduino/messages +# Das Basis-Topic (Root-Präfix) für MQTT-Kommunikation. +# Der Code hängt automatisch '/v1' an, um das Basis-Topic zu versionieren (z.B. 'signalduino/v1'). +# Nachrichten werden unter $MQTT_TOPIC/v1/state/messages veröffentlicht. +# Befehle werden unter $MQTT_TOPIC/v1/commands/# erwartet. +MQTT_TOPIC=signalduino # Signalduino Verbindungseinstellungen (für direkte Verwendung in main.py) # Wähle entweder eine serielle Verbindung ODER eine TCP-Verbindung. diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8d900d9..ec3606c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -20,12 +20,18 @@ jobs: with: ruby-version: 3.4 + # INSTALLATION: Installiere asciidoctor-kroki Gem für Mermaid-Unterstützung + - name: Install Asciidoctor Kroki Gem + run: gem install asciidoctor-kroki + - uses: reitzig/actions-asciidoctor@v2.0.2 with: version: 2.0.26 - - name: run asciidoctor - run: asciidoctor -R docs -D build/site/html -a docinfo=shared -a toc=left -a toclevels=2 'docs/index.adoc' + - 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: asciidoctor -R docs -D build/site/html -a docinfo=shared -a toc=left -a toclevels=2 -r asciidoctor-kroki -a kroki= 'docs/index.adoc' - name: Setup Python for Sitemap Generation uses: actions/setup-python@v5 diff --git a/docs/01_user_guide/index.adoc b/docs/01_user_guide/index.adoc index aea98d4..0fd85d1 100644 --- a/docs/01_user_guide/index.adoc +++ b/docs/01_user_guide/index.adoc @@ -71,10 +71,10 @@ Die Hauptkomponenten sind: Für einen schnellen Einstieg folgen Sie diesen Schritten: -1. **Installation**: Siehe link:installation.adoc[Installationsanleitung]. -2. **Konfiguration**: Setzen Sie die erforderlichen Umgebungsvariablen (z.B. `SIGNALDUINO_SERIAL_PORT`, `MQTT_HOST`). -3. **Programm starten**: Führen Sie `python3 main.py` aus. -4. **MQTT‑Nachrichten überwachen**: Abonnieren Sie das Topic `signalduino/messages`, um dekodierte Signale zu empfangen. +. **Installation**: Siehe link:installation.adoc[Installationsanleitung]. +. **Konfiguration**: Setzen Sie die erforderlichen Umgebungsvariablen (z.B. `SIGNALDUINO_SERIAL_PORT`, `MQTT_HOST`). +. **Programm starten**: Führen Sie `python3 main.py` aus. +. **MQTT‑Nachrichten überwachen**: Abonnieren Sie das Topic `signalduino/messages`, um dekodierte Signale zu empfangen. Ausführliche Anleitungen finden Sie in den folgenden Kapiteln. diff --git a/docs/01_user_guide/installation.adoc b/docs/01_user_guide/installation.adoc index 3c920ac..755b024 100644 --- a/docs/01_user_guide/installation.adoc +++ b/docs/01_user_guide/installation.adoc @@ -1,8 +1,9 @@ -= Installation +== Installation [NOTE] ==== -PySignalduino ist noch in Entwicklung. Es gibt bisher keine stabile Version – nutzen Sie die Software mit entsprechender Vorsicht. +PySignalduino ist noch in Entwicklung. +Es gibt bisher keine stabile Version – nutzen Sie die Software mit entsprechender Vorsicht. ==== == Voraussetzungen @@ -30,7 +31,9 @@ Die einfachste Methode ist die Installation aus dem geklonten Repository im Entw [source,bash] ---- -include::../examples/bash/install_via_pip.sh[] +git clone https://github.com/Ein-Einfaches-Beispiel/PySignalduino.git +cd PySignalduino +pip install -e . ---- Dadurch wird das Paket `signalduino-mqtt` in Ihrer Python-Umgebung installiert und alle Runtime-Abhängigkeiten werden erfüllt. @@ -41,7 +44,7 @@ Falls Sie das Paket nicht installieren, sondern nur die Abhängigkeiten nutzen m [source,bash] ---- -include::../examples/bash/install_requirements.sh[] +pip install -r requirements.txt ---- Die Datei `requirements.txt` enthält die gleichen Pakete wie oben aufgelistet. @@ -52,7 +55,7 @@ Für Beiträge zum Projekt oder zum Ausführen der Tests installieren Sie zusät [source,bash] ---- -include::../examples/bash/install_dev_requirements.sh[] +pip install -r requirements-dev.txt ---- Dies installiert: @@ -68,7 +71,7 @@ Dies installiert: [source,bash] ---- -include::../examples/bash/verify_installation.sh[] +python3 main.py --help ---- Sie sollten eine Ausgabe mit allen verfügbaren Kommandozeilenoptionen sehen. diff --git a/docs/01_user_guide/mqtt_api.adoc b/docs/01_user_guide/mqtt_api.adoc index 4ab6d63..4fc18c6 100644 --- a/docs/01_user_guide/mqtt_api.adoc +++ b/docs/01_user_guide/mqtt_api.adoc @@ -1,8 +1,5 @@ = MQTT API Reference -:doctype: book -:icons: font -:toc: left -:toclevels: 2 +:doctype: book :icons: font :toc: left :toclevels: 2 :sectnums: [[_mqtt_introduction]] @@ -12,7 +9,9 @@ Die MQTT-Schnittstelle ermöglicht die Steuerung des PySignalduino-Gateways und === Topics und Struktur -Die Basis aller Topics ist `/v1`, wobei `` standardmäßig `signalduino` ist. Alle Beispiele verwenden `signalduino/v1` als Basis. +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`. +Alle nachfolgenden Beispiele verwenden `signalduino/v1` als Basis. |=== | Zweck | Topic-Format | Anmerkungen diff --git a/docs/01_user_guide/usage.adoc b/docs/01_user_guide/usage.adoc index 9084a8c..7ac8ae1 100644 --- a/docs/01_user_guide/usage.adoc +++ b/docs/01_user_guide/usage.adoc @@ -54,7 +54,8 @@ include::../../main.py[lines=55..84] ==== Heartbeat-Funktionalität -Der Publisher sendet regelmäßig einen Heartbeat („online“) unter `{topic}/status`, solange die Verbindung besteht. Bei Verbindungsabbruch wird „offline“ gepublished. +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 @@ -106,7 +107,9 @@ Die folgenden Befehle werden unterstützt (Auswahl): ==== 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. +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 diff --git a/docs/02_developer_guide/architecture.adoc b/docs/02_developer_guide/architecture.adoc index 1f70012..9e5c1d2 100644 --- a/docs/02_developer_guide/architecture.adoc +++ b/docs/02_developer_guide/architecture.adoc @@ -2,7 +2,9 @@ == Übersicht -PySignalduino ist modular aufgebaut und trennt die Protokolldefinitionen (JSON) strikt von der Verarbeitungslogik (Python). Seit der Migration zu asyncio (Version 0.9.0) folgt das System einer ereignisgesteuerten, asynchronen Architektur, die auf asyncio-Tasks und -Queues basiert. Dies ermöglicht eine effiziente Verarbeitung von Sensordaten, Kommandos und MQTT-Nachrichten ohne Blockierung. +PySignalduino ist modular aufgebaut und trennt die Protokolldefinitionen (JSON) strikt von der Verarbeitungslogik (Python). +Seit der Migration zu asyncio (Version 0.9.0) folgt das System einer ereignisgesteuerten, asynchronen Architektur, die auf asyncio-Tasks und -Queues basiert. +Dies ermöglicht eine effiziente Verarbeitung von Sensordaten, Kommandos und MQTT-Nachrichten ohne Blockierung. == Kernkomponenten @@ -154,9 +156,10 @@ Die Sitemap wird durch das Python-Skript `tools/generate_sitemap.py` generiert, Das Skript kann manuell ausgeführt werden: -```bash +[source,bash] +---- python tools/generate_sitemap.py --build-dir build/site/html --output sitemap.xml --branch main -``` +---- === robots.txt-Konfiguration diff --git a/docs/02_developer_guide/contribution.adoc b/docs/02_developer_guide/contribution.adoc index 37baf15..fbcb73e 100644 --- a/docs/02_developer_guide/contribution.adoc +++ b/docs/02_developer_guide/contribution.adoc @@ -2,18 +2,19 @@ [NOTE] ==== -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. +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. ==== Beiträge zum Projekt sind willkommen! == Workflow -1. **Fork & Clone:** Projekt forken und lokal klonen. -2. **Branch:** Feature-Branch erstellen (`git checkout -b feature/mein-feature`). -3. **Entwicklung:** Änderungen implementieren. -4. **Tests:** Sicherstellen, dass alle Tests bestehen (`pytest`). -5. **Pull Request:** PR auf GitHub öffnen. +. **Fork & Clone:** Projekt forken und lokal klonen. +. **Branch:** Feature-Branch erstellen (`git checkout -b feature/mein-feature`). +. **Entwicklung:** Änderungen implementieren. +. **Tests:** Sicherstellen, dass alle Tests bestehen (`pytest`). +. **Pull Request:** PR auf GitHub öffnen. == Entwicklungsumgebung @@ -23,7 +24,7 @@ Das Projekt verwendet `poetry` für die Abhängigkeitsverwaltung. Installieren S [source,bash] ---- -include::../../examples/bash/install_dev_deps.sh[] +include::../examples/bash/install_dev_deps.sh[] ---- Oder verwenden Sie `poetry install` (falls Poetry konfiguriert ist). @@ -42,25 +43,37 @@ Das Projekt folgt PEP 8. Verwenden Sie `black` für automatische Formatierung un [source,bash] ---- -include::../../examples/bash/format_code.sh[] +include::../examples/bash/format_code.sh[] ---- Es gibt keine strikte CI-Prüfung, aber konsistenter Stil wird erwartet. +=== Dokumentationsstil + +Für alle AsciiDoc-Dateien im `docs/` Verzeichnis ist die Regel "Ein Satz pro Zeile" verpflichtend. +Dies erleichtert die Überprüfung von Änderungen mittels `git diff`. + +[IMPORTANT] +==== +Jeder Satz muss auf einer neuen Zeile beginnen. +Ein Satz endet typischerweise mit einem Punkt (`.`), Ausrufezeichen (`!`) oder Fragezeichen (`?`). +Achten Sie darauf, dass Codeblöcke und Tabellen nicht betroffen sind. +==== + == Tests ausführen Das Projekt nutzt `pytest`. Stellen Sie sicher, dass `requirements-dev.txt` installiert ist. [source,bash] ---- -include::../../examples/bash/run_pytest.sh[] +include::../examples/bash/run_pytest.sh[] ---- Für spezifische Testmodule: [source,bash] ---- -include::../../examples/bash/run_specific_tests.sh[] +include::../examples/bash/run_specific_tests.sh[] ---- === Asyncio-Tests @@ -91,7 +104,7 @@ Coverage-Bericht generieren: [source,bash] ---- -include::../../examples/bash/coverage_report.sh[] +include::../examples/bash/coverage_report.sh[] ---- Der Bericht wird im Verzeichnis `htmlcov/` erstellt. diff --git a/docs/02_developer_guide/index.adoc b/docs/02_developer_guide/index.adoc index 526e51b..bff708f 100644 --- a/docs/02_developer_guide/index.adoc +++ b/docs/02_developer_guide/index.adoc @@ -2,8 +2,7 @@ Dieser Abschnitt beschreibt die Architektur, wie man zur Entwicklung beitragen kann (Contributing) und wie man Tests durchführt. -include::architecture.adoc[] -include::contribution.adoc[] +include::architecture.adoc[] include::contribution.adoc[] == Weitere Ressourcen diff --git a/docs/03_protocol_reference/protocol_details.adoc b/docs/03_protocol_reference/protocol_details.adoc index 6f6f6fe..66d0fef 100644 --- a/docs/03_protocol_reference/protocol_details.adoc +++ b/docs/03_protocol_reference/protocol_details.adoc @@ -22,6 +22,6 @@ Die Datei `sd_protocols/protocols.json` ist die definitive Quelle für alle Prot == Neues Protokoll hinzufügen -1. Definition in `protocols.json` ergänzen. -2. Dekodierungsmethode implementieren (z.B. in `sd_protocols/manchester.py`). -3. Tests hinzufügen. \ No newline at end of file +. Definition in `protocols.json` ergänzen. +. Dekodierungsmethode implementieren (z.B. in `sd_protocols/manchester.py`). +. Tests hinzufügen. \ No newline at end of file diff --git a/docs/architecture/decisions/ADR-001-mqtt-get-frequency.adoc b/docs/architecture/decisions/ADR-001-mqtt-get-frequency.adoc index 117dd3e..f65c66e 100644 --- a/docs/architecture/decisions/ADR-001-mqtt-get-frequency.adoc +++ b/docs/architecture/decisions/ADR-001-mqtt-get-frequency.adoc @@ -1,7 +1,5 @@ = 001. Implementierung des MQTT-Befehls get/frequency -:author: Roo -:revdate: 2026-01-03 -:status: Accepted +:author: Roo :revdate: 2026-01-03 :status: Accepted [[status]] == Status @@ -26,9 +24,9 @@ $$f_{RF} = \frac{26}{65536} \times F_{REG} \, \text{MHz}$$ Wir implementieren den `get/frequency` Befehl als Teil der `MqttHandler`- und `Commands`-Klassen. -1. *MQTT Topic*: Der Befehl wird über `cmd/get/frequency` empfangen (komplettes Topic: `/commands/get/frequency`). -2. *Antwort Topic*: Die Antwort wird über das etablierte Antwort-Topic (`/responses`) veröffentlicht, um Konsistenz mit dem bestehenden `get/system/version` Befehl zu gewährleisten. Der Payload muss das Feld `command` enthalten, um die Herkunft zu kennzeichnen. -3. *Berechnungslogik*: Die Berechnung wird exakt nach der CC1101-Formel unter Verwendung von $F_{XOSC} = 26 \, \text{MHz}$ durchgeführt. +. *MQTT Topic*: Der Befehl wird über `cmd/get/frequency` empfangen (komplettes Topic: `/commands/get/frequency`). +. *Antwort Topic*: Die Antwort wird über das etablierte Antwort-Topic (`/responses`) veröffentlicht, um Konsistenz mit dem bestehenden `get/system/version` Befehl zu gewährleisten. Der Payload muss das Feld `command` enthalten, um die Herkunft zu kennzeichnen. +. *Berechnungslogik*: Die Berechnung wird exakt nach der CC1101-Formel unter Verwendung von $F_{XOSC} = 26 \, \text{MHz}$ durchgeführt. * Wir erstellen eine asynchrone Methode in `signalduino/hardware.py` (z.B. `get_frequency_registers()`) zum Auslesen von FREQ2, FREQ1, FREQ0. * 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. diff --git a/docs/architecture/decisions/ADR-002-mqtt-command-dispatcher.adoc b/docs/architecture/decisions/ADR-002-mqtt-command-dispatcher.adoc index 01600cd..7f10576 100644 --- a/docs/architecture/decisions/ADR-002-mqtt-command-dispatcher.adoc +++ b/docs/architecture/decisions/ADR-002-mqtt-command-dispatcher.adoc @@ -1,10 +1,5 @@ = ADR 002: Verwendung des MqttCommandDispatcher für die MQTT-Befehlsbehandlung -:doctype: article -:encoding: utf-8 -:lang: de -:status: Accepted -:decided-at: 2026-01-04 -:decided-by: Roo (Architekt) +:doctype: article :encoding: utf-8 :lang: de :status: Accepted :decided-at: 2026-01-04 :decided-by: Roo (Architekt) [[kontext]] == Kontext @@ -20,9 +15,9 @@ Die zentrale Verwaltung der Befehle und deren Validierung ist eine bewährte Met Die hartcodierte `if/elif`-Logik in `signalduino/mqtt.py` wird durch die Verwendung des `MqttCommandDispatcher` ersetzt. -1. Der `MqttPublisher` in `signalduino/mqtt.py` wird eine Instanz des `MqttCommandDispatcher` erhalten. -2. Die Methode `_handle_command` in `MqttPublisher` wird umgeschrieben, um den eingehenden Befehlspfad und Payload direkt an `MqttCommandDispatcher.dispatch()` zu übergeben. -3. Die Fehler- und Erfolgsantworten werden vom `MqttCommandDispatcher` zurückgegeben und von `MqttPublisher` an die entsprechenden MQTT-Topics (`/responses` und `/errors`) publiziert. +. Der `MqttPublisher` in `signalduino/mqtt.py` wird eine Instanz des `MqttCommandDispatcher` erhalten. +. Die Methode `_handle_command` in `MqttPublisher` wird umgeschrieben, um den eingehenden Befehlspfad und Payload direkt an `MqttCommandDispatcher.dispatch()` zu übergeben. +. Die Fehler- und Erfolgsantworten werden vom `MqttCommandDispatcher` zurückgegeben und von `MqttPublisher` an die entsprechenden MQTT-Topics (`/responses` und `/errors`) publiziert. [[konsequenzen]] == Konsequenzen @@ -40,4 +35,4 @@ Die hartcodierte `if/elif`-Logik in `signalduino/mqtt.py` wird durch die Verwend [[alternativen]] == Alternativen * **Beibehaltung der if/elif-Kette:** Dies wurde abgelehnt, da es gegen die Prinzipien der Wartbarkeit und der Single Responsibility Principle (SRP) verstößt. -* **Anderer Dispatch-Mechanismus:** Die Verwendung des vorhandenen `MqttCommandDispatcher` ist die pragmatischste Lösung, da die Klasse bereits existiert und die Validierungsinfrastruktur bietet. +* **Anderer Dispatch-Mechanismus:** Die Verwendung des vorhandenen `MqttCommandDispatcher` ist die pragmatischste Lösung, da die Klasse bereits existiert und die Validierungsinfrastruktur bietet. \ No newline at end of file diff --git a/docs/architecture/decisions/ADR-003-cc1101-parameter-set-logic.adoc b/docs/architecture/decisions/ADR-003-cc1101-parameter-set-logic.adoc index 718dcb8..beb0a99 100644 --- a/docs/architecture/decisions/ADR-003-cc1101-parameter-set-logic.adoc +++ b/docs/architecture/decisions/ADR-003-cc1101-parameter-set-logic.adoc @@ -1,19 +1,20 @@ = 003. Verwendung von CC1101-Standardformeln für Frequenz und Datenrate -:revdate: 2026-01-04 -:status: Accepted +:revdate: 2026-01-04 :status: Accepted == Context Die Implementierung der MQTT SET-Befehle für CC1101-Parameter (Frequenz, Datenrate) erfordert die Umrechnung von physikalischen Werten (MHz, kBaud) in die spezifischen Registerwerte des CC1101-Chips. Andere Parameter wie Bandbreite, Sensitivity und Rampl verwendeten früher spezielle, abstraktere Kommandos des Signalduino-Firmware-Protokolls (`C101`, `X4C`, `X5C`). -Um die Steuerung der CC1101-Parameter zu konsolidieren, wurden die Spezialbefehle (`X4C`, `X5C`) in der Python-Implementierung durch generische Register-Writes (`W`) ersetzt, wobei die Umrechnungslogik (z.B. Index in Registerwert) in Python implementiert wurde. +Um die Steuerung der CC1101-Parameter zu konsolidieren, wurden die Spezialbefehle (`X4C`, `X5C`) in der Python-Implementierung durch generische Register-Writes (`W`) ersetzt, wobei die Umrechnungslogik (z.B. +Index in Registerwert) in Python implementiert wurde. Für Frequenz und Datenrate existiert keine solche Abstraktion im Signalduino-Protokoll, oder die vorhandene Logik ist unvollständig/unzureichend für eine präzise Steuerung. == Decision -Die Umrechnung von Frequenz (MHz) in die drei Registerwerte (FREQ2, FREQ1, FREQ0) und die Umrechnung der Datenrate (kBaud) in MDMCFG4/MDMCFG3-Registerwerte erfolgt *direkt* in der Python-Implementierung von `SignalduinoCommands` unter Verwendung der im CC1101-Datenblatt definierten Standardformeln (z.B. Freq = f_xosc * FREQ / 2^16). +Die Umrechnung von Frequenz (MHz) in die drei Registerwerte (FREQ2, FREQ1, FREQ0) und die Umrechnung der Datenrate (kBaud) in MDMCFG4/MDMCFG3-Registerwerte erfolgt *direkt* in der Python-Implementierung von `SignalduinoCommands` unter Verwendung der im CC1101-Datenblatt definierten Standardformeln (z.B. +Freq = f_xosc * FREQ / 2^16). Diese Registerwerte werden dann über generische CC1101-Schreibbefehle des Signalduino-Protokolls (`W`) übertragen. @@ -28,4 +29,4 @@ Nach dem Senden aller Register-SET-Befehle muss die Methode `SignalduinoCommands * **Alternative 1: Nur Signalduino-Spezialbefehle verwenden:** * _Ablehnungsgrund:_ Für Frequenz und Datenrate gibt es keine oder keine ausreichend präzisen/dokumentierten Signalduino-Spezialbefehle, die eine Einstellung über MQTT in physikalischen Einheiten (MHz, kBaud) ermöglichen. * **Alternative 2: Berechnung in die Controller-Klasse verschieben:** - * _Ablehnungsgrund:_ Die `SignalduinoCommands`-Klasse ist der logische Ort für die Umrechnung von physikalischen Einheiten in serielle Protokolle, da sie die Schnittstelle zum physischen Gerät darstellt. Die `SignalduinoController`-Klasse soll nur die MQTT-Payload entpacken. + * _Ablehnungsgrund:_ Die `SignalduinoCommands`-Klasse ist der logische Ort für die Umrechnung von physikalischen Einheiten in serielle Protokolle, da sie die Schnittstelle zum physischen Gerät darstellt. Die `SignalduinoController`-Klasse soll nur die MQTT-Payload entpacken. \ No newline at end of file diff --git a/docs/architecture/proposals/mqtt_factory_reset_and_settings.adoc b/docs/architecture/proposals/mqtt_factory_reset_and_settings.adoc index 021a4b1..8b9be5b 100644 --- a/docs/architecture/proposals/mqtt_factory_reset_and_settings.adoc +++ b/docs/architecture/proposals/mqtt_factory_reset_and_settings.adoc @@ -1,12 +1,5 @@ = Architektur-Proposal: MQTT-basierter Factory Reset und Hardware-Status -:doctype: article -:encoding: utf-8 -:lang: de -:author: Roo (Architekt) -:email: roo@pythonsignalduino.com -:revnumber: 1.0 -:revdate: 2026-01-04 -:xrefstyle: full +:doctype: article :encoding: utf-8 :lang: de :author: Roo (Architekt) :email: roo@pythonsignalduino.com :revnumber: 1.0 :revdate: 2026-01-04 :xrefstyle: full [[status]] == Status @@ -156,4 +149,4 @@ Es wird ein kleines Python-Helfer-Tool (z.B. `signalduino-mqtt-cli`) entworfen, * `sd-mqtt-cli get hardware-status --req-id --parameter bandwidth` (Sendet `get/cc1101/bandwidth`) * `sd-mqtt-cli get hardware-status --all --req-id ` (Optional: Implementiert einen Batch-Abruf oder ruft alle einzelnen GET-Befehle sequenziell ab und gibt das konsolidierte Ergebnis aus.) -Dieses Tool würde die `MqttPublisher` Logik des Hauptprogramms in einem CLI-Kontext nachbilden, um PUBLISH/SUBSCRIBE für Request/Response zu handhaben. +Dieses Tool würde die `MqttPublisher` Logik des Hauptprogramms in einem CLI-Kontext nachbilden, um PUBLISH/SUBSCRIBE für Request/Response zu handhaben. \ No newline at end of file diff --git a/docs/architecture/proposals/mqtt_get_frequency.adoc b/docs/architecture/proposals/mqtt_get_frequency.adoc index 861e799..4ef3604 100644 --- a/docs/architecture/proposals/mqtt_get_frequency.adoc +++ b/docs/architecture/proposals/mqtt_get_frequency.adoc @@ -1,10 +1,7 @@ = Architektur-Proposal: MQTT-Kommando `get/cc1101/frequency` -:author: Roo -:revdate: 2026-01-03 -:page-layout: proposal +:author: Roo :revdate: 2026-01-03 :page-layout: proposal :sectnums: -:toc: left -:toclevels: 3 +:toc: left :toclevels: 3 [[section-hintergrund]] == 1. Hintergrund und Motivation @@ -16,9 +13,9 @@ Dieses Proposal beschreibt die Implementierung des MQTT-Kommandos `get/cc1101/fr Der Befehl wird über das MQTT-Topic `[base_topic]/commands/get/cc1101/frequency` empfangen und löst eine Kette von Funktionsaufrufen aus: -1. *`signalduino/mqtt.py`*: Empfängt das Kommando und ruft die Kommando-Logik auf. -2. *`signalduino/commands.py`*: Implementiert die High-Level-Logik, welche die Registerwerte von der Hardware abruft und die Frequenz berechnet. -3. *`signalduino/hardware.py`*: Stellt eine neue Methode zum Lesen der FREQ2, FREQ1 und FREQ0 Register bereit. +. *`signalduino/mqtt.py`*: Empfängt das Kommando und ruft die Kommando-Logik auf. +. *`signalduino/commands.py`*: Implementiert die High-Level-Logik, welche die Registerwerte von der Hardware abruft und die Frequenz berechnet. +. *`signalduino/hardware.py`*: Stellt eine neue Methode zum Lesen der FREQ2, FREQ1 und FREQ0 Register bereit. Das Ergebnis wird als JSON-Objekt auf dem zentralen Antwort-Topic (`/responses`) veröffentlicht, um Konsistenz mit bestehenden Befehlen zu gewährleisten. @@ -213,4 +210,4 @@ sequenceDiagram C-->>M: frequency_mhz (float) M->>M: Erstelle JSON Payload {command: "get/cc1101/frequency", success: true, req_id: "...", payload: {frequency_mhz: 433.920}} M->>U: PUBLISH /responses {payload} ----- +---- \ No newline at end of file diff --git a/docs/architecture/proposals/mqtt_set_commands.adoc b/docs/architecture/proposals/mqtt_set_commands.adoc index 9d78357..b264042 100644 --- a/docs/architecture/proposals/mqtt_set_commands.adoc +++ b/docs/architecture/proposals/mqtt_set_commands.adoc @@ -5,7 +5,10 @@ // Absicht und Zielsetzung == 1. Zielsetzung und Scope -Dieses Architekturproposal beschreibt die Implementierung der CC1101-Parameter-Set-Befehle über MQTT. Die Funktionalität umfasst das Setzen von Frequenz, Bandbreite, Datenrate, Sensitivity und Ramping-Level (Rampl). Das Ziel ist es, eine konsistente, zuverlässige Kette vom MQTT-Topic bis zum seriellen Kommando an den Signalduino zu gewährleisten. + +Dieses Architekturproposal beschreibt die Implementierung der CC1101-Parameter-Set-Befehle über MQTT. +Die Funktionalität umfasst das Setzen von Frequenz, Bandbreite, Datenrate, Sensitivity und Ramping-Level (Rampl). +Das Ziel ist es, eine konsistente, zuverlässige Kette vom MQTT-Topic bis zum seriellen Kommando an den Signalduino zu gewährleisten. == 2. Betroffene Komponenten |=== @@ -101,9 +104,9 @@ Das Feld `req_id` in allen MQTT-Command-Payloads (sowohl `set/...` als auch `get * **Antwort:** Bei Fehlen der `req_id` in der Anfrage wird das Feld `req_id` in der Antwort-Payload (Topics `responses` und `errors`) den Wert `null` (JSON null) annehmen. == 4. Fehlerbehandlung und Validierung -1. **Validierung (Dispatcher):** Die MQTT-Payloads werden durch das in [`SignalduinoCommands.COMMAND_MAP`](signalduino/commands.py) definierte `schema` (z.B. `FREQ_SCHEMA`, `DATARATE_SCHEMA`) vor dem Aufruf der Controller-Methode validiert. -2. **Serial-Kommunikation:** `SignalduinoCommands._send_command` wird bei Timeout eine `SignalduinoCommandTimeout` werfen. Diese wird im `SignalduinoController` gefangen und als NACK-Statusmeldung zurückgegeben. -3. **`cc1101_write_init`:** Nach jedem Set-Vorgang muss `SignalduinoCommands.cc1101_write_init()` aufgerufen werden, um die CC1101-Konfiguration erneut in das Chip-Register zu schreiben und die Änderungen zu aktivieren. +. **Validierung (Dispatcher):** Die MQTT-Payloads werden durch das in [`SignalduinoCommands.COMMAND_MAP`](signalduino/commands.py) definierte `schema` (z.B. `FREQ_SCHEMA`, `DATARATE_SCHEMA`) vor dem Aufruf der Controller-Methode validiert. +. **Serial-Kommunikation:** `SignalduinoCommands._send_command` wird bei Timeout eine `SignalduinoCommandTimeout` werfen. Diese wird im `SignalduinoController` gefangen und als NACK-Statusmeldung zurückgegeben. +. **`cc1101_write_init`:** Nach jedem Set-Vorgang muss `SignalduinoCommands.cc1101_write_init()` aufgerufen werden, um die CC1101-Konfiguration erneut in das Chip-Register zu schreiben und die Änderungen zu aktivieren. == 5. Teststrategie * **Unit Tests (`tests/test_mqtt_cc1101.py` oder neu: `tests/test_set_commands.py`):** @@ -113,4 +116,4 @@ Das Feld `req_id` in allen MQTT-Command-Payloads (sowohl `set/...` als auch `get - Testen des gesamten Flows vom MQTT-Topic bis zur Befehlsausführung, indem `_send_command` gemockt und die Argumente geprüft werden. == 6. Konformitätsprüfung -Dieses Proposal ist konform mit dem "Architecture-First Development Process". Die Architekturentscheidungen werden vor der Implementierung getroffen und dokumentiert. +Dieses Proposal ist konform mit dem "Architecture-First Development Process". Die Architekturentscheidungen werden vor der Implementierung getroffen und dokumentiert. \ No newline at end of file diff --git a/docs/architecture/templates/adr_template.adoc b/docs/architecture/templates/adr_template.adoc index f671b01..5fa9941 100644 --- a/docs/architecture/templates/adr_template.adoc +++ b/docs/architecture/templates/adr_template.adoc @@ -1,10 +1,5 @@ = ADR {Nummer}: {Titel} -:doctype: article -:encoding: utf-8 -:lang: de -:status: {Status} -:decided-at: {Datum} -:decided-by: {Entscheidungsträger} +:doctype: article :encoding: utf-8 :lang: de :status: {Status} :decided-at: {Datum} :decided-by: {Entscheidungsträger} [[kontext]] == Kontext @@ -31,4 +26,4 @@ [[alternativen]] == Alternativen -{Hier können kurz abgelehnte Alternativen aufgeführt werden.} +{Hier können kurz abgelehnte Alternativen aufgeführt werden.} \ No newline at end of file diff --git a/docs/architecture/templates/proposal_template.adoc b/docs/architecture/templates/proposal_template.adoc index 1f96e2d..a47d5fa 100644 --- a/docs/architecture/templates/proposal_template.adoc +++ b/docs/architecture/templates/proposal_template.adoc @@ -1,12 +1,5 @@ = Architektur-Proposal: {Proposal-Titel} -:doctype: article -:encoding: utf-8 -:lang: de -:author: {Autor} -:email: {Email} -:revnumber: 1.0 -:revdate: {Datum} -:xrefstyle: full +:doctype: article :encoding: utf-8 :lang: de :author: {Autor} :email: {Email} :revnumber: 1.0 :revdate: {Datum} :xrefstyle: full [[status]] == Status @@ -44,6 +37,7 @@ [mermaid] ---- {Mermaid Diagramm} + ---- === 4.2. Sequenz-Diagramm (Mermaid) @@ -71,4 +65,4 @@ [[implementierungsplan]] == 8. Implementierungs-Plan -{High-Level Implementierungsschritte (Verweis auf Implementierungs-Plan in Phase 2).} +{High-Level Implementierungsschritte (Verweis auf Implementierungs-Plan in Phase 2).} \ No newline at end of file diff --git a/docs/index.adoc b/docs/index.adoc index 6de66e1..6d0842d 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -1,12 +1,10 @@ = SIGNALduino - Projektübersicht -:doctype: book -:homepage: index.html -:description: Der SIGNALduino ist ein vielseitiges Funkmodul zum Empfangen und Senden von 433/868MHz Signalen in Smart-Home-Umgebungen wie FHEM. Er dient als Signal-Transceiver und Protokolldekoder. -:keywords: SIGNALduino, FHEM, 433MHz, 868MHz, Smart Home, Funkprotokolle, DIY, Arduino, ESP32 -:toc: left -:toclevels: 2 +:doctype: book :homepage: index.html :description: Der SIGNALduino ist ein vielseitiges Funkmodul zum Empfangen und Senden von 433/868MHz Signalen in Smart-Home-Umgebungen wie FHEM. +:keywords: SIGNALduino, FHEM, 433MHz, 868MHz, Smart Home, Funkprotokolle, DIY, Arduino, ESP32 :toc: left :toclevels: 2 :experimental: +Er dient als Signal-Transceiver und Protokolldekoder. + [[section-uebersicht]] == Zweck und Funktion @@ -17,7 +15,47 @@ Dadurch werden verschiedenste proprietäre Funkprotokolle für die Nutzung in Sm Die verfügbare Hardware-Basis reicht von einfachen Arduino/nanoCUL-Lösungen bis hin zu erweiterten Varianten wie dem Maple-SignalDuino und dem ESP32-SignalDuino, die erweiterte Funktionen (z.B. WLAN) bieten. -image::images/signalduino_uebersicht.png[SIGNALduino Übersicht - Hardware und Funktion] +.Übersicht: Hardware und Funktion + +[mermaid] +---- +graph TD + subgraph "Input (Funksignale)" + A[433/868 MHz Signale] + B[Sensoren / Fernbedienungen] + end + + subgraph "Hardware-Plattform" + C[CC1101 Funkmodul] + D[Arduino Nano] + E[ESP8266 / ESP32] + end + + subgraph "PySignalduino (Software-Verarbeitung)" + F[Empfangen / Senden] + G[Protokolldemodulation] + H[Dekodierung Protokolle] + end + + subgraph "Output (Home Automation)" + I[MQTT Bridge] + J[Serielle Schnittstelle] + K[FHEM / Home Assistant / ioBroker] + end + + A --> C + B --> C + C -- "Funksignale" --> F + D -- "Strom/Schnittstelle" --> F + E -- "Strom/Schnittstelle" --> F + + F -- "Rohdaten" --> G + G -- "Demodulierte Daten" --> H + H -- "Decodierte Nachricht" --> I + H -- "Decodierte Nachricht" --> J + I --> K + J --> K +---- [[section-historie]] == Projektgeschichte und Entwicklung