Skip to content

Installation Guide

Jump to bottom
Veldkornet edited this page Oct 15, 2026 · 5 revisions

Installation Guide

There are two ways to install the HYXI integration. HACS is recommended — it handles updates and dependencies automatically.

Method 1: HACS (Recommended)

HYXI is in the default HACS store, so no custom-repository step is needed.

  1. Open HACS in Home Assistant and search for HYXI.
  2. Click Download.
  3. Restart Home Assistant.
Can't find it in HACS?

If HYXI doesn't appear in search (e.g. an older HACS version), add it as a custom repository first:

  1. In HACS, open the ⋮ menu → Custom repositories.
  2. Repository https://github.com/Veldkornet/ha-hyxi-cloud, category Integration → Add.
  3. Search for and download HYXI as above.

Trying upcoming features (beta channel)

New features are sometimes in pre-releases (vX.Y.Z-beta.N) before they reach stable:

  1. In HACS, open HYXI → the ⋮ menu → Redownload.
  2. Under Need a different version?, pick a -beta version.
  3. Restart Home Assistant.

Beta releases get the same testing as any other release, but haven't accumulated real-world usage yet — stick to stable if you'd rather wait for that.

Method 2: Manual Installation

  1. Download the latest Release.
  2. Extract the custom_components/hyxi_cloud/ folder from the zip file.
  3. Using SFTP or Samba, copy that folder into your Home Assistant /config/custom_components/ directory.
  4. Your structure should look like this: /config/custom_components/hyxi_cloud/__init__.py
  5. Restart Home Assistant.

Configuration

Once installed and restarted, go to Settings > Devices & Services > Add Integration and search for HYXI. Setup opens with a choice of transport:

Transport Needs Best for
HYXI Cloud (default) An Open API Access Key + Secret Key Most users — multi-device discovery, real-time push, remote access
Local Modbus (RS485) A wired RS485 connection (USB adapter or TCP gateway) to one inverter No account/internet dependency, faster polling — see Local Modbus RS485 for its own setup steps

The rest of this page covers the HYXI Cloud path.

Getting your Access Key and Secret Key

Important: This integration does NOT use your HYXi mobile app email/password to log in.
It authenticates with Open API credentials instead.
  1. Log in to the HYXIPower Developer Platform using the same email address your devices are registered to in the HYXi app.
  2. Create an Application to generate an Access Key (AK) and Secret Key (SK).

These are User Authorization keys, which is what the integration needs. Keys with VPP or Plant Authorization are refused at setup with a message saying so (see Troubleshooting).

Adding the integration

  1. Go to Settings > Devices & Services.
  2. Click Add Integration in the bottom right and search for HYXI.
  3. Leave the transport as HYXI Cloud (online account).
  4. Enter:
    • Access Key
    • Secret Key
    • Region — Europe, North America, or China, matching where your HYXi account is registered.
    • Enable Real-Time Webhook Push — optional, off by default; see Real-Time Push. If on, the next screen asks for an optional custom callback URL.
  5. Click Submit.

The integration will automatically discover your inverter and all associated sensors. See Supported Devices for what to expect per device type, and Available Sensors for the entities it creates.

Optional features

Click Configure on the HYXI integration card at any time:

Option What it does
Polling Interval Data refresh rate, 1–60 minutes (default 5).
Enable Discovery via Alarms Proactively discover child devices that are reporting active alarms (advanced).
Enable Device Control & Protection Reveal the control entities. On a cloud entry that's the micro-inverter controls only; battery controls (mode buttons, power numbers, battery-protection thresholds) need a Local Modbus RS485 entry. Off by default to avoid conflicts with an external controller or grid schedule. See Device Control.
Enable Real-Time Webhook Push Register webhooks and subscribe to HYXI Cloud push notifications for instant updates (cloud entries). See Real-Time Push.
Enable Energy Manager Standalone (Beta) The automated battery-management engine, on a Local Modbus entry. Only visible once Device Control & Protection is on. See Local Energy Manager.

Clone this wiki locally