docker-voltronic-homeassistant/documentation/QUICKSTART.md

# Quick Start Guide - Development & Debug

Questa guida fornisce un rapido riferimento per iniziare a sviluppare e debuggare il progetto.

## Setup Iniziale

### 1. Requisiti Sistema

```bash
# Aggiorna sistema
sudo apt-get update

# Installa dipendenze build
sudo apt-get install -y build-essential cmake gdb git

# Installa dipendenze runtime
sudo apt-get install -y mosquitto-clients jq

# Aggiungi utente al gruppo per accesso seriale (opzionale)
sudo usermod -a -G dialout $USER
# Logout e login necessari per applicare
```

### 2. Setup VS Code

```bash
# Apri progetto
code /home/pi/Progetti

# Installa estensioni raccomandate quando richiesto
# Oppure manualmente: Ctrl+Shift+P → "Extensions: Show Recommended Extensions"
```

### 3. Prima Build

```bash
# Opzione A: Da VS Code
# Premi Ctrl+Shift+B → Seleziona "build-inverter-cli"

# Opzione B: Da terminale
cd /home/pi/Progetti/sources/inverter-cli
mkdir -p bin
cmake .
make
```

### 4. Verifica Build

```bash
# Test esecuzione (senza device fisico, darà errore ma verifica che compili)
./sources/inverter-cli/bin/inverter_poller --help
```

## Workflow di Sviluppo

### Scenario 1: Modificare e Testare Codice

```bash
1. Apri file da modificare (es. sources/inverter-cli/main.cpp)
2. Fai modifiche al codice
3. Build: Ctrl+Shift+B (oppure F5 per build+debug)
4. Test: Tasks → "run-inverter-cli-once"
5. Verifica output JSON
```

### Scenario 2: Debug di un Bug

```bash
1. Riproduci il bug manualmente
2. Identifica file sorgente coinvolto
3. Apri file e imposta breakpoint (F9)
4. Premi F5 → Seleziona "(gdb) Debug inverter_poller - Run Once with Debug"
5. Usa Debug toolbar:
   - F10: Step Over (prossima riga)
   - F11: Step Into (entra in funzione)
   - Shift+F11: Step Out (esci da funzione)
6. Ispeziona variabili nel pannello Variables/Watch
7. Continua (F5) o Stop (Shift+F5)
```

### Scenario 3: Aggiungere Nuovo Comando Inverter

```bash
1. Apri sources/inverter-cli/main.cpp
2. Aggiungi parsing nella sezione sscanf
3. Aggiungi output nella sezione printf JSON
4. Build e test: Ctrl+Shift+B
5. Verifica JSON output
6. Aggiorna sources/inverter-mqtt/mqtt-push.sh per pushare nuovo valore
7. Aggiorna sources/inverter-mqtt/mqtt-init.sh per auto-discovery
```

### Scenario 4: Debug con Device Reale

```bash
1. Connetti inverter via USB/RS232
2. Identifica device:
   ls -la /dev/ttyUSB*  # o ttyS*, hidraw*
   
3. Configura device:
   # Modifica config/inverter.conf
   device=/dev/ttyUSB0
   
4. Verifica permessi:
   sudo chmod 666 /dev/ttyUSB0
   
5. Debug normale:
   F5 → Seleziona configurazione debug
   
6. Imposta breakpoint in inverter.cpp → query()
7. Osserva comunicazione seriale in tempo reale
```

### Scenario 5: Test Docker Locale

```bash
# Opzione A: Da VS Code Tasks
1. Tasks → "docker-build"
2. Tasks → "docker-run"
3. Tasks → "docker-logs" (monitora output)
4. Quando finito: Tasks → "docker-stop"

# Opzione B: Da terminale
cd /home/pi/Progetti
docker-compose up --build

# Test manuale nel container
docker exec -it voltronic-mqtt bash
/opt/inverter-cli/bin/inverter_poller -d -1
```

## Comandi Utili

### Build e Run

```bash
# Build Release
cd sources/inverter-cli && cmake . && make

# Build Debug (con simboli)
cd sources/inverter-cli && cmake -DCMAKE_BUILD_TYPE=Debug . && make

# Clean build
cd sources/inverter-cli && rm -rf bin CMakeFiles CMakeCache.txt cmake_install.cmake Makefile

# Run con debug flag
./sources/inverter-cli/bin/inverter_poller -d -1

# Run comando raw
./sources/inverter-cli/bin/inverter_poller -r QPIGS

# Run in loop
./sources/inverter-cli/bin/inverter_poller -d
```

### Test Device

```bash
# Verifica device disponibili
ls -la /dev/tty* /dev/hidraw*

# Test read da device (richiede screen o minicom)
sudo apt-get install screen
sudo screen /dev/ttyUSB0 2400

# Verifica permessi
sudo chmod 666 /dev/ttyUSB0
# O permanente:
sudo usermod -a -G dialout $USER && newgrp dialout
```

### Debug GDB Manuale

```bash
# Build con debug symbols
cd sources/inverter-cli
cmake -DCMAKE_BUILD_TYPE=Debug . && make

# Avvia in GDB
gdb --args bin/inverter_poller -d -1

# Comandi GDB utili:
(gdb) break main.cpp:150     # Breakpoint a linea
(gdb) break cInverter::query # Breakpoint a funzione
(gdb) run                    # Avvia
(gdb) next                   # Step over (n)
(gdb) step                   # Step into (s)
(gdb) continue              # Continua (c)
(gdb) print voltage_grid    # Stampa variabile (p)
(gdb) info locals           # Mostra tutte variabili locali
(gdb) backtrace            # Stack trace (bt)
(gdb) quit                 # Esci (q)
```

