diff --git a/ha_addon_debug/DOCS.md b/ha_addon_debug/DOCS.md new file mode 100644 index 0000000..4034b0b --- /dev/null +++ b/ha_addon_debug/DOCS.md @@ -0,0 +1,157 @@ +# Home Assistant Add-on: TSUN Proxy + +[TSUN Proxy][tsunproxy] enables a reliable connection between TSUN third generation +inverters and an MQTT broker. With the proxy, you can easily retrieve real-time values +such as power, current and daily energy and integrate the inverter into Home Assistant. +This works even without an internet connection. +The optional connection to the TSUN Cloud can be disabled! + +## Pre-requisites + +1. This Add-on requires an MQTT broker to work. +For a typical installation, we recommend the [Mosquitto add-on][Mosquitto] running on your Home Assistant. + +2. You need to loop the proxy into the connection between the inverter and the TSUN Cloud, +you must adapt the DNS record within the network that your inverter uses. You need a mapping +from logger.talent-monitoring.com and/or iot.talent-monitoring.com to the IP address of your +Home Assistant. +This can be done, for example, by adding a local DNS record to [AdGuard Home Add-on][AdGuard] +(navigate to `filters` on the AdGuard panel and add an entry under `custom filtering rules`). + +## Installation + +The installation of this add-on is pretty straightforward and not different in +comparison to installing any other Home Assistant add-on. + +1. Add the repository URL to the Home Assistant add-on store +[![Add repository on my Home Assistant][repository-badge]][repository-url] +2. Reload the add-on store page +3. Click the "Install" button to install the add-on. +4. Add your inverter configuration to the add-on configuration +5. Start the "TSUN-Proxy" add-on +6. Check the logs of the "TSUN-Proxy" add-on to see if everything went well. + +_Please note, the add-on is pre-configured to connect with +Home Assistants default MQTT Broker. There is no need to configure any MQTT parameters +if you're running an MOSQUITTO add-on. Home Assistant communication and TSUN Cloud URL +and Ports are also pre-configured._ + +This automatic handling of the TSUN Cloud and MQTT Broker conflicts with the +[TSUN Proxy official documentation][tsunproxy]. The official documentation +will state `mqtt.host`, `mqtt.port`, `mqtt.user`, `mqtt.passwd` `solarman.host`, +`solarman.port` `tsun.host`, `tsun.port` and Home Assistant options are required. +For the add-on, however, this isn't needed. + +## Configuration + +**Note**: _Remember to restart the add-on when the configuration is changed._ + +Example add-on configuration after installation: + +```yaml +inverters: + - serial: R17E760702080400 + node_id: PV-Garage + suggested_area: Garage + modbus_polling: false + pv1.manufacturer: Shinefar + pv1.type: SF-M18/144550 + pv2.manufacturer: Shinefar + pv2.type: SF-M18/144550 +``` + +**Note**: _This is just an example, you need to replace the values with your own!_ + +Example add-on configuration for GEN3PLUS inverters: + +```yaml +inverters: + - serial: Y17000000000000 + monitor_sn: '2000000000' + node_id: PV-Garage + suggested_area: Garage + modbus_polling: true + pv1.manufacturer: Shinefar + pv1.type: SF-M18/144550 + pv2.manufacturer: Shinefar + pv2.type: SF-M18/144550 + pv3.manufacturer: Shinefar + pv3.type: SF-M18/144550 + pv4.manufacturer: Shinefar + pv4.type: SF-M18/144550 +``` + +**Note**: _This is just an example, you need to replace the values with your own!_ + +## MQQT settings + +By default, this add-on requires no `mqtt` config from the user. **This is not an error!** + +However, you are free to set them if you want to override, however, in +general usage, that should not be needed and is not recommended for this add-on. + +## Changelog & Releases + +This repository keeps a change log using [GitHub's releases][releases] +functionality. + +Releases are based on [Semantic Versioning][semver], and use the format +of `MAJOR.MINOR.PATCH`. In a nutshell, the version will be incremented +based on the following: + +- `MAJOR`: Incompatible or major changes. +- `MINOR`: Backwards-compatible new features and enhancements. +- `PATCH`: Backwards-compatible bugfixes and package updates. + +## Support + +Got questions? + +You have several options to get them answered: + +- The Discussions section on [GitHub][discussions]. +- The [Home Assistant Discord chat server][discord-ha] for general Home + Assistant discussions and questions. + +You could also [open an issue here][issue] GitHub. + +## Authors & contributors + +The original setup of this repository is by [Stefan Allius][author]. + +We're very happy to receive contributions to this project! You can get started by reading [CONTRIBUTING.md][contribute]. + +## License + +This project is licensed under the [BSD 3-clause License][bsd]. + +Note the aiomqtt library used is based on the paho-mqtt library, which has a dual license. +One of the licenses is the so-called [Eclipse Distribution License v1.0.][eclipse] +It is almost word-for-word identical to the BSD 3-clause License. The only differences are: + +- One use of "COPYRIGHT OWNER" (EDL) instead of "COPYRIGHT HOLDER" (BSD) +- One use of "Eclipse Foundation, Inc." (EDL) instead of "copyright holder" (BSD) + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +[tsunproxy]: https://github.com/s-allius/tsun-gen3-proxy +[discussions]: https://github.com/s-allius/tsun-gen3-proxy/discussions +[addon-badge]: https://my.home-assistant.io/badges/supervisor_addon.svg +[author]: https://github.com/s-allius +[discord-ha]: https://discord.gg/c5DvZ4e +[issue]: https://github.com/s-allius/tsun-gen3-proxy/issues +[releases]: https://github.com/s-allius/tsun-gen3-proxy/releases +[contribute]: https://github.com/s-allius/tsun-gen3-proxy/blob/main/CONTRIBUTING.md +[semver]: http://semver.org/spec/v2.0.0.htm +[bsd]: https://opensource.org/licenses/BSD-3-Clause +[eclipse]: https://www.eclipse.org/org/documents/edl-v10.php +[Mosquitto]: https://github.com/home-assistant/addons/blob/master/mosquitto/DOCS.md +[AdGuard]: https://github.com/hassio-addons/addon-adguard-home +[repository-badge]: https://img.shields.io/badge/Add%20repository%20to%20my-Home%20Assistant-41BDF5?logo=home-assistant&style=for-the-badge +[repository-url]: https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fs-allius%2Ftsun-gen3-proxy \ No newline at end of file diff --git a/ha_addon_debug/config.yaml b/ha_addon_debug/config.yaml new file mode 100644 index 0000000..5f3e3d5 --- /dev/null +++ b/ha_addon_debug/config.yaml @@ -0,0 +1,102 @@ +name: TSUN-Proxy (Debug) +description: MQTT Proxy for TSUN Photovoltaic Inverters with Debug Logging +version: debug +image: docker.io/sallius/tsun-gen3-addon +url: https://github.com/s-allius/tsun-gen3-proxy +slug: tsun-proxy-debug +init: false +arch: + - aarch64 + - amd64 + - armhf + - armv7 +startup: services +homeassistant_api: true +services: + - mqtt:want +ports: + 8127/tcp: 8127 + 5005/tcp: 5005 + 10000/tcp: 10000 + +# Definition of parameters in the configuration tab of the addon +# parameters are available within the container as /data/options.json +# and should become picked up by the proxy - current workaround as a transfer script +# TODO: check again for multi hierarchie parameters +# TODO: implement direct reading of the configuration file +schema: + inverters: + - serial: str + monitor_sn: int? + node_id: str + suggested_area: str + modbus_polling: bool + client_mode_host: str? + client_mode_port: int? + #strings: # leider funktioniert es nicht die folgenden 3 parameter im schema aufzulisten. möglicherweise wird die verschachtelung nicht unterstützt. + # - string: str + # type: str + # manufacturer: str + # daher diese variante + pv1.manufacturer: str? + pv1.type: str? + pv2.manufacturer: str? + pv2.type: str? + pv3.manufacturer: str? + pv3.type: str? + pv4.manufacturer: str? + pv4.type: str? + pv5.manufacturer: str? + pv5.type: str? + pv6.manufacturer: str? + pv6.type: str? + tsun.enabled: bool + solarman.enabled: bool + inverters.allow_all: bool + # optionale parameter + # TODO besser strukturieren und vervollständigen + mqtt.host: str? + mqtt.port: int? + mqtt.user: str? + mqtt.passwd: password? + ha.auto_conf_prefix: str? # suggeriert optionale konfigurationsoption -> es darf jedoch kein default unter "options" angegeben werden + ha.discovery_prefix: str? # dito + ha.entity_prefix: str? #dito + ha.proxy_node_id: str? #dito + ha.proxy_unique_id: str? #dito + tsun.host: str? + solarman.host: str? + gen3plus.at_acl.tsun.allow: + - str + gen3plus.at_acl.tsun.block: + - str? + gen3plus.at_acl.mqtt.allow: + - str + gen3plus.at_acl.mqtt.block: + - str? + +# set default options for mandatory parameters +# for optional parameters do not define any default value in the options dictionary. +# If any default value is given, the option becomes a required value. +options: + inverters: + - serial: R17E760702080400 + node_id: PV-Garage + suggested_area: Garage + modbus_polling: false + # strings: + # - string: PV1 + # type: SF-M18/144550 + # manufacturer: Shinefar + # - string: PV2 + # type: SF-M18/144550 + # manufacturer: Shinefar + pv1.manufacturer: Shinefar + pv1.type: SF-M18/144550 + pv2.manufacturer: Shinefar + pv2.type: SF-M18/144550 + tsun.enabled: true # set default + solarman.enabled: true # set default + inverters.allow_all: false # set default + gen3plus.at_acl.tsun.allow: ["AT+Z", "AT+UPURL", "AT+SUPDATE"] + gen3plus.at_acl.mqtt.allow: ["AT+"] \ No newline at end of file diff --git a/ha_addon_debug/icon.png b/ha_addon_debug/icon.png new file mode 100644 index 0000000..f11771f Binary files /dev/null and b/ha_addon_debug/icon.png differ diff --git a/ha_addon_debug/logo.png b/ha_addon_debug/logo.png new file mode 100644 index 0000000..f11771f Binary files /dev/null and b/ha_addon_debug/logo.png differ diff --git a/ha_addon_debug/translations/en.yaml b/ha_addon_debug/translations/en.yaml new file mode 100755 index 0000000..9331e48 --- /dev/null +++ b/ha_addon_debug/translations/en.yaml @@ -0,0 +1,85 @@ +--- +configuration: + inverters: + name: Inverters + description: >+ + For each GEN3 inverter, the serial number of the inverter must be mapped to an MQTT + definition. To do this, the corresponding configuration block is started with + <16-digit serial number> so that all subsequent parameters are assigned + to this inverter. Further inverter-specific parameters (e.g. polling mode) can be set + in the configuration block + + The serial numbers of all GEN3 inverters start with `R17`! + + monitor_sn # The GEN3PLUS "Monitoring SN:" + node_id # MQTT replacement for inverters serial number + suggested_area # suggested installation area for home-assistant + modbus_polling # Disable optional MODBUS polling + pv1 # Optional, PV module descr + pv2 # Optional, PV module descr + + tsun.enabled: + name: Connection to TSUN Cloud - for GEN3 inverter only + description: >- + switch on/off connection to the TSUN cloud + This connection is only required if you want send data to the TSUN cloud + eg. to use the TSUN APPs or receive firmware updates. + + on - normal proxy operation + off - The Inverter become isolated from Internet + solarman.enabled: + name: Connection to Solarman Cloud - for GEN3PLUS inverter only + description: >- + switch on/off connection to the Solarman cloud + This connection is only required if you want send data to the Solarman cloud + eg. to use the Solarman APPs or receive firmware updates. + + on - normal proxy operation + off - The Inverter become isolated from Internet + inverters.allow_all: + name: Allow all connections from all inverters + description: >- + The proxy only usually accepts connections from known inverters. + Switch on for test purposes and unknown serial numbers. + mqtt.host: + name: MQTT Broker Host + description: >- + Hostname or IP address of the MQTT broker. if not set, the addon will try to connect to the Home Assistant MQTT broker + mqtt.port: + name: MQTT Broker Port + description: >- + Port of the MQTT broker. if not set, the addon will try to connect to the Home Assistant MQTT broker + mqtt.user: + name: MQTT Broker User + description: >- + User for the MQTT broker. if not set, the addon will try to connect to the Home Assistant MQTT broker + mqtt.passwd: + name: MQTT Broker Password + description: >- + Password for the MQTT broker. if not set, the addon will try to connect to the Home Assistant MQTT broker + ha.auto_conf_prefix: + name: MQTT prefix for subscribing for homeassistant status updates + ha.discovery_prefix: + name: MQTT prefix for discovery topic + ha.entity_prefix: + name: MQTT topic prefix for publishing inverter values + ha.proxy_node_id: + name: MQTT node id, for the proxy_node_id + ha.proxy_unique_id: + name: MQTT unique id, to identify a proxy instance + tsun.host: + name: TSUN Cloud Host + description: >- + Hostname or IP address of the TSUN cloud. if not set, the addon will try to connect to the cloud default + on logger.talent-monitoring.com + solarman.host: + name: Solarman Cloud Host + description: >- + Hostname or IP address of the Solarman cloud. if not set, the addon will try to connect to the cloud default + on iot.talent-monitoring.com + + +network: + 8127/tcp: x... + 5005/tcp: listening Port for TSUN GEN3 Devices + 10000/tcp: listening Port for TSUN GEN3PLUS Devices diff --git a/ha_addon_dev/config.yaml b/ha_addon_dev/config.yaml index 8a070c5..518df74 100755 --- a/ha_addon_dev/config.yaml +++ b/ha_addon_dev/config.yaml @@ -1,9 +1,9 @@ -name: "TSUN-Proxy (Debug)" -description: "MQTT Proxy for TSUN Photovoltaic Inverters with Debug Logging" -version: "debug" +name: TSUN-Proxy (Dev) +description: MQTT Proxy for TSUN Photovoltaic Inverters +version: dev image: docker.io/sallius/tsun-gen3-addon url: https://github.com/s-allius/tsun-gen3-proxy -slug: "tsun-proxy-dev" +slug: tsun-proxy-dev init: false arch: - aarch64