Konzept weiterentwickelt und gameplay hinzugefügt

doc/docs/konzept/gameplay.md

@@ -0,0 +1,124 @@
+# Gameplay & Spielmodi (für Spieltester)
+
+Dieses Dokument ist bewusst leicht verständlich. Ziel: Euch zeigen, was wir vorhaben, und euer Feedback einsammeln. Welche Ideen habt ihr? Was macht am meisten Spaß?
+
+## Kurz erklärt
+
+- Wir spielen draußen mit Westen (zeigen Treffer) und Waffen (schießen mit Infrarot-Licht, ungefährlich für Augen).
+- Jede Weste gehört zu einem Team (z.B. Rot, Blau, Grün). Treffer werden von der Weste gezählt.
+- Ein Spiel dauert meist 5–15 Minuten – danach gibt es Punkte/Statistiken.
+
+## Rollen
+
+- **Leader-Box**: Startet/stoppt das Spiel, zeigt den Countdown, sammelt Punkte.
+- **Weste**: Zeigt Treffer, Leben und Teamfarbe.
+- **Waffe**: Schießt IR-Licht. Manche Waffen fühlen sich unterschiedlich an (z.B. Sniper = weiter, Shotgun = breiter Streukegel).
+- **Medic**: Kann heilen (kurze Distanz, breiter Strahl). Hat begrenzte Heilungen oder eine Pause zwischen Heilungen.
+- **Medipack**: Kleines Gerät, das per Taste eine Heilung auslöst (kurze Distanz, breite Streuung), mit Limit oder Cooldown. Kann Sounds abspielen (z.B. „nääääääään“ bei Cooldown, „Sorry, I am empty“ wenn leer).
+
+## Spielmodi (Ideen)
+
+- **Team Battle (Standard)**: Zwei Teams, wer mehr Treffer/Eliminierungen hat, gewinnt.
+- **Base Domination**: Stationen auf dem Feld. Wer länger eine Station hält, sammelt Punkte.
+- **King of the Hill**: Ein Spot in der Mitte – wer ihn hält, sammelt Punkte.
+- **Zombie**: Wenige starten als Zombie. Wird ein Mensch getroffen, wird er zum Zombie. Menschen gewinnen, wenn sie bis zum Ende überleben; Zombies, wenn alle infiziert sind.
+- **Medic Rescue**: Nur Medics können Teamkameraden wiederbeleben. Heilen geht nur aus nächster Nähe.
+- **Capture the Flag (leicht)**: Eine „Flagge“ (Box) muss ins eigene Lager gebracht werden. Treffer lassen dich die Flagge fallen.
+- **Stealth Runde**: Wenig Licht, niedrige Lebenspunkte, kürzere Spielzeit – mehr Spannung.
+
+## Zonen-Ideen
+
+- **Heal-Zone**: In der eigenen Basis heilt man langsam.
+- **Kill-/Radiation-Zone**: Warnung, dann langsam Schaden, wenn man zu lange drin bleibt.
+- **Respawn-Zone**: Tote Spieler müssen in ihre Home-Zone oder eine eroberte Base zurück, um neu zu starten.
+
+## Power-Ups & Items
+Power-Ups können auf mehrere Arten ausgelöst werden – alle machen das Spiel strategischer und spannender!
+
+### Aktive Power-Up-Stationen (mit Deckel)
+
+- **Hardware**: Box mit Deckel (Sensor), Status-LED, IR-Sender
+- **So funktioniert's:** 
+  1. Spieler öffnet den Deckel → LED blinkt grün
+  2. Spieler schießt drauf (mit Waffe oder Medipack)
+  3. Box dekodiert den Schuss (Shooter-ID aus IR) und sendet das Power-Up per **Thread Unicast** an genau diesen Spieler (CoAP `game/powerup`).
+  4. **Weste** des Schützen bekommt das Power-Up und schickt das Kommando an ihre **Waffe**: „20s kein Schaden" oder „20s doppel Damage". IR-Fallback nur, falls kein Mesh verfügbar.
+  5. Box hat Cooldown (z.B. 30s), dann kann sie wieder aktiviert werden
+- **Beispiel-Power-Ups**: 🛡️ Shield (1 Treffer blocken), ⚡ Damage-Boost (+50%), 🩹 Health-Pack, 🔫 Ammo-Reload (für Medics)
+- **Teamplay:** Eine Person öffnet, die andere schießt drauf → beide profitieren
+
+### Passive Power-Up-Boxen (Buzzer)
+
+- **Hardware**: Kleine Box mit Buzzer-Button, schwacher IR-Sender, Cooldown-LED
+- **So funktioniert's:**
+  1. Spieler drückt Buzzer → schwaches IR-Signal wird gesendet
+  2. Weste in unmittelbarer Nähe empfängt es (z.B. nur 2m Reichweite)
+  3. Power-Up gilt 15-30s, dann lädt es wieder auf
+- **Vorteil**: Keine großen Boxen nötig, schneller zu nutzen, mehr Platz für Power-Ups auf dem Feld
+
+### Zonen-Effekte (von Basen/Joinern)
+
+- **Hardware**: Leader-Box sendet periodisch ein Netzwerk-Signal (Thread)
+- **So funktioniert's:**
+  1. Base von Team Rot sendet: „Wer von Team Rot in 15m Reichweite? Ihr bekommt +50% Damage für 30s"
+  2. Weste prüft: „Bin ich von Team Rot? Bin ich nah bei der Base (RSSI-Check)? → Ja, aktiviere +50% Damage"
+  3. Weste sendet zu ihrer Waffe: „Nächste 30s: 1.5x Damage"
+- **Beispiele:**
+  - Heal-Zone: In der eigenen Basis langsam heilen
+  - Danger-Zone: In gegnerischer Base nehmt ihr 1s Schaden
+  - Team-Präsenz-Effekt: Wenn **alle** Spieler eines Teams in Reichweite der eigenen Base sind → alle erhalten +100% Angriff für 10s
+
+### Strategische/zentrale Power-Ups (vom Spielleiter)
+Der Spielleiter kann jederzeit per Tastendruck ein Team-weites Power-Up auslösen:
+
+- **Underdog-Bonus**: Wenn ein Team unterliegt → 20s Unsterblichkeit (kein Schaden) für das schwächere Team
+- **Base-Schuss-Trigger**: Wenn Spieler A die gegnerische Base beschießt → Team A erhält 30s Shield
+- **Turbo-Round**: Alle Spieler beide Teams: 60s lang 2x Damage und 2x Speed
+- **Spannungs-Booster**: Letzten 30s vor Spielende: Alle Spieler können nicht sterben (Shield-Dauerbuff)
+
+### Wie Power-Ups wirken
+
+| Power-Up | Effekt auf Weste | Effekt auf Waffe | Dauer |
+| :--- | :--- | :--- | :--- |
+| 🛡️ Shield | 1 Treffer wird abgeblockt | — | 20–40s |
+| ⚡ Damage-Boost | Weniger Schaden empfangen (Attacken weniger effektiv) | Doppelter Schaden beim Schießen | 20–60s |
+| 🩹 Heal-Pack | +50 Health sofort | — | Sofort |
+| 🏃 Speed | Schneller reagieren | Schneller schießen (kürzerer Cooldown) | 15–30s |
+| 💀 Weakness | Mehr Schaden empfangen | Weniger Schaden beim Schießen | 10–20s |
+| 🔫 Ammo | Medipack wird aufgeladen | — | 1 Magazin |
+
+**Wichtig**: Power-Ups können so konfiguriert werden, dass sie:
+
+- Bei Spieler-Death verfallen (Shield ist weg nach Tod)
+- **Oder** beim Respawn erhalten bleiben (wichtig bei strategischen Boosts)
+
+### Regeln
+
+- Nur **eine** Box pro Power-Up-Typ pro Spieler gleichzeitig
+- Wenn zwei Power-Ups aktiv sind (z.B. Shield UND Damage-Boost) → beide wirken
+- Fallen in Dead-State weg (Power-Up hat keine Wirkung, wenn Spieler schon tot ist)
+
+## Match-Ablauf (typisch)
+
+1) Alle wählen Team/Waffe/Rolle (optional Medic).  
+2) Leader startet den Countdown (laut & Licht).  
+3) Spiel läuft 5–15 Minuten.  
+4) Am Ende sammelt die Leader-Box die Treffer-Logs.  
+5) Punkte/Statistik ansehen: Kills, Tode, Heals, wer die Base wie lange hielt.
+
+## Safety & Fair Play
+
+- Kein Rennen auf rutschigem Boden; keine Schläge/Checks.  
+- Treffer zählen nur über IR (kein „Nachrufen“).  
+- Headshots sind erlaubt, aber vorsichtig zielen (IR ist ungefährlich, trotzdem fair bleiben).  
+- Respekt: Keine Beleidigungen, kein Schummeln (z.B. Sensor verdecken).
+
+## Was sagt ihr?
+
+- Welche Modi gefallen euch am besten?  
+- Wollt ihr mehr Spannung (wenig HP) oder längere Matches (viel HP)?  
+- Mehr Action (Shotgun/Spread) oder mehr Taktik (Sniper/Shield/Medic)?  
+- Findet ihr Heal-/Kill-Zonen spannend oder nervig?  
+- Braucht es mehr Sounds/Lichter, oder ist es so schon genug?
+
+Schreibt eure Ideen/Anmerkungen dazu – wir bauen das ein!

