{"id":13535706,"url":"https://github.com/ned-kelly/docker-voltronic-homeassistant","last_synced_at":"2025-04-02T02:31:13.672Z","repository":{"id":40762728,"uuid":"188953710","full_name":"ned-kelly/docker-voltronic-homeassistant","owner":"ned-kelly","description":"Programmatically read data from your Voltronic, Axpert, Mppsolar PIP, Voltacon, Effekta etc Inverter and send it to Home Assistant via MQTT - Works with RS232 \u0026 USB! ","archived":false,"fork":false,"pushed_at":"2023-09-07T16:16:38.000Z","size":755,"stargazers_count":270,"open_issues_count":73,"forks_count":145,"subscribers_count":37,"default_branch":"master","last_synced_at":"2024-11-03T00:32:47.016Z","etag":null,"topics":["axpert","effekta","home-assistant","home-assistant-sensor","mppsolar","pip-inverter","voltacon","voltronic","voltronic-axpert-inverters"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ned-kelly.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-28T04:27:27.000Z","updated_at":"2024-10-06T09:10:50.000Z","dependencies_parsed_at":"2024-11-03T00:31:33.236Z","dependency_job_id":null,"html_url":"https://github.com/ned-kelly/docker-voltronic-homeassistant","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ned-kelly%2Fdocker-voltronic-homeassistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ned-kelly%2Fdocker-voltronic-homeassistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ned-kelly%2Fdocker-voltronic-homeassistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ned-kelly%2Fdocker-voltronic-homeassistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ned-kelly","download_url":"https://codeload.github.com/ned-kelly/docker-voltronic-homeassistant/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246743594,"owners_count":20826558,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["axpert","effekta","home-assistant","home-assistant-sensor","mppsolar","pip-inverter","voltacon","voltronic","voltronic-axpert-inverters"],"created_at":"2024-08-01T09:00:23.672Z","updated_at":"2025-04-02T02:31:13.308Z","avatar_url":"https://github.com/ned-kelly.png","language":"C++","funding_links":[],"categories":["Interesting Projects"],"sub_categories":[],"readme":"# A Docker based Home Assistant interface for MPP/Voltronic Solar Inverters \n\n**Docker Hub:** [`bushrangers/ha-voltronic-mqtt:latest`](https://hub.docker.com/r/bushrangers/ha-voltronic-mqtt/)\n\n![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)\n\n----\n\nThe 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:\n\n - [EPEver MPPT Stats (MQTT, Docker Image)](https://github.com/ned-kelly/docker-epever-homeassistant)\n - [LeChacal.com's CT Clamp Current/Energy Monitors for your Breaker Box](https://github.com/ned-kelly/docker-lechacal-homeassistant)\n\n---\n\nThis 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...\n\nThe program can also receive commands from Home Assistant (via MQTT) to change the state of the inverter remotely.\n\nBy remotely setting values via MQTT you can implement many more complex forms of automation _(triggered from Home Assistant)_ such as:\n\n - 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...\n\n - Programatically set the charge \u0026 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...\n\n - 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... \n\n--------------------------------------------------\n\nThe 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.\n\n![Example Lovelace Dashboard](images/lovelace-dashboard.jpg \"Example Lovelace Dashboard\")\n_Example #1: My \"Lovelace\" dashboard using data collected from the Inverter \u0026 the ability to change modes/configuration via MQTT._\n\n![Example Lovelace Dashboard](images/grafana-example.jpg \"Example Grafana Dashboard\")\n_Example #2: Grafana summary allowing more detailed analysis of data collected, and the ability to 'deep-dive' historical data._\n\n\n## Prerequisites\n\n- Docker\n- Docker-compose\n- [Voltronic/Axpert/MPPSolar](https://www.ebay.com.au/sch/i.html?_from=R40\u0026_trksid=p2334524.m570.l1313.TR11.TRC1.A0.H0.Xaxpert+inverter.TRS0\u0026_nkw=axpert+inverter\u0026_sacat=0\u0026LH_TitleDesc=0\u0026LH_PrefLoc=2\u0026_osacat=0\u0026_odkw=solar+inverter\u0026LH_TitleDesc=0) based inverter that you want to monitor\n- Home Assistant [running with a MQTT Server](https://www.home-assistant.io/components/mqtt/)\n\n\n## Configuration \u0026 Standing Up\n\nIt's pretty straightforward, just clone down the sources and set the configuration files in the `config/` directory:\n\n```bash\n# Clone down sources on the host you want to monitor...\ngit clone https://github.com/ned-kelly/docker-voltronic-homeassistant.git /opt/ha-inverter-mqtt-agent\ncd /opt/ha-inverter-mqtt-agent\n\n# Configure the 'device=' directive (in inverter.conf) to suit for RS232 or USB.. \nvi config/inverter.conf\n\n# Configure your MQTT server's IP/Host Name, Port, Credentials, HA topic, and name of the Inverter that you want displayed in Home Assistant...\n# If your MQTT server does not need a username/password just leave these values empty.\n\nvi config/mqtt.json\n```\n\nThen, plug in your Serial or USB cable to the Inverter \u0026 stand up the container:\n\n```bash\ndocker-compose up -d\n\n```\n\n_**Note:**_\n\n  - 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.\n  \n  - 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**.\n\n## Integrating into Home Assistant.\n\nProviding 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.\n\nFrom 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:\n\n![Example, Changing the Charge Priority](images/mqtt-publish-packet.png \"Example, Changing the Charge Priority\")\n_Example: Changing the Charge Priority of the Inverter_\n\n**COMMON COMMANDS THAT CAN BE SENT TO THE INVERTER**\n\n_(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)_\n\n\n\n```\nDESCRIPTION:                PAYLOAD:  OPTIONS:\n----------------------------------------------------------------\nSet output source priority  POP00     (Utility first)\n                            POP01     (Solar first)\n                            POP02     (SBU)\n\nSet charger priority        PCP00     (Utility first)\n                            PCP01     (Solar first)\n                            PCP02     (Solar and utility)\n                            PCP03     (Solar only)\n\nSet the Charge/Discharge Levels \u0026 Cutoff\n                            PBDV26.9  (Don't discharge the battery unless it is at 26.9v or more)\n                            PBCV24.8  (Switch back to 'grid' when battery below 24.8v)\n                            PBFT27.1  (Set the 'float voltage' to 27.1v)\n                            PCVV28.1  (Set the 'charge voltage' to 28.1v)\n\nSet other commands          PEa / PDa (Enable/disable buzzer)\n                            PEb / PDb (Enable/disable overload bypass)\n                            PEj / PDj (Enable/disable power saving)\n                            PEu / PDu (Enable/disable overload restart);\n                            PEx / PDx (Enable/disable backlight)\n```\n\n*NOTE:* When setting/configuring your charge, discharge, float \u0026 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\n\n\n### Using `inverter_poller` binary directly\n\nThis 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).\n\nJust head to the `sources/inverter-cli` directory and build it directly using: `cmake . \u0026\u0026 make`.\n\nBasic arguments supported are:\n\n```\nUSAGE:  ./inverter_poller \u003cargs\u003e [-r \u003ccommand\u003e], [-h | --help], [-1 | --run-once]\n\nSUPPORTED ARGUMENTS:\n          -r \u003craw-command\u003e      TX 'raw' command to the inverter\n          -h | --help           This Help Message\n          -1 | --run-once       Runs one iteration on the inverter, and then exits\n          -d                    Additional debugging\n\n```\n\n### Bonus: Lovelace Dashboard Files\n\n_**Please refer to the screenshot above for an example of the dashboard.**_\n\nI'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.\n\nNote 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:\n\n - [vertical-stack-in-card](https://github.com/custom-cards/vertical-stack-in-card)\n - [circle-sensor-card](https://github.com/custom-cards/circle-sensor-card)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fned-kelly%2Fdocker-voltronic-homeassistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fned-kelly%2Fdocker-voltronic-homeassistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fned-kelly%2Fdocker-voltronic-homeassistant/lists"}