Roadmap

doc/docs/javascripts/mathjax.js

@@ -0,0 +1,19 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => { 
+  MathJax.startup.output.clearCache()
+  MathJax.typesetClear()
+  MathJax.texReset()
+  MathJax.typesetPromise()
+})

doc/docs/konzept_hardware.md

@@ -1,6 +1,8 @@
-# Hardware Konzept
+# Hardware-Konzept
 
-Dieses Diagramm zeigt die Verknüpfung zwischen dem Leader, den Westen und den zugewiesenen Waffen.
+## 1. Systemübersicht
+
+Das Lasertag-System besteht aus einer hierarchischen Architektur, bei der ein Leader-Element mehrere Westeneinheiten mit zugeordneten Waffensystemen steuert.
 
 ```mermaid
 graph TD
@@ -17,5 +19,100 @@ graph TD
     %% Styling (Optional)
     %% style Leader fill:#f96,stroke:#333,stroke-width:2px
     %% style Weste1 fill:#bbf,stroke:#333
-    %% style Weste2 fill:#bbf,stroke:#333 -->
+    %%       style Weste2 fill:#bbf,stroke:#333 -->
 ```
+## 2. Schaltungskomponenten
+
+### 2.1 LED-Treiber
+
+#### Grundkonzept
+
+Der LED-Treiber realisiert eine präzise Konstantstromquelle als Hybridschaltung aus PNP- und NPN-Transistoren. Diese Architektur ermöglicht eine stabile und effiziente Ansteuerung von Infrarot-Leuchtdioden mit definierten Stromwerten.
+
+![LED DRIVER](img/concept_hardware_led_driver.svg)
+
+#### Stromeinstelling
+
+Der Zielstrom wird über den Messwiderstand $R_{set}$ eingestellt. Die Berechnung folgt der Formel:
+
+$$R_{set} = \frac{0,65V}{I_{LED}}$$
+
+Die folgenden Tabelle zeigt typische Stromwerte, die erforderlichen Widerstände und die entsprechenden Anwendungsfälle:
+
+| Stromstärke ($I_{LED}$) | Widerstand ($R_{set}$) | Ausgangsleistung ($P_{min}$) | Einsatzbereich |
+| :--- | :--- | :--- | :--- |
+| 0,5 A | 1,30 $\Omega$ | 0,5 W | Standard / Nahkampf |
+| 1,0 A | 0,65 $\Omega$ | 1,0 W | Hohe Reichweite (SFH 4550) |
+| 2,0 A | 0,33 $\Omega$ | 2,0 W | Extrem hohe Leistung (Pulsbetrieb) |
+| 3,0 A | 0,22 $\Omega$ | 3,0 W | Scharfschützen-Modus (Oslon Black) |
+
+#### Thermische Betrachtung
+
+Im Lasertag-Betrieb werden die Infrarot-Signale hochfrequent moduliert (beispielsweise mit 38 kHz). Dies führt zu einem signifikant geringeren mittleren Wärmeeintrag in den Messwiderstand als eine kontinuierliche Strombelastung suggeriert:
+
+$$P_{avg} = (R_{set} \cdot I_{LED}^2) \cdot \text{Duty Cycle}$$
+
+!!! info "Bedeutung der Widerstandsspezifikation"
+    Obwohl die Duty-Cycle-Modulation die durchschnittliche Verlustleistung reduziert, müssen Widerstände für $R_{set}$ für die auftretenden Stromspitzen ausgelegt sein. Wir empfehlen impulsfeste Typen (Metallschicht- oder Drahtwiderständen), um die Stromspitzen bis zu 3 A ohne Materialermüdung zu verkraften.
+
+#### Spannungsversorgung und Headroom-Anforderungen
+
+Die Konstantstromquelle benötigt eine Mindestverspannung zwischen Versorgung und Ausgang, um präzise die Sollstromstärke zu halten. Diese sogenannte Headroom-Spannung errechnet sich aus:
+
+$$V_{CC} > V_{f(\text{LED})} + 0,65V + 1,0V_{\text{Headroom}}$$
+
+**Kritischer Aspekt bei Lithium-Ionen-Akkus:** Die Akkuspannung sinkt während der Entladung kontinuierlich. Unterschreitet $V_{CC}$ den erforderlichen Schwellwert, bricht die Regelung zusammen und der LED-Strom kann die Sollvorgabe nicht mehr erreichen. Dies führt zu einer drastischen Reduktion der Reichweite des Senders.
+
+Die Minimalspannung für stabilen Betrieb wird bestimmt durch:
+
+$$V_{CC,\text{min}} = V_{f(\text{LED})} + V_{R_{set}} + V_{\text{Headroom}}$$
+
+Die folgende Tabelle zeigt die erforderlichen Minimalspannungen für verschiedene Stromvorgaben und die Eignung unterschiedlicher Akkusysteme:
+
+| Stromstärke ($I_{LED}$) | Typ. LED-Spannung ($V_{f}$) | Erforderliche Spannung ($V_{CC,\text{min}}$) | Akku-Empfehlung |
+| :--- | :--- | :--- | :--- |
+| 0,5 A | ~2,0 V | 3,65 V | 1S (nur bei voller Ladung) |
+| 1,0 A | ~2,4 V | 4,05 V | 2S empfohlen |
+| 2,0 A | ~2,8 V | 4,45 V | 2S erforderlich |
+| 3,0 A | ~3,2 V | 4,85 V | 2S erforderlich |
+
+!!! warning "1S-System: Einschränkungen unter Last"
+    Ein einzelner 1S Li-Po Akku sinkt unter hohen Stromlasten schnell auf 3,4 V bis 3,6 V ab. Für konstante Reichweite bei Strömen ab 1 A ist ein 2S-System daher technisch überlegen.
+
+#### 2S-Akkusystem: Komplexität und Lösungsansätze
+
+Ein 2S-Akkusystem bietet zwar Spannungsstabilität, erfordert jedoch anspruchsvollere Schutz- und Überwachungsfunktionen:
+
+- **Laden:** Moderne 2S-Ladechips mit integriertem Balancing (beispielsweise der IP2326) ermöglichen vereinfachte Ladevorgänge.
+- **Zellenschutz:** Ein Zellenschutz-IC wie der HY2120-CB in Kombination mit einem Dual-Channel MOSFET (beispielsweise FS8205A) verhindert Über- und Unterspannungszustände.
+- **Fuel Gauge:** Spezielle Fuel-Gauge-ICs für 2S-Systeme sind selten oder komplex. Als praktische Alternative wird eine Spannungsteiler-ADC-Messung zur Ladezustandsabschätzung eingesetzt. Der Spannungsteiler muss durch ein Schaltgattersystem steuerbar sein.
+
+### 2.2 Akku-Überwachung (Fuel Gauge)
+
+#### Spannungsmessung bei 2S-Akkus
+
+Für 2S-Akkusysteme mit Spannungen bis 8,4 V wird die Akkuspannung über einen Spannungsteiler auf den ADC-Eingangspegel reduziert. Dieser Messwert dient zur Ladezustandsabschätzung und Fehlerdiagnose.
+
+#### Schaltungskomponenten
+
+| Komponente | Wert | Funktion |
+| :--- | :--- | :--- |
+| $R_1$ | 100 k$\Omega$ | Spannungsteiler – oberer Zweig |
+| $R_2$ | 47 k$\Omega$ | Spannungsteiler – unterer Zweig |
+| $C_1$ | 100 nF | Glättungskondensator am ADC-Eingang |
+
+#### Softwarelogik
+
+Die Ladezustandsbestimmung erfolgt in drei Schritten:
+
+1. **ADC-Konvertierung:** Der Rohwert des ADC-Eingangs wird eingelesen.
+
+2. **Spannungsrückrechnung:** Die Realspannung wird aus dem ADC-Wert berechnet:
+   $V_{\text{bat}} = V_{\text{adc}} \cdot \frac{R_1 + R_2}{R_2}$
+
+3. **Ladezustand-Mapping:** Die Batteriespannung wird auf einen prozentualen Ladezustand abgebildet:
+
+   - **6,0 V** → 0 % (Entladungsschutz aktiv)
+   - **8,4 V** → 100 % (vollständig geladen)
+
+   Für höhere Genauigkeit können mehrere Messpunkte verwendet und linear interpoliert werden.

