docker-voltronic-homeassistant/documentation/TEST_LOOP_REFERENCE.md

# Quick Reference - Test Loop & MQTT Configuration

## 🔧 Configurazione MQTT Server

### File di Configurazione

**Development:**
```
/home/pi/Progetti/config/mqtt.json
```

**Container (Production):**
```
/etc/inverter/mqtt.json
```

### Parametri Chiave

```json
{
  "server": "[HA_MQTT_IP]",           // ← Indirizzo IP Home Assistant
  "port": "1883",                      // Porta MQTT standard
  "topic": "homeassistant",            // Topic base
  "devicename": "voltronic",           // Nome device (prefix topic)
  "username": "",                      // Username MQTT (se richiesto)
  "password": "",                      // Password MQTT (se richiesto)
  "clientid": "voltronic_...",        // Client ID univoco
  "influx": {
    "enabled": "false",                // InfluxDB (opzionale)
    ...
  }
}
```

### Modificare la Configurazione

```bash
# Editare il file
nano /home/pi/Progetti/config/mqtt.json

# Cambiare l'IP del server MQTT
# Sostituire [HA_MQTT_IP] con l'IP reale di Home Assistant
# Esempio: "server": "192.168.1.100"
```

---

## 🔄 Test Loop - Simulazione Container

### Script Principale

```bash
/home/pi/Progetti/sources/inverter-mqtt/test-loop-parallel.sh
```

### Esecuzione Manuale

**Modalità interattiva (infinito):**
```bash
bash /home/pi/Progetti/sources/inverter-mqtt/test-loop-parallel.sh
```

**Modalità con limiti:**
```bash
# 5 iterazioni con intervallo 10 secondi
LOOP_INTERVAL=10 MAX_ITERATIONS=5 bash test-loop-parallel.sh

# 2 iterazioni con intervallo 5 secondi (test rapido)
LOOP_INTERVAL=5 MAX_ITERATIONS=2 bash test-loop-parallel.sh
```

### Variabili d'Ambiente

| Variabile | Descrizione | Default |
|-----------|-------------|---------|
| `LOOP_INTERVAL` | Secondi tra iterazioni | 30 |
| `MAX_ITERATIONS` | Numero massimo iterazioni (0=infinito) | 0 |

### Fasi del Test Loop

#### **Phase 1: Initial Discovery** (eseguito una volta all'avvio)

1. **Buffer Sizes Auto-Discovery** (`-a`)
   - Rileva dimensioni corrette per QMOD, QPIGS, QPIRI, QPIWS
   - Output: `DISCOVERY_QMOD=5`, `DISCOVERY_QPIGS=110`, etc.

2. **Parallel Inverters Discovery** (`-p`)
   - Cerca inverter in configurazione parallela (QPGS0-QPGS9)
   - Filtra serial validi (no "00000000000000")
   - Filtra duplicati
   - Output: `PARALLEL_COUNT=2`, `INVERTER_1_SERIAL=...`, etc.

#### **Phase 2: Main Polling Loop** (ripetuto ogni N secondi)

1. **Test Standard Commands** (inverter locale via USB)
   - QPIGS - General status
   - QPIRI - Configuration
   - QMOD - Operating mode
   - QPIWS - Warning status

2. **Read Parallel Inverters** (tutti gli inverter via QPGS)
   - Per ogni inverter trovato:
     - Legge dati QPGS
     - Estrae: Mode, Grid Voltage, Battery Voltage, Load Watts

3. **MQTT Push** (pubblica su Home Assistant)
   - Esegue `mqtt-push-parallel.sh`
   - Pubblica topic separati per ogni inverter
   - Formato: `homeassistant/sensor/voltronic_inv1_*`

---

## 📊 Topic MQTT Pubblicati

### Per Ogni Inverter

```
homeassistant/sensor/voltronic_inv1_serial              → "92932111105114"
homeassistant/sensor/voltronic_inv1_mode                → "B" (Battery mode)
homeassistant/sensor/voltronic_inv1_AC_grid_voltage     → "229.8"
homeassistant/sensor/voltronic_inv1_AC_grid_frequency   → "50.0"
homeassistant/sensor/voltronic_inv1_AC_out_voltage      → "229.5"
homeassistant/sensor/voltronic_inv1_AC_out_frequency    → "49.9"
homeassistant/sensor/voltronic_inv1_Load_va             → "481"
homeassistant/sensor/voltronic_inv1_Load_watt           → "465"
homeassistant/sensor/voltronic_inv1_Load_pct            → "8"
homeassistant/sensor/voltronic_inv1_Battery_voltage     → "53.9"
homeassistant/sensor/voltronic_inv1_Battery_charge_current → "4"
homeassistant/sensor/voltronic_inv1_Battery_capacity    → "100"
homeassistant/sensor/voltronic_inv1_PV_in_voltage       → "246.8"
homeassistant/sensor/voltronic_inv1_PV_in_current       → "4"
```