doc/docs/konzept/hardware.md

@@ -12,9 +12,9 @@ Die Waffe ist das primäre Interaktionsgerät. Sie muss robust und reaktionsschn
 
 * **Controller:** nRF52840 (Dongle oder Modul).
 * **IR-Sender:** High-Power IR-LED (940nm oder 850nm) mit Optik/Linse und Treiberstufe (Reichweite > 50m).
-* **Feedback:** Muzzle Flash (helle LED), Vibrationsmotor, Audio (Schussgeräusche, "Leer"-Klicken).
+* **Feedback:** Muzzle Flash (helle LED), Solenoid (6V Open Frame, Rückstoss), Audio (Schussgeräusche, "Leer"-Klicken).
 * **Eingabe:** Abzug (Trigger), Nachladen (Taster), optionaler Schalter für Feuermodus.
-* **Stromversorgung:** 2S LiPo (7.4V) mit Step-Down auf 3.3V.
+* **Stromversorgung:** 2S LiPo (7.4V) mit Buck auf 5V, nRF52840 mit interner 3.3V-Regelung.
 
 ### 1.2 Weste (Player Hub)
 
@@ -35,12 +35,113 @@ Die Leader Box dient zur Spielsteuerung und als Infrastruktur-Knoten.
 * **Ausstattung:** IR-Empfänger, RGB-LEDs, Bluetooth-Gateway zur Smartphone-App.
 * **Stromversorgung:** Großer Akku für lange Laufzeit.
 
-## 2. Energie & Verkabelung
+### 1.4 Power-Up-Stationen (Deckel-Boxen)
 
