Skip to content

Commit 370d7e3

Browse files
sidey79sidey79
committed
docs: added more
1 parent 9e01d2c commit 370d7e3

File tree

6 files changed

+146
-11
lines changed

6 files changed

+146
-11
lines changed

‎docs/01_user_guide/installation.adoc‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,25 @@
1-
== Installation
1+
= Installation
22

3-
Details zur Installation von PySignalduino (z.B. mit pip, in FHEM).
3+
== Voraussetzungen
4+
* Python 3.8 oder höher
5+
* pip (Python Package Installer)
6+
7+
== Installation via pip
8+
9+
Am einfachsten installieren Sie PySignalduino direkt aus dem Repository:
10+
11+
[source,bash]
12+
----
13+
git clone https://github.com/Ein-Einfaches-Beispiel/PySignalduino.git
14+
cd PySignalduino
15+
pip install -r requirements.txt
16+
----
17+
18+
== Entwicklungsumgebung einrichten
19+
20+
Für Entwickler empfehlen wir die Installation der zusätzlichen Abhängigkeiten (z.B. für Tests):
21+
22+
[source,bash]
23+
----
24+
pip install -r requirements-dev.txt
25+
----

‎docs/01_user_guide/usage.adoc‎

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,37 @@
1-
== Verwendung und Konfiguration
1+
= Verwendung und Konfiguration
22

3-
Beschreibung der grundlegenden API-Nutzung und der Konfigurationsmöglichkeiten.
3+
== Grundlegende Nutzung
4+
5+
Die Hauptklasse `SDProtocols` stellt die Schnittstelle zur Protokollverarbeitung bereit.
6+
7+
[source,python]
8+
----
9+
from sd_protocols import SDProtocols
10+
11+
# Protokolle laden
12+
sd = SDProtocols()
13+
14+
# Verfügbare Protokolle auflisten
15+
print(f"Geladene Protokolle: {len(sd.get_protocol_list())}")
16+
17+
# Beispiel: Prüfen ob ein Protokoll existiert
18+
# ID 10 = Oregon Scientific v2|v3
19+
if sd.protocol_exists("10"):
20+
print("Protokoll 10 (Oregon Scientific v2|v3) ist verfügbar.")
21+
----
22+
23+
== Integration
24+
25+
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.
26+
27+
=== Logging
28+
29+
Für Debugging-Zwecke können Sie eine eigene Callback-Funktion registrieren:
30+
31+
[source,python]
32+
----
33+
def my_logger(message, level):
34+
print(f"[LOG LEVEL {level}] {message}")
35+
36+
sd.register_log_callback(my_logger)
37+
----

‎docs/02_developer_guide/architecture.adoc‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,31 @@
1-
== Architektur
1+
= Architektur
22

3-
Details zum Aufbau von PySignalduino, insbesondere der Manchester Parsing Chain und der Protokoll-Implementierung.
3+
== Übersicht
4+
5+
PySignalduino ist modular aufgebaut und trennt die Protokolldefinitionen (JSON) strikt von der Verarbeitungslogik (Python).
6+
7+
== Kernkomponenten
8+
9+
=== SDProtocols Klasse
10+
Die Klasse `SDProtocols` (`sd_protocols/sd_protocols.py`) ist der zentrale Einstiegspunkt. Sie vereint Funktionalitäten durch Mehrfachvererbung von Mixins:
11+
12+
* **ProtocolHelpersMixin:** Grundlegende Bit-Operationen.
13+
* **ManchesterMixin:** Spezifische Logik für Manchester-kodierte Signale (`mcBit2*` Methoden).
14+
* **PostdemodulationMixin:** Nachbearbeitung dekodierter Daten (`postDemo_*` Methoden).
15+
* **RSLMixin:** Handler für das RSL-Protokoll.
16+
17+
=== Protokolldefinition (JSON)
18+
Die Datei `sd_protocols/protocols.json` enthält die statischen Definitionen. Jedes Protokoll besitzt eine ID und Eigenschaften wie:
19+
20+
* `format`: Kodierung (z.B. `manchester`, `twostate`, `pwm`).
21+
* `preamble`: Erkennungsmuster.
22+
* `method`: Mapping auf die Python-Methode zur Dekodierung.
23+
24+
=== Parsing Chain (Manchester)
25+
26+
Der Ablauf bei Manchester-Signalen ist wie folgt:
27+
1. **Erkennung:** Match anhand der Preamble/Muster.
28+
2. **Vorvalidierung:** `ManchesterMixin._demodulate_mc_data()` prüft Länge und Taktung.
29+
3. **Dekodierung:** Aufruf der spezifischen `mcBit2*`-Methode.
30+
31+
*Hinweis:* Einige Protokolle wie TFA (`mcBit2TFA`) oder Grothe (`mcBit2Grothe`) haben spezielle Anforderungen an die Längenprüfung oder Duplikatfilterung.

