# 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/) ![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: - [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 Lovelace Dashboard](images/lovelace-dashboard.jpg "Example Lovelace Dashboard") _Example #1: My "Lovelace" dashboard using data collected from the Inverter & the ability to change modes/configuration via MQTT._ ![Example Lovelace Dashboard](images/grafana-example.jpg "Example Grafana Dashboard") _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](documentation/AUTO_DISCOVERY.md) for complete documentation** including: - How auto-discovery works - Environment variable reference - Multi-inverter setups - Troubleshooting guide - Migration from older versions ### πŸ”Œ Multi-Inverter Support Il sistema supporta il monitoraggio di **piΓΉ inverter in parallelo**. Ogni inverter richiede un container separato con: - Device seriale dedicato (`/dev/ttyUSB0`, `/dev/ttyUSB1`, ecc.) - Nome device MQTT unico (`inverter1`, `inverter2`, ecc.) - Directory config separata per ogni inverter **πŸ“– Guida completa:** [MULTI_INVERTER.md](documentation/MULTI_INVERTER.md) **Esempio configurazione 2 inverter:** ```yaml services: voltronic-inverter1: environment: - INVERTER_DEVICE=/dev/ttyUSB0 - MQTT_DEVICENAME=inverter1 - MQTT_USERNAME=mqtt_user - MQTT_PASSWORD=your_password volumes: - ./config/inverter1/:/etc/inverter/ devices: - /dev/ttyUSB0:/dev/ttyUSB0:rwm voltronic-inverter2: environment: - INVERTER_DEVICE=/dev/ttyUSB1 - MQTT_DEVICENAME=inverter2 - MQTT_USERNAME=mqtt_user - MQTT_PASSWORD=your_password volumes: - ./config/inverter2/:/etc/inverter/ devices: - /dev/ttyUSB1:/dev/ttyUSB1:rwm ``` **Topic MQTT risultanti:** - Inverter 1: `homeassistant/sensor/inverter1_Battery_voltage`, `inverter1_PV_in_watts`, ecc. - Inverter 2: `homeassistant/sensor/inverter2_Battery_voltage`, `inverter2_PV_in_watts`, ecc. ### ⚑ Performance Optimization (v2.0+) Il container Γ¨ stato ottimizzato per ridurre il consumo di risorse: - **CPU**: ~0-2% per inverter (spike durante polling ogni 30s) - **RAM**: ~10-15 MB per inverter - **Network**: ~1-2 KB/s per inverter **Ottimizzazioni implementate:** - Caricamento configurazione MQTT una sola volta all'avvio - Eliminazione letture ripetute file con `jq` - Redirect stderr per ridurre I/O - Timeout su operazioni inverter per evitare hang **πŸ“– See [AUTO_DISCOVERY.md](documentation/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_ **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 [-r ], [-h | --help], [-1 | --run-once], [-a | --auto-discover] SUPPORTED ARGUMENTS: -r 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