Metadata-Version: 2.1
Name: hoymiles-mqtt
Version: 0.2.0
Summary: Send data from Hoymiles photovoltaic installation to MQTT server.
Home-page: https://github.com/wasilukm/hoymiles-mqtt
License: MIT
Author: Foo Bar
Author-email: foo@bar.com
Requires-Python: >=3.6.2,<4.0
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Provides-Extra: dev
Provides-Extra: doc
Provides-Extra: test
Requires-Dist: ConfigArgParse (>=1.5.3,<2.0.0)
Requires-Dist: black (==22.3.0); extra == "test"
Requires-Dist: bump2version (>=1.0.1,<2.0.0); extra == "dev"
Requires-Dist: flake8 (>=3.9.2,<4.0.0); extra == "test"
Requires-Dist: flake8-docstrings (>=1.6.0,<2.0.0); extra == "test"
Requires-Dist: hoymiles-modbus (==0.4.0)
Requires-Dist: isort (>=5.8.0,<6.0.0); extra == "test"
Requires-Dist: mkdocs (>=1.1.2,<2.0.0); extra == "doc"
Requires-Dist: mkdocs-autorefs (>=0.2.1,<0.3.0); extra == "doc"
Requires-Dist: mkdocs-include-markdown-plugin (>=1.0.0,<2.0.0); extra == "doc"
Requires-Dist: mkdocs-material (>=6.1.7,<7.0.0); extra == "doc"
Requires-Dist: mkdocs-material-extensions (>=1.0.1,<2.0.0)
Requires-Dist: mkdocstrings (>=0.15.2,<0.16.0); extra == "doc"
Requires-Dist: mypy (>=0.900,<0.901); extra == "test"
Requires-Dist: paho-mqtt (>=1.6.1,<2.0.0)
Requires-Dist: pip (>=20.3.1,<21.0.0); extra == "dev"
Requires-Dist: pre-commit (>=2.12.0,<3.0.0); extra == "dev"
Requires-Dist: pytest (>=6.2.4,<7.0.0); extra == "test"
Requires-Dist: pytest-cov (>=2.12.0,<3.0.0); extra == "test"
Requires-Dist: toml (>=0.10.2,<0.11.0); extra == "dev"
Requires-Dist: tox (>=3.20.1,<4.0.0); extra == "dev"
Requires-Dist: twine (>=3.3.0,<4.0.0); extra == "dev"
Requires-Dist: virtualenv (>=20.2.2,<21.0.0); extra == "dev"
Description-Content-Type: text/markdown

# Hoymiles MQTT