### Docker

```bash
# Build locale
docker build -f Dockerfile.dev -t voltronic-mqtt:dev .

# Run
docker-compose up -d

# Logs
docker logs -f voltronic-mqtt

# Exec nel container
docker exec -it voltronic-mqtt bash

# Debug nel container
docker exec -it voltronic-mqtt /opt/inverter-cli/bin/inverter_poller -d -1

# Stop
docker-compose down
```

### Git Workflow

```bash
# Prima di modifiche
git checkout -b feature/nuova-funzionalita

# Durante sviluppo
git add sources/inverter-cli/main.cpp
git commit -m "Add: nuova metrica XYZ"

# Push
git push origin feature/nuova-funzionalita

# Gitea Actions builderà automaticamente su push
```

## Configurazioni Debug VS Code

### Configurazioni Disponibili (F5)

| Nome | Uso | Quando Usare |
|------|-----|--------------|
| Debug inverter_poller | Build Release | Debug rapido, problemi performance |
| Run Once with Debug | Build completa | Debug approfondito, simboli completi |
| Loop Mode | Loop continuo | Debug threading, problemi intermittenti |
| Raw Command | Comando specifico | Test singolo comando inverter |
| Attach to running | Attach esterno | Debug container o daemon |

### Tasks Disponibili (Ctrl+Shift+P → Tasks: Run Task)

| Task | Descrizione |
|------|-------------|
| build-inverter-cli | Build Release (default: Ctrl+Shift+B) |
| build-inverter-cli-debug | Build con simboli debug |
| clean-inverter-cli | Pulizia file build |
| rebuild-inverter-cli | Clean + Build |
| run-inverter-cli-once | Build e esegui una volta |
| run-inverter-cli-loop | Build e esegui in loop |
| docker-build | Build immagine Docker |
| docker-run | Avvia container |
| docker-logs | Visualizza log |
| docker-stop | Ferma container |

## Shortcuts VS Code

| Shortcut | Azione |
|----------|--------|
| `Ctrl+Shift+B` | Build (default task) |
| `F5` | Start Debugging |
| `Ctrl+F5` | Run Without Debugging |
| `F9` | Toggle Breakpoint |
| `F10` | Step Over |
| `F11` | Step Into |
| `Shift+F11` | Step Out |
| `Shift+F5` | Stop Debugging |
| `Ctrl+Shift+F5` | Restart Debugging |
| `Ctrl+` ` | Toggle Terminal |
| `Ctrl+Shift+P` | Command Palette |
| `Ctrl+P` | Quick Open File |

## Testing

### Unit Test Locale

```bash
# Test parsing dati
./sources/inverter-cli/bin/inverter_poller -d -1 | jq .

# Test comando specifico
./sources/inverter-cli/bin/inverter_poller -r QPIGS

# Test con output su file
./sources/inverter-cli/bin/inverter_poller -d -1 > /tmp/test_output.json
cat /tmp/test_output.json | jq .
```

### Integration Test MQTT

```bash
# Terminal 1: Subscribe a topic
mosquitto_sub -h localhost -t "homeassistant/#" -v

# Terminal 2: Esegui poller e push
cd sources/inverter-mqtt
./mqtt-push.sh

# Verifica messaggi ricevuti in Terminal 1
```

### Test Docker End-to-End

```bash
# 1. Build
docker-compose build

# 2. Run
docker-compose up -d

# 3. Verifica logs
docker logs -f voltronic-mqtt

# 4. Test MQTT output
mosquitto_sub -h [MQTT_SERVER] -t "homeassistant/sensor/voltronic/#" -v

# 5. Test comando
mosquitto_pub -h [MQTT_SERVER] \
  -t "homeassistant/sensor/voltronic/command" \
  -m "QPIGS"
```

## Troubleshooting Rapido

| Problema | Soluzione |
|----------|-----------|
| "Unable to open device" | Verifica device in config/inverter.conf e permessi |
| "CRC error" | Controlla cablaggio RS232 e buffer size in config |
| GDB non trova simboli | Build con: `cmake -DCMAKE_BUILD_TYPE=Debug .` |
| IntelliSense non funziona | Reload Window (Ctrl+Shift+P → "Reload Window") |
| Build fallisce | Clean: `rm -rf CMakeFiles CMakeCache.txt` poi rebuild |
| Permission denied device | `sudo chmod 666 /dev/ttyUSB0` o aggiungi a gruppo dialout |

## Risorse

- **[.vscode/DEBUG.md]** - Guida debug completa
- **[.vscode/README.md]** - Documentazione configurazioni VS Code
- **[.github/copilot-instructions.md]** - Documentazione completa progetto
- **[README.md]** - Documentazione principale
- **[manual/]** - Manuali protocollo inverter

## Prossimi Passi

1. ✅ Setup ambiente completato
2. 📖 Leggi documentazione protocollo in `/manual/`
3. 🔧 Prova modifiche semplici (es. aggiungi log)
4. 🐛 Usa debug per capire flusso programma
5. 🚀 Contribuisci: aggiungi nuove metriche o comandi
6. 🐳 Testa in Docker prima di production

## Support

- Issues: [GitHub/Gitea Issues]
- Docs: File README.md e .vscode/DEBUG.md
- Forum: AEVA Forum (link in README.md principale)

---

**Happy Coding! 🚀**