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:

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:

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:

environment:
  - SKIP_DISCOVERY=true

Scenari d'Uso

Scenario 1: Primo Avvio (Default)

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)

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

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

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

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:

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:

   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:

   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:

environment:
  - FORCE_DISCOVERY=true

Soluzione 2 - Configurazione Manuale:

environment:
  - SKIP_DISCOVERY=true

E modifica manualmente config/inverter.conf:

device=/dev/ttyUSB1
qmod=5
qpigs=110
qpiri=103
qpiws=40

Test Manuale

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

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

   docker logs voltronic-mqtt
   

Esempio Completo docker-compose.yml

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:

   cp config/inverter.conf config/inverter.conf.old
   

2. Aggiungi variabili d'ambiente al docker-compose.yml:

   environment:
     - INVERTER_DEVICE=/dev/ttyUSB1  # Il tuo device attuale
   

3. Primo avvio con auto-discovery:

   docker-compose down
   docker-compose up -d
   docker logs -f voltronic-mqtt
   

4. Verifica risultati:

   cat config/.discovery_done
   

5. Se tutto OK, abilita skip per avvio rapido:

   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.