Hoymiles Cloud Integration for Home Assistant

This custom integration for Home Assistant allows you to monitor and control your Hoymiles solar inverter system through the Hoymiles Cloud API.

Features

• Data Monitoring:

  • Solar PV power generation
  • Battery power (charge/discharge)
  • Battery state of charge
  • Grid power import/export
  • Load power consumption
  • Daily and total energy generation
  • Dynamic PV channel discovery based on the indicators returned by the account
  • Per-channel PV voltage/current/power values via the module-data endpoint when the indicators feed only returns placeholders
  • Reported inverter count and battery settings access diagnostics

• Control Functions:

  • Set battery operation mode when the account exposes writable battery settings
  • Configure battery reserve state of charge for the modes returned by the account
  • Peak Shaving Mode specific settings (max_soc, meter_power) when supported
  • Home Assistant-native draft editors for Economy and Time of Use schedules using built-in selects, text fields, numbers, buttons, and summary sensors
  • Advanced battery mode payload updates through Home Assistant services for Economy and Time of Use schedules

Development Status

This integration focuses on safe production use:

• Read-only telemetry should still work even if the account cannot access battery settings
• Controls are only exposed when the Hoymiles account returns writable settings data
• Battery setting reads and writes now follow the observed async Hoymiles read/write -> job id -> status poll flow
• Station discovery supports accounts with more than one page of stations
• Authentication now preserves more specific Hoymiles failure reasons instead of flattening them into a generic login error

Not all available Hoymiles API fields are exposed as entities yet, but unsupported or permission-denied controls should now stay out of Home Assistant instead of showing misleading defaults.

Installation

HACS (Recommended)

1. Make sure you have HACS installed
2. Go to HACS → Integrations → Plus Icon → "Add Custom Repository"
3. Enter the URL: https://github.com/Philra94/homeassistant-hoymiles-cloud
4. Select category: "Integration"
5. Click "Add"
6. Find and install "Hoymiles Cloud"
7. Restart Home Assistant

Manual Installation

1. Download this repository
2. Copy the custom_components/hoymiles_cloud directory to your Home Assistant custom_components directory
3. Restart Home Assistant

Configuration

1. Go to Home Assistant → Settings → Devices & Services → Add Integration
2. Search for "Hoymiles Cloud"
3. Enter your Hoymiles Cloud login credentials
4. Click "Submit"

The integration currently auto-tries multiple authentication strategies:

• browser-compatible v3 login
• an S-Miles Installer v3 retry with app-version metadata
• an S-Miles Home v3 retry with app-version metadata
• legacy v0 login fallback

If Hoymiles rejects an account with a more specific message, the config flow should now surface that reason instead of only showing a generic authentication failure.

Usage

After configuration, the integration will create:

• A device for each Hoymiles station with sensors for power, energy, and battery levels
• Controls for battery mode and reserve capacity settings only when the account exposes writable battery settings
• A schedule editor surface for Economy (mode: 2) and Time of Use (mode: 8) when those modes are present in the live Hoymiles payload

The integration creates PV input sensors from the indicator keys returned by the API. If a system has more than two PV inputs and Hoymiles exposes them in the indicators payload, matching Home Assistant sensors will be created automatically.

The sensors will update every minute by default, but this can be changed in the integration options.

Schedule editor

The integration now exposes a Home Assistant-native draft editor for the two schedule-bearing battery modes:

• Schedule Editor Mode chooses whether you are editing Economy or Time of Use
• Summary and count sensors show the live/draft schedule at a glance
• Validation and dirty-state sensors show whether the draft is safe to apply
• Built-in buttons load, apply, discard, add, and remove schedule rows

Time of Use draft entities expose:

• active period selector
• charge/discharge start and end times
• charge/discharge power
• charge and discharge SOC targets

Economy draft entities expose:

• active date window selector
• active weekday-group selector
• active duration-type selector
• start and end date fields (MM-DD)
• start and end time fields for the selected duration
• in and out numeric fields for the selected duration

