docker-voltronic-homeassistant/documentation/AUTO_DISCOVERY.md

# Auto-Discovery Feature

Il sistema di auto-discovery rileva automaticamente i parametri di comunicazione corretti del tuo inverter all'avvio del container.

## Come Funziona

All'avvio, il container:

1. **Controlla** se esiste già una configurazione salvata (`.discovery_done`)
2. **Testa** la comunicazione con l'inverter inviando i 4 comandi principali
3. **Rileva** le dimensioni corrette del buffer per ogni comando
4. **Salva** i parametri scoperti in `/etc/inverter/.discovery_done`
5. **Aggiorna** `/etc/inverter/inverter.conf` con i valori corretti
6. **Avvia** i servizi MQTT normalmente

## Variabili d'Ambiente

### `INVERTER_DEVICE`
Specifica il device seriale dell'inverter.

**Default:** `/dev/ttyUSB0`

**Esempi:**
```yaml
environment:
  - INVERTER_DEVICE=/dev/ttyUSB1   # USB-to-Serial adapter
  - INVERTER_DEVICE=/dev/ttyS0     # Built-in serial port
  - INVERTER_DEVICE=/dev/hidraw0   # USB HID device
```

### `FORCE_DISCOVERY`
Forza l'auto-discovery ad ogni avvio, anche se esistono già parametri salvati.

**Default:** `false`

**Quando usarlo:**
- Dopo aver cambiato inverter
- Se sospetti che i parametri salvati siano errati
- Per debug o testing

**Esempio:**
```yaml
environment:
  - FORCE_DISCOVERY=true
```

### `SKIP_DISCOVERY`
Salta completamente l'auto-discovery e usa solo i valori da `inverter.conf`.

**Default:** `false`

**Quando usarlo:**
- Quando conosci già i parametri corretti
- Per velocizzare l'avvio (risparmia ~10 secondi)
- In ambienti di produzione stabili

**Esempio:**
```yaml
environment:
  - SKIP_DISCOVERY=true
```

## Scenari d'Uso

### Scenario 1: Primo Avvio (Default)
```yaml
services:
  voltronic-mqtt:
    environment:
      - INVERTER_DEVICE=/dev/ttyUSB1
```

**Cosa succede:**
- ✓ Container rileva che non esiste `.discovery_done`
- ✓ Esegue auto-discovery (~10-15 secondi)
- ✓ Salva i parametri trovati
- ✓ Avvia i servizi MQTT

**Log:**
```
=== Voltronic MQTT Bridge Starting ===
Configuration:
  Device: /dev/ttyUSB1
  Force Discovery: false
  Skip Discovery: false

ℹ No previous discovery found, will run auto-discovery

=== Running Auto-Discovery ===
This will take about 10-15 seconds...

Testing QMOD command (buffer 5-100)...
✓ QMOD: found response at 5 bytes
...
✓ Auto-discovery completed successfully!
device=/dev/ttyUSB1
qmod=5
qpigs=110
qpiri=103
qpiws=40
```

### Scenario 2: Avvii Successivi (Cached)
```yaml
services:
  voltronic-mqtt:
    environment:
      - INVERTER_DEVICE=/dev/ttyUSB1
```

**Cosa succede:**
- ✓ Container trova `.discovery_done` esistente
- ✓ Verifica che il device non sia cambiato
- ✓ Carica i parametri salvati
- ✓ Avvia immediatamente i servizi (nessun ritardo)

**Log:**
```
=== Voltronic MQTT Bridge Starting ===
Configuration:
  Device: /dev/ttyUSB1
  Force Discovery: false
  Skip Discovery: false

✓ Using previous discovery results
Current configuration:
device=/dev/ttyUSB1
qmod=5
qpigs=110
qpiri=103
qpiws=40

=== Starting MQTT Bridge Services ===
```

### Scenario 3: Cambio Device
```yaml
services:
  voltronic-mqtt:
    environment:
      - INVERTER_DEVICE=/dev/ttyUSB0  # Cambiato da ttyUSB1
```

**Cosa succede:**
- ✓ Container rileva che il device è cambiato
- ✓ Elimina `.discovery_done` esistente
- ✓ Esegue nuovamente l'auto-discovery
- ✓ Salva i nuovi parametri

**Log:**
```
⚠ Device changed from /dev/ttyUSB1 to /dev/ttyUSB0
  Running new discovery...

=== Running Auto-Discovery ===
...
```

### Scenario 4: Force Discovery
```yaml
services:
  voltronic-mqtt:
    environment:
      - INVERTER_DEVICE=/dev/ttyUSB1
      - FORCE_DISCOVERY=true
```

**Cosa succede:**
- ✓ Ignora `.discovery_done` esistente
- ✓ Esegue sempre auto-discovery
- ✓ Aggiorna parametri salvati

**Quando usarlo:** Dopo aggiornamento firmware inverter, troubleshooting.

### Scenario 5: Skip Discovery
```yaml
services:
  voltronic-mqtt:
    environment:
      - INVERTER_DEVICE=/dev/ttyUSB1
      - SKIP_DISCOVERY=true
```

**Cosa succede:**
- ✓ Non esegue mai auto-discovery
- ✓ Usa solo valori da `config/inverter.conf`
- ✓ Avvio istantaneo

**Quando usarlo:** Parametri già noti e stabili, avvio rapido richiesto.

## File Generati

### `/etc/inverter/.discovery_done`
Contiene i parametri scoperti con timestamp:

```bash
device=/dev/ttyUSB1
qmod=5
qpigs=110
qpiri=103
qpiws=40
timestamp=2024-01-15T10:30:00+01:00
```