-* **Akkus:** 2S LiPo (7.4V) als Standard; 1S nur für Tests/Low-Power-Aufbau.
-* **Spannungswandler:** Abwärtswandler auf 3.3V für Logik, separater Treiberpfad für IR-LEDs (hoher Pulsstrom, niedriger Duty-Cycle).
-* **Verkabelung Weste:** Sternförmige Abgänge zu Sensorgürteln (Kopf, Brust/Rücken, Schultern) mit verriegelnden Steckern; Datensignal (LED) + Versorgung gebündelt.
-* **Absicherung:** Polyfuse pro Ast empfohlen, Verpolschutz an jedem Modulanschluss.
+Physische Gegenstände, die Spieler aktivieren, um Power-Ups auszulösen.
+
+* **Controller:** nRF52840 Modul oder DK.
+* **Sensoren:** Magnetschalter oder Druckschalter (unter Deckel) zur Erkennung von "Deckel offen".
+* **Aktor:** IR-LED-Treiber (ähnlich zur Waffe) – sendet Power-Up-Codes.
+* **Feedback:** RGB-LED (Status: Idle grün, aktiv blinkend, Cooldown rot).
+* **Kommunikation:** Optional Thread (CoAP) für Logging an Leader ("Station XYZ wurde von Spieler 3 aktiviert").
+* **Stromversorgung:** 2S LiPo oder USB-betrieben (wenn stationär).
+* **Cooldown:** Hardware oder Software gesteuert (z.B. 30s nach Aktivierung).
+
+### 1.5 Buzzer-Power-Ups
+
+Kompakte passive Power-Up-Geräte mit Druckschalter.
+
+* **Controller:** nRF52840 Modul.
+* **Eingabe:** Einfacher Druckschalter (Buzzer-Button).
+* **Aktor:** Schwacher IR-LED-Sender (kurze Reichweite ~2-3m, breiter Strahl) für Power-Up-Code.
+* **Feedback:** Cooldown-LED (Rot = kann nicht drücken, Grün = aktiv).
+* **Kommunikation:** Optional Thread (nur für Admin-Logging, nicht kritisch für Gameplay).
+* **Stromversorgung:** 2S LiPo mit Schutzschaltung.
+* **Cooldown:** Intern gesteuert (z.B. 15s zwischen Aktivierungen).
+
+## 2. Energieversorgung & Verkabelung
+
+### 2.1 Akkusystem
+
+**Standard:** 2S LiPo (7.4 V nominal, 8.4 V voll geladen, 6.0 V Entladungsschutz).  
+**Alternative:** 1S nur für Tests oder Low-Power-Prototypen – ungeeignet für hohe IR-LED-Ströme (siehe Abschnitt 4.1).
+
+**Schutz & Laden:**
+
+- **Zellenschutz-IC:** HY2120-CB + FS8205A (Dual-FET) – schützt vor Über-/Unterspannung, Überstrom, Kurzschluss.
+- **Lade-IC:** IP2326 (2S Balancing, USB-C) – ermöglicht einfaches Laden ohne externe Balancer.
+- **Fuel Gauge:** Spannungsteiler-basierte ADC-Messung (R1=100k, R2=47k) → Software-Mapping auf Ladestand (6.0 V = 0 %, 8.4 V = 100 %).
+
+!!! info "Warum 2S?"
+    2S-Systeme bieten ausreichend Headroom für IR-LED-Konstantstromquellen (>4.8 V nötig bei 3A) und stabile Versorgung auch bei hoher Last. 1S-Zellen brechen unter 1A+ schnell auf 3.4–3.6 V ein.
+
+### 2.2 Spannungsebenen & Wandler
+
+**Primär-Rail (Batterie, 6.0–8.4 V):**  
+Direkt gespeist: IR-LED-Treiber, Muzzle-Flash-LED, Solenoid 6V (Open Frame, taktiles Feedback Rückstoss).
+
+**Sekundär-Rail (5.0 V, ~1.5 A):**  
+Buck-Converter (z.B. MP2315, TPS62130) für Audio-IC (MAX98357A), adressierbare LEDs (WS2812B) und nachgeschalteten LDO. Hohe Schaltfrequenz gewünscht (geringe Induktivität, kompakte Bauform).
+
+**Tertiär-Rail (3.3 V, ~30 mA):**  
+LDO (z.B. MCP1826, AMS1117-3.3) aus 5V Buck-Ausgang für nRF52840 und QSPI Flash. Geringer Dropout (5V → 3.3V = 1.7V) reduziert Wärmeentwicklung; Low-Noise-Design minimiert Störungen auf der RF-Schaltung.
+
+**IR-Empfänger (5V mit Level-Shift):**  
+TSOP48xx-Module laufen an 5V (besserer SNR, robuster gegen Sonnenlicht). Output-Signal wird per **AO4300A N-Channel MOSFET** (Open-Drain) auf 3.3V gewandelt → invertierendes Level-Shifting. Software kompensiert Invertierung mit `GPIO_ACTIVE_LOW`.
+
+**Verkabelung Weste:**  
+Sternförmige Abgänge zu Sensor-Modulen (Kopf/Brust/Schultern); jeweils 5V + GND + WS2812-Data; verriegelnde Stecker (JST-XH o.ä.), Polyfuse pro Ast, Verpolschutz (Diode/FET).
+
+### 2.3 Leistungsbilanz (Weste)
+
+Die Weste hat durch LEDs und Audio den höchsten Verbrauch; hier die Peak-Abschätzung:
+
+**5V-Rail (Buck-Converter):**
+
+| Komponente | Zustand | Strom | Leistung |
+| :--- | :--- | ---: | ---: |
+| Audio (MAX98357A) | Volllast (3W @ 90% η) | ~670 mA | 3.35 W |
+| WS2812B LEDs (5×) | 100 % Weiß | 300 mA | 1.50 W |
+| IR-Empfänger (5×) | Dauerbetrieb @ 5V | ~50 mA | 0.25 W |
+| LDO 3.3V (Durchleitung) | 30 mA @ 3.3V | ~30 mA | 0.15 W |
+| **Gesamt 5V (Peak)** | | **~1.05 A** | **5.25 W** |
+
+**3.3V-Rail (LDO aus 5V Buck):**
+
+| Komponente | Zustand | Strom | Leistung |
+| :--- | :--- | ---: | ---: |
+| nRF52840 | BLE+Thread aktiv | ~15 mA | 0.05 W |
+| QSPI Flash | Read/Write Burst | ~15 mA | 0.05 W |
+| **Gesamt 3.3V (Peak)** | | **~30 mA** | **0.10 W** |
+
+**Auslegung:**  
+- **Buck-Regler:** 1.5 A Nennstrom (30 % Reserve), hohe Schaltfrequenz (>1 MHz) für kompakte Drossel/Kondensatoren.  
+- **LDO:** 100 mA Nennstrom ausreichend; Verlustleistung bei 30 mA: $P_{loss} = (5V - 3.3V) \cdot 30mA = 51 mW$ (unkritisch). Low-Noise-Design (< 50 µVrms) für sauberen RF-Betrieb.
+
+### 2.4 Blockschaltbild Energieversorgung
+
+```mermaid
+flowchart TD
+    BAT["2S LiPo<br/>6.0–8.4V"] <--> PROT["Zellenschutz<br/>HY2120+FS8205A"]
+    CHG["USB-C Lader<br/>IP2326"] --> PROT
+    
+    PROT --> BUCK["Buck 5.0V<br/>MP2315/TPS62130<br/>1.5A"]
+    PROT --> IR_DRV["IR-LED<br/>Konstantstromquelle"]
+    PROT --> MUZZLE["Muzzle Flash<br/>LED-Treiber"]
+    PROT --> SOL["Solenoid 6V<br/>Open Frame"]
+    
+    BUCK --> AUDIO["Audio Amp<br/>MAX98357A"]
+    BUCK --> LED["WS2812B LEDs<br/>mit Level Shift"]
+    BUCK --> IR_RX["IR-Empfänger<br/>TSOP48xx (5V)"]
+    BUCK --> LDO["LDO 3.3V<br/>MCP1826/AMS1117<br/>100mA"]
+    
+    LDO --> NRF["nRF52840<br/>3.3V"]
+    LDO --> FLASH["QSPI Flash<br/>3.3V"]
+    
+    IR_RX -->|"AO4300A<br/>MOSFET Shifter"| NRF
+```
+
+---
 
 ## 3. Stückliste (Übersicht)
 
