> 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/victron.md).

# Victron

Our EMS supports battery systems from Victron.

Victron develops compact and modular energy storage solutions for residential and small commercial applications.

### Supported devices

We support all Victron battery/hybrid inverters that expose themselves through the VE.Bus service of a Venus OS GX device (Cerbo GX, CCGX, Venus GX, MultiPlus-II GX, …):

* **Victron MultiPlus**: compact solution for efficient energy storage and daily battery cycling
* **Victron MultiPlus-II**: enhanced hybrid inverter/charger for advanced energy management
* **Victron Quattro**: flexible dual-input power solution for off-grid and backup systems
* **Victron Quattro-II**: next-generation dual-input inverter/charger for demanding energy setups
* **Victron EasySolar-II**: all-in-one inverter/charger with built-in MPPT solar charger

## System topology

The integration communicates over **Modbus TCP with the GX device**, not with the inverters directly. The GX device exposes every connected Victron component as a separate Modbus unit ID:

| Component                                 | Modbus unit ID                                               |
| ----------------------------------------- | ------------------------------------------------------------ |
| System / settings service                 | `100` (fixed)                                                |
| VE.Bus inverter/charger                   | The VE.Bus service unit ID (e.g. `227`, `229`, …)            |
| GX managed battery (BMS)                  | `225`                                                        |
| DC-coupled MPPT solar chargers            | Device instance (VE.Can: `1`+, VE.Direct ports: `223`–`247`) |
| AC-coupled PV inverters (Fronius, ABB, …) | `20`–`29`                                                    |
| Victron grid meters                       | `30`–`34`                                                    |

Check the unit IDs on the GX device under **Settings → Integrations → Modbus TCP server → Available services**. The EMS scans these ranges when the device is added and creates the child devices (BMS, MPPT solar chargers, PV inverters, grid meter) automatically.

The EMS models the system as one parent **PCS** device (the VE.Bus inverter/charger) with child devices:

* **PCS (battery inverter)** — receives the charge/discharge setpoints and reports battery power, voltage, current and the VE.Bus state.
* **BMS (GX managed battery)** — reports state of charge, allowed charge/discharge power and battery health from the battery that is managed by the GX (DVCC).
* **PV (DC-coupled MPPT solar chargers)** — one child device per MPPT, reporting PV power and yield.
* **PV (AC-coupled PV inverters)** — PV inverters that the GX monitors on AC-in or AC-out.
* **Grid meter** — a Victron energy meter configured as grid meter, when present.

## Control approach

### External control with setpoint compensation

The EMS puts the Victron ESS in **external control** (ESS mode 3) and writes per-phase AC power setpoints to the VE.Bus service each control cycle (≈1 s).

An important Victron particularity: the ESS power setpoint steers the power at the **AC input** of the inverter, not the battery power. Two other flows move the battery besides the setpoint:

* **Loads on AC-out** are supplied by the inverter on top of the setpoint. Without correction, a battery setpoint of 0 kW would still discharge the battery into the AC-out loads.
* **DC-coupled MPPT solar chargers** (and other DC sources/loads) charge the battery directly. Without correction, morning PV would charge the battery even when the EMS asks for 0 kW.

The EMS therefore continuously measures the inverter's AC output power (net loads on AC-out, including any AC-coupled PV on the output), the DC-coupled PV power, DC charger power and DC system power on the GX, and compensates the written setpoint so the **battery** ends up at the requested charge/discharge power:

```
AC setpoint = requested battery power
            + AC output power (net AC-out loads)
            − DC-coupled PV − DC charger power
            + DC system power
```

The setpoint is split over the phases that actually exist (the phase count is read from the VE.Bus system), so single-phase and three-phase systems both receive the full requested power.

Battery power follows the EMS convention: **positive = charge, negative = discharge**.

### Self-consumption mode

When a **Victron grid meter** is connected to the GX and the EMS control mode allows it, the EMS can hand local balancing over to Victron's own ESS self-consumption logic (ESS mode 1) instead of writing explicit setpoints. Without a Victron grid meter the inverter cannot measure grid power itself, so the EMS always drives explicit setpoints.

### DC-coupled PV and inverter capacity

DC-coupled MPPT solar chargers feed the same DC bus as the battery, so any solar power the EMS does not want stored has to leave through the inverter's AC connection. The battery therefore follows the EMS setpoint accurately only as long as the inverter can physically deliver it.

When the DC-coupled PV exceeds what the inverter can push out on AC (bounded by its rated AC power, and reduced further by any load it is already serving on AC-out), the surplus cannot leave through AC and charges the battery instead. In that situation the EMS cannot hold the battery at zero or discharge it while that much sun is present, and once the battery is full the MPPTs curtail themselves. For full EMS control of the battery under peak sun, size the inverter's AC rating at or above the DC-coupled PV peak.

### PV curtailment

* **DC-coupled MPPT solar chargers** can be switched fully on or off, but Victron MPPTs expose no variable power limit over Modbus, so partial curtailment is not possible. A DC-coupled PV surplus is instead absorbed by the battery, or curtailed by the MPPTs themselves once the battery is full.
* **AC-coupled PV inverters** are steered through their own PV-inverter integration, not through the Victron GX. Leave them in unmanaged mode when the EMS should only monitor them.

## What is read back

| Quantity                              | Source                                                        |
| ------------------------------------- | ------------------------------------------------------------- |
| **Battery power / voltage / current** | GX system service (battery as managed by DVCC)                |
| **State of charge**                   | GX system service / GX managed battery                        |
| **DC-coupled PV power**               | GX system service + per-MPPT solar charger services           |
| **AC output power (AC-out loads)**    | VE.Bus service                                                |
| **VE.Bus state / errors / alarms**    | VE.Bus service (bulk, absorption, float, external control, …) |
| **Grid frequency**                    | VE.Bus AC input                                               |

Energy counters on the VE.Bus service are volatile (they reset when the GX or the inverter restarts), so the EMS accumulates energy from the power measurements instead.

## Configure Victron within our EMS

{% stepper %}
{% step %}

### Enable Modbus TCP

On the GX device, open **Settings → Integrations → Modbus TCP server** and enable it. Note the unit IDs listed under **Available services**.
{% endstep %}

{% step %}

### Configure ESS

Install the ESS assistant on the inverter and configure ESS on the GX device. The EMS controls the ESS mode itself; no specific ESS mode needs to be pre-selected.
{% endstep %}

{% step %}

### Disable scheduled charging

Disable scheduled charging before connecting the device to the EMS, so the GX does not overrule the EMS setpoints.
{% endstep %}

{% step %}

### Add the device in the platform

Add the Victron PCS with the GX IP address and the **VE.Bus unit ID** as slave ID. The EMS discovers the battery, MPPT solar chargers, PV inverters and grid meter automatically.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
If these steps are not followed the system will not work!!
{% endhint %}

<figure><img src="/files/G1NRvgzJMtCsrVdawhXi" alt=""><figcaption></figcaption></figure>


---

# 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/victron.md?ask=<question>&goal=<endgoal>
```

`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.