Questo file è **persistente** nel volume `./config/` e sopravvive ai restart del container.

### `/etc/inverter/inverter.conf.backup`
Backup automatico della configurazione originale prima dell'auto-discovery.

## Troubleshooting

### Discovery Fallisce

**Log:**
```
✗ Auto-discovery failed!
Please check:
  1. Inverter is powered on
  2. Cable is properly connected
  3. Device path is correct: /dev/ttyUSB1

Falling back to default configuration...
```

**Soluzioni:**
1. Verifica che l'inverter sia acceso
2. Controlla il cablaggio RS232/USB
3. Verifica il device corretto: `ls -la /dev/tty*`
4. Testa manualmente:
   ```bash
   docker exec -it voltronic-mqtt /opt/inverter-cli/bin/inverter_poller -a
   ```

### Device Non Trovato

**Errore:**
```
Unable to open device file
```

**Soluzioni:**
1. Verifica mapping in docker-compose.yml:
   ```yaml
   devices:
     - /dev/ttyUSB1:/dev/ttyUSB1:rwm
   ```
2. Controlla permessi: `sudo chmod 666 /dev/ttyUSB1`
3. Verifica che il device esista: `ls -la /dev/ttyUSB1`

### Valori Scoperti Errati

**Soluzione 1 - Force Discovery:**
```yaml
environment:
  - FORCE_DISCOVERY=true
```

**Soluzione 2 - Configurazione Manuale:**
```yaml
environment:
  - SKIP_DISCOVERY=true
```
E modifica manualmente `config/inverter.conf`:
```bash
device=/dev/ttyUSB1
qmod=5
qpigs=110
qpiri=103
qpiws=40
```

## Test Manuale

Puoi testare l'auto-discovery manualmente senza riavviare il container:

```bash
# Test base
docker exec -it voltronic-mqtt /opt/inverter-cli/bin/inverter_poller -a

# Test con debug
docker exec -it voltronic-mqtt /opt/inverter-cli/bin/inverter_poller -d -a

# Test singolo comando
docker exec -it voltronic-mqtt /opt/inverter-cli/bin/inverter_poller -r QPIGS
```

## Best Practices

1. **Primo Setup:** Lascia auto-discovery attivo (default)
2. **Produzione:** Dopo aver verificato che funzioni, considera `SKIP_DISCOVERY=true` per avvio rapido
3. **Multi-Inverter:** Usa container separati con `INVERTER_DEVICE` diversi
4. **Backup:** Salva `config/.discovery_done` dopo il primo successo
5. **Logging:** Monitora i log del primo avvio per verificare discovery:
   ```bash
   docker logs voltronic-mqtt
   ```

## Esempio Completo docker-compose.yml

```yaml
version: '3'

services:
  # Inverter primario su ttyUSB1
  voltronic-mqtt-primary:
    image: bushrangers/ha-voltronic-mqtt
    container_name: voltronic-mqtt-primary
    privileged: true
    restart: always
    
    environment:
      - INVERTER_DEVICE=/dev/ttyUSB1
      - FORCE_DISCOVERY=false
      - SKIP_DISCOVERY=false
    
    volumes:
      - ./config-primary/:/etc/inverter/
    
    devices:
      - /dev/ttyUSB1:/dev/ttyUSB1:rwm

  # Inverter secondario su ttyUSB0 (discovery skippato)
  voltronic-mqtt-secondary:
    image: bushrangers/ha-voltronic-mqtt
    container_name: voltronic-mqtt-secondary
    privileged: true
    restart: always
    
    environment:
      - INVERTER_DEVICE=/dev/ttyUSB0
      - SKIP_DISCOVERY=true  # Parametri già noti
    
    volumes:
      - ./config-secondary/:/etc/inverter/
    
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0:rwm
```

## Migrazione da Versione Precedente

Se stai aggiornando da una versione senza auto-discovery:

1. **Backup configurazione esistente:**
   ```bash
   cp config/inverter.conf config/inverter.conf.old
   ```

2. **Aggiungi variabili d'ambiente al docker-compose.yml:**
   ```yaml
   environment:
     - INVERTER_DEVICE=/dev/ttyUSB1  # Il tuo device attuale
   ```

3. **Primo avvio con auto-discovery:**
   ```bash
   docker-compose down
   docker-compose up -d
   docker logs -f voltronic-mqtt
   ```

4. **Verifica risultati:**
   ```bash
   cat config/.discovery_done
   ```

5. **Se tutto OK, abilita skip per avvio rapido:**
   ```yaml
   environment:
     - INVERTER_DEVICE=/dev/ttyUSB1
     - SKIP_DISCOVERY=true  # Usa parametri scoperti
   ```

## FAQ

**Q: Quanto tempo impiega l'auto-discovery?**  
A: Circa 10-15 secondi al primo avvio. Gli avvii successivi sono istantanei.

**Q: Posso usare auto-discovery con più inverter?**  
A: Sì! Usa container separati con `INVERTER_DEVICE` diversi e directory config separate.

**Q: Cosa succede se l'inverter è spento durante discovery?**  
A: Il container fallisce gracefully e usa i parametri di default da `inverter.conf`.

**Q: Devo eliminare `.discovery_done` manualmente?**  
A: No, il container lo fa automaticamente quando cambi `INVERTER_DEVICE` o usi `FORCE_DISCOVERY=true`.

**Q: Posso disabilitare completamente auto-discovery?**  
A: Sì, usa `SKIP_DISCOVERY=true`.

**Q: I parametri scoperti sono persistenti?**  
A: Sì, sono salvati nel volume `./config/` e sopravvivono ai restart.