docker-voltronic-homeassistant/documentation/MULTI_INVERTER.md

Configurazione Multi-Inverter

Panoramica

Il sistema supporta un inverter per container. Per monitorare più inverter, devi eseguire più istanze del container, ciascuna configurata con:

• Device seriale diverso (/dev/ttyUSB0, /dev/ttyUSB1, ecc.)
• Nome device MQTT unico (voltronic1, voltronic2, ecc.)
• Topic MQTT dedicato (opzionale)

Configurazione Docker Compose per Due Inverter

version: '3'

services:
  # Primo Inverter - /dev/ttyUSB0
  voltronic-inverter1:
    image: gitea.home-nas-ds.org/alessio/docker-voltronic-homeassistant:latest
    container_name: voltronic-inverter1
    privileged: true
    restart: always
    
    environment:
      - INVERTER_DEVICE=/dev/ttyUSB0
      - MQTT_SERVER=192.168.1.37
      - MQTT_PORT=1883
      - MQTT_TOPIC=homeassistant
      - MQTT_DEVICENAME=inverter1        # Nome unico per primo inverter
      - MQTT_USERNAME=mqtt_user
      - MQTT_PASSWORD=your_password_here
      - FORCE_DISCOVERY=false
      - SKIP_DISCOVERY=false
    
    volumes:
      - ./config/inverter1/:/etc/inverter/
      - voltronic-cache1:/cache/
    
    devices:
      - /dev/bus/usb:/dev/bus/usb:rwm
      - /dev/ttyUSB0:/dev/ttyUSB0:rwm
  
  # Secondo Inverter - /dev/ttyUSB1
  voltronic-inverter2:
    image: gitea.home-nas-ds.org/alessio/docker-voltronic-homeassistant:latest
    container_name: voltronic-inverter2
    privileged: true
    restart: always
    
    environment:
      - INVERTER_DEVICE=/dev/ttyUSB1
      - MQTT_SERVER=192.168.1.37
      - MQTT_PORT=1883
      - MQTT_TOPIC=homeassistant
      - MQTT_DEVICENAME=inverter2        # Nome unico per secondo inverter
      - MQTT_USERNAME=mqtt_user
      - MQTT_PASSWORD=your_password_here
      - FORCE_DISCOVERY=false
      - SKIP_DISCOVERY=false
    
    volumes:
      - ./config/inverter2/:/etc/inverter/
      - voltronic-cache2:/cache/
    
    devices:
      - /dev/bus/usb:/dev/bus/usb:rwm
      - /dev/ttyUSB1:/dev/ttyUSB1:rwm

volumes:
  voltronic-cache1:
  voltronic-cache2:

Struttura Directory Config

Ogni inverter deve avere la propria directory di configurazione:

config/
├── inverter1/
│   ├── inverter.conf      # Configurazione inverter 1
│   ├── mqtt.json          # Template MQTT (credenziali vuote)
│   └── .discovery_done    # Cache discovery (creato automaticamente)
└── inverter2/
    ├── inverter.conf      # Configurazione inverter 2
    ├── mqtt.json          # Template MQTT (credenziali vuote)
    └── .discovery_done    # Cache discovery (creato automaticamente)

Topic MQTT Risultanti

Con la configurazione sopra, i sensori verranno pubblicati su:

Inverter 1:

• homeassistant/sensor/inverter1_Battery_voltage
• homeassistant/sensor/inverter1_PV_in_watts
• homeassistant/sensor/inverter1_Load_watt
• ...

Inverter 2:

• homeassistant/sensor/inverter2_Battery_voltage
• homeassistant/sensor/inverter2_PV_in_watts
• homeassistant/sensor/inverter2_Load_watt
• ...

Identificazione Device Seriali

Per identificare quale inverter è connesso a quale porta USB:

# Lista tutti i device USB seriali
ls -la /dev/ttyUSB*

# Mostra info dettagliate device
udevadm info --name=/dev/ttyUSB0 | grep ID_SERIAL

# Test comunicazione con inverter
docker run --rm --device=/dev/ttyUSB0:/dev/ttyUSB0 \
  gitea.home-nas-ds.org/alessio/docker-voltronic-homeassistant:latest \
  /opt/inverter-cli/bin/inverter_poller -d -1

Creazione File di Configurazione

inverter.conf (per ogni inverter)

# Crea directory config per ogni inverter
mkdir -p config/inverter1 config/inverter2

# Crea inverter.conf per inverter1
cat > config/inverter1/inverter.conf << 'EOF'
device=/dev/ttyUSB0
run_interval=120
amperage_factor=1.0
watt_factor=1.01
qpiri=103
qpiws=40
qmod=5
qpigs=110
EOF

# Crea inverter.conf per inverter2
cat > config/inverter2/inverter.conf << 'EOF'
device=/dev/ttyUSB1
run_interval=120
amperage_factor=1.0
watt_factor=1.01
qpiri=103
qpiws=40
qmod=5
qpigs=110
EOF

mqtt.json (template per ogni inverter)

# Crea mqtt.json per inverter1
cat > config/inverter1/mqtt.json << 'EOF'
{
    "server": "192.168.1.37",
    "port": "1883",
    "topic": "homeassistant",
    "devicename": "inverter1",
    "username": "",
    "password": "",
    "clientid": "inverter1_auto",
    "influx": {
        "enabled": "false"
    }
}
EOF

