# IR-Kommunikationsprotokoll

## Übersicht

Das Infrarot-Kommunikationsprotokoll basiert auf Pulse-Distance-Codierung mit 38 kHz Träger und ist ähnlich Sony SIRC, aber optimiert für die Anforderungen des Lasertag-Systems. Das Protokoll bietet robuste Übertragung mit CRC-Fehlerprüfung und kurzen Frame-Zeiten (~36 ms).

## Physikalische Schicht

| Parameter | Wert | Anmerkung |
|-----------|------|----------|
| Trägerfrequenz | 38 kHz | Standard für TSOP48xx Empfänger |
| Tastgrad (Duty Cycle) | 50 % | Konfigurierbar (25–75 %) |
| Modulation | PWM mit Pulse-Distance-Codierung | Hardware-basiert via nRF52 PWM-Peripheral |
| Empfänger | TSOP4838 (kompatibel) | Active-Low Ausgang, 38 kHz Bandpass |

## Timing-Spezifikation

| Symbol | Dauer | Toleranz | Beschreibung |
|--------|-------|----------|-------------|
| **Start Burst** | 4 × Basistakt (Standard 2400 µs) | ±200 µs | Träger AN, Frame-Synchronisations-Impuls |
| **Gap** | 1 × Basistakt (Standard 600 µs) | ±100 µs | Träger AUS nach Start (optional, konfigurierbar) |
| **Mark** | 1 × Basistakt (Standard 600 µs) | ±100 µs | Träger AN (konstant für alle Bits) |
| **Space 0** | 1 × Basistakt (Standard 600 µs) | ±100 µs | Träger AUS für logisch 0 |
| **Space 1** | 2 × Basistakt (Standard 1200 µs) | ±150 µs | Träger AUS für logisch 1 |

**Basistakt:** `CONFIG_IR_PROTO_BASE_US` (Standard 600 µs). Alle Zeiten ergeben sich daraus per Multiplikatoren (`IR_PROTO_*_MULT`).

### Bit-Codierung

```
Bit 0:  [Mark 600µs] + [Space 600µs]   = 1.2 ms
Bit 1:  [Mark 600µs] + [Space 1.2ms]   = 1.8 ms
```

### Beispiel-Wellenform (3 Bits: `101`)

**Träger-Timing für Bits 1-0-1:**

| Segment | Dauer | State | Bit-Wert |
|---------|-------|-------|---------|
| Mark | 600 µs | AN | |
| Space 1 | 1200 µs | AUS | **1** (1.8 ms total) |
| Mark | 600 µs | AN | |
| Space 0 | 600 µs | AUS | **0** (1.2 ms total) |
| Mark | 600 µs | AN | |
| Space 1 | 1200 µs | AUS | **1** (1.8 ms total) |

## Frame-Format

Alle Frames bestehen aus 24 Bits, übertragen MSB-first:

title Frame
| Feld | Start Burst + Gap | Type | Data | CRC8 |
|------|-------------------|------|------|------|
| **Dauer** | (Start: 4× Basis) + (Gap: 1× Basis) | 3 Bits | 13 Bits | 8 Bits |
| **Funktion** | Synchronisation | Frame-Typ | Payload | Fehlerprüfung |
| **Summe** | – | – | – | **24 Bits** |

**Gesamte Frame-Zeit:** ~39 ms bei Standardwerten (Start 2400 µs + Gap 600 µs + 24 × 1.5 ms Bit-Durchschnitt). Mit angepasstem Basistakt/Multi skaliert alles linear.

### Type-Feld (3 Bits)

| Wert | Typ | Beschreibung |
|------|-----|-------------|
| `000` | Hit | Standard-Schuss |
| `001` | Heal | Medic-Heilung oder Health Pack |
| `010` | PowerUp | Station Power-Up Grant |
| `011` | Admin | System-Steuerbefehle |
| `100`–`111` | Reserviert | Zukünftige Nutzung |

### Data-Feld (13 Bits) – Type-abhängig

#### Hit-Frame (`000`)

| Bit-Range | Feld | Wertbereich | Beschreibung |
|-----------|------|-------------|-------------|
| 0–7 | Shooter ID | 0–255 | ID des Schützen (256 mögliche Spieler) |
| 8–12 | Damage | 0–31 | Schadenpunkte (0 = kein Schaden, 31 = Maximum) |

#### Heal-Frame (`001`)

| Bit-Range | Feld | Wertbereich | Beschreibung |
|-----------|------|-------------|-------------|
| 0–7 | Healer ID | 0–255 | ID des Heilers (Medic oder Station) |
| 8–12 | Amount | 0–31 | Heilpunkte wiederhergestellt |

