> For the complete documentation index, see [llms.txt](https://docs.voltmasters.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voltmasters.io/device-integrations/battery-systems/hoymiles.md). # 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. {% hint style="info" %} Hoymiles **PV inverters** are supported separately through the generic [SunSpec](/device-integrations/pv-inverters/sunspec.md) integration. This page covers the HoyUltra 2 battery system. {% endhint %} ### 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**. {% hint style="info" %} 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. {% endhint %} ### 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 {% stepper %} {% step %} ### 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. {% endstep %} {% step %} ### 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. {% endstep %} {% step %} ### 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. {% endstep %} {% step %} ### 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. {% endstep %} {% endstepper %} ## 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.voltmasters.io/device-integrations/battery-systems/hoymiles.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.