[![pypi](https://img.shields.io/pypi/v/hoymiles-mqtt.svg)](https://pypi.org/project/hoymiles-mqtt/)
[![python](https://img.shields.io/pypi/pyversions/hoymiles-mqtt.svg)](https://pypi.org/project/hoymiles-mqtt/)
[![Build Status](https://github.com/wasilukm/hoymiles-mqtt/actions/workflows/dev.yml/badge.svg)](https://github.com/wasilukm/hoymiles-mqtt/actions/workflows/dev.yml)
[![codecov](https://codecov.io/gh/wasilukm/hoymiles-mqtt/branch/main/graphs/badge.svg)](https://codecov.io/github/wasilukm/hoymiles-mqtt)



Send data from Hoymiles photovoltaic installation to Home Assistant through MQTT broker.

* GitHub: <https://github.com/wasilukm/hoymiles-mqtt>
* PyPI: <https://pypi.org/project/hoymiles-mqtt/>
* Free software: MIT

The tool periodically communicates with Hoymiles DTU trough ModbusTCP and sends gathered data to MQTT broker.
Data to MQTT broker are sent with topics that can be recognized by Home Assistant.
In a result DTU and each micro-inverter can be represented in Home Assistant as a separate device with set of entities. Example:

![MQTT Devices](/docs/mqtt_devices.png)

![MQTT Entities](/docs/mqtt_entities.png)

DTU device represent overall data for the installation:
- pv_power - current power - sum from all micro-inverters
- today_production - today energy production - sum from all micro-inverters, for each micro-inverter last known
  good value is cached to prevent disturbances in statistics when part of the installation is temporarily off
  or off-line. This entity can be used in Home Assistant energy panel as a production from solar panels.
  An example chart:

  ![Solar production](/docs/solar%20production.png)
- total_production - lifetime energy production - sum from all micro-inverters

Each micro-inverter has the following entities:
- port_number
- pv_voltage
- pv_current
- grid_voltage
- grid_frequency
- pv_power
- today_production
- total_production
- temperature
- operating_status
- alarm_code
- alarm_count
- link_status

Depending on the installation (number of micro-inverter), the tool may create many entities. One may limit the entities
or with the option _--mi-entities_.

## Usage

### Prerequisites
- DTUs' _Ethernet_ port connected to a network
- DTU has assigned IP address by DHCP server. IP address shall be reserved for the device
- running MQTT broker, for example https://mosquitto.org/
- MQTT integration enabled in Home Assistant, https://www.home-assistant.io/integrations/mqtt/

### From command line
    usage: python3 -m hoymiles_mqtt [-h] [-c CONFIG] --mqtt-broker MQTT_BROKER [--mqtt-port MQTT_PORT] [--mqtt-user MQTT_USER] [--mqtt-password MQTT_PASSWORD] --dtu-host DTU_HOST [--dtu-port DTU_PORT]
                                    [--modbus-unit-id MODBUS_UNIT_ID] [--query-period QUERY_PERIOD] [--microinverter-type {MI,HM}] [--mi-entities MI_ENTITIES [MI_ENTITIES ...]]

    options:
      -h, --help            show this help message and exit
      -c CONFIG, --config CONFIG
                            Config file path (default: None)
      --mqtt-broker MQTT_BROKER
                            Address of MQTT broker [env var: MQTT_BROKER] (default: None)
      --mqtt-port MQTT_PORT
                            MQTT broker port [env var: MQTT_PORT] (default: 1883)
      --mqtt-user MQTT_USER
                            User name for MQTT broker [env var: MQTT_USER] (default: None)
      --mqtt-password MQTT_PASSWORD
                            Password to MQTT broker [env var: MQTT_PASSWORD] (default: None)
      --dtu-host DTU_HOST   Address of Hoymiles DTU [env var: DTU_HOST] (default: None)
      --dtu-port DTU_PORT   DTU modbus port [env var: DTU_PORT] (default: 502)
      --modbus-unit-id MODBUS_UNIT_ID
                            Modbus Unit ID [env var: MODBUS_UNIT_ID] (default: 1)
      --query-period QUERY_PERIOD
                            How often (in seconds) DTU shall be queried. [env var: QUERY_PERIOD] (default: 60)
      --microinverter-type {MI,HM}
                            Type od microinverters in the installation. Mixed types are not supported. [env var: MICROINVERTER_TYPE] (default: MI)
      --mi-entities MI_ENTITIES [MI_ENTITIES ...]
                            Microinverter entities that will be sent to MQTT. By default all entities are presented. [env var: MI_ENTITIES] (default: ['port_number', 'pv_voltage', 'pv_current', 'grid_voltage',
                            'grid_frequency', 'pv_power', 'today_production', 'total_production', 'temperature', 'operating_status', 'alarm_code', 'alarm_count', 'link_status'])

    Args that start with '--' (eg. --mqtt-broker) can also be set in a config file (specified via -c). Config file syntax allows: key=value, flag=true, stuff=[a,b,c] (for details, see syntax at https://goo.gl/R74nmi). If an
    arg is specified in more than one place, then commandline values override environment variables which override config file values which override defaults.

### Docker

Build an image

    docker build https://github.com/wasilukm/hoymiles-mqtt.git#v0.1.0 -t hoymiles_mqtt

Run (replace IP addresses)

    docker run -d -e MQTT_BROKER=192.168.1.101 -e DTU_HOST=192.168.1.100 hoymiles_mqtt

Please note, depending on the needs more options can be specified with _-e_. See above for all possible options.

## Known issues
Hoymiles DUTs are not the most stable devices. Therefore, from time to time the tool may not be able to connect to DTU
and will print the following exception:

    Modbus Error: [Invalid Message] No response received, expected at least 8 bytes (0 received)

The tool will continue its operation and try communication with DTU with the next period.

## Credits

This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [waynerv/cookiecutter-pypackage](https://github.com/waynerv/cookiecutter-pypackage) project template.