‎docs/02_developer_guide/contribution.adoc‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,20 @@
1-
== Beitrag leisten (Contributing)
1+
= Beitrag leisten (Contributing)
22

3-
Anleitung, wie man Code beitragen, Probleme melden und Tests schreiben kann.
3+
Beiträge zum Projekt sind willkommen!
4+
5+
== Workflow
6+
7+
1. **Fork & Clone:** Projekt forken und lokal klonen.
8+
2. **Branch:** Feature-Branch erstellen (`git checkout -b feature/mein-feature`).
9+
3. **Entwicklung:** Änderungen implementieren.
10+
4. **Tests:** Sicherstellen, dass alle Tests bestehen (`pytest`).
11+
5. **Pull Request:** PR auf GitHub öffnen.
12+
13+
== Tests ausführen
14+
15+
Das Projekt nutzt `pytest`. Stellen Sie sicher, dass `requirements-dev.txt` installiert ist.
16+
17+
[source,bash]
18+
----
19+
pytest
20+
----

‎docs/03_protocol_reference/protocol_details.adoc‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,27 @@
1-
== Protokolldetails
1+
= Protokolldetails
22

3-
Platzhalter für die detaillierte Beschreibung jedes unterstützten Protokolls.
3+
PySignalduino unterstützt eine Vielzahl von Funkprotokollen im 433 MHz und 868 MHz Bereich.
4+
5+
== Protokolldefinition
6+
7+
Die Datei `sd_protocols/protocols.json` ist die definitive Quelle für alle Protokollparameter (Timings, Preambles, Methoden).
8+
9+
== Auszug unterstützter Protokolle
10+
11+
* **ID 10:** Oregon Scientific v2/v3 (Manchester, 433 MHz)
12+
* **ID 13:** Flamingo FA21 Rauchmelder
13+
* **ID 58:** TFA Wettersensoren
14+
* **ID 70:** FHT80TF Tür-/Fensterkontakt (868 MHz)
15+
* **ID 80:** EM1000WZ Energiemonitor
16+
17+
== Protokoll-Typen
18+
19+
* **Manchester:** Selbsttaktend (z.B. Oregon, TFA).
20+
* **TwoState / PWM:** Kodierung über Pulslängen.
21+
* **FSK:** Frequenzumtastung (oft bei 868 MHz Geräten wie Lacrosse).
22+
23+
== Neues Protokoll hinzufügen
24+
25+
1. Definition in `protocols.json` ergänzen.
26+
2. Dekodierungsmethode implementieren (z.B. in `sd_protocols/manchester.py`).
27+
3. Tests hinzufügen.

‎docs/index.adoc‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,4 +28,14 @@ Detaillierte Informationen zu den unterstützten Geräten und Protokollen finden
2828
[[section-firmware]]
2929
== Firmware
3030

31-
Die Firmware wird kontinuierlich weiterentwickelt und ist nicht auf jedem prinzipiell geeigneten Gerät lauffähig, da spezifische Anpassungen an die Hardware erforderlich sind.
31+
Die Firmware wird kontinuierlich weiterentwickelt und ist nicht auf jedem prinzipiell geeigneten Gerät lauffähig, da spezifische Anpassungen an die Hardware erforderlich sind.
32+
33+
include::01_user_guide/installation.adoc[]
34+
35+
include::01_user_guide/usage.adoc[]
36+
37+
include::02_developer_guide/architecture.adoc[]
38+
39+
include::02_developer_guide/contribution.adoc[]
40+
41+
include::03_protocol_reference/protocol_details.adoc[]

0 commit comments

Comments
 (0)