#### PowerUp-Frame (`010`)

| Bit-Range | Feld | Wertbereich | Beschreibung |
|-----------|------|-------------|-------------|
| 0–7 | Station ID | 0–255 | Stations-ID, die das Power-Up gewährt |
| 8–12 | PowerUp | 0–31 | Power-Up-Typ-Identifier |

#### Admin-Frame (`011`)

| Bit-Range | Feld | Wertbereich | Beschreibung |
|-----------|------|-------------|-------------|
| 0–12 | Command Data | 0–8191 | Implementierungsdefinierte Steuerbefehle |

### CRC-Feld (8 Bits)

- **Algorithmus:** CRC-8-CCITT
- **Polynom:** 0x07 (x⁸ + x² + x + 1)
- **Initialwert:** 0x00
- **Eingabe:** Type (3 Bits) + Data (13 Bits) = 16 Bits
- **Zweck:** Fehlererkennung bei Bitfehlern durch Umgebungslicht oder Interferenzen

**Erwartete Fehlererkennungsrate:** >99.5 % für Einfach- oder Doppelbitfehler

## Beispiel-Frame

**Hit von Spieler 42 mit 10 Schaden:**

```
Type: 000 (Hit)
Data: 00101010 01010 (ShooterID=42, Damage=10)
CRC8: [berechnet aus obigen Daten]

Kompletter Frame (24 Bits):
000 00101010 01010 CCCCCCCC
│   │        │     └─ CRC8
│   │        └─ Damage (10)
│   └─ Shooter ID (42)
└─ Type (Hit)
```

**Übertragungsabfolge:**

1. Start Burst: 2400 µs Träger AN
2. Bit 0 (Type): 600 µs Mark + 600 µs Space
3. Bit 1 (Type): 600 µs Mark + 600 µs Space
4. Bit 2 (Type): 600 µs Mark + 600 µs Space
5. ... (21 weitere Bits)
6. Ende: Träger AUS

## Empfänger-Implementierung

### Hardware-Anforderungen

- TSOP4838 verbunden mit GPIO mit Interrupt-Fähigkeit
- Steigende/fallende Flanken-Erkennung
- Timer zur Messung der Space-Dauern

### Software-State-Machine

1. **IDLE:** Auf Start Burst warten (2000–2800 µs)
2. **SYNC:** Start Burst erkannt, Vorbereitung zur Bit-Empfang
3. **DATA:** Space nach jedem Mark messen, 24 Bits dekodieren
4. **VALIDATE:** CRC prüfen, Frame bei Gültigkeit verarbeiten

### Timing-Toleranzen

- Breite Toleranzbereiche (±17–33 %) kompensieren Interrupt-Jitter und Träger-Drift
- Fehlgeschlagener CRC zeigt beschädigten Frame an → stille Verwerfung
- Empfänger resynchronisiert automatisch beim nächsten Start Burst

## Konfigurierbare Parameter

Die Protokoll-Timing kann via Kconfig für verschiedene Umgebungen angepasst werden:

- `CONFIG_IR_SEND_CARRIER_HZ`: Trägerfrequenz (30–45 kHz)
- `CONFIG_IR_SEND_DUTY_CYCLE_PERCENT`: PWM Tastgrad (25–75 %)
- `CONFIG_IR_PROTO_BASE_US`: Basistakt (300–1000 µs)
- `CONFIG_IR_PROTO_START_MULT`: Startburst-Faktor (2–8)
- `CONFIG_IR_PROTO_GAP_MULT`: Gap-Faktor (0–4; 0 = kein Gap)
- `CONFIG_IR_PROTO_MARK_MULT`: Mark-Faktor (1–2)
- `CONFIG_IR_PROTO_SPACE0_MULT`: Space0-Faktor (1–3)
- `CONFIG_IR_PROTO_SPACE1_MULT`: Space1-Faktor (1–4)

Die Standardwerte folgen Sony SIRC Timing-Konventionen für bewährte Zuverlässigkeit.

## Leistungscharakteristiken

| Metrik | Wert |
|--------|------|
| Frame-Zeit | ~39 ms |
| Datenrate | ~410 bit/s |
| Max. Spieler-IDs | 256 |
| Reichweite (Außen) | ~50–100 m (abhängig von Sender-Leistung und Umgebungslicht) |
| Fehler-Erkennung | >99.5 % via CRC-8 |
| Störfestigkeit | Hoch (Hardware-Bandpass 38 kHz) |

---

## Bluetooth LE Protokoll

*Zu dokumentieren: BLE-Charakteristiken für Spielstatus-Synchronisierung, Team-Zuordnung, etc.*