# Crea mqtt.json per inverter2
cat > config/inverter2/mqtt.json << 'EOF'
{
    "server": "192.168.1.37",
    "port": "1883",
    "topic": "homeassistant",
    "devicename": "inverter2",
    "username": "",
    "password": "",
    "clientid": "inverter2_auto",
    "influx": {
        "enabled": "false"
    }
}
EOF

Nota: Le credenziali MQTT vengono fornite tramite ENV variables e aggiornate automaticamente all'avvio del container.

Avvio Container

# Avvia entrambi i container
docker compose up -d

# Verifica stato
docker compose ps

# Verifica log primo inverter
docker logs -f voltronic-inverter1

# Verifica log secondo inverter
docker logs -f voltronic-inverter2

Discovery Automatica

Al primo avvio, ogni container:

1. Rileva automaticamente i buffer sizes dell'inverter connesso
2. Salva la configurazione in .discovery_done
3. Nei successivi restart, usa i valori cached

Per forzare re-discovery:

# Primo inverter
docker exec voltronic-inverter1 rm /etc/inverter/.discovery_done
docker restart voltronic-inverter1

# Secondo inverter
docker exec voltronic-inverter2 rm /etc/inverter/.discovery_done
docker restart voltronic-inverter2

Home Assistant Integration

Entrambi gli inverter verranno rilevati automaticamente in Home Assistant tramite MQTT Discovery. I sensori appariranno come dispositivi separati:

• Device: inverter1
  • Sensori: Battery Voltage, PV Watts, Load, ecc.
• Device: inverter2
  • Sensori: Battery Voltage, PV Watts, Load, ecc.

Troubleshooting

Problema: Container non riesce ad accedere al device

Soluzione: Verifica permessi device e gruppo utente

# Aggiungi utente al gruppo dialout
sudo usermod -aG dialout $USER

# Verifica permessi device
ls -la /dev/ttyUSB*

# Dovrebbe mostrare: crw-rw---- 1 root dialout ...

Problema: Discovery fallisce per un inverter

Causa: Buffer sizes incompatibili o device non risponde

Soluzione: Esegui discovery manuale con debug

docker exec -it voltronic-inverter1 \
  /opt/inverter-cli/bin/inverter_poller -d -a

Problema: Topic MQTT sovrapposti

Causa: Entrambi i container usano lo stesso MQTT_DEVICENAME

Soluzione: Verifica che ogni container abbia nome unico:

• inverter1: MQTT_DEVICENAME=inverter1
• inverter2: MQTT_DEVICENAME=inverter2

Problema: Alto consumo CPU

Causa: Intervallo polling troppo frequente

Soluzione: Aumenta run_interval in inverter.conf:

# Default: 120 (ogni 30s)
# Meno frequente: 240 (ogni 60s)
run_interval=240

Performance e Risorse

Consumo per singolo container:

• CPU: ~0-2% (spike ogni 30s durante polling)
• RAM: ~10-15 MB
• Network: ~1-2 KB/s (MQTT messages)

Consumo totale per 2 inverter:

• CPU: ~0-4%
• RAM: ~20-30 MB
• Network: ~2-4 KB/s

Sicurezza

⚠️ IMPORTANTE:

• Non committare credenziali MQTT in mqtt.json (devono rimanere vuote)
• Le credenziali vengono fornite solo tramite ENV variables
• Usa password forti per l'accesso MQTT broker
• Considera l'uso di Docker secrets per ambienti production

Esempio Completo: Due Inverter in Parallelo

# docker-compose.yml
version: '3'

services:
  inverter-garage:
    image: gitea.home-nas-ds.org/alessio/docker-voltronic-homeassistant:latest
    container_name: inverter-garage
    privileged: true
    restart: always
    environment:
      - INVERTER_DEVICE=/dev/ttyUSB0
      - MQTT_SERVER=192.168.1.37
      - MQTT_DEVICENAME=garage
      - MQTT_USERNAME=mqtt_user
      - MQTT_PASSWORD=${MQTT_PASSWORD}  # Da .env file
    volumes:
      - ./config/garage/:/etc/inverter/
      - voltronic-garage:/cache/
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0:rwm

  inverter-cantina:
    image: gitea.home-nas-ds.org/alessio/docker-voltronic-homeassistant:latest
    container_name: inverter-cantina
    privileged: true
    restart: always
    environment:
      - INVERTER_DEVICE=/dev/ttyUSB1
      - MQTT_SERVER=192.168.1.37
      - MQTT_DEVICENAME=cantina
      - MQTT_USERNAME=mqtt_user
      - MQTT_PASSWORD=${MQTT_PASSWORD}  # Da .env file
    volumes:
      - ./config/cantina/:/etc/inverter/
      - voltronic-cantina:/cache/
    devices:
      - /dev/ttyUSB1:/dev/ttyUSB1:rwm

volumes:
  voltronic-garage:
  voltronic-cantina:

.env file:

MQTT_PASSWORD=your_secure_password_here

Questo setup permette di monitorare due inverter in parallelo con nomi descrittivi e gestione centralizzata delle credenziali.