feat(v2.0): Auto-discovery, correzione bug critici, e documentazione completa

🆕 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

README.md

@@ -4,6 +4,19 @@
 
 ![License](https://img.shields.io/github/license/ned-kelly/docker-voltronic-homeassistant.svg) ![Docker Pulls](https://img.shields.io/docker/pulls/bushrangers/ha-voltronic-mqtt.png) ![buildx](https://github.com/ned-kelly/docker-voltronic-homeassistant/workflows/buildx/badge.svg)
 
+## ✨ Version 2.0 - Auto-Discovery Feature
+
+Questa versione introduce l'**auto-discovery automatica dei parametri dell'inverter**, eliminando la necessità di configurazione manuale dei buffer sizes. Il container rileva automaticamente i parametri corretti al primo avvio e li salva per utilizzi futuri.
+
+**Novità principali:**
+- 🔍 Auto-detection buffer sizes per diversi modelli di inverter
+- ⚙️ Configurazione tramite variabili d'ambiente Docker
+- 💾 Caching persistente dei parametri scoperti
+- 🔄 Multi-inverter support con discovery indipendente
+- 🐛 Bug fixes: parsing interi, sincronizzazione thread, gestione QPIWS
+
+📖 **Documentazione completa:** [documentation/](documentation/)
+
 ----
 
 The following other projects may also run on the same SBC _(using the same style docker setup as this)_, to give you a fully featured solution with other sensors and devices:
@@ -60,26 +73,40 @@ vi config/inverter.conf
 # If your MQTT server does not need a username/password just leave these values empty.
 
 vi config/mqtt.json
+
+# OPTIONAL: Configure auto-discovery environment variables in docker-compose.yml
+# See AUTO_DISCOVERY.md for detailed documentation
+vi docker-compose.yml
 ```
 
 Then, plug in your Serial or USB cable to the Inverter & stand up the container:
 
 ```bash
 docker-compose up -d
-
 ```
 
-_**Note:**_
+### 🆕 Auto-Discovery Feature (v2.0+)
 
-  - builds on docker hub are currently for `linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64,linux/386` -- If you have issues standing up the image on your Linux distribution (i.e. An old Pi/ARM device) you may need to manually build the image to support your local device architecture - This can be done by uncommenting the build flag in your docker-compose.yml file.
-  
-  - The default `docker-compose.yml` file includes Watchtower, which can be  configured to auto-update this image when we push new changes to github - Please **uncomment if you wish to auto-update to the latest builds of this project**.
+The container now includes **automatic buffer size detection** for different inverter models. At first startup, it will:
 
-## Integrating into Home Assistant.
+1. **Auto-detect** the correct communication parameters for your specific inverter
+2. **Save** the discovered settings to `/etc/inverter/.discovery_done`
+3. **Reuse** saved settings on subsequent startups (instant start)
 
-Providing you have setup [MQTT](https://www.home-assistant.io/components/mqtt/) with Home Assistant, the device will automatically register in your Home Assistant when the container starts for the first time -- You do not need to manually define any sensors.
+**Environment Variables:**
+```yaml
+environment:
+  - INVERTER_DEVICE=/dev/ttyUSB1      # Your RS232/USB device
+  - FORCE_DISCOVERY=false             # Re-run discovery on every start
+  - SKIP_DISCOVERY=false              # Skip discovery, use inverter.conf values
+```
 
-From here you can setup [Graphs](https://www.home-assistant.io/lovelace/history-graph/) to display sensor data, and optionally change state of the inverter by "[publishing](https://www.home-assistant.io/docs/mqtt/service/)" a string to the inverter's primary topic like so:
+**📖 See [AUTO_DISCOVERY.md](AUTO_DISCOVERY.md) for complete documentation** including:
+- How auto-discovery works
+- Environment variable reference
+- Multi-inverter setups
+- Troubleshooting guide
+- Migration from older versions
 
 ![Example, Changing the Charge Priority](images/mqtt-publish-packet.png "Example, Changing the Charge Priority")
 _Example: Changing the Charge Priority of the Inverter_
@@ -127,13 +154,14 @@ Just head to the `sources/inverter-cli` directory and build it directly using: `
 Basic arguments supported are:
 
 ```
-USAGE:  ./inverter_poller <args> [-r <command>], [-h | --help], [-1 | --run-once]
+USAGE:  ./inverter_poller <args> [-r <command>], [-h | --help], [-1 | --run-once], [-a | --auto-discover]
 
 SUPPORTED ARGUMENTS:
           -r <raw-command>      TX 'raw' command to the inverter
           -h | --help           This Help Message
           -1 | --run-once       Runs one iteration on the inverter, and then exits
           -d                    Additional debugging
+          -a | --auto-discover  Auto-detect correct buffer sizes for your inverter
 
 ```
 
@@ -147,3 +175,75 @@ Note that in addition to merging the sample Yaml files with your Home Assistant,
 
  - [vertical-stack-in-card](https://github.com/custom-cards/vertical-stack-in-card)
  - [circle-sensor-card](https://github.com/custom-cards/circle-sensor-card)
+
+---
+
+## 📚 Documentazione
+
+### Guide Utente
+- **[AUTO_DISCOVERY.md](documentation/AUTO_DISCOVERY.md)** - Guida completa all'auto-discovery
+  - Come funziona
+  - Variabili d'ambiente
+  - Scenari d'uso e troubleshooting
+  - Setup multi-inverter
+
+- **[QUICKSTART.md](documentation/QUICKSTART.md)** - Setup rapido del progetto
+  - Build e debug locale
+  - Configurazione VS Code
+  - Comandi essenziali
+
+### Documentazione Tecnica
+- **[CODE_ARCHITECTURE.md](documentation/CODE_ARCHITECTURE.md)** - Architettura completa del codice
+  - Mappa logica funzioni e variabili
+  - Flusso di esecuzione dettagliato
+  - Diagrammi e mappe concettuali
+  - Sincronizzazione multi-thread
+
+- **[IMPLEMENTATION.md](documentation/IMPLEMENTATION.md)** - Changelog implementazione v2.0
+  - Feature aggiunte
+  - Bug risolti
+  - Test eseguiti
+
+### Guide Sviluppatore
+- **[DEBUG.md](documentation/DEBUG.md)** - Guida completa al debugging
+  - Configurazioni VS Code
+  - GDB workflows
+  - Troubleshooting comuni
+
+- **[.vscode/README.md](documentation/README.md)** - Setup ambiente sviluppo
+  - Estensioni raccomandate
+  - Tasks e launch configurations
+  - Shortcuts utili
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Per contribuire al progetto:
+
+1. Fork del repository
+2. Crea branch feature (`git checkout -b feature/AmazingFeature`)
+3. Commit delle modifiche (`git commit -m 'feat: Add amazing feature'`)
+4. Push al branch (`git push origin feature/AmazingFeature`)
+5. Apri Pull Request
+
+**Per sviluppatori:** Consulta [CODE_ARCHITECTURE.md](documentation/CODE_ARCHITECTURE.md) per comprendere il flusso del codice prima di contribuire.
+
+---
+
+## 📜 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙏 Credits
+
+- Original skymax project by [manio](https://github.com/manio/skymax-demo)
+- [Skyboo's monitoring tutorial](https://skyboo.net/2017/03/monitoring-voltronic-power-axpert-mex-inverter-under-linux/)
+- [AEVA Forums](http://forums.aeva.asn.au/viewtopic.php?t=4332) for protocol documentation
+
+---
+
+**Version:** 2.0.0  
+**Last Updated:** 25 gennaio 2026