hoymiles-wifi

This Python library enables local communication with Hoymiles DTUs, HMS-XXXXW microinverters, and hybrid inverters using protobuf messages.

For the Home Assistant integration have a look here: https://github.com/suaveolent/ha-hoymiles-wifi

Supported Devices

The library was successfully tested with:

• Hoymiles HMS-400W-1T
• Hoymiles HMS-800W-2T
• Hoymiles HMS-1000W-2T
• Hoymiles HMS-2000DW-4T
• Hoymiles DTU-WLite
• Hoymiles DTU-Pro (S)
• Hoymiles HAS-5.0LV-EUG1
• Hoymiles HYS-4.6LV-EUG1
• Hoymiles HYT-5.0HV-EUG1
• Hoymiles HAT-8.0HV-EUG1
• Solenso H-1000 (not tested for command, only to get data)
• Solenso DTU_SLS (not tested for command, only to get data)

Installation

Quick install (system-wide or existing environment)

pip install hoymiles-wifi

Isolated install with a virtual environment (recommended)

A virtual environment keeps the library and its dependencies isolated from your system Python and other projects. Works on Linux, macOS, and Windows.

Linux / macOS

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install hoymiles-wifi

Windows (PowerShell)

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install hoymiles-wifi

Windows (Command Prompt)

python -m venv .venv
.\.venv\Scripts\activate.bat
python -m pip install --upgrade pip
pip install hoymiles-wifi

After activation, the hoymiles-wifi command is available inside the venv. To leave the environment, run deactivate.

Editable install from a cloned source tree (for development):

python3 -m venv .venv
source .venv/bin/activate        # Windows: .\.venv\Scripts\Activate.ps1
pip install -e .

Usage

You can integrate the library into your own project, or simply use it in the command line.

Warning

Command line:

hoymiles-wifi --host HOST <command> [additional-arguments]

CLI Arguments

The following arguments are available when using the CLI:

The following arguments are only available when using the --disable-interactive flag:

Encryption (enc_rand)

Some DTUs enforce encrypted communication. This is notably the case for devices running firmware v01.x, where encryption is mandatory. On older firmware (v00.x), data could be retrieved without encryption; firmware v01.x enables encryption, so enc_rand must be supplied.

To obtain the enc_rand value, use the is-encrypted command:

hoymiles-wifi --host HOST is-encrypted

Example output (with --as-json):

{
  "is_encrypted": true,
  "enc_rand": "00112233445566778899aabbccddeeff"
}

Then pass the retrieved value via --enc-rand when running any command:

hoymiles-wifi --host HOST --enc-rand 00112233445566778899aabbccddeeff get-real-data-new

🔧 BMS Working Modes & Required Parameters

For set-energy-storage-working-mode different CLI parameters must be provided depending on the selected BMS working mode. Below is an overview:

--time-settings (Economic working mode)

START-END:WEEKDAYS=PEAK_START-PEAK_END-PEAK_IN-PEAK_OUT,OFF_START-OFF_END-OFF_IN-OFF_OUT,PARTIAL_START-PARTIAL_END-PARTIAL_IN-PARTIAL_OUT;WEEKDAYS=...||START-END:...||...

• START, END: Date in DD.MM
• For each date range, exactly two time ranges must be configured
• Each time range includes:
  • WEEKDAYS: Comma-separated days (1=Mon, ..., 7=Sun)
  • 3 tariff blocks: PEAK, OFF_PEAK, PARTIAL_PEAK
• Each block format: START-END-IN_PRICE-OUT_PRICE
• Use ; to separate Time Range 1 and Time Range 2
• Use || to separate multiple date ranges

Example

01.01-31.03:1,2,3=06:00-10:00-0.20-0.10,00:00-06:00-0.10-0.05,10:00-18:00-0.15-0.08;4,5=07:00-11:00-0.22-0.11,00:00-07:00-0.08-0.04,11:00-17:00-0.14-0.07

--time-periods (Time of use mode)

CHARGE_FROM-CHARGE_TO-CHARGE_PWR-MAX_SOC|DISCHARGE_FROM-DISCHARGE_TO-DISCHARGE_PWR-MIN_SOC||...

• All values are required
• Use || to separate multiple time periods
• Power and SOC values must be 0–100

Example

06:00-08:00-50-90|18:00-20:00-40-20

Python code

from hoymiles_wifi.dtu import DTU
...
dtu = DTU(<ip_address>)
response = await dtu.<command>

if response:
    print(f"DTU Response: {response}")
else:
    print("Unable to get response!")

Available functions

• async_get_real_data_new(): Retrieve real-time data
• async_get_real_data(): Retrieve real-time data
• async_get_config(): Retrieve configuration information
• async_network_info(): Retrieve network information
• async_app_information_data(): Retrieve application information data
• async_app_get_hist_power(): Retrieve historical power data
• async_set_power_limit(power_limit): Set the persistent power limit of the inverter (0-100%)
• async_set_power_limit_temporary(power_watts): Set a temporary watt limit on supported HMS-W-2T devices.
• async_set_wifi(wifi_ssid, wifi_password): Configure the wifi network
• async_firmware_update(): Update to latest firmware
• async_restart_dtu(): Restart the DTU
• async_turn_on_inverter(): Turn the inverter on
• async_turn_off_inverter(): Turn the inverter off
• async_get_information_data(): Retrieve information data
• async_heartbeat(): Request a heartbeat message from the DTU
• async_get_alarm_list(): Get alarm list from the DTU
• async_enable_performance_data_mode(): Experimental: Enable higher update interval mode (30s or less)
• async_get_gateway_info(): Get gateway information for hybrid-inverters
• async_get_gateway_network_info() : Get network information for hybrid-inverters
• async_get_energy_storage_registry(): Get information about the hybrid-inverter
• async_get_energy_storage_data(): Get live data of the hybrid-inverter
• async_set_energy_storage_working_mode(): Set the working mode of the hybrid-inverter

Note

Please be aware:

Caution

Use this library responsibly and be aware of potential risks. There are no guarantees provided, and any misuse or incorrect implementation may result in undesirable outcomes. Ensure that your inverter is not compromised during communication.

Known Limitations

Update Frequency:

Compatibility:

Attribution

A special thank you for the inspiration and codebase to:

• DennisOSRM: hms-mqtt-publisher
• henkwiedig: Hoymiles-DTU-Proto