@@ -52,7 +153,7 @@ Diese Tabelle gibt einen Überblick über die groben Komponenten pro Einheit. De
 | IR-LED (High-Power) | ✓ | | | | 940nm, > 50m Reichweite |
 | IR-Empfänger (38kHz) | | ✓ | ✓ | 5–10 | Verteilt auf Kopf/Torso/Schulter |
 | RGB-LED (WS2812B) | | ✓ | ✓ | 1–3 | Teamfarbe + Status |
-| Vibrationsmotor | ✓ | | | | Taktiles Feedback Schuss |
+| Solenoid (6V Open Frame) | ✓ | | | | Taktiles Feedback Rückstoss |
 | Lautsprecher | ✓ | ✓ | | | Schussgeräusche + Sprachausgabe |
 | 2S LiPo Akku | ✓ | ✓ | ✓ | 1 | 7.4V, ggf. unterschiedliche Kapazität |
 | Lade-IC (IP2326) | ✓ | ✓ | ✓ | 1 | 2S Balancing |
@@ -62,111 +163,136 @@ Diese Tabelle gibt einen Überblick über die groben Komponenten pro Einheit. De
 | USB-C / Pogo-Pad | ✓ | ✓ | ✓ | 1 | Laden + Debug-Konsole |
 | Steckverbinder (JST-XH) | ✓ | ✓ | | | Modular aufgebaut |
 
-## 4. Schaltungskomponenten
+## 4. Schaltungskomponenten (Detail)
 
-### 4.1 LED-Treiber
+### 4.1 IR-LED-Treiber (Konstantstromquelle)
 
-#### Grundkonzept
+#### Funktionsprinzip
 
-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.
+Hybride PNP/NPN-Topologie für präzisen, modulierten IR-Puls (38 kHz). Die Stromquelle stellt sicher, dass bei wechselnder Batteriespannung der LED-Strom konstant bleibt (→ reproduzierbare Reichweite).
 
 ![LED DRIVER](../img/concept_hardware_led_driver.svg)
 
 #### Stromeinstellung
 
-Der Zielstrom wird über den Messwiderstand $R_{set}$ eingestellt. Die Berechnung folgt der Formel:
+Der Sollstrom wird über $R_{set}$ definiert:
 
-$$R_{set} = \frac{0,65V}{I_{LED}}$$
+$$R_{set} = \frac{0,65\,\text{V}}{I_{\text{LED}}}$$
 
-Die folgenden Tabelle zeigt typische Stromwerte, die erforderlichen Widerstände und die entsprechenden Anwendungsfälle:
+**Beispiele:**
 
-| 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.
-
-### 4.2 Audio-Driver
-Um Audio (z. B. Schussgeräusche, Sprachansagen) von einem externen Flash abzuspielen, ohne die CPU zu belasten, müssen wir auf Hardware-DMA-Transfer setzen.
-
-Die beste Lösung für ein kompaktes, batteriebetriebenes System wie eine Lasertag-Waffe ist ein I2S Class-D Verstärker. Dieser kombiniert DAC und Verstärker in einem Chip und wird digital angesteuert.
-
-Der "Industriestandard" für Mikrocontroller ist da der MAX98357A:
-
-* **Schnittstelle**: I2S (Digital)
-* **Leistung**: 3.2W an 4Ω (sollte mehr als genug laut sein)
-* **Vortiele**:
-    * Kein externer DAC nötig
-    * Direkter Anschluss an den Lautsprecher
-    * Extrem Energieeffizient (schont die Akkus)
-    * Filterlose Class-D Architektur (wenige Bauteile)
-* **CPU-Last**: Minimal, da der nRF52840 die Daten per EasyDMA schickt (zur Anpassung der Lautstärke wird etwas Rechenleistung benötigt)
-
-### 4.3 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 |
+| $I_{\text{LED}}$ | $R_{set}$ | Einsatz |
 | :--- | :--- | :--- |
-| $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 |
+| 0,5 A | 1,30 Ω | Standard/Nahkampf |
+| 1,0 A | 0,65 Ω | Hohe Reichweite (SFH 4550) |
+| 2,0 A | 0,33 Ω | Pulsbetrieb (extreme Leistung) |
+| 3,0 A | 0,22 Ω | Scharfschütze (Oslon Black) |
 
-#### Softwarelogik
+**Thermik:** Bei 38-kHz-Modulation (Duty-Cycle ~30 %) ist $P_{\text{avg}} = R_{set} \cdot I^2_{\text{LED}} \cdot DC$ → deutlich unter Peak. $R_{set}$ muss aber Spitzenstrom verkraften → impulsfeste Typen (Metallschicht, Drahtwiderstand).
 
-Die Ladezustandsbestimmung erfolgt in drei Schritten:
+#### Headroom & Akkuwahl
 
-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.
+Minimalspannung für stabile Regelung:
 
