feat(v2.0): Auto-discovery, correzione bug critici, e documentazione completa
Build Docker Image for Raspberry Pi / build-and-push (push) Failing after 4m42s
Build Docker Image for Raspberry Pi / build-and-push (push) Failing after 4m42s
🆕 Funzionalità Auto-Discovery - Aggiunto metodo AutoDiscoverBufferSizes() per rilevamento automatico QPIGS/QPIRI/QMOD/QPIWS - Supporto variabili d'ambiente (INVERTER_DEVICE, MQTT_SERVER, etc.) - Caching persistente buffer sizes in /cache/inverter.conf.cache - Flag -a/--auto-discover per modalità auto-detection 🐛 Bug Fixes Critici - **Parsing interi**: Aggiunta attemptAddSettingInt() con stoi() invece di stof() - Fix: stof('98') = 98.0f → 97 (int), ora stoi('98') = 98 direttamente - Applicato a: qpiri, qpiws, qmod, qpigs - **Thread sync**: Aggiunto ups_qpiws_changed a main loop e condizione exit poll() - Fix: loop principale controllava solo 3 flag su 4, causava hang - Fix: thread poll() non usciva in runOnce perché mancava controllo QPIWS - **Config accuracy**: Corretti buffer sizes (qpiri: 98→103, qpiws: 36→40) - Rimosso sources/inverter-cli/inverter.conf che sovrascriveva config globale - Validato con test: inverter_poller -1 completa in 6s con JSON completo 📚 Documentazione Completa - Creato documentation/CODE_ARCHITECTURE.md (38KB) - Mappa logica variabili globali - Flusso esecuzione main() con diagrammi ASCII - Sequence diagram classe cInverter (poll, query, auto-discovery) - Thread synchronization diagrams - MQTT integration bash scripts flow - Mappa concettuale 5-layer system architecture - Error handling e performance optimizations - Organizzati file .md in documentation/ (AUTO_DISCOVERY, IMPLEMENTATION, QUICKSTART, DEBUG) - Aggiornato README.md con sezione v2.0 e indice documentazione - Aggiornato .github/copilot-instructions.md con novità v2.0 🔧 Miglioramenti Build & CI/CD - Gitea Actions per build multi-arch (arm/v6, arm/v7, arm64, amd64, 386) - Configurazione VS Code completa (tasks, launch, debug GDB) - Script test-autodiscovery.sh e test-device.sh ✅ Testing Validato - inverter_poller -1 completa in 6 secondi - Output JSON completo con tutte le metriche - Exit pulito senza timeout (exit code 0) - Tutte le 4 query QMOD/QPIGS/QPIRI/QPIWS funzionanti
This commit is contained in:
Pi Developer
@@ -0,0 +1,392 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user