Skip to content

Device Control

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

🔧 Device Control

The integration can write control commands to compatible devices — operating-mode buttons, charge/discharge power targets, battery-protection thresholds, and micro-inverter controls. The automated Local Energy Manager and the hyxi_cloud.set_battery_mode action are built on top of these controls.

Battery control needs a Local Modbus RS485 connection. HYXI confirmed that battery commands sent with your own (User Authorization) API keys are not forwarded to the inverter; HYXI only forwards them for authorized VPP providers. So a cloud entry offers no battery controls, battery protection or Energy Manager (if you had them on, a repair notice explains the change and the options are switched off). Over the cloud, only the micro inverter controls below work.

Controls are opt-in. To stop Home Assistant fighting an external device manager or a grid-curtailment schedule, every control entity (mode buttons, power numbers, switches) is hidden until you turn it on:

  1. Settings → Devices & Services → HYXI → Configure.
  2. Tick Enable Device Control & Protection and save.
  3. The integration reloads and the control entities appear.

Controls are scoped per device type — each device only gets the controls it actually supports.

Hybrid Inverter / All-in-One (cloud API reference)

Not offered on cloud entries, since HYXI doesn't forward these commands for owners' API keys (see above). Kept for reference: should HYXI open them up, this is how they map.

The HYXI API defines these controls by phase type (Single-Phase / Three-Phase), and the integration detects the phase type to pick the matching set:

Phase Controls controlId
Three-Phase Operating Mode buttons — Idle / Charge / Discharge / Self-Consumption 1062–1065
Three-Phase Target Charge / Discharge Power —
Single-Phase Peak Shaving buttons — Turn Off / Force Charge / Force Discharge / Stop / Hold 1021
Single-Phase Frequency Control — Enable / Disable 1020

Phase detection

Determined in priority order:

  1. Model-name suffix — -HT / -HTA / -ET → Three-Phase; -HS / -LS → Single-Phase.
  2. Runtime metrics — phase-power keys (ph2Loadp / ph3Loadp / ph2p / ph3p) or a non-zero phase 2/3 voltage (ph2v / ph3v) → Three-Phase.

If the phase type can't be determined from either the model name or runtime metrics, no control entities are created — a safety measure to avoid sending unsupported commands. If you think your device should have controls, open a GitHub issue with the model number.

Micro Inverter

Control controlId
Power On / Off 3011
Power Limit (0–100 %) 3012
Restart 3013

Micro ESS (HALO) — unsupported controls

Operating Mode / Peak Shaving / Frequency Control (controlIds 1020, 1021, 1062–1065): not supported. These describe PV–battery interplay (e.g. "PV charges the battery first, shortfall from grid") that assumes the controlled device has its own PV input. AC-coupled Micro ESS units like the HYX-MS3000AC have only AC in/out and battery terminals — no PV/DC input — so these controls don't apply, regardless of device type.

Power On/Off (controlId 1011): implemented in code but currently disabled. It's the one Energy Storage Control instruction with no PV dependency, so it's architecturally applicable to AC-coupled units — but community testing against a live HYX-MS3000AC found HYXI's API rejects the write with B003026 ("The current application does not have permission to call this API"), and the HYXI developer portal has no way to request that access (it only issues an AccessKey/SecretKey pair). This is a platform-side restriction. The switch entity is fully built and tested but gated off by MICRO_ESS_CONTROL_SUPPORTED = False; it will be re-enabled if HYXI grants control-API access for this device type.

Over Local Modbus RS485, that cloud restriction doesn't apply — see the next section.

Local Modbus (RS485)

The cloud phase-type rules above don't apply to a Local Modbus RS485 entry — the register maps expose one control surface for both families, regardless of phase count. With Device Control & Protection enabled you get:

Control HALO Hybrid Register
Operating Mode buttons — Idle / Charge / Discharge / Self-Consume ✅ ✅ VPP block 4146–4152 (HALO) · scheduling block 3000–3015 (Hybrid)
Target Charge / Discharge Power (number) ✅ ✅ —
Battery Dispatch Control (switch) ✅ ✅ vpp_enable 4146 (HALO) · scheduling_enabled 3000 (Hybrid)
Power On / Off / Restart buttons — ✅ power_command 3002
Anti-Starvation Protection (switch), SOC / feed-in setpoints (numbers) ✅ ✅ settings block
Refresh Settings button ✅ ✅ — (forces an immediate re-read of the settings block)

Battery Dispatch Control is the "is the integration driving the battery at all" toggle. Every Idle / Charge / Discharge command turns it on; switching it off hands the battery back to the inverter's own configured work mode. It's also released automatically when the entry stops managing the device — you disable Device Control, delete the entry, or it reloads — but not on a Home Assistant shutdown/restart, so the battery keeps doing whatever it was last told across a reboot.

On the Hybrid there's no "self-consume" setpoint in the scheduling block (and the operating-mode register is read-only), so the Self-Consume button there also clears scheduling_enabled — it lands in the same state as turning the switch off, because that's the only way to reach the inverter's native self-use behaviour. On the HALO, Self-Consume is VPP mode 3 and dispatch stays on.

Peak shaving and frequency control aren't available locally — neither register map has a confirmed equivalent.

Battery protection

On a Local Modbus entry, enabling Device Control & Protection also exposes the SOC minimum/maximum protection number entities. These are always respected by the Local Energy Manager — it manages within those limits, never past them.

The hyxi_cloud.set_battery_mode action

For scripts and automations, the hyxi_cloud.set_battery_mode action sends one operating-mode command to a targeted inverter in a single call:

action: hyxi_cloud.set_battery_mode
target:
  device_id: <your inverter>
data:
  mode: charge        # idle | charge | discharge | self_consume
  power: 2500         # W — charge/discharge only; omit to use the Charge/Discharge Power number
  # force: true       # send even while the Energy Manager is running (see below)
  • Needs Device Control & Protection enabled for that entry.
  • Refused while the Energy Manager is actively managing the targeted inverter — the engine would just override it on its next tick — unless you pass force: true.
  • Honours the same SOC-min/SOC-max protection as the mode buttons.
  • power falls back to the inverter's Charge/Discharge Power number entity, then 100 W, when omitted.
  • Works on any control-capable device, cloud or Modbus (three-phase / all-in-one, and a HALO over Modbus).

The mode buttons are the same operation for a single inverter; the action adds the target picker, the one-call power, and the Energy-Manager guard.

See also

  • Local Energy Manager — the automated engine that drives these controls from your P1 meter, solar, SOC, and forecast.
  • Available Sensors — the read-only sensors, separate from these control entities.
  • Troubleshooting — if a control echoes back instead of taking effect.

Clone this wiki locally