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

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

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

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

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

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

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

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

```yaml
# 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:**
```bash
MQTT_PASSWORD=your_secure_password_here
```

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