-*Stand: 03.04.2025*
+$$V_{\text{CC,min}} = V_{f(\text{LED})} + 0,65\,\text{V} + 1,0\,\text{V}_{\text{Headroom}}$$
+
+| $I_{\text{LED}}$ | $V_f$ (typ.) | $V_{\text{CC,min}}$ | Akku |
+| :--- | :--- | :--- | :--- |
+| 0,5 A | 2,0 V | 3,65 V | 1S (nur voll geladen) |
+| 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 ungeeignet für >1A"
+    1S-Akkus brechen unter Last auf 3,4–3,6 V ein → Regelung versagt, Reichweite bricht ein. 2S liefert auch bei Teilentladung (7,0 V) genug Headroom.
+
+### 4.2 Adressierbare LEDs (WS2812B)
+
+**Anforderung:** 5V-Versorgung, aber Daten-Pegel kompatibel mit nRF52840 (3.3V Logic).
+
+**Level-Shift:** SN74AHCT1G125 (3.3V → 5V, Single-Gate); schnell genug für WS2812-Timing (800 kHz).  
+**Serienwiderstand:** ~330 Ω nach dem Shifter → dämpft Reflexionen auf der Data-Leitung, verhindert Überschwinger.
+
+**Layout:** Data-Leitung kurz halten; bei mehreren LEDs in Serie: Bypass-Kondensator (100 nF + 10 µF) pro 3–5 LEDs.
+
+### 4.3 Audio-Verstärker (MAX98357A)
+
+**Ziel:** Klare Schuss- und Sprach-Ausgabe mit minimalem Aufwand und geringer CPU-Last.
+
+**Architektur:** I2S Class-D Verstärker – DAC + Endstufe integriert, filterlose Topologie (wenige Bauteile).
+
+* **Schnittstelle:** I2S (digital); Audio-Stream per EasyDMA vom nRF52840 → CPU bleibt frei für Game Logic.
+* **Leistung:** ~3.2 W @ 4Ω – laut genug für Outdoor-Einsatz.
+* **Effizienz:** ~90 % → Akku-schonend; geringer Ruhestrom im Idle.
+* **Layout:** Kurze, symmetrische Leitungen zu Speaker-Terminals; separate Ground-Plane; Entkopplung (10 µF + 100 nF) nahe VDD-Pin.
+
+### 4.4 Flash-Speicher (QSPI)
+
+**Aufgabe:** Audio-Files (Schuss-FX, Ansagen) und Spiel-Logs (optional Treffer-Historie).
+
+* **Technik:** QSPI-NOR-Flash (z.B. W25Q128JV, GD25Q16C); 1.8 V oder 3.3 V; XIP-fähig (Execute-in-Place für Code möglich).
+* **Kapazität:** 8–16 MB; reicht für ~3 min @ 22 kHz oder ~1.5 min @ 44 kHz (16 bit mono). Empfehlung: 22 kHz – höhere Sample-Rate bringt bei Outdoor-Speaker kaum Mehrwert.
+* **Interface:** QSPI (4-Bit parallel); nRF52840 unterstützt DMA-basierten Zugriff → schnelle Reads ohne CPU-Last.
+* **Layout:** Flash nahe am MCU (< 5 cm Leitungslänge); Differenzen in Trace-Längen < 1 mm; saubere Ground-Plane; JEDEC-ID beim Boot prüfen.
+
+### 4.5 Akku-Überwachung (Fuel Gauge)
+
+**Prinzip:** Spannungsteiler + ADC für 2S-Akkus (0–8.4 V) → Software-basierte Ladezustandsschätzung (kein dediziertes Fuel-Gauge-IC nötig).
+
+**Schaltungskomponenten:**
+
+| Bauteil | Wert | Funktion |
+| :--- | :--- | :--- |
+| $R_1$ | 100 kΩ | Spannungsteiler – oberer Zweig |
+| $R_2$ | 47 kΩ | Spannungsteiler – unterer Zweig (→ ADC) |
+| $C_1$ | 100 nF | Tiefpass-Glättung am ADC-Eingang |
+
+**Softwarelogik:**
+
+1. **ADC-Konvertierung:** 12-bit ADC liest $V_{\text{div}}$ (max. 3.3 V bei VRef = 3.3 V).
+2. **Rückrechnung:** $V_{\text{bat}} = V_{\text{adc}} \cdot \frac{R_1 + R_2}{R_2} = V_{\text{adc}} \cdot 3.13$
+3. **Mapping:** Lookup-Table oder linear interpoliert:
+   - 8.4 V → 100 % (voll geladen)
+   - 7.4 V → ~50 % (nominal)
+   - 6.0 V → 0 % (Schutzschaltung aktiv)
+
+**Kalibrierung:** Einmalig bei Produktion: Spannung an bekanntem Referenzpunkt messen, Offset/Gain in NVS speichern.
+
+---
+
+## 5. Bauteil-Übersicht & Empfehlungen
+
+Konsolidierte Liste der Schlüsselkomponenten mit konkreten Part-Vorschlägen. Detaillierte BOMs folgen in separaten Docs (Waffe/Weste/Leader).
+
+| Kategorie | Bauteil/Funktion | Vorschlag | Alternativen | Anmerkung |
+| :--- | :--- | :--- | :--- | :--- |
+| **MCU** | Mikrocontroller | nRF52840 | — | Zephyr-Support, BLE+Thread |
+| **Energie** | 2S-Akku | Li-Po 7.4V, 1000–2000 mAh | — | Kapazität je nach Gerät |
+| | Zellenschutz | HY2120-CB + FS8205A | DW01A + 8205A | OV/UV/OC-Protection |
+| | Lade-IC | IP2326 (2S Balancing) | TP4056 (nur 1S) | USB-C, Balancing integriert |
+| | Buck 5V | MP2315, TPS62130 | — | 1.5 A, >1 MHz Schaltfrequenz |
+| | LDO 3.3V | MCP1826, AMS1117-3.3 | XC6206P332MR | Low-Noise für RF, < 0.5V Dropout |
+| **IR** | IR-LED | SFH 4550, Oslon Black | TSAL6400 | 940 nm, >50 m Reichweite |
+| | IR-Empfänger | TSOP4838, TSOP38438 | VS1838B | 38 kHz Demodulator, 5V Supply |
+| | LED-Treiber | PNP/NPN diskret | IRL530 (Logic-FET) | Konstantstrom, PWM-fähig |
+| | Level-Shifter IR | AO4300A (N-Ch MOSFET) | BSS138, 2N7002 | 5V → 3.3V, invertierend |
+| **LED** | Adressierbare | WS2812B (5050) | SK6812, APA102 | 5V, ~60 mA/LED @ weiß |
+| | Level-Shift | SN74AHCT1G125 | 74HCT245 (8-Kanal) | 3.3V → 5V, single-gate |
+| **Audio** | Class-D Amp | MAX98357A | PAM8302, TPA2005D1 | I2S, 3.2W @ 4Ω |
+| | Speaker | 4Ω, 3–5W | 8Ω (lower SPL) | Outdoor-tauglich |
+| **Speicher** | QSPI Flash | W25Q128JV (16 MB) | GD25Q16C (2 MB) | NOR-Flash, 3.3V |
+| **Feedback** | Solenoid | 6V Open Frame | — | Rückstoss direkt ab Batterie |
+| | Muzzle LED | Weiß/Gelb, 1W+ | Cree XP-E2 | Sichtbar bei Tag |
+| **Passiv** | $R_{\text{set}}$ (IR) | 0.22–1.3 Ω, 3W | Metallschicht, Draht | Impulsfest |
+| | Spannungsteiler | 100k + 47k, 1% | 0.1% für Präzision | Fuel Gauge |
+| **Mechanik** | Stecker | JST-XH (2.54mm) | Molex PicoBlade | Verriegelnd, 3–5 Pole |
+| | Taster | Omron B3F, Alps SKQG | Cherry MX (größer) | Trigger, Reload |
+
+**Hinweise:**
+
+- **IR-LED:** Oslon Black für extreme Reichweite (3A-Betrieb), SFH 4550 für Standard (1–2A).
+- **Audio:** MAX98357A ist quasi-Standard; Alternativen (PAM8302) haben höheren THD, aber OK für SFX.
+- **Flash:** 16 MB erlauben ~6 min Audio @ 22 kHz – gut für zukünftige Erweiterungen (z.B. mehrsprachige Ansagen).
+- **Stecker:** JST-XH ist weit verbreitet und günstig; Molex PicoBlade kompakter, aber teurer.
+
+*Stand: 04.01.2026*

