# G2H LoRaWAN Heat Control

Intelligente Heizungssteuerung für STM32WL basierte LoRaWAN-Geräte mit dualer Temperaturüberwachung.

## Funktionsübersicht

### Sensoren
- **SHT4X**: Raumtemperatur und Luftfeuchtigkeit
- **MLX90614**: IR-Bodentemperatur (optional)
- **Relais**: Heizungssteuerung (Ein/Aus)

### Automatische Heizungsregelung
Das System schaltet die Heizung automatisch basierend auf zwei Temperaturschwellwerten:

1. **Raumtemperatur** (Standard: 21°C)
2. **Bodentemperatur** (Standard: 22°C, nur wenn Sensor verfügbar)

**Regel**: Heizung ist AN wenn **beide** Bedingungen erfüllt sind:
- Raumtemperatur < Schwellwert UND
- Bodentemperatur < Schwellwert (falls Sensor verfügbar)

**Fallback**: Wenn MLX90614-Sensor nicht verfügbar → nur Raumtemperatur wird überwacht.

## LoRaWAN-Konfiguration

### Netzwerk
- **Aktivierung**: ABP (Activation by Personalization)
- **Region**: EU868
- **Port**: 2
- **Sendeintervall**: Standard 10 Minuten (konfigurierbar 1-255 min)

## Downlink-Befehle

Alle Befehle als Base64 in ChirpStack eingeben:

### Kombinierte Konfiguration (3 Bytes)
**Format**: `[heating_enable][room_temp][floor_temp]`

| Beschreibung | Hex | Base64 | Funktion |
|--------------|-----|--------|----------|
| Heizung AN, 22°C Raum, 25°C Boden | `01 16 19` | `ARYa` | Automatik aktiviert mit neuen Schwellwerten |
| Heizung AUS | `00 14 18` | `ABQa` | Heizung komplett deaktiviert |
| Heizung AN, 20°C Raum, 24°C Boden | `01 14 18` | `ARQa` | Automatik mit niedrigeren Schwellwerten |

### Sendeintervall ändern (2 Bytes)
**Format**: `'i'[minuten]`

| Beschreibung | Hex | Base64 | Funktion |
|--------------|-----|--------|----------|
| 5 Minuten Intervall | `69 05` | `aQU=` | Häufigere Übertragung |
| 15 Minuten Intervall | `69 0F` | `aQ8=` | Normale Übertragung |
| 60 Minuten Intervall | `69 3C` | `aTw=` | Seltene Übertragung |

**Hinweis**:
- Temperaturwerte: 0-255°C möglich
- Sendeintervall: 1-255 Minuten möglich
- Heating Enable: 0=AUS (Relais bleibt aus), 1=AN (automatische Regelung)

## Datenformat (Uplink)

Alle 10 Minuten wird ein 7-Byte Datenpaket gesendet:

| Byte | Inhalt | Format |
|------|--------|--------|
| 0-1 | Raumtemperatur | int16 × 100 (z.B. 2134 = 21.34°C) |
| 2-3 | Bodentemperatur | int16 × 100 |
| 4-5 | Luftfeuchtigkeit | int16 × 100 (z.B. 4520 = 45.20%) |
| 6 | Relais-Status | 0 = AUS, 1 = AN |

## Betriebsmodi

### 1. Automatik-Modus (Standard)
- Heizung wird automatisch basierend auf Temperaturschwellwerten gesteuert
- Beide Temperaturen werden überwacht (falls MLX-Sensor verfügbar)

### 2. Manueller Override
- Aktiviert durch Heizung AUS Befehl (Byte 0 = 0) → Heizung permanent AUS
- Deaktiviert durch Heizung AN Befehl (Byte 0 = 1)

### 3. Sensor-Fallback
- Wenn MLX90614 nicht verfügbar → nur Raumtemperatur wird überwacht
- Automatische Erkennung bei jedem Lesezyklus

## Status-Ausgabe

Über serielle Konsole (115200 baud):

```
hum: 45.20%
temp: 21.34 °C
floor_temp: 19.87 °C
relais: 1 (manual: 0, temp_th: 21°C, floor_th: 22°C)
```

- **relais**: 0=AUS, 1=AN
- **manual**: 0=Automatik, 1=Manueller Override
- **temp_th**: Raumtemperatur-Schwellwert
- **floor_th**: Bodentemperatur-Schwellwert

## Fehlerbehandlung

### MLX90614-Sensor nicht verfügbar
```
[ERR] MLX90614 reading sensor values failed 5 times with error 251!
```
→ System wechselt automatisch zu Raumtemperatur-only Modus

### LoRaWAN-Verbindungsfehler
```
[WRN] LoRaWAN busy (duty cycle), retrying in 1s...
```
→ Automatische Wiederholung nach 1 Sekunde

## Beispiel-Szenarien

### Szenario 1: Normale Heizung
- Raumtemp: 19°C (< 21°C) ✓
- Bodentemp: 20°C (< 22°C) ✓
- **Resultat**: Heizung AN

### Szenario 2: Überhitzungsschutz
- Raumtemp: 23°C (≥ 21°C) ✗
- Bodentemp: 20°C (< 22°C) ✓
- **Resultat**: Heizung AUS

### Szenario 3: Bodentemperaturschutz
- Raumtemp: 19°C (< 21°C) ✓
- Bodentemp: 25°C (≥ 22°C) ✗
- **Resultat**: Heizung AUS

