feat(v2.0): Auto-discovery, correzione bug critici, e documentazione completa
Build Docker Image for Raspberry Pi / build-and-push (push) Failing after 4m42s
Build Docker Image for Raspberry Pi / build-and-push (push) Failing after 4m42s
🆕 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
This commit is contained in:
Pi Developer
@@ -0,0 +1,363 @@
|
||||
# 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! 🚀**
|
||||
Reference in New Issue
Block a user