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

# 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

# Apri progetto
code /home/pi/Progetti

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

3. Prima Build

# 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

# 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

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

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

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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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! 🚀