docker-voltronic-homeassistant/documentation/DEBUG.md

Debug Configuration - inverter-cli

Questa directory contiene le configurazioni per il debug dell'applicazione inverter-cli in VS Code.

Prerequisiti

Software Richiesto

# 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)

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

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:

   # Modifica temporaneamente main.cpp per usare dati mock
   # Oppure esegui con un device virtuale
   

2. Debug con socat (porta seriale virtuale):

   # 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:

   ls -la /dev/ttyUSB* /dev/ttyS* /dev/hidraw*
   dmesg | grep tty  # Per vedere device USB
   

2. Verifica permessi:

   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:

   # 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):

# 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:

{
    "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

# 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

# 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

# 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

# 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:

   # 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

# 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

sudo chmod 666 /dev/ttyUSB0
# O permanentemente:
sudo usermod -a -G dialout $USER

VS Code non trova GDB

# 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
• GDB Documentation
• CMake Tutorial
• Protocol Manual - Documentazione protocollo inverter