### Szenario 4: Sensor-Ausfall
- Raumtemp: 19°C (< 21°C) ✓
- MLX-Sensor: Nicht verfügbar
- **Resultat**: Heizung AN (nur Raumtemp wird geprüft)

## Setup & Installation

### 1. Framework Setup (Windows)
```bash
# Automatische PlatformIO-Konfiguration
setup_framework.bat
```

### 2. Neues Gerät einrichten

#### 2.1 ChirpStack Konfiguration
1. **Application erstellen** (falls nicht vorhanden):
   - Name: `G2H-Heat-Control`
   - Description: `LoRaWAN Heizungssteuerung`

2. **Device Profile erstellen** (falls nicht vorhanden):
   - Name: `STM32WL-ABP`
   - Region: `EU868`
   - MAC Version: `1.0.4`
   - Regional Parameters Revision: `RP002-1.0.3`
   - Activation: `ABP`
   - Class: `A`
   - Supports OTAA: ❌
   - ADR Algorithm: `Default`

3. **Device erstellen**:
   - **General Tab**:
     - Device name: `Heat-Controller-001` (eindeutig wählen)
     - Device description: `Heizungssteuerung Raum XY`
     - Device EUI: Neue eindeutige EUI generieren (z.B. `4633500400ABCD01`)
     - Device Profile: `STM32WL-ABP`
     - Skip FCnt check: ✅ (für Entwicklung/Test)

   - **Activation Tab** (ABP):
     - Device address: Neue Adresse generieren (z.B. `01234567`)
     - Network session key: 32 Zeichen Hex (z.B. `268FDA933F4CAEBF96A30FE76027A41E`)
     - Application session key: 32 Zeichen Hex (z.B. `408009CA1D9FE2B822F4684D76331300`)

#### 2.2 Firmware-Konfiguration
Öffne `src/lora/lorawan.h` und trage die ChirpStack-Werte ein:

```c
/* ABP Configuration */
#define LORAWAN_DEV_ADDR {0x01, 0x23, 0x45, 0x67}  // Device Address (Big Endian!)
#define LORAWAN_NWKS_KEY {0x26, 0x8F, 0xDA, 0x93, \  // Network Session Key
                          0x3F, 0x4C, 0xAE, 0xBF, \
                          0x96, 0xA3, 0x0F, 0xE7, \
                          0x60, 0x27, 0xA4, 0x1E}
#define LORAWAN_APPS_KEY {0x40, 0x80, 0x09, 0xCA, \  // Application Session Key
                          0x1D, 0x9F, 0xE2, 0xB8, \
                          0x22, 0xF4, 0x68, 0x4D, \
                          0x76, 0x33, 0x13, 0x00}
```

**Wichtig**: DevEUI wird in `src/lora/lorawan.c` gesetzt:
```c
// Zeile ~113-120: Eindeutige DevEUI eintragen
dev_eui[0] = 0x46;  // Entspricht ChirpStack DevEUI
dev_eui[1] = 0x33;  // 4633500400ABCD01 wird zu:
dev_eui[2] = 0x50;  // {0x46, 0x33, 0x50, 0x04,
dev_eui[3] = 0x04;  //  0x00, 0xAB, 0xCD, 0x01}
dev_eui[4] = 0x00;
dev_eui[5] = 0xAB;
dev_eui[6] = 0xCD;
dev_eui[7] = 0x01; // Letztes Byte für Gerät eindeutig machen
```

#### 2.3 Format-Konvertierung ChirpStack → Code

| ChirpStack | Code Format | Beispiel |
|------------|-------------|----------|
| Device Address: `01234567` | `{0x01, 0x23, 0x45, 0x67}` | Big Endian Bytes |
| DevEUI: `4633500400ABCD01` | `dev_eui[0] = 0x46; ... dev_eui[7] = 0x01;` | Byte Array |
| Session Keys: `268F...A41E` | `{0x26, 0x8F, ..., 0x1E}` | 16 Byte Array |

### 3. Build & Flash
```bash
# Projekt kompilieren
pio run

# Firmware flashen (Device per USB verbinden)
pio run -t upload
```

### 4. Verification
1. **Serielle Konsole** öffnen (115200 baud):
   ```
   === Device starting ===
   DevEUI: 46:33:50:04:00:AB:CD:01
   DevAddr: 0x67452301
   ✓ Successfully activated LoRaWAN network via ABP
   ```

2. **ChirpStack Monitoring**:
   - Device sollte nach ~30 Sekunden erste Uplinks senden
   - LoRaWAN Frames Tab: Uplinks alle 10 Minuten
   - Payload: 7 Bytes Sensordaten

3. **Test Downlink**:
   - In ChirpStack: Queue Downlink
   - Payload: `ARYa` (Base64) - Heizung AN, 22°C Raum, 25°C Boden
   - Port: 2
   - Confirmed: ❌

### 5. Troubleshooting

#### Keine Uplinks in ChirpStack
- [ ] DevEUI in Code korrekt gesetzt?
- [ ] DevAddr Big Endian konvertiert?
- [ ] Session Keys richtig formatiert?
- [ ] Gateway in Reichweite und online?

#### ABP Activation Failed
- [ ] Device Profile auf ABP konfiguriert?
- [ ] Skip FCnt Check aktiviert?
- [ ] Korrekte Region (EU868)?

#### Sensor Fehler
```
[ERR] MLX90614 reading sensor values failed 5 times
```
→ Normal wenn kein Bodensensor angeschlossen, System läuft trotzdem