# Hoymiles

> Hoymiles HoyUltra 2 (HESS-261-2h) battery system integration within our EMS

Source: https://voltmasters.io/en/docs/device-integrations/battery-systems/hoymiles/

Our EMS supports the **Hoymiles HoyUltra 2** (`HESS-261-2h`), a liquid-cooled all-in-one commercial battery system of **261 kWh** with a **125 kW** power conversion system.

> **Note**
>
> Hoymiles **PV inverters** are supported separately through the generic [SunSpec](https://voltmasters.io/en/docs/device-integrations/pv-inverters/sunspec/) integration. This page covers the HoyUltra 2 battery system.

### Supported devices

| Model | Capacity | Rated power |
| --- | --- | --- |
| HoyUltra 2 (HESS-261-2h) | 261 kWh | 125 kW |

The integration communicates over **Modbus TCP** (default port `502`).

## How the integration works

One HoyUltra 2 cabinet is modelled as a parent battery inverter (PCS) with a battery management system as child device, both served by the same Modbus connection:

-   **PCS (battery inverter)**: the parent device. Receives the charge and discharge setpoints and reports the system active and reactive power.
-   **BMS**: reports the total state of charge and state of health, and the charge and discharge power the hardware currently allows.

The battery capacity is configured on the battery child device; the rated power is configured on the PCS and defaults to 125 kW.

### Master and member cabinets

Cabinets can be placed in parallel. Our EMS probes each cabinet on connection and recognises whether it is the **master** or a **member**:

-   The **master** carries the system-wide register map and receives all control commands. It reports the totals of the complete system.
-   A **member** cabinet exposes only its own PCS and battery rack, and is never sent a setpoint.

This happens automatically. You do not have to configure which cabinet is which.

### Control approach

We steer the system through the HoyUltra 2 telecommand interface. The cabinet is held in **remote control mode**, asserted continuously so it keeps following our setpoints, and every control cycle the requested commands are written again:

-   **Battery setpoint**: a direct charge and discharge power setpoint, clamped to the rated power and to the real-time maximum charge and discharge power reported by the device.
-   **Reactive power setpoint**: a separate reactive power command.
-   **System start and stop**.

> **Note**
>
> Setpoints below 6 kW make the Hoymiles user interface and its zero-export status look idle. Hoymiles R&D confirmed the cabinet still follows the setpoint, so our EMS does not round these away.

### What is read back

-   **Battery**: total state of charge and state of health, maximum charge and discharge power, maximum charge and discharge energy, total charged and discharged energy, and per-rack voltage, current, state of charge, temperature and allowed power.
-   **System**: operating mode (on-grid or off-grid), system status (standby, shutdown, charging or discharging), total active and reactive power, control mode and fault level.

The full fault map of the HoyUltra 2 is read out and translated into incidents on the device, each with its own severity so a level 1 alarm does not raise the same alert as a level 3 fault.

## Setup

1. **Prepare the network**
   
   Give the cabinet a fixed IP address in the same subnet as the Voltmasters controller, and make sure port `502` is reachable between the two. With several cabinets in parallel, every cabinet needs its own reachable address.
2. **Set the cabinet to remote control**
   
   The HoyUltra 2 only accepts setpoints in **remote control mode**. Our EMS asserts this mode itself on every control cycle, so no permanent setting on the device is required, but the local EMS interface of the cabinet must allow remote control.
3. **Add the device in Voltmasters**
   
   Add a new device of type **Battery system (PCS)**, brand **Hoymiles**, model **HoyUltra 2 (HESS-261-2h)**, and fill in the IP address, port and slave id of the cabinet.
   
   The battery management system is added automatically as a child device. Set the battery capacity and the minimum and maximum state of charge there; the capacity defaults to 261 kWh.
4. **Verify**
   
   Check on the device page that the state of charge and the system status come in, and that the cabinet follows a manual charge or discharge setpoint.

## Validation status

The integration is implemented against the **HoyUltra 2 Local EMS protocol REV1.3.2**. Additional functionality may be added over time as integration capabilities evolve.