From 954f6fd201f8fd0eb68cdfae2b41851eb3cf43ab Mon Sep 17 00:00:00 2001 From: bohdan-s Date: Mon, 7 Mar 2022 15:34:38 +1100 Subject: [PATCH] Update index.md --- docs/index.md | 338 ++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 317 insertions(+), 21 deletions(-) diff --git a/docs/index.md b/docs/index.md index 884fcee..91e9858 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,37 +1,333 @@ -## Welcome to GitHub Pages +
-You can use the [editor on GitHub](https://github.com/bohdan-s/SunGather/edit/main/docs/index.md) to maintain and preview the content for your website in Markdown files. +[![Contributors][contributors-shield]][contributors-url] +[![Forks][forks-shield]][forks-url] +[![Stargazers][stars-shield]][stars-url] +[![Issues][issues-shield]][issues-url] +[![GPL3 License][license-shield]][license-url] -Whenever you commit to this repository, GitHub Pages will run [Jekyll](https://jekyllrb.com/) to rebuild the pages in your site, from the content in your Markdown files. +
+
-### Markdown +

SunGather

-Markdown is a lightweight and easy-to-use syntax for styling your writing. It includes conventions for +

+ Collect data from Sungrow Inverters using ModbusTcpClient, SungrowModbusTcpClient or SungrowModbusWebClient and export to various locations. +
+
+ Report Bug + · + Request Feature +

+
-```markdown -Syntax highlighted code block + +## About The Project -# Header 1 -## Header 2 -### Header 3 +Join the Discord Server to discuss, suggestions or for any help: SunGather Discord -- Bulleted -- List +Access ModBus data from almost any network connected Sungow Inverter. -1. Numbered -2. List +On first connection the tool will query your inverter, retrieve the model and return the correct registers for your device. No more searching registers or creating model files. -**Bold** and _Italic_ and `Code` text +Register information based on official documentation: Communication Protocol of PV Grid-Connected String Inverters and Communication Protocol of Residential Hybrid Inverters -[Link](url) and ![Image](src) +Has multiple export locations out of the box: +* Console - Log directly to screen +* MQTT - Load into MQTT, and optionally Home Assistance including Discovery +* PVOutput - Load into PVOutput.org +* InfluxDB - Load data directly into InfluxDB +* Simple webserver showing collected data +* Rasberry Pi Docker support +* and more coming.... + +I have learned a lot from the following projects, THANK YOU +* [solariot](https://github.com/meltaxa/solariot) +* [modbus4mqtt](https://github.com/tjhowse/modbus4mqtt) +* [ModbusTCP2MQTT](https://github.com/TenySmart/ModbusTCP2MQTT) + +

(back to top)

+ +## Raodmap / TO DO +* Full Home Assistant integration, as HACS addon + +## Updates +**0.3.2** +* Added logging to file +* Hopefully better connection recovery +* Bug fixes + +**0.3.0** +**IMPORTANT: If updating from v0.1.x or v0.2.x please check config against config-example. some options for MQTT and PVOutput have changed** +* Heaps bug fixes +* Fixed PVOutput not working after midnight +* MQTT now auto-reconnects +* MQTT/PVOutput now verify values exist before trying to publish +* Rasberry Pi Docker support +* lots more... + + +**0.2.2** +* Minor bug fixes +* Add support for some inverter scrapes to fail +* Add support for zero_on_standby, this will 0 registers like temp that 'stick' to the last value when the inverter goes into standy. Handy if you want to graph 0 instead of the last read overnight + +**0.2.1** +* Minor bug fixes +* Updated config-example.yaml to clearly explain each option and if it is required or optional +* Replace is_running with run_state, was using bool which was causing errors in MQTT, run_state uses "ON" and "OFF" + +**0.2.0** +**IMPORTANT: If updating from v0.1.x please check config against config-example. some options for MQTT and PVOutput have changed** +* Re-write to Inverter scanning code, improved performance and more resilient to failures +* Re-write to PVOutput code, now uploads every 5 minutes as per API documentation, averages all data points over the 5 min window to reduce random high/low values +* Re-Write to MQTT code, now supports multiple sensor types + +**0.1.3** +* Improved error recovery, e.g. Inverter powers down overnight + +**0.1.2** +* Added InfluxDB export + +**0.1.1** +* Added docker image +* Added simple http web server +* Improved recovery when errors (See: SungrowModbusWebClient 0.2.6) + +**0.1.0** +Initial build + +### Built With + +* [Python3](https://www.python.org/) + +### Requires +* [paho-mqtt>=1.5.1](https://pypi.org/project/paho-mqtt/) +* [pymodbus>=2.4.0](https://pypi.org/project/pymodbus/) +* [SungrowModbusTcpClient>=0.1.6](https://pypi.org/project/SungrowModbusTcpClient/) +* [SungrowModbusWebClient>=0.2.6](https://pypi.org/project/SungrowModbusWebClient/) +* [PyYAML>=6.0](https://pypi.org/project/PyYAML/) +* [requests>=2.26.0](https://pypi.org/project/requests/) +* [influxdb-client>=1.24.0](https://pypi.org/project/influxdb-client/) + +

(back to top)

+ + +## Getting Started +# Local +```sh +git clone https://github.com/bohdan-s/SunGather.git +cd SunGather +pip3 install --upgrade -r requirements.txt +``` +Copy config-example.py to config.py, change values as required (see comments in file) +```sh +copy config-example.py config.py +``` +Run SunGather: +```sh +python3 sungather.py ``` -For more details see [Basic writing and formatting syntax](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). +# Docker +docker run options: +-v {path to}/config.yaml:/config/config.yaml <- Set Config File Location +-v {logpath}:/logs <- Set Log folder Location if using log to file (also set log_file in config.yaml) +-e TZ=Australia/Sydney <- Set Timezone +-p 8080:8080 <- Set Web server port (only if using the webserver export) -### Jekyll Themes +```sh +docker pull bohdans/sungather +docker run -d --name sungather \ + --restart always \ + -v {path to}/config.yaml:/config/config.yaml \ + -v {logpath}:/logs \ + -e TZ=Australia/Sydney \ + -p 8080:8080 \ + bohdans/sungather +``` +Note: replace Australia/Sydney with relevant timezone +

(back to top)

-Your Pages site will use the layout and styles from the Jekyll theme you have selected in your [repository settings](https://github.com/bohdan-s/SunGather/settings/pages). The name of this theme is saved in the Jekyll `_config.yml` configuration file. -### Support or Contact + +## Usage -Having trouble with Pages? Check out our [documentation](https://docs.github.com/categories/github-pages-basics/) or [contact support](https://support.github.com/contact) and we’ll help you sort it out. +See config-example.py it contains default options and comments. + +If you want to use the new Energy section in Home Assistant, follow the Home Assistant setup below. +

(back to top)

+ +### Commandline Arguments +usage: python3 sungather.py [options] + +Commandline arguments override any config file settings +**-c config.yaml** - Specify config file. +**-v 30** - Logging Level, 10 = Debug, 20 = Info, 30 = Warning (default), 40 = Error +**--runonce** - Run once then exit +**-h** - print this help message and exit (also --help) + +Example: +```sh +python3 sungather.py -c /full/path/config.yaml +``` + +## Exports + +A collection of exports are available: + +* console: Output information to console, useful for troubleshooting +* webserver: Output to a simple website, default http://localhost:8080 or http://\:8080 +* mqtt: Output to a pre-existing MQTT server, needed for Home Assistant integration +* pvoutput: Output to PVOutput.org, requires account and solar is set up on website first. +* InfluxDB: Output directly to InfluxDB, can then be used by Grafana, etc.. + +## Registers + +This tool should be able to access most registers exposed. +Set the following in config.yaml under inverters section. +* level: 1 - This is the most useful data for day to day +* Level: 2 - This should be everything your inverter supports +* Level: 3 - This will try every register, you will get lots of 0/65535 responses for registers not supported. + +* smart_meter: True - Set to true if you have a smart reader installed, this will return power usage at the meter box, without it you can not calculate house power usage. + +### Useful Registers: +This is just a brief list of registers I have found useful + +**daily_power_yields** - Total Power in kWh generated today +**total_power_yields** - Total Power in kWh generated since inverter install +**total_running_time** - Total Hours inverter has been powered on since install +**internal_temperature** - Internal temperature of the Inverter +**total_active_power** - Current power being generated by the inverter in Watts +**meter_power** - Power usage at the meter box, needs a smart meter installed. +ve means consuming from the grid, -ve means exporting to the grid +**load_power** - Power being consumed in total +**export_to_grid** - How much being currently exported to the grid. This is calculated from meter_power if -ve value, returned as a positive value +**import_from_grid** - How much being currently imported from grid. This is calculated from meter_power if +ve value +**timestamp** - Last time data was collected, based on Inverters clock by default + +

(back to top)

+ +## Home Assistant setup + +In the SunGather config.yaml you need to set the smart_meter if you have one; + +``` +smart_meter: True +``` + +HA sensors created by the MQTT auto-discovery; +``` +sensor.inverter_active_power +sensor.inverter_daily_generation +sensor.inverter_export_to_grid +sensor.inverter_import_from_grid +sensor.inverter_load_power +sensor.inverter_meter_power + +``` + +The Inverter reports Power (W), but HA needs Energy (Wh). +You can use a "Riemann sum integral" (called integration) to convert it. +Put the following into your sensors.yaml +``` +sensor: + - platform: integration + source: sensor.inverter_active_power + name: Solar Production (Sungather) + - platform: integration + source: sensor.inverter_export_to_grid + name: Return to Grid (Sungather) + - platform: integration + source: sensor.inverter_import_from_grid + name: Grid Consumption (Sungather) +``` + +The additional sensors then setup in HA are the following with Wh unit of measurement for the Energy platform. + +Solar Production (Sungather) +Return to Grid (Sungather) +Grid Consumption (Sungather) + +Restart Home Assistant for the sensors.yaml to be loaded. +Make sure SunGather is running, wait 5 minutes for initial data to populate. +Navigate to the Energy platform (Configuration > Energy). Add these sensors to the following areas: + +Electricity Grid > Grid Consumption -> Grid Consumption (Sungather) +Electricity Grid > Return to Grid -> Return to Grid (Sungather) +Solar Panels > Solar Production -> Solar Production (Sungather) + +

(back to top)

+ +## Tested +* SG7.0RT with WiNet-S Dongle +* SG10RT with WiNet-S Dongle and Ethernet (Credit: @rark-ha) + +

(back to top)

+ +## Supported +### PV Grid-Connected String Inverters +SG30KTL, SG10KTL, SG12KTL, SG15KTL, SG20KTL, SG30KU, SG36KTL, SG36KU, SG40KTL, SG40KTL-M, SG50KTL-M, SG60KTL-M, SG60KU, SG30KTL-M, SG30KTL-M-V31, SG33KTL-M, SG36KTL-M, SG33K3J, SG49K5J, SG34KJ, LP_P34KSG, SG50KTL-M-20, SG60KTL, SG80KTL, SG80KTL-20, SG60KU-M, SG5KTL-MT, SG6KTL-MT, SG8KTL-M, SG10KTL-M, SG10KTL-MT, SG12KTL-M, SG15KTL-M, SG17KTL-M, SG20KTL-M, SG80KTL-M, SG111HV, SG125HV, SG125HV-20, SG30CX, SG33CX, SG36CX-US, SG40CX, SG50CX, SG60CX-US, SG110CX, SG250HX, SG250HX-US, SG100CX, SG100CX-JP, SG250HX-IN, SG25CX-SA, SG75CX, SG3.0RT, SG4.0RT, SG5.0RT, SG6.0RT, SG7.0RT, SG8.0RT, SG10RT, SG12RT, SG15RT, SG17RT, SG20RT + +### PV Grid-Connected String Inverters Gen 2 +SG5K-D, SG8K-D + +### Residential Hybrid Inverters +SH5K-20, SH3K6, SH4K6, SH5K-V13, SH5K-30, SH3K6-30, SH4K6-30, SH5.0RS, SH3.6RS, SH4.6RS, SH6.0RS, SH10RT, SH8.0RT, SH6.0RT, SH5.0RT + +

(back to top)

+ + +## Building +Multi Arch (BuildX) Including Raspberry Pi +```sh +docker run --privileged --rm tonistiigi/binfmt --install all +docker buildx create --platform linux/amd64,linux/arm64/v8 --use +docker buildx build --push --platform linux/amd64,linux/arm64/v8 -t bohdans/sungather:latest -t bohdans/sungather:v . +``` +Current Arch (docker build) +```sh +docker build --no-cache --rm -t bohdans/sungather:latest -t bohdans/sungather:v . +docker push bohdans/sungather -a +``` + + +

(back to top)

+ + +## License + +Distributed under the GPL3 License. See `LICENSE.txt` for more information. + +

(back to top)

+ + +## Contact + +Project Link: [https://github.com/bohdan-s/SungrowModbusWebClient](https://github.com/bohdan-s/SungrowModbusWebClient) + +

(back to top)

+ + +## Acknowledgments + +* [solariot](https://github.com/meltaxa/solariot) +* [modbus4mqtt](https://github.com/tjhowse/modbus4mqtt) +* [ModbusTCP2MQTT](https://github.com/TenySmart/ModbusTCP2MQTT) + +

(back to top)

+ + + + + +[contributors-shield]: https://img.shields.io/github/contributors/bohdan-s/SunGather.svg?style=for-the-badge +[contributors-url]: https://github.com/bohdan-s/SunGather/graphs/contributors +[forks-shield]: https://img.shields.io/github/forks/bohdan-s/SunGather.svg?style=for-the-badge +[forks-url]: https://github.com/bohdan-s/SunGather/network/members +[stars-shield]: https://img.shields.io/github/stars/bohdan-s/SunGather.svg?style=for-the-badge +[stars-url]: https://github.com/bohdan-s/SunGather/stargazers +[issues-shield]: https://img.shields.io/github/issues/bohdan-s/SunGather.svg?style=for-the-badge +[issues-url]: https://github.com/bohdan-s/SunGather/issues +[license-shield]: https://img.shields.io/github/license/bohdan-s/SunGather.svg?style=for-the-badge +[license-url]: https://github.com/bohdan-s/SunGather/blob/main/LICENSE.txt