doc/docs/konzept/software.md

@@ -10,7 +10,7 @@ Dieses Dokument beschreibt die Software-Architektur, die Rollenverteilung und di
 
 ## 1. System-Rollen & Hardware-Typen
 
-Das System basiert auf nRF52840-Chips, die über OpenThread (802.15.4) kommunizieren.
+Das System basiert auf nRF52840-Chips, die über OpenThread (802.15.4) kommunizieren. Am wichtigsten dabei ist die Kommunikation von der Weste zur Waffe, da die Waffe beim Death des Spielers sofort deaktiviert werden muss. Die OpenThread Message Priority soll verwendet werden, um die Weste-Waffe-Kommunikation zusätzlich zu optimieren. Multicasts: Low, Weste -> Waffe enable und disable: High, Rest normal.
 
 ### A. Leader Box (Game Controller)
 * **Funktion:** Zentrale Spielsteuerung, Zeitgeber, Gateway zur Smartphone-App.
@@ -114,6 +114,8 @@ sequenceDiagram
     5. **Feedback:** Weste B leuchtet/vibriert/spielt Sound ("Ugh!").
     6. **Speicherung:** Weste B speichert den Treffer im internen Flash-Log (`Timestamp, ShooterID, Zone, Damage`).
     7. *(Optional)* Weste B sendet UDP-Paket an Leader für Live-Scoreboard (Best Effort).
+* **Heilquellen:** Medic/Medipack-IR (breit gestreut, kurze Reichweite, negativer Damage) werden als Heilung interpretiert.
+* **Zonen-Effekte:** Bases/Joiner senden `game/zone` (Link-Local, Hop=1); Weste prüft RSSI-Schwelle und addiert HP-Deltas (friend/foe) nach optionalem Warn-Countdown.
 
 ### Phase D: Spieler eliminiert
 * **Bedingung:** Lebenspunkte <= 0.
@@ -201,6 +203,33 @@ Die Logik für die Modi wird primär auf den Westen implementiert (Regelwerk), g
     * Base-Box zählt Zeit für das haltende Team.
     * Am Ende fragt Leader alle Base-Boxen ab: "Wie lange warst du Rot? Wie lange Blau?".
 
+### Medic & Heal Packs
+* **Rollen:**
+    * **Medic-Spieler:** Rolle `Medic` in der Spieler-Konfiguration; deren Waffe feuert ein "Heal-IR" mit breiter Streuung und sehr kurzer Reichweite.
+    * **Medipacks (Objekte):** Aktiv durch Tastendruck; senden erst nach Button-Press ein Heal-IR mit breiter Streuung.
+* **Wirkung:**
+    * Heal-IR ist als eigene Damage-Class kodiert (negativer Schaden → Heilung).
+    * Reichweite absichtlich klein (< 2–3 m) und stark gestreut, damit Heilen ein Positionierungs-Feature bleibt.
+    * Treffer-Logik auf der Weste interpretiert diese Pakete als Heilung (+HP, begrenzt durch `health_max`).
+* **Balancing:**
+    * Heal pro Tick konfigurierbar; zusätzlich wählbar: max. Anzahl Heilungen, Mindest-Pause zwischen Heilungen oder beides.
+    * Friendly-only oder auch Self-Heal konfigurierbar.
+    * Hardware: Kann identisch zur Waffe sein (Trigger/Taster, Audio). Beispiele: "nääääääään" bei Cooldown, "Sorry, I am empty" wenn Magazin leer ist.
+
+### Zonen-Effekte (Bases/Joiner)
+* **Joiner/Base-Knoten** können zusätzlich periodisch CoAP-Pakete auf Ressource `zone` senden (Link-Local, Hop-Limit=1).
+* **Anwendungsfälle:**
+    * **Heal-Zonen:** In Team-Homebase oder dominierten Bases → Team-Mitglieder werden geheilt, Gegner ggf. geschwächt.
+    * **Kill-/Radiation-Zonen:** Schadenszonen mit Warn-Countdown; Gegner müssen den Bereich verlassen.
+    * **Respawn-Zonen:** Spielmodi, in denen tote Spieler nur in der eigenen Home-Zone oder einer dominierten Base respawnen dürfen; die Zone validiert Präsenz (RSSI) und erlaubt dann Respawn.
+* **Paketfelder (Beispiel):** `team: 2, friend: +20, foe: -10, rssi: -70, warn: 5`
+    * `team`: Besitzer der Zone (z.B. 2 = Blau)
+    * `friend`: HP-Delta für eigenes Team (+20 Heal)
+    * `foe`: HP-Delta für andere Teams (-10 Schaden)
+    * `rssi`: Mindest-RSSI (dBm) für Wirksamkeit (z.B. -70 → nur nahe dran)
+    * `warn`: Anzahl Aussendungen als Warnung, bevor der Effekt scharf wird
+* **Instant-Death Beispiel:** `team: 0, friend: -128, foe: -128, warn: 0, rssi: -60` → Jeder Empfänger mit RSSI besser als -60 dBm fällt sofort auf 0 HP.
+
 ---
 
 ## 5. Technische Spezifikation (API & Datenstrukturen)
