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

```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