Advanced battery services

For structured battery settings and automation-friendly editor flows, the integration registers these services:

• hoymiles_cloud.set_battery_mode
• hoymiles_cloud.set_battery_mode_settings
• hoymiles_cloud.load_schedule_draft
• hoymiles_cloud.apply_schedule_draft
• hoymiles_cloud.reset_schedule_draft
• hoymiles_cloud.add_schedule_entry
• hoymiles_cloud.remove_schedule_entry

set_battery_mode_settings accepts a raw settings dictionary and merges it into the live Hoymiles mode payload by default. This is the recommended path for advanced Economy (mode: 2) and Time of Use (mode: 8) schedule updates because the backend expects the full mode payload to be preserved.

Notes

• The integration uses the modern Hoymiles v3 authentication flow with the observed browser-compatible hashing fallback.
• Some accounts appear to require a different Hoymiles client/account family. If Hoymiles responds with messages like Can only login to the S-Miles Home. or Your app version is low. Please update to the latest version., the integration now exposes those outcomes more clearly in the config flow and logs while still keeping the user-facing setup flow simple.
• Some accounts expose live battery telemetry but deny access to battery settings. In that case the integration keeps the telemetry sensors and hides the unsupported controls.
• Economy and Time-of-Use schedules now have draft editor entities in Home Assistant, but the integration still writes the full structured Hoymiles payload on apply.
• Validation is intentionally conservative for schedule editing: time/date formats and basic numeric ranges are checked before writes, while ambiguous Hoymiles-specific semantics are kept internal.
• API endpoints and payload structures are based on observed Hoymiles Cloud behavior and may still vary by region, account role, and hardware family.
• On some hardware (observed: HF-800-1WB) the indicators endpoint returns placeholder values for per-channel PV data; the integration then falls back to the module-data chart endpoint (see docs/hoymiles-module-data-api.md) for single-microinverter stations. Those values are cached for a few minutes to match the cloud's own refresh rate, and drop to 0 once the inverter stops reporting for the day rather than repeating the last daylight reading.

Contributing

Contributions are welcome! If you have recommendations, improvements, or additions to this repository, please feel free to:

• Open an issue with your suggestions
• Create a pull request with your changes
• Share your feedback on what could be improved

Please note that this code was developed with the assistance of AI, which may explain why some parts are not always the prettiest or most straightforward. Your help in improving and refining the codebase would be greatly appreciated.

Troubleshooting

• Check Home Assistant logs for details about any errors
• Verify your Hoymiles Cloud credentials
• If setup fails, note the exact Hoymiles message shown in the logs or config flow. Messages about S-Miles Home or app version requirements usually indicate an account/client compatibility issue rather than a wrong password.
• The integration logs now include all attempted auth profiles and their returned status/message. Useful loggers are custom_components.hoymiles_cloud.config_flow and custom_components.hoymiles_cloud.hoymiles_api.
• If a browser login works but the integration still fails, the most helpful follow-up is a sanitized network trace of the v3 login flow: the full /iam/pub/3/auth/pre-insp response body, the /iam/pub/3/auth/login request body, and the relevant request headers with secrets masked.
• Ensure your Home Assistant instance has internet access to reach the Hoymiles Cloud API

Auth test script

You can test live authentication outside Home Assistant without saving credentials in the repository:

python3 scripts/test_login_flow.py --username "you@example.com" --try-matrix

Target a single profile:

python3 scripts/test_login_flow.py --username "you@example.com" --auth-mode home_v3

Override the app version for installer/home testing:

python3 scripts/test_login_flow.py --username "you@example.com" --auth-mode installer_v3 --app-version 3.7.1

Support

For bugs or feature requests, please open an issue on GitHub.

Disclaimer

This integration is not affiliated with, endorsed by, or connected to Hoymiles Power Electronics Inc. This is a third-party integration developed for personal use.