doc/docs/planung.md

@@ -0,0 +1,57 @@
+# Projekt: Lasertag Kommunikation (nRF52840)
+
+Dieses Projekt beschreibt ein modulares Lasertag-System basierend auf dem nRF52840. Es nutzt **Dynamic Multiprotocol** (Bluetooth Low Energy & OpenThread), um eine nahtlose Kommunikation zwischen einer Weboberfläche (Game-Leader), Westen und Waffen zu ermöglichen.
+
+## System-Architektur
+
+* **Game-Leader:** Fungiert als Brücke (Bridge). Er kommuniziert via **BLE (Web Bluetooth)** mit einem Smartphone/Laptop und via **Thread (CoAP/UDP)** mit den Spielgeräten.
+* **Westen/Waffen:** Reine Thread-Knoten, die Befehle empfangen und Statusmeldungen (Treffer) senden.
+* **Bases:** Stationäre Geräte, die Spielmodi wie "Capture the Base" ermöglichen.
+
+## Geplante Verzeichnisstruktur
+
+Das Projekt ist als Zephyr-Workspace-Struktur angelegt, um Code-Redundanz zu vermeiden.
+
+```text
+lasertag/
+├── apps/                   # Applikations-spezifischer Code (Binaries)
+│   ├── leader_base/        # Kombinierte Firmware für Game-Leader & Bases
+│   ├── weapon/             # Firmware für die Waffen-Einheit
+│   └── vest/               # Firmware für die Westen-Einheit
+├── libs/                   # Gemeinsame Bibliotheken (Zephyr Module)
+│   ├── ble_mgmt/           # BLE Services & Advertising Profile
+│   ├── thread_mgmt/        # CoAP Server/Client & Thread Stack Setup
+│   └── game_logic/         # Treffer-Logik & Spielstatus-Management
+├── boards/                 # Custom Board Definitions (PCBs)
+├── common/                 # Gemeinsame Header (UUIDs, CoAP-Pfade, IDs)
+└── scripts/                # Hilfsskripte (Provisioning, Shell-Tools)
+```
+
+## Roadmap
+
+### Phase 1: Foundation (Struktur & Shell)
+- [ ] Verzeichnisstruktur und `CMakeLists.txt` Verknüpfungen erstellen.
+- [ ] Basis-Firmware mit **Zephyr Shell** zur Konfiguration.
+- [ ] Implementierung von NVS (Non-Volatile Storage) zum Speichern von Gerätenamen und Team-IDs.
+
+### Phase 2: Connectivity (BLE & Thread)
+- [ ] **BLE-Provisioning:** Übertragung von Thread-Credentials via Bluetooth.
+- [ ] **Thread-Setup:** Aufbau eines stabilen Mesh-Netzwerks zwischen Leader und Westen.
+- [ ] **Web-Interface:** Verbindung der Chrome Web Bluetooth App mit dem Leader.
+
+### Phase 3: Core Game Logic (CoAP Brücke)
+- [ ] **Multicast-Broadcast:** "Spiel Start"-Kommando von Web-App -> Leader -> Thread-Mesh.
+- [ ] **Unicast-Feedback:** Treffermeldung von Weste -> Leader -> Web-App.
+- [ ] **Reliability:** Implementierung von CoAP Confirmable Messages für kritische Befehle (z. B. Waffe deaktivieren).
+
+### Phase 4: Erweitert (Bases & NFC)
+- [ ] **Rollen-Switch:** Leader-Hardware erkennt via GPIO (Schalter), ob sie als Base agiert.
+- [ ] **Capture the Base:** Logik für Teambesitz und Zeitmessung.
+- [ ] **NFC-Provisioning:** (Optional) Schnelles Zuweisen von IDs via Smartphone-NFC.
+
+## Technologie-Stack
+- **Hardware:** nRF52840 (DK & Custom PCBs)
+- **OS:** Zephyr RTOS via nRF Connect SDK
+- **Funk:** OpenThread (Mesh) & BLE 5.x
+- **Protokolle:** CoAP über UDP, GATT (BLE)
+- **Frontend:** Web Bluetooth API (JavaScript)