@@ -216,6 +245,10 @@ Die Kommunikation erfolgt über CoAP (UDP). Alle Payloads sind binär (`__packed
 | `game/wconf` | PUT | Unicast | Konfiguration für eine Waffe | `struct weapon_config_packet` |
 | `game/hit` | POST | Unicast | Treffer-Meldung (Live-Ticker) | `struct hit_report_packet` |
 | `game/log` | GET | Unicast | Abruf der gespeicherten Trefferdaten | `struct flash_log_entry[]` |
+| `game/zone` | PUT | Multicast (Link-Local, Hop=1) | Zonen-Effekte (Heal/Kill) aus Bases/Joinern | `struct zone_effect_packet` |
+
+| `game/powerup` | PUT | Unicast | Power-Up-Event von Weste zu Waffe | `struct powerup_event_packet` |
+| `game/pup_log` | GET | Unicast | Abruf aller Power-Up-Aktivierungen | `struct powerup_log_entry[]` |
 
 ### 5.2 Datenstrukturen
 
@@ -260,6 +293,33 @@ struct hit_report_packet {
     uint8_t damage;         // Erlittener Schaden
     uint8_t hit_location;   // 0=Unbekannt, 1=Kopf, 2=Brust, 3=Rücken
 } __packed;
+
+// Zonen-Effekte (link-local, Hop-Limit=1)
+struct zone_effect_packet {
+    uint8_t team_id;        // Besitzer der Zone (0=neutral)
+    int8_t friend_delta;    // HP-Delta für eigenes Team (z.B. +20 Heal)
+    int8_t foe_delta;       // HP-Delta für andere Teams (z.B. -10 Schaden)
+    int8_t rssi_thresh_dbm; // Mindest-RSSI für Wirksamkeit (z.B. -70 dBm)
+    uint8_t warn_count;     // Anzahl Warn-Pakete vor scharfem Effekt
+} __packed;
+
+// Power-Up Event (von Weste zu Waffe nach IR-Empfang)
+struct powerup_event_packet {
+    uint16_t player_id;        // Betroffener Spieler
+    uint8_t powerup_type;      // 0=SHIELD, 1=DAMAGE_BOOST, 2=HEAL, 3=SPEED, etc.
+    uint16_t duration_sec;     // Dauer des Power-Ups in Sekunden
+    uint8_t persist_on_death;  // 0=verfällt bei Death, 1=bleibt auch nach Respawn
+    uint16_t damage_multiplier;// Für Damage-Boost: z.B. 150 = 1.5x
+    int8_t health_delta;       // Für Heal-Pack: z.B. +50
+} __packed;
+
+// Power-Up Log Entry (für Auswertung nach Spielende)
+struct powerup_log_entry {
+    uint32_t timestamp;        // ms seit Spielstart
+    uint16_t player_id;        // Spieler, der Powerup aktiviert hat
+    uint8_t powerup_type;      // Type des PU
+    uint8_t source;            // 0=IR-Station, 1=Buzzer-Box, 2=Leader-Kommando, 3=Zone
+} __packed;
 ```
 
 ---
@@ -267,10 +327,50 @@ struct hit_report_packet {
 ## 6. IR-Protokoll (Physical Layer)
 
 Das IR-Signal nutzt eine 38kHz Trägerfrequenz (NEC-ähnlich).
-Payload (32-bit):
-* `8 bit` Protokoll-ID (Magic Byte zur Unterscheidung von Fernbedienungen)
-* `16 bit` Shooter ID
-* `8 bit` Info (4 bit Team, 4 bit Damage Class)
+
+### 6.1 Standard-Shooting-Payload (32-bit)
+
+Payloads von Waffen und Medics (Protokoll-ID `0xAA`):
+
+* Bits 24-31: `Protokoll-ID` (`0xAA` für Standard-Spiel-IRs)
+* Bits 8-23: `Shooter ID` (16-bit, eindeutig für jeden Spieler)
+* Bits 4-7: `Team-Code` (4-bit, 0=Rot, 1=Blau, 2=Grün, 3=Neutral)
+* Bits 0-3: `Damage Class` (4-bit, 0-15, definiert Basis-Schaden; 0xFF = Healing)
+
+**Beispiel:** ShooterID=42, Team=Rot, Damage=10 → `0xAA002A0A`
+
+### 6.2 Power-Up-Payload (32-bit)
+
+Payloads von Power-Up-Stationen und Buzzer-Boxen (Protokoll-ID `0xBB`):
+
+* Bits 24-31: `Protokoll-ID` (`0xBB` für Power-Up-Signale)
+* Bits 16-23: `Power-Up-Type` (0=SHIELD, 1=DAMAGE_BOOST, 2=HEAL_PACK, 3=SPEED, 4=WEAKNESS, 5=AMMO, etc.)
+* Bits 0-15: `Power-Up-Flags` (optional: Duration-Encoding, Persist-Flag, etc.)
+
+**Beispiel (Shield):** `0xBB000000` (Duration wird in CoAP-Paket übertragen)
+
+---
+
+## 7. Power-Ups & Items (erweitert)
+
+### Hardw are-Seite
+* **Power-Up-Stationen (Deckel-Boxen):** nRF52840 + Magnetschalter + IR-Sender + Status-LED; Cooldown intern gesteuert (z.B. 30s).
+* **Buzzer-Power-Ups:** nRF52840 + Druckschalter + schwacher IR-Sender (2-3m) + LED; optional Thread-Logging.
+* **Beide Typen können zentral über Leader konfiguriert werden.**
+
+### Software-Seite
+* **IR-Dekodierung:** Weste prüft Protokoll-ID (`0xAA` vs. `0xBB`) und ruft Handler auf.
+* **Weste:** Speichert aktive Power-Ups lokal (Typ, Duration, Multiplier); sendet via `game/powerup` Unicast zu Waffe; prüft `persist_on_death` bei Respawn.
+* **Waffe:** Empfängt `game/powerup`, appliziert Damage-Multiplier auf nächste Schüsse.
+* **Power-Up-Typen:**
+    - SHIELD: Blockiert 1 Treffer
+    - DAMAGE_BOOST: Multipliziert ausgehenden Schaden (z.B. 1.5x)
+    - HEAL_PACK: Instant +HP
+    - SPEED: Schneller schießen (Cooldown-Reducer)
+    - WEAKNESS: Negativ, mehr Schaden empfangen
+    - AMMO: Medipack-Magazine aufladen
+* **Leader-Kommandos:** Kann zentrale Power-Ups auslösen (Underdog-Bonus, Base-Schuss-Trigger, Turbo-Round) → Multicast/Unicast.
+* **Logging:** Alle Power-Up-Aktivierungen in Flash-Log speichern, abrufbar via `game/pup_log` nach Spielende.
 
 ## 8. Weste – Zustandsautomat (detailliert)
 

doc/docs/planung.md

@@ -29,25 +29,52 @@ lasertag/
 
 ## 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.
+### Entwicklungs-Roadmap (Schritt-für-Schritt)
 
-### 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.
+Diese Roadmap führt vom nRF52840DK bis zum fertigen Produkt.
 
-### 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 1: Die "Tisch"-Basis (PoC)
+**Ziel:** Stabile Thread-Kommunikation und IR-Signalerzeugung verifizieren.
 
-### 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.
+- [ ] Zephyr Setup: Installation des nRF Connect SDK (NCS) und VS Code.
+- [ ] Custom Board Definition: Board-File anlegen, das die Pins des nRF52840DK auf die geplanten Funktionen mappt (PWM für IR, GPIO für Buttons).
+- [ ] Thread Mesh: Minimalen OpenThread-Stack aufsetzen. Ein DK als Leader (FTD), einer als Child. UDP/CoAP-Ping bei Knopfdruck.
+- [ ] IR-Engine: MilesTag-Encoder mit nrfx_pwm + PPI implementieren. Signal mit Oszilloskop/Logic Analyzer verifizieren. Sicherstellen, dass Funk die IR-Engine nicht stört.
+
+#### Phase 2: Der "Prototyp" (Integration)
+**Ziel:** Einbindung von Audio und Solenoid.
+
+- [ ] Audio: MAX98357A am I2S-Interface. WAV-Player, der Samples aus internem Flash abspielt.
+- [ ] Solenoid-Treiber: MOSFET-Schaltung auf Breadboard. PWM-Logik für "Kick" (100% für 30ms) und "Hold" (30%). Thermik des Solenoids testen.
+- [ ] Haptik-Sync: Audio ("Bang!") und Solenoid-Kick in der Software synchronisieren.
+
+#### Phase 3: Die "Optik & Sensorik" (Physik)
+**Ziel:** Reichweitentest.
+
+- [ ] Linsen-Test: Oslon Black LED auf Star-Platine + Carclo/LEDiL-Linse justieren (Abstand exakt einhalten).
+- [ ] Sensor-Array: TSOP-Sensoren für die Weste verdrahten. Outdoor-Test bei Sonne. Software-Filterung anpassen, um Reflexions-Fehler zu minimieren.
+
+#### Phase 4: Die "App & Logik" (System)
+**Ziel:** Spielsteuerung.
+
+- [ ] BLE Gateway: Leader-Box sendet Thread-Statusdaten via BLE an Smartphone (Web Bluetooth API oder nRF Toolbox App).
+- [ ] Web App: Einfache HTML/JS-Seite, die via Web Bluetooth API mit dem Leader spricht, um ein Spiel zu starten ("Start Game" als Thread Broadcast).
+
+#### Phase 5: Das "Custom PCB" (Hardware)
+**Ziel:** Miniaturisierung.
+
+- [ ] Schaltplan: Schaltungen in KiCad übertragen. Trennung von Analog-GND (Sensoren) und Power-GND (Solenoid) beachten.
+- [ ] Layout: Antennenplatzierung/Impedanz anpassen; Testpunkte für SWD vorsehen (Debug).
+
+### Grobe Zeitachsen (Richtwerte)
+
+| Phase | Ziel | Dauer (Richtwert) | Abhängigkeiten |
+| :--- | :--- | :--- | :--- |
+| 1 | Thread + IR PoC | 1–2 Wochen | HW: nRF52840DK, Logic-Analyzer |
+| 2 | Audio + Solenoid | 2 Wochen | Phase 1 abgeschlossen |
+| 3 | Optik & Sensorik | 1–2 Wochen | Phase 2 abgeschlossen, Outdoor-Tests |
+| 4 | App & Steuerung | 1–2 Wochen | Phase 2 abgeschlossen, BLE-Gateway vorhanden |
+| 5 | Custom PCB | 3–4 Wochen | Phasen 1–3 verifiziert, Schaltplan stabil |
 
 ## Technologie-Stack
 - **Hardware:** nRF52840 (DK & Custom PCBs)

doc/mkdocs.yml

@@ -6,6 +6,7 @@ nav:
   - Konzept:
       - Hardware: konzept/hardware.md
       - Software: konzept/software.md
+      - Gameplay & Modi: konzept/gameplay.md
   - Planung: planung.md
 
 theme:
@@ -15,6 +16,17 @@ theme:
     - navigation.sections
     - navigation.expand
 
+plugins:
+  - search
+  - print-site:
+      add_to_navigation: true
+      print_page_title: 'PDF / Druckversion'
+      add_print_site_banner: false
+      add_cover_page: true
+      cover_page_template: ""
+      path_to_pdf: "lasertag-dokumentation.pdf"
+      enabled: true
+
 markdown_extensions:
   - pymdownx.superfences:
       custom_fences:

doc/requirements.txt

@@ -1,3 +1,4 @@
 mkdocs
 mkdocs-material
 pymdown-extensions
+mkdocs-print-site-plugin