Pi Developer
6af9fcad7e
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
250 lines
12 KiB
Markdown
250 lines
12 KiB
Markdown
# A Docker based Home Assistant interface for MPP/Voltronic Solar Inverters
|
||
|
||
**Docker Hub:** [`bushrangers/ha-voltronic-mqtt:latest`](https://hub.docker.com/r/bushrangers/ha-voltronic-mqtt/)
|
||
|
||
  
|
||
|
||
## ✨ 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:
|
||
|
||
- [EPEver MPPT Stats (MQTT, Docker Image)](https://github.com/ned-kelly/docker-epever-homeassistant)
|
||
- [LeChacal.com's CT Clamp Current/Energy Monitors for your Breaker Box](https://github.com/ned-kelly/docker-lechacal-homeassistant)
|
||
|
||
---
|
||
|
||
This project [was derived](https://github.com/manio/skymax-demo) from the 'skymax' [C based monitoring application](https://skyboo.net/2017/03/monitoring-voltronic-power-axpert-mex-inverter-under-linux/) designed to take the monitoring data from Voltronic, Axpert, Mppsolar PIP, Voltacon, Effekta, and other branded OEM Inverters and send it to a [Home Assistant](https://www.home-assistant.io/) MQTT server for ingestion...
|
||
|
||
The program can also receive commands from Home Assistant (via MQTT) to change the state of the inverter remotely.
|
||
|
||
By remotely setting values via MQTT you can implement many more complex forms of automation _(triggered from Home Assistant)_ such as:
|
||
|
||
- Changing the power mode to '_solar only_' during the day, but then change back to '_grid mode charging_' for your AGM or VLRA batteries in the evenings, but if it's raining (based on data from your weather station), set the charge mode to `PCP02` _(Charge based on 'Solar and Utility')_ so that the following day there's plenty of juice in your batteries...
|
||
|
||
- Programatically set the charge & float voltages based on additional sensors _(such as a Zigbee [Temperature Sensor](https://www.zigbee2mqtt.io/devices/WSDCGQ11LM.html), or a [DHT-22 + ESP8266](https://github.com/bastianraschke/dht-sensor-esp8266-homeassistant))_ - This way if your battery box is too hot/cold you can dynamically adjust the voltage so that the batteries are not damaged...
|
||
|
||
- Dynamically adjust the inverter's "solar power balance" and other configuration options to ensure that you get the most "bang for your buck" out of your setup...
|
||
|
||
--------------------------------------------------
|
||
|
||
The program is designed to be run in a Docker Container, and can be deployed on a lightweight SBC next to your Inverter (i.e. an Orange Pi Zero running Arabian), and read data via the RS232 or USB ports on the back of the Inverter.
|
||
|
||
|
||
_Example #1: My "Lovelace" dashboard using data collected from the Inverter & the ability to change modes/configuration via MQTT._
|
||
|
||
|
||
_Example #2: Grafana summary allowing more detailed analysis of data collected, and the ability to 'deep-dive' historical data._
|
||
|
||
|
||
## Prerequisites
|
||
|
||
- Docker
|
||
- Docker-compose
|
||
- [Voltronic/Axpert/MPPSolar](https://www.ebay.com.au/sch/i.html?_from=R40&_trksid=p2334524.m570.l1313.TR11.TRC1.A0.H0.Xaxpert+inverter.TRS0&_nkw=axpert+inverter&_sacat=0&LH_TitleDesc=0&LH_PrefLoc=2&_osacat=0&_odkw=solar+inverter&LH_TitleDesc=0) based inverter that you want to monitor
|
||
- Home Assistant [running with a MQTT Server](https://www.home-assistant.io/components/mqtt/)
|
||
|
||
|
||
## Configuration & Standing Up
|
||
|
||
It's pretty straightforward, just clone down the sources and set the configuration files in the `config/` directory:
|
||
|
||
```bash
|
||
# Clone down sources on the host you want to monitor...
|
||
git clone https://github.com/ned-kelly/docker-voltronic-homeassistant.git /opt/ha-inverter-mqtt-agent
|
||
cd /opt/ha-inverter-mqtt-agent
|
||
|
||
# Configure the 'device=' directive (in inverter.conf) to suit for RS232 or USB..
|
||
vi config/inverter.conf
|
||
|
||
# Configure your MQTT server's IP/Host Name, Port, Credentials, HA topic, and name of the Inverter that you want displayed in Home Assistant...
|
||
# 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
|
||
```
|
||
|
||
### 🆕 Auto-Discovery Feature (v2.0+)
|
||
|
||
The container now includes **automatic buffer size detection** for different inverter models. At first startup, it will:
|
||
|
||
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)
|
||
|
||
**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
|
||
```
|
||
|
||
**📖 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 of the Inverter_
|
||
|
||
**COMMON COMMANDS THAT CAN BE SENT TO THE INVERTER**
|
||
|
||
_(see [protocol manual](http://forums.aeva.asn.au/uploads/293/HS_MS_MSX_RS232_Protocol_20140822_after_current_upgrade.pdf) for complete list of supported commands)_
|
||
|
||
|
||
|
||
```
|
||
DESCRIPTION: PAYLOAD: OPTIONS:
|
||
----------------------------------------------------------------
|
||
Set output source priority POP00 (Utility first)
|
||
POP01 (Solar first)
|
||
POP02 (SBU)
|
||
|
||
Set charger priority PCP00 (Utility first)
|
||
PCP01 (Solar first)
|
||
PCP02 (Solar and utility)
|
||
PCP03 (Solar only)
|
||
|
||
Set the Charge/Discharge Levels & Cutoff
|
||
PBDV26.9 (Don't discharge the battery unless it is at 26.9v or more)
|
||
PBCV24.8 (Switch back to 'grid' when battery below 24.8v)
|
||
PBFT27.1 (Set the 'float voltage' to 27.1v)
|
||
PCVV28.1 (Set the 'charge voltage' to 28.1v)
|
||
|
||
Set other commands PEa / PDa (Enable/disable buzzer)
|
||
PEb / PDb (Enable/disable overload bypass)
|
||
PEj / PDj (Enable/disable power saving)
|
||
PEu / PDu (Enable/disable overload restart);
|
||
PEx / PDx (Enable/disable backlight)
|
||
```
|
||
|
||
*NOTE:* When setting/configuring your charge, discharge, float & cutoff voltages for the first time, it's worth understanding how to optimize charging conditions to extend service life of your battery: https://batteryuniversity.com/learn/article/charging_the_lead_acid_battery
|
||
|
||
|
||
### Using `inverter_poller` binary directly
|
||
|
||
This project uses heavily modified sources, from [manio's](https://github.com/manio/skymax-demo) original demo, and be compiled to run standalone on Linux, Mac, and Windows (via Cygwin).
|
||
|
||
Just head to the `sources/inverter-cli` directory and build it directly using: `cmake . && make`.
|
||
|
||
Basic arguments supported are:
|
||
|
||
```
|
||
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
|
||
|
||
```
|
||
|
||
### Bonus: Lovelace Dashboard Files
|
||
|
||
_**Please refer to the screenshot above for an example of the dashboard.**_
|
||
|
||
I've included some Lovelace dashboard files in the `homeassistant/` directory, however you will need to need to adapt to your own Home Assistant configuration and/or name of the inverter if you have changed it in the `mqtt.json` config file.
|
||
|
||
Note that in addition to merging the sample Yaml files with your Home Assistant, you will need the following custom Lovelace cards installed if you wish to use my templates:
|
||
|
||
- [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
|