doc/docs/stylesheets/extra.css

@@ -4,14 +4,22 @@
 }
 
 /* Mermaid Diagramme zentrieren */
-.mermaid {
+mermaid {
   display: flex;
   justify-content: center;
   margin: 20px 0;
 }
 
-/* LaTeX Mathe-Formeln etwas hervorheben (größer) */
+/* Bilder zentrieren */
+img {
+  display: block;      /* Macht das Bild zum Block-Element */
+  margin: 20px auto;   /* Zentriert das Bild horizontal durch 'auto' Ränder */
+  max-width: 100%;     /* Verhindert, dass Bilder über den Rand ragen */
+  height: auto;
+}
+
+/* LaTeX Mathe-Formeln etwas hervorheben (größer)
 .arithmatex {
   font-size: 1.3rem;
   color: #1a237e; /* Ein schönes Dunkelblau für die Aufgaben */
-}
+} */

doc/mkdocs.yml

@@ -4,8 +4,8 @@ site_url: https://gitea.iten.pro/edi/lasertag
 nav:
   - Übersicht: index.md
   - Konzept:
-      - Hardware: konzept_hardware.md
-      - Software: konzept_software.md
+      - Software: konzept_hardware.md
+  - Planung: planung.md
 
 theme:
   name: material
@@ -22,10 +22,16 @@ markdown_extensions:
           format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.arithmatex: # Für die Mathe-Formeln
       generic: true
+  - pymdownx.tasklist:
+        clickable_checkbox: true
+  - pymdownx.betterem
+  - admonition
+  - pymdownx.details
 
 extra_javascript:
   - https://unpkg.com/mermaid/dist/mermaid.min.js
-  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.2/es5/tex-mml-chtml.js
+  - javascripts/mathjax.js
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
 
 extra_css:
   - stylesheets/extra.css