Repository navigation
Troubleshooting
The integration ships a small set of sensors specifically for telling local hardware problems apart from cloud problems:
| Sensor | What it tells you |
|---|---|
| Cloud Status (binary) | Whether Home Assistant can reach HYXI Cloud. Carries Connection Quality and Data Freshness as attributes. |
| Device Alarm (binary) |
On when the hardware itself is reporting active alarms. |
| Data Collected Time / Last Cloud Sync / Integration Last Updated | The three "hops" the data travels — inverter → cloud → Home Assistant. Compare them to locate a delay. See Understanding Data Timestamps below. |
Important: This integration does NOT use your mobile app email and password. It requires Open API Credentials (Access Key and Secret Key).
- Log in to the HYXiPOWER Developer Platform.
- Create an "Application" to generate your Access Key (AK) and Secret Key (SK).
- If you get an "Invalid Auth" error, ensure your application status is "Approved" in the HYXi portal.
If HYXI later rejects the keys (for example after you regenerate them), Home Assistant shows a reauthentication prompt for the entry; enter the new keys there.
HYXI issues keys with different kinds of authorization. The integration needs User Authorization keys, which are what you get when you create an application under your own developer account. VPP Authorization keys can't read your devices' data, so setup and reauthentication refuse them (and Plant Authorization keys) with this message, and an existing entry whose keys turn out to be of either kind asks for new keys.
The HYXi Cloud API typically updates every 5–10 minutes. If the app shows new data but Home Assistant doesn't, wait at least 15 minutes before assuming there is an error.
Attach both to a bug report:
- Debug logs — Settings → Devices & Services → HYXI → ⋮ → Enable debug logging, wait 5–10 minutes, then Disable debug logging to download the file. Serial numbers, plant IDs and your address are masked automatically.
- Diagnostics — Settings → Devices & Services → HYXI → ⋮ → Download diagnostics. They hold the entry's settings, connection and push status, subscriptions and the latest device data, with API keys, addresses, callback URLs, subscription codes and device names removed and serial numbers replaced by placeholders.
Only relevant if you set up the Local Modbus transport instead of the cloud — see Local Modbus RS485.
- Wrong device type, or sensors stuck at zero. The family (HALO vs Hybrid) was mis-detected, so the wrong register map is in use. Local Modbus Troubleshooting walks through a read-only script that shows what the device returns at the detection registers and why the guess went the way it did.
-
Setup can't detect my inverter family. Double-check wiring and serial settings (115200bps, no parity, 8 data bits, 1 stop bit) and, for a TCP gateway, that it's actually forwarding raw RTU frames or speaking Modbus-TCP — not filtering or repackaging them.
docs/modbus-provenance.mdin the repo has per-model pinouts. Local Modbus Troubleshooting has the full checklist. - Connection Type sensor says the wrong transport, or is missing. It reflects how that config entry was set up; if you need to switch a Cloud entry to Modbus (or vice versa) it currently needs to be removed and re-added rather than reconfigured in place.
Only relevant if you enabled Real-Time Telemetry & Alarm Push in Configure.
The integration cancels leftover subscriptions for the same devices by itself before subscribing (see Real-Time Push). If registration still fails with error B004002 ("device serial number has been subscribed to repeatedly"), the blocking subscription was most likely made with other API keys, which this entry can't cancel:
- Open the entry's Real-Time Subscription Status sensor and check its
subscriptionsattribute: it lists every subscription HYXI holds for this entry's keys. - Go to Developer Tools > Actions (or Services on older Home Assistant).
- Call HYXI: Cancel Subscription (
hyxi_cloud.cancel_subscription) with the subscription code. The action is admin-only; with several HYXI Cloud entries, choose the Entry whose keys made the subscription if the integration can't tell. A subscription made with keys you no longer use has to be cancelled with those keys.
Only relevant if you enabled the Local Energy Manager.
Check the EM Status sensor first — it tells you why nothing is happening before you dig further:
| Status | Meaning |
|---|---|
disabled |
The Energy Manager switch is off, or Device Control & Protection isn't enabled |
stale |
Paused: the inverter's data is older than four poll intervals (at least two minutes). A repair issue explains it; both clear themselves once fresh data arrives |
stopped |
Master switch is off |
cooldown |
Working as intended — waiting out a mode-switch or power-adjust cooldown period |
dry_run |
Dry-Run Mode is on — decisions are logged and events fire, but no commands are sent to the inverter |
error |
Something failed — check the logs |
running |
Normal operation — check EM Decision for which priority is currently active |
This integration provides three distinct timestamp sensors. Because solar data travels through multiple stages (Inverter → Logger → Cloud → Home Assistant), these sensors help you identify exactly where a delay or connection break is occurring.
| Sensor Name | Technical Key | Description | What it monitors |
|---|---|---|---|
| Data Collected Time | collectTime |
The actual moment the Inverter measured the solar/battery metrics. | The Hardware: Tells you if the Inverter is active and communicating with its logger. |
| Last Cloud Sync | last_seen |
The moment the HYXi Cloud servers received the data packet from your home. | The WiFi/Internet: Tells you if your Data Logger stick has a stable connection to the internet. |
| Integration Last Updated | integration_last_updated |
The moment Home Assistant successfully fetched data from the HYXi API. | The API Bridge: Tells you if your API keys are working and if the HYXi Cloud service is reachable. |
If your data feels "frozen" or "stale," compare these three sensors:
- Symptoms: All three sensors show a time from several hours ago.
- Likely Cause: The HYXi Cloud API is down, or your Access Keys have expired.
- Fix: If HYXI rejected your keys, Home Assistant shows a reauthentication prompt for the entry; enter new keys there. Otherwise HYXI's cloud is likely down: the integration keeps showing the last known values and catches up once it's back.
- Symptoms: Integration Last Updated says "Just now," but the others are old.
- Likely Cause: Home Assistant is talking to the cloud fine, but the cloud hasn't heard from your home.
- Fix: Check your Data Logger (WiFi/Ethernet stick). Ensure your home internet is working and the stick has a green "Link" LED.
- Symptoms: The cloud is receiving packets, but the data inside them is old.
- Likely Cause: Communication break between the Inverter and the Logger.
- Fix: Check the RS485/USB connection between the stick and the inverter. Note: Data may also pause if the inverter is in "Deep Sleep" at night.
Add these three sensors to a History Graph card. In a healthy system, all three lines should track closely together. This allows you to spot "latency" at a glance!