### Topic Sistema

```
homeassistant/sensor/voltronic_system_parallel_count → "2"
```

---

## 🐛 Debug Profiles VS Code

### 1. Parallel Discovery - Container Mode
**Profile:** `(gdb) Parallel Discovery - Container Mode`
- Esegue: `inverter_poller -p`
- Simula ambiente container (cwd="/")
- ENV: `INVERTER_DEVICE=/dev/ttyUSB0`

### 2. Test MQTT Parallel - Container Simulation
**Profile:** `(bash) Test MQTT Parallel - Container Simulation`
- Esegue: `mqtt-push-parallel.sh`
- Debug bash script MQTT

### 3. Test Loop - Full Simulation
**Profile:** `(bash) Test Loop - Full Simulation`
- Esegue: `test-loop-parallel.sh`
- 3 iterazioni con intervallo 10s
- Full simulation discovery + polling + MQTT

---

## 📝 Comandi Utili

### Discovery Manuale

```bash
# Buffer sizes discovery
sudo /home/pi/Progetti/sources/inverter-cli/bin/inverter_poller -a

# Parallel inverters discovery
sudo /home/pi/Progetti/sources/inverter-cli/bin/inverter_poller -p

# Test comando specifico
sudo /home/pi/Progetti/sources/inverter-cli/bin/inverter_poller -r QPGS0
```

### MQTT Push Manuale

```bash
# Single run
bash /home/pi/Progetti/sources/inverter-mqtt/mqtt-push-parallel.sh

# Con debug output
bash /home/pi/Progetti/sources/inverter-mqtt/mqtt-push-parallel.sh 2>&1 | less
```

### Monitoraggio MQTT (da altro terminal)

```bash
# Subscribe a tutti i topic
mosquitto_sub -h [HA_MQTT_IP] -t "homeassistant/#" -v

# Solo sensori voltronic
mosquitto_sub -h [HA_MQTT_IP] -t "homeassistant/sensor/voltronic_#" -v
```

---

## 🔍 Output Esempio Test Loop

```
╔════════════════════════════════════════════════════════════════╗
║     VOLTRONIC PARALLEL INVERTER - TEST LOOP                   ║
╚════════════════════════════════════════════════════════════════╝

Mode: Development
Binary: /home/pi/Progetti/sources/inverter-cli/bin/inverter_poller
MQTT Config: /home/pi/Progetti/config/mqtt.json
Loop Interval: 30s
Max Iterations: ∞ (infinite)
MQTT Server: 192.168.1.100

╔════════════════════════════════════════════════════════════════╗
║ PHASE 1: INITIAL DISCOVERY                                    ║
╚════════════════════════════════════════════════════════════════╝

[1.1] Buffer Sizes Auto-Discovery
✓ Buffer sizes discovered successfully
  • QMOD:  5 bytes
  • QPIGS: 110 bytes
  • QPIRI: 103 bytes
  • QPIWS: 40 bytes

[1.2] Parallel Inverters Discovery
✓ Found 2 parallel inverter(s)
  • Inverter #1: Serial 92932111105114 (QPGS0)
  • Inverter #2: Serial 96332205100144 (QPGS2)

╔════════════════════════════════════════════════════════════════╗
║ PHASE 2: MAIN POLLING LOOP                                    ║
╚════════════════════════════════════════════════════════════════╝

═══════════════════════════════════════════════════════════════
Iteration #1 - 2026-01-31 15:25:35
═══════════════════════════════════════════════════════════════
[2.1] Testing standard commands (local inverter)
  ✓ QPIGS: OK (106 chars)
  ✓ QPIRI: OK (99 chars)
  ✓ QMOD: OK (1 chars)
  ✓ QPIWS: OK (36 chars)

[2.2] Reading parallel inverters data
  ✓ Inverter #1 (92932111105114): Mode=B, Grid=229.8V, Battery=53.6V, Load=0488W
  ✓ Inverter #2 (96332205100144): Mode=B, Grid=232.4V, Battery=53.6V, Load=0300W

[2.3] MQTT Push
✓ MQTT push completed

Waiting 30s until next iteration...
```

---

## 🚀 Setup Rapido per Test

1. **Configura MQTT server:**
   ```bash
   nano /home/pi/Progetti/config/mqtt.json
   # Cambia "server": "[HA_MQTT_IP]" con IP reale
   ```

2. **Esegui test rapido (2 iterazioni):**
   ```bash
   cd /home/pi/Progetti
   LOOP_INTERVAL=5 MAX_ITERATIONS=2 bash sources/inverter-mqtt/test-loop-parallel.sh
   ```

3. **Verifica MQTT (in altro terminal):**
   ```bash
   mosquitto_sub -h [HA_MQTT_IP] -t "homeassistant/sensor/voltronic_#" -v
   ```

4. **Per produzione (loop continuo):**
   ```bash
   bash sources/inverter-mqtt/test-loop-parallel.sh
   ```