feat(v2.0): Auto-discovery, correzione bug critici, e documentazione completa

🆕 Funzionalità Auto-Discovery - Aggiunto metodo AutoDiscoverBufferSizes() per rilevamento automatico QPIGS/QPIRI/QMOD/QPIWS - Supporto variabili d'ambiente (INVERTER_DEVICE, MQTT_SERVER, etc.) - Caching persistente buffer sizes in /cache/inverter.conf.cache - Flag -a/--auto-discover per modalità auto-detection 🐛 Bug Fixes Critici - **Parsing interi**: Aggiunta attemptAddSettingInt() con stoi() invece di stof() - Fix: stof('98') = 98.0f → 97 (int), ora stoi('98') = 98 direttamente - Applicato a: qpiri, qpiws, qmod, qpigs - **Thread sync**: Aggiunto ups_qpiws_changed a main loop e condizione exit poll() - Fix: loop principale controllava solo 3 flag su 4, causava hang - Fix: thread poll() non usciva in runOnce perché mancava controllo QPIWS - **Config accuracy**: Corretti buffer sizes (qpiri: 98→103, qpiws: 36→40) - Rimosso sources/inverter-cli/inverter.conf che sovrascriveva config globale - Validato con test: inverter_poller -1 completa in 6s con JSON completo 📚 Documentazione Completa - Creato documentation/CODE_ARCHITECTURE.md (38KB) - Mappa logica variabili globali - Flusso esecuzione main() con diagrammi ASCII - Sequence diagram classe cInverter (poll, query, auto-discovery) - Thread synchronization diagrams - MQTT integration bash scripts flow - Mappa concettuale 5-layer system architecture - Error handling e performance optimizations - Organizzati file .md in documentation/ (AUTO_DISCOVERY, IMPLEMENTATION, QUICKSTART, DEBUG) - Aggiornato README.md con sezione v2.0 e indice documentazione - Aggiornato .github/copilot-instructions.md con novità v2.0 🔧 Miglioramenti Build & CI/CD - Gitea Actions per build multi-arch (arm/v6, arm/v7, arm64, amd64, 386) - Configurazione VS Code completa (tasks, launch, debug GDB) - Script test-autodiscovery.sh e test-device.sh ✅ Testing Validato - inverter_poller -1 completa in 6 secondi - Output JSON completo con tutte le metriche - Exit pulito senza timeout (exit code 0) - Tutte le 4 query QMOD/QPIGS/QPIRI/QPIWS funzionanti
2026-01-25 15:00:48 +01:00
parent ac2642639f
commit 6af9fcad7e
30 changed files with 4503 additions and 139 deletions
@@ -0,0 +1,367 @@
+# Debug Configuration - inverter-cli
+
+Questa directory contiene le configurazioni per il debug dell'applicazione `inverter-cli` in VS Code.
+
+## Prerequisiti
+
+### Software Richiesto
+
+```bash
+# Installa gli strumenti di build e debug
+sudo apt-get update
+sudo apt-get install -y build-essential cmake gdb
+
+# Verifica installazione
+gdb --version
+cmake --version
+g++ --version
+```
+
+### Estensioni VS Code Consigliate
+
+- **C/C++** (ms-vscode.cpptools) - IntelliSense, debugging, browsing
+- **CMake** (twxs.cmake) - Syntax highlighting per CMakeLists.txt
+- **CMake Tools** (ms-vscode.cmake-tools) - Integrazione CMake avanzata
+
+## Configurazioni di Debug Disponibili
+
+### 1. Debug inverter_poller (Release Build)
+**Nome:** `(gdb) Debug inverter_poller`
+- Build in modalità Release con ottimizzazioni
+- Esegue con flag `-d -1` (debug + run-once)
+- Utile per debug rapido senza simboli completi
+
+### 2. Debug inverter_poller - Run Once with Debug
+**Nome:** `(gdb) Debug inverter_poller - Run Once with Debug`
+- Build in modalità Debug con simboli completi
+- Esegue con flag `-d -1`
+- Include tutti i simboli di debug per analisi dettagliata
+- **Consigliato per debug approfondito**
+
+### 3. Debug inverter_poller - Loop Mode
+**Nome:** `(gdb) Debug inverter_poller - Loop Mode`
+- Build in modalità Debug
+- Esegue in modalità loop continuo con debug `-d`
+- Utile per debug di problemi intermittenti o di threading
+
+### 4. Debug inverter_poller - Raw Command
+**Nome:** `(gdb) Debug inverter_poller - Raw Command`
+- Build in modalità Debug
+- Esegue comando raw specifico: `-r QPIGS`
+- Modifica l'argomento in launch.json per testare altri comandi
+
+### 5. Attach to running inverter_poller
+**Nome:** `(gdb) Attach to running inverter_poller`
+- Attach a processo già in esecuzione
+- Utile per debug di container o processi daemon
+- Richiede permessi adeguati (potrebbe richiedere sudo)
+
+## Tasks di Build
+
+### Build Tasks
+
+#### build-inverter-cli (Default)
+```bash
+Ctrl+Shift+B
+```
+Build in modalità Release con ottimizzazioni (-O2).
+
+#### build-inverter-cli-debug
+Build in modalità Debug con simboli completi (-O0 -g).
+
+#### clean-inverter-cli
+Pulisce tutti i file di build generati.
+
+#### rebuild-inverter-cli
+Pulisce e ricompila completamente il progetto.
+
+### Run Tasks
+
+#### run-inverter-cli-once
+```bash
+Tasks: Run Task → run-inverter-cli-once
+```
+Compila ed esegue il poller una volta con debug abilitato.
+
+#### run-inverter-cli-loop
+Compila ed esegue il poller in modalità loop continuo.
+
+### Docker Tasks
+
+#### docker-build
+Build dell'immagine Docker locale per development.
+
+#### docker-run
+Avvia il container con docker-compose.
+
+#### docker-logs
+Mostra i log del container in tempo reale.
+
+#### docker-stop
+Ferma il container docker-compose.
+
+## Workflow di Debug Tipici
+
+### Debug Locale (senza device fisico)
+
+Il programma proverà ad aprire il device seriale. Se non è disponibile, otterrai errori ma puoi comunque:
+
+1. **Debug della logica di parsing:**
+   ```bash
+   # Modifica temporaneamente main.cpp per usare dati mock
+   # Oppure esegui con un device virtuale
+   ```
+
+2. **Debug con socat (porta seriale virtuale):**
+   ```bash
+   # Installa socat
+   sudo apt-get install socat
+   
+   # Crea coppia di porte virtuali
+   socat -d -d pty,raw,echo=0 pty,raw,echo=0
+   # Output: PTY is /dev/pts/2 e /dev/pts/3
+   
+   # Modifica config/inverter.conf
+   device=/dev/pts/2
+   
+   # In un altro terminale, simula risposte inverter su /dev/pts/3
+   ```
+
+### Debug con Device Reale
+
+1. **Identifica il device:**
+   ```bash
+   ls -la /dev/ttyUSB* /dev/ttyS* /dev/hidraw*
+   dmesg | grep tty  # Per vedere device USB
+   ```
+
+2. **Verifica permessi:**
+   ```bash
+   sudo chmod 666 /dev/ttyUSB0  # O il tuo device
+   # OPPURE aggiungi utente al gruppo
+   sudo usermod -a -G dialout $USER
+   # Logout e login necessari
+   ```
+
+3. **Aggiorna configurazione:**
+   ```bash
+   # Modifica config/inverter.conf
+   device=/dev/ttyUSB0
+   ```
+
+4. **Avvia debug:**
+   - Imposta breakpoint dove necessario
+   - Premi F5 o seleziona configurazione dal menu Debug
+   - Step through con F10 (step over), F11 (step into)
+
+### Debug Problemi Comuni
+
+#### CRC Errors
+**Breakpoint:** `inverter.cpp` → funzione `CheckCRC()`
+- Verifica calcolo CRC
+- Controlla dati ricevuti in `buf[]`
+
+#### Device Communication Issues
+**Breakpoint:** `inverter.cpp` → funzione `query()`
+- Verifica apertura device (errno)
+- Controlla configurazione seriale (baud rate, etc.)
+- Monitora `write()` e `read()` operations
+
+#### Threading Issues
+**Breakpoint:** `inverter.cpp` → `poll()` e `main.cpp` → main loop
+- Verifica sincronizzazione mutex
+- Controlla `atomic_bool` flags
+- Watch variables: `ups_status_changed`, ecc.
+
+#### JSON Parsing Issues
+**Breakpoint:** `main.cpp` → dopo `sscanf()` calls
+- Verifica parsing corretto delle risposte
+- Controlla valori delle variabili dopo sscanf
+- Debug calcoli (ampfactor, wattfactor)
+
+## Debugging con Watchpoints
+
+### Variabili Chiave da Monitorare
+
+In VS Code Debug View → Watch, aggiungi:
+
+```
+voltage_grid
+voltage_batt
+pv_input_watts
+mode
+ups_qpigs_changed
+device_status
+```
+
+### GDB Commands Utili
+
+Nel Debug Console (Ctrl+Shift+Y):
+
+```gdb
+# Print strutture dati
+-exec p voltage_grid
+-exec p device_status
+
+# Backtrace
+-exec bt
+
+# Info threads
+-exec info threads
+
+# Print tutti i local vars
+-exec info locals
+
+# Watch memory
+-exec x/100c buf
+```
+
+## Configurazione IntelliSense
+
+Il file `.vscode/c_cpp_properties.json` viene auto-generato. Se necessario, puoi personalizzarlo:
+
+```json
+{
+    "configurations": [
+        {
+            "name": "Linux",
+            "includePath": [
+                "${workspaceFolder}/**",
+                "/usr/include"
+            ],
+            "defines": [],
+            "compilerPath": "/usr/bin/g++",
+            "cStandard": "c11",
+            "cppStandard": "c++11",
+            "intelliSenseMode": "linux-gcc-arm"
+        }
+    ],
+    "version": 4
+}
+```
+
+## Debug Container Docker
+
+### Attach a Container in Esecuzione
+
+```bash
+# Trova il processo nel container
+docker exec -it voltronic-mqtt ps aux | grep inverter
+
+# Installa gdbserver nel container (se necessario)
+docker exec -it voltronic-mqtt apt-get install -y gdbserver
+
+# Avvia gdbserver nel container
+docker exec -it voltronic-mqtt gdbserver :2345 /opt/inverter-cli/bin/inverter_poller -d -1
+
+# Nella configurazione launch.json, aggiungi:
+{
+    "name": "(gdb) Remote Debug",
+    "type": "cppdbg",
+    "request": "launch",
+    "program": "${workspaceFolder}/sources/inverter-cli/bin/inverter_poller",
+    "miDebuggerServerAddress": "localhost:2345",
+    "miDebuggerPath": "/usr/bin/gdb",
+    "MIMode": "gdb"
+}
+```
+
+### Debug Logs
+
+```bash
+# Tail logs in tempo reale
+docker logs -f voltronic-mqtt
+
+# Exec nel container per debug manuale
+docker exec -it voltronic-mqtt bash
+cd /opt/inverter-cli/bin
+./inverter_poller -d -1
+```
+
+## Performance Profiling
+
+### Con valgrind
+
+```bash
+# Installa valgrind
+sudo apt-get install valgrind
+
+# Memory leak detection
+valgrind --leak-check=full --show-leak-kinds=all \
+    ./sources/inverter-cli/bin/inverter_poller -1
+
+# Profiling
+valgrind --tool=callgrind ./sources/inverter-cli/bin/inverter_poller -1
+```
+
+### Con gprof
+
+```bash
+# Compila con profiling
+cd sources/inverter-cli
+cmake -DCMAKE_CXX_FLAGS="-pg" .
+make
+
+# Esegui
+./bin/inverter_poller -1
+
+# Analizza
+gprof bin/inverter_poller gmon.out > analysis.txt
+```
+
+## Tips & Tricks
+
+1. **Conditional Breakpoints:**
+   - Click destro su breakpoint → Edit Breakpoint
+   - Aggiungi condizione, es: `voltage_batt < 24.0`
+
+2. **Logpoints:**
+   - Invece di breakpoint, logpoint stampa senza fermare
+   - Click destro → Add Logpoint
+   - Esempio: `Voltage: {voltage_grid}V`
+
+3. **Debug con file di log:**
+   - Il programma scrive su `/tmp/inverter.log` (vedi LOG_FILE in tools.h)
+   - Usa `tail -f /tmp/inverter.log` in terminale separato
+
+4. **Quick Debug:**
+   ```bash
+   # Build e run rapido senza VS Code
+   cd sources/inverter-cli
+   cmake -DCMAKE_BUILD_TYPE=Debug . && make && gdb --args bin/inverter_poller -d -1
+   ```
+
+## Troubleshooting Debug Setup
+
+### GDB non trova simboli
+```bash
+# Verifica che binary abbia simboli debug
+file sources/inverter-cli/bin/inverter_poller
+# Output dovrebbe contenere: "not stripped"
+
+# Se stripped, rebuilda in debug mode
+cd sources/inverter-cli && cmake -DCMAKE_BUILD_TYPE=Debug . && make
+```
+
+### Permission denied su /dev/ttyUSB0
+```bash
+sudo chmod 666 /dev/ttyUSB0
+# O permanentemente:
+sudo usermod -a -G dialout $USER
+```
+
+### VS Code non trova GDB
+```bash
+# Installa gdb
+sudo apt-get install gdb
+
+# Verifica path in launch.json
+which gdb  # Usa questo path in miDebuggerPath
+```
+
+## Risorse Aggiuntive
+
+- [VS Code C++ Debugging](https://code.visualstudio.com/docs/cpp/cpp-debug)
+- [GDB Documentation](https://sourceware.org/gdb/documentation/)
+- [CMake Tutorial](https://cmake.org/cmake/help/latest/guide/tutorial/)
+- [Protocol Manual](../../manual/) - Documentazione protocollo inverter