From eb286eb48551db6d4f84ce924c83dd5e3c05e586 Mon Sep 17 00:00:00 2001 From: sidey79 <7968127+sidey79@users.noreply.github.com> Date: Thu, 4 Dec 2025 22:11:53 +0000 Subject: [PATCH 01/12] docs: added docs for static site generator --- .github/workflows/docs.yml | 47 +++++++++++++++++++ docToolchainConfig.groovy | 18 +++++++ docs/01_user_guide/index.adoc | 7 +++ docs/01_user_guide/installation.adoc | 3 ++ docs/01_user_guide/usage.adoc | 3 ++ docs/02_developer_guide/architecture.adoc | 3 ++ docs/02_developer_guide/contribution.adoc | 3 ++ docs/02_developer_guide/index.adoc | 6 +++ docs/03_protocol_reference/index.adoc | 5 ++ .../protocol_details.adoc | 3 ++ docs/index.adoc | 32 +++++++++++++ 11 files changed, 130 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 docToolchainConfig.groovy create mode 100644 docs/01_user_guide/index.adoc create mode 100644 docs/01_user_guide/installation.adoc create mode 100644 docs/01_user_guide/usage.adoc create mode 100644 docs/02_developer_guide/architecture.adoc create mode 100644 docs/02_developer_guide/contribution.adoc create mode 100644 docs/02_developer_guide/index.adoc create mode 100644 docs/03_protocol_reference/index.adoc create mode 100644 docs/03_protocol_reference/protocol_details.adoc create mode 100644 docs/index.adoc diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..e02d136 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,47 @@ +name: Documentation Build and Deploy + +on: + push: + branches: + - main + workflow_dispatch: + +jobs: + deploy: + runs-on: ubuntu-latest + concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + permissions: + contents: write # Für peaceiris/actions-gh-pages@v3 + pages: write + id-token: write + + steps: + - name: Checkout + uses: actions/checkout@v4 + + # 1. docToolchain benötigt Java (Gradle-Basis) + - name: Setup Java + uses: actions/setup-java@v4 + with: + distribution: 'temurin' + java-version: '17' + + # 2. docToolchain Wrapper herunterladen und ausführbar machen (dtcw) + - name: Download docToolchain Wrapper + run: | + curl -Lo dtcw https://raw.githubusercontent.com/docToolchain/docToolchain/master/dtcw + chmod +x dtcw + + # 3. Dokumentation bauen (Build-Befehl aus docToolchain-Demo) + # Die docToolchainConfig.groovy konfiguriert den Pfad auf 'docs' + - name: Build Documentation + run: ./dtcw buildHtml + + # 4. Deployment zu gh-pages (peaceiris action, wie im Demo-Repo) + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/build/site/html # Ausgabepfad aus docToolchainConfig.groovy + publish_branch: gh-pages \ No newline at end of file diff --git a/docToolchainConfig.groovy b/docToolchainConfig.groovy new file mode 100644 index 0000000..19f7c00 --- /dev/null +++ b/docToolchainConfig.groovy @@ -0,0 +1,18 @@ +// docToolchain configuration file +docToolchain { + // Defines the directory where the documentation source files are located + docDir = "docs" + + // Configure the build to output to build/site/html for GitHub Pages deployment + // (This is the expected artifact path in ./github/workflows/docs.yml) + build.html5.outputDir = 'build/site/html' + + // Configure Asciidoctor to use the :description: and :keywords: attributes + // to generate the meta tags for search engine optimization. + // 'docinfo': 'shared' is key to ensuring document info (like meta tags) is included. + config.asciidoctorConfig = [ + attributes: [ + 'docinfo': 'shared' + ] + ] +} \ No newline at end of file diff --git a/docs/01_user_guide/index.adoc b/docs/01_user_guide/index.adoc new file mode 100644 index 0000000..4eac83f --- /dev/null +++ b/docs/01_user_guide/index.adoc @@ -0,0 +1,7 @@ += Benutzer-Leitfaden +:leveloffset: 1 + +Der Benutzer-Leitfaden enthält Anweisungen zur Installation, Konfiguration und grundlegenden Verwendung von PySignalduino. + +include::installation.adoc[] +include::usage.adoc[] \ No newline at end of file diff --git a/docs/01_user_guide/installation.adoc b/docs/01_user_guide/installation.adoc new file mode 100644 index 0000000..04f6bf7 --- /dev/null +++ b/docs/01_user_guide/installation.adoc @@ -0,0 +1,3 @@ +== Installation + +Details zur Installation von PySignalduino (z.B. mit pip, in FHEM). \ No newline at end of file diff --git a/docs/01_user_guide/usage.adoc b/docs/01_user_guide/usage.adoc new file mode 100644 index 0000000..29e9f7f --- /dev/null +++ b/docs/01_user_guide/usage.adoc @@ -0,0 +1,3 @@ +== Verwendung und Konfiguration + +Beschreibung der grundlegenden API-Nutzung und der Konfigurationsmöglichkeiten. \ No newline at end of file diff --git a/docs/02_developer_guide/architecture.adoc b/docs/02_developer_guide/architecture.adoc new file mode 100644 index 0000000..3e5d7ce --- /dev/null +++ b/docs/02_developer_guide/architecture.adoc @@ -0,0 +1,3 @@ +== Architektur + +Details zum Aufbau von PySignalduino, insbesondere der Manchester Parsing Chain und der Protokoll-Implementierung. \ No newline at end of file diff --git a/docs/02_developer_guide/contribution.adoc b/docs/02_developer_guide/contribution.adoc new file mode 100644 index 0000000..8126e3d --- /dev/null +++ b/docs/02_developer_guide/contribution.adoc @@ -0,0 +1,3 @@ +== Beitrag leisten (Contributing) + +Anleitung, wie man Code beitragen, Probleme melden und Tests schreiben kann. \ No newline at end of file diff --git a/docs/02_developer_guide/index.adoc b/docs/02_developer_guide/index.adoc new file mode 100644 index 0000000..8e4f235 --- /dev/null +++ b/docs/02_developer_guide/index.adoc @@ -0,0 +1,6 @@ += Entwickler-Leitfaden + +Dieser Abschnitt beschreibt die Architektur, wie man zur Entwicklung beitragen kann (Contributing) und wie man Tests durchführt. + +include::architecture.adoc[] +include::contribution.adoc[] \ No newline at end of file diff --git a/docs/03_protocol_reference/index.adoc b/docs/03_protocol_reference/index.adoc new file mode 100644 index 0000000..487328c --- /dev/null +++ b/docs/03_protocol_reference/index.adoc @@ -0,0 +1,5 @@ += Protokoll-Referenz + +Eine detaillierte Referenz aller unterstützten Protokolle, deren Implementierungsdetails und bekannten Einschränkungen. + +include::protocol_details.adoc[] \ No newline at end of file diff --git a/docs/03_protocol_reference/protocol_details.adoc b/docs/03_protocol_reference/protocol_details.adoc new file mode 100644 index 0000000..1b7a8a8 --- /dev/null +++ b/docs/03_protocol_reference/protocol_details.adoc @@ -0,0 +1,3 @@ +== Protokolldetails + +Platzhalter für die detaillierte Beschreibung jedes unterstützten Protokolls. \ No newline at end of file diff --git a/docs/index.adoc b/docs/index.adoc new file mode 100644 index 0000000..3ed205b --- /dev/null +++ b/docs/index.adoc @@ -0,0 +1,32 @@ += 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 +:experimental: + +[[section-uebersicht]] +== Zweck und Funktion + +Der SIGNALduino (bestehend aus Hardware-Stick und Firmware) ist ein leistungsstarkes I/O-Gerät zur Erfassung, zum Empfang und zur Verarbeitung von digitalen Funksignalen (typischerweise 433 MHz und 868 MHz). + +Seine Hauptaufgabe ist es, Funksignale anhand von Mustern zu erkennen und sie in maximal detaillierter Form an die übergeordnete Hausautomations-Software (wie FHEM) zur Dekodierung weiterzugeben. +Dadurch werden verschiedenste proprietäre Funkprotokolle für die Nutzung in Smart-Home-Systemen zugänglich. + +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] + +[[section-protokolle]] +== Unterstützte Protokolle + +Eine breite Palette von Funkprotokollen wird unterstützt und ständig erweitert. +Detaillierte Informationen zu den unterstützten Geräten und Protokollen finden Sie im Benutzerhandbuch. + +[[section-firmware]] +== Firmware + +Die Firmware wird kontinuierlich weiterentwickelt und ist nicht auf jedem prinzipiell geeigneten Gerät lauffähig, da spezifische Anpassungen an die Hardware erforderlich sind. +Es existieren verschiedene, parallel entwickelte Firmware-Versionen (z.B. die Original-Version und erweiterte Versionen wie `SIGNALduinoAdv`). \ No newline at end of file From f99e27fd077d9f4a07892c5198ed82047b49b019 Mon Sep 17 00:00:00 2001 From: sidey79 <7968127+sidey79@users.noreply.github.com> Date: Thu, 4 Dec 2025 22:16:01 +0000 Subject: [PATCH 02/12] feat: run docs pipeline on all branches --- .github/workflows/docs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e02d136..1c8764b 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -4,6 +4,7 @@ on: push: branches: - main + - '**' # Run on all branches for build/test workflow_dispatch: jobs: @@ -40,6 +41,7 @@ jobs: # 4. Deployment zu gh-pages (peaceiris action, wie im Demo-Repo) - name: Deploy to GitHub Pages + if: github.ref == 'refs/heads/main' uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} From c7eca864f4676d85c95a67b5b5222eb7680de2ec Mon Sep 17 00:00:00 2001 From: sidey79 <7968127+sidey79@users.noreply.github.com> Date: Thu, 4 Dec 2025 22:18:04 +0000 Subject: [PATCH 03/12] fix: dtcw url --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 1c8764b..887f605 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -31,7 +31,7 @@ jobs: # 2. docToolchain Wrapper herunterladen und ausführbar machen (dtcw) - name: Download docToolchain Wrapper run: | - curl -Lo dtcw https://raw.githubusercontent.com/docToolchain/docToolchain/master/dtcw + curl -Lo dtcw https://doctoolchain.org/dtcw chmod +x dtcw # 3. Dokumentation bauen (Build-Befehl aus docToolchain-Demo) From 14ff6a71283a9b266383d461ace340e10db187cd Mon Sep 17 00:00:00 2001 From: sidey79 <7968127+sidey79@users.noreply.github.com> Date: Fri, 5 Dec 2025 17:32:34 +0100 Subject: [PATCH 04/12] docs: add meta and correct download --- .github/workflows/docs.yml | 2 +- docs/docinfo.html | 10 ++++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) create mode 100644 docs/docinfo.html diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 887f605..ae310e2 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -31,7 +31,7 @@ jobs: # 2. docToolchain Wrapper herunterladen und ausführbar machen (dtcw) - name: Download docToolchain Wrapper run: | - curl -Lo dtcw https://doctoolchain.org/dtcw + curl -fsSL https://doctoolchain.org/dtcw -o dtcw chmod +x dtcw # 3. Dokumentation bauen (Build-Befehl aus docToolchain-Demo) diff --git a/docs/docinfo.html b/docs/docinfo.html new file mode 100644 index 0000000..f4f77fd --- /dev/null +++ b/docs/docinfo.html @@ -0,0 +1,10 @@ + + + \ No newline at end of file From afe12a0b635c38230b4bced04985dd39cb6d9fb6 Mon Sep 17 00:00:00 2001 From: sidey79 <7968127+sidey79@users.noreply.github.com> Date: Fri, 5 Dec 2025 18:56:17 +0000 Subject: [PATCH 05/12] feat: use asciidoctor --- .github/workflows/docs.yml | 24 ++++++------------------ docToolchainConfig.groovy | 18 ------------------ 2 files changed, 6 insertions(+), 36 deletions(-) delete mode 100644 docToolchainConfig.groovy diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ae310e2..baf4d04 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -21,29 +21,17 @@ jobs: - name: Checkout uses: actions/checkout@v4 - # 1. docToolchain benötigt Java (Gradle-Basis) - - name: Setup Java - uses: actions/setup-java@v4 - with: - distribution: 'temurin' - java-version: '17' - - # 2. docToolchain Wrapper herunterladen und ausführbar machen (dtcw) - - name: Download docToolchain Wrapper - run: | - curl -fsSL https://doctoolchain.org/dtcw -o dtcw - chmod +x dtcw - - # 3. Dokumentation bauen (Build-Befehl aus docToolchain-Demo) - # Die docToolchainConfig.groovy konfiguriert den Pfad auf 'docs' + # 1. Dokumentation mit Asciidoctor bauen (unter Verwendung von Docker) - name: Build Documentation - run: ./dtcw buildHtml + uses: docker://asciidoctor/docker-asciidoctor + with: + args: asciidoctor -R docs -D build/site/html -a docinfo=shared -a toc=left -a toclevels=2 'docs/index.adoc' - # 4. Deployment zu gh-pages (peaceiris action, wie im Demo-Repo) + # 2. Deployment zu gh-pages - name: Deploy to GitHub Pages if: github.ref == 'refs/heads/main' uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./docs/build/site/html # Ausgabepfad aus docToolchainConfig.groovy + publish_dir: ./build/site/html publish_branch: gh-pages \ No newline at end of file diff --git a/docToolchainConfig.groovy b/docToolchainConfig.groovy deleted file mode 100644 index 19f7c00..0000000 --- a/docToolchainConfig.groovy +++ /dev/null @@ -1,18 +0,0 @@ -// docToolchain configuration file -docToolchain { - // Defines the directory where the documentation source files are located - docDir = "docs" - - // Configure the build to output to build/site/html for GitHub Pages deployment - // (This is the expected artifact path in ./github/workflows/docs.yml) - build.html5.outputDir = 'build/site/html' - - // Configure Asciidoctor to use the :description: and :keywords: attributes - // to generate the meta tags for search engine optimization. - // 'docinfo': 'shared' is key to ensuring document info (like meta tags) is included. - config.asciidoctorConfig = [ - attributes: [ - 'docinfo': 'shared' - ] - ] -} \ No newline at end of file From 057b27729446c889079302a14cc2454221f5dd09 Mon Sep 17 00:00:00 2001 From: sidey79 <7968127+sidey79@users.noreply.github.com> Date: Fri, 5 Dec 2025 23:22:28 +0000 Subject: [PATCH 06/12] feat[docs.yml]: use asciidoctor-ghpages-action --- .github/workflows/docs.yml | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index baf4d04..a17c4b3 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -20,18 +20,14 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 - - # 1. Dokumentation mit Asciidoctor bauen (unter Verwendung von Docker) - - name: Build Documentation - uses: docker://asciidoctor/docker-asciidoctor - with: - args: asciidoctor -R docs -D build/site/html -a docinfo=shared -a toc=left -a toclevels=2 'docs/index.adoc' - - # 2. Deployment zu gh-pages - - name: Deploy to GitHub Pages + + + # Includes the AsciiDoctor GitHub Pages Action to convert adoc files to html and publish to gh-pages branch + - name: asciidoctor-ghpages if: github.ref == 'refs/heads/main' - uses: peaceiris/actions-gh-pages@v3 + uses: manoelcampos/asciidoctor-ghpages-action@v2 with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./build/site/html - publish_branch: gh-pages \ No newline at end of file + pdf_build: false + source_dir: docs/ + asciidoctor_attributes: "docinfo=shared toc=left toclevels=2" + \ No newline at end of file From 02c58d4f5337b7db7851b8b2bc42535f125f0e4c Mon Sep 17 00:00:00 2001 From: sidey79 <7968127+sidey79@users.noreply.github.com> Date: Fri, 5 Dec 2025 23:42:07 +0000 Subject: [PATCH 07/12] fix[docs.yml]: fix pipeline --- .github/workflows/docs.yml | 44 +++++++++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 10 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a17c4b3..ce10b11 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -8,7 +8,7 @@ on: workflow_dispatch: jobs: - deploy: + build: runs-on: ubuntu-latest concurrency: group: ${{ github.workflow }}-${{ github.ref }} @@ -20,14 +20,38 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 - - - # Includes the AsciiDoctor GitHub Pages Action to convert adoc files to html and publish to gh-pages branch - - name: asciidoctor-ghpages + + - uses: ruby/setup-ruby@v1 + with: + ruby-version: 2.7 + + - uses: reitzig/actions-asciidoctor@v2.0.2 + with: + version: 2.0.18 + + - name: run asciidoctor + run: asciidoctor -R docs -D build/site/html -a docinfo=shared -a toc=left -a toclevels=2 'docs/index.adoc' + + - name: Add CNAME file + if: github.ref != 'refs/heads/main' + run: echo 'preview.rfd-fhem.github.io' > build/site/html/CNAME" + + - name: Add CNAME file if: github.ref == 'refs/heads/main' - uses: manoelcampos/asciidoctor-ghpages-action@v2 + run: echo 'pysignalduino.rfd-fhem.github.io' > build/site/html/CNAME" + + - name: Upload artifact + uses: actions/upload-pages-artifact@v4 with: - pdf_build: false - source_dir: docs/ - asciidoctor_attributes: "docinfo=shared toc=left toclevels=2" - \ No newline at end of file + path: build/site/html + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file From 922e86f29cd63e744f2d84c6083ff4f603d56272 Mon Sep 17 00:00:00 2001 From: sidey79 <7968127+sidey79@users.noreply.github.com> Date: Fri, 5 Dec 2025 23:43:40 +0000 Subject: [PATCH 08/12] fix: last commit --- .github/workflows/docs.yml | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ce10b11..f9cd277 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -12,11 +12,6 @@ jobs: runs-on: ubuntu-latest concurrency: group: ${{ github.workflow }}-${{ github.ref }} - permissions: - contents: write # Für peaceiris/actions-gh-pages@v3 - pages: write - id-token: write - steps: - name: Checkout uses: actions/checkout@v4 @@ -34,11 +29,11 @@ jobs: - name: Add CNAME file if: github.ref != 'refs/heads/main' - run: echo 'preview.rfd-fhem.github.io' > build/site/html/CNAME" + run: echo 'preview.rfd-fhem.github.io' > "build/site/html/CNAME" - name: Add CNAME file if: github.ref == 'refs/heads/main' - run: echo 'pysignalduino.rfd-fhem.github.io' > build/site/html/CNAME" + run: echo 'pysignalduino.rfd-fhem.github.io' > "build/site/html/CNAME" - name: Upload artifact uses: actions/upload-pages-artifact@v4 @@ -46,6 +41,10 @@ jobs: path: build/site/html deploy: + permissions: + contents: write + pages: write + id-token: write environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} From 9e01d2cbb37e133e9e6339e5a9b61a495d3e3064 Mon Sep 17 00:00:00 2001 From: sidey79 <7968127+sidey79@users.noreply.github.com> Date: Fri, 5 Dec 2025 23:57:10 +0000 Subject: [PATCH 09/12] fix: doc updated --- docs/index.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/index.adoc b/docs/index.adoc index 3ed205b..62bdd5a 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -28,5 +28,4 @@ Detaillierte Informationen zu den unterstützten Geräten und Protokollen finden [[section-firmware]] == Firmware -Die Firmware wird kontinuierlich weiterentwickelt und ist nicht auf jedem prinzipiell geeigneten Gerät lauffähig, da spezifische Anpassungen an die Hardware erforderlich sind. -Es existieren verschiedene, parallel entwickelte Firmware-Versionen (z.B. die Original-Version und erweiterte Versionen wie `SIGNALduinoAdv`). \ No newline at end of file +Die Firmware wird kontinuierlich weiterentwickelt und ist nicht auf jedem prinzipiell geeigneten Gerät lauffähig, da spezifische Anpassungen an die Hardware erforderlich sind. \ No newline at end of file From 370d7e36aa82fedb22bc39498e46fbefac9acbca Mon Sep 17 00:00:00 2001 From: sidey79 <7968127+sidey79@users.noreply.github.com> Date: Sat, 6 Dec 2025 00:25:16 +0000 Subject: [PATCH 10/12] docs: added more --- docs/01_user_guide/installation.adoc | 26 ++++++++++++- docs/01_user_guide/usage.adoc | 38 ++++++++++++++++++- docs/02_developer_guide/architecture.adoc | 32 +++++++++++++++- docs/02_developer_guide/contribution.adoc | 21 +++++++++- .../protocol_details.adoc | 28 +++++++++++++- docs/index.adoc | 12 +++++- 6 files changed, 146 insertions(+), 11 deletions(-) diff --git a/docs/01_user_guide/installation.adoc b/docs/01_user_guide/installation.adoc index 04f6bf7..6458195 100644 --- a/docs/01_user_guide/installation.adoc +++ b/docs/01_user_guide/installation.adoc @@ -1,3 +1,25 @@ -== Installation += Installation -Details zur Installation von PySignalduino (z.B. mit pip, in FHEM). \ No newline at end of file +== Voraussetzungen +* Python 3.8 oder höher +* pip (Python Package Installer) + +== Installation via pip + +Am einfachsten installieren Sie PySignalduino direkt aus dem Repository: + +[source,bash] +---- +git clone https://github.com/Ein-Einfaches-Beispiel/PySignalduino.git +cd PySignalduino +pip install -r requirements.txt +---- + +== Entwicklungsumgebung einrichten + +Für Entwickler empfehlen wir die Installation der zusätzlichen Abhängigkeiten (z.B. für Tests): + +[source,bash] +---- +pip install -r requirements-dev.txt +---- \ No newline at end of file diff --git a/docs/01_user_guide/usage.adoc b/docs/01_user_guide/usage.adoc index 29e9f7f..f1d9915 100644 --- a/docs/01_user_guide/usage.adoc +++ b/docs/01_user_guide/usage.adoc @@ -1,3 +1,37 @@ -== Verwendung und Konfiguration += Verwendung und Konfiguration -Beschreibung der grundlegenden API-Nutzung und der Konfigurationsmöglichkeiten. \ No newline at end of file +== Grundlegende Nutzung + +Die Hauptklasse `SDProtocols` stellt die Schnittstelle zur Protokollverarbeitung bereit. + +[source,python] +---- +from sd_protocols import SDProtocols + +# Protokolle laden +sd = SDProtocols() + +# Verfügbare Protokolle auflisten +print(f"Geladene Protokolle: {len(sd.get_protocol_list())}") + +# Beispiel: Prüfen ob ein Protokoll existiert +# ID 10 = Oregon Scientific v2|v3 +if sd.protocol_exists("10"): + print("Protokoll 10 (Oregon Scientific v2|v3) ist verfügbar.") +---- + +== 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 + +Für Debugging-Zwecke können Sie eine eigene Callback-Funktion registrieren: + +[source,python] +---- +def my_logger(message, level): + print(f"[LOG LEVEL {level}] {message}") + +sd.register_log_callback(my_logger) +---- \ No newline at end of file diff --git a/docs/02_developer_guide/architecture.adoc b/docs/02_developer_guide/architecture.adoc index 3e5d7ce..e20d145 100644 --- a/docs/02_developer_guide/architecture.adoc +++ b/docs/02_developer_guide/architecture.adoc @@ -1,3 +1,31 @@ -== Architektur += Architektur -Details zum Aufbau von PySignalduino, insbesondere der Manchester Parsing Chain und der Protokoll-Implementierung. \ No newline at end of file +== Übersicht + +PySignalduino ist modular aufgebaut und trennt die Protokolldefinitionen (JSON) strikt von der Verarbeitungslogik (Python). + +== Kernkomponenten + +=== SDProtocols Klasse +Die Klasse `SDProtocols` (`sd_protocols/sd_protocols.py`) ist der zentrale Einstiegspunkt. Sie vereint Funktionalitäten durch Mehrfachvererbung von Mixins: + +* **ProtocolHelpersMixin:** Grundlegende Bit-Operationen. +* **ManchesterMixin:** Spezifische Logik für Manchester-kodierte Signale (`mcBit2*` Methoden). +* **PostdemodulationMixin:** Nachbearbeitung dekodierter Daten (`postDemo_*` Methoden). +* **RSLMixin:** Handler für das RSL-Protokoll. + +=== Protokolldefinition (JSON) +Die Datei `sd_protocols/protocols.json` enthält die statischen Definitionen. Jedes Protokoll besitzt eine ID und Eigenschaften wie: + +* `format`: Kodierung (z.B. `manchester`, `twostate`, `pwm`). +* `preamble`: Erkennungsmuster. +* `method`: Mapping auf die Python-Methode zur Dekodierung. + +=== Parsing Chain (Manchester) + +Der Ablauf bei Manchester-Signalen ist wie folgt: +1. **Erkennung:** Match anhand der Preamble/Muster. +2. **Vorvalidierung:** `ManchesterMixin._demodulate_mc_data()` prüft Länge und Taktung. +3. **Dekodierung:** Aufruf der spezifischen `mcBit2*`-Methode. + +*Hinweis:* Einige Protokolle wie TFA (`mcBit2TFA`) oder Grothe (`mcBit2Grothe`) haben spezielle Anforderungen an die Längenprüfung oder Duplikatfilterung. \ No newline at end of file diff --git a/docs/02_developer_guide/contribution.adoc b/docs/02_developer_guide/contribution.adoc index 8126e3d..f1779af 100644 --- a/docs/02_developer_guide/contribution.adoc +++ b/docs/02_developer_guide/contribution.adoc @@ -1,3 +1,20 @@ -== Beitrag leisten (Contributing) += Beitrag leisten (Contributing) -Anleitung, wie man Code beitragen, Probleme melden und Tests schreiben kann. \ No newline at end of file +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. + +== Tests ausführen + +Das Projekt nutzt `pytest`. Stellen Sie sicher, dass `requirements-dev.txt` installiert ist. + +[source,bash] +---- +pytest +---- \ No newline at end of file diff --git a/docs/03_protocol_reference/protocol_details.adoc b/docs/03_protocol_reference/protocol_details.adoc index 1b7a8a8..6f6f6fe 100644 --- a/docs/03_protocol_reference/protocol_details.adoc +++ b/docs/03_protocol_reference/protocol_details.adoc @@ -1,3 +1,27 @@ -== Protokolldetails += Protokolldetails -Platzhalter für die detaillierte Beschreibung jedes unterstützten Protokolls. \ No newline at end of file +PySignalduino unterstützt eine Vielzahl von Funkprotokollen im 433 MHz und 868 MHz Bereich. + +== Protokolldefinition + +Die Datei `sd_protocols/protocols.json` ist die definitive Quelle für alle Protokollparameter (Timings, Preambles, Methoden). + +== Auszug unterstützter Protokolle + +* **ID 10:** Oregon Scientific v2/v3 (Manchester, 433 MHz) +* **ID 13:** Flamingo FA21 Rauchmelder +* **ID 58:** TFA Wettersensoren +* **ID 70:** FHT80TF Tür-/Fensterkontakt (868 MHz) +* **ID 80:** EM1000WZ Energiemonitor + +== Protokoll-Typen + +* **Manchester:** Selbsttaktend (z.B. Oregon, TFA). +* **TwoState / PWM:** Kodierung über Pulslängen. +* **FSK:** Frequenzumtastung (oft bei 868 MHz Geräten wie Lacrosse). + +== 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 diff --git a/docs/index.adoc b/docs/index.adoc index 62bdd5a..33cb071 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -28,4 +28,14 @@ Detaillierte Informationen zu den unterstützten Geräten und Protokollen finden [[section-firmware]] == Firmware -Die Firmware wird kontinuierlich weiterentwickelt und ist nicht auf jedem prinzipiell geeigneten Gerät lauffähig, da spezifische Anpassungen an die Hardware erforderlich sind. \ No newline at end of file +Die Firmware wird kontinuierlich weiterentwickelt und ist nicht auf jedem prinzipiell geeigneten Gerät lauffähig, da spezifische Anpassungen an die Hardware erforderlich sind. + +include::01_user_guide/installation.adoc[] + +include::01_user_guide/usage.adoc[] + +include::02_developer_guide/architecture.adoc[] + +include::02_developer_guide/contribution.adoc[] + +include::03_protocol_reference/protocol_details.adoc[] \ No newline at end of file From 655e9a6f39a36f046565579df4b0600bff70de31 Mon Sep 17 00:00:00 2001 From: sidey79 <7968127+sidey79@users.noreply.github.com> Date: Sat, 6 Dec 2025 00:45:17 +0000 Subject: [PATCH 11/12] chore: update used asciidoc version --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f9cd277..84957f0 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -22,7 +22,7 @@ jobs: - uses: reitzig/actions-asciidoctor@v2.0.2 with: - version: 2.0.18 + 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' From 423e8b95b16d54ec11076274bb32a63f8bdf8bbf Mon Sep 17 00:00:00 2001 From: sidey79 <7968127+sidey79@users.noreply.github.com> Date: Sat, 6 Dec 2025 00:47:45 +0000 Subject: [PATCH 12/12] chore: update ruby version to 3.4 --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 84957f0..9c2d432 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -18,7 +18,7 @@ jobs: - uses: ruby/setup-ruby@v1 with: - ruby-version: 2.7 + ruby-version: 3.4 - uses: reitzig/actions-asciidoctor@v2.0.2 with: