Quick Summary (TL;DR)
For Home Assistant 2026.5 or newer, start with the built-in Victron GX integration. It connects directly to a GX device running Venus OS over the local network using MQTT, automatically discovers supported equipment, and exposes battery, solar, grid, inverter and other entities. It is usually the simplest path for a Cerbo GX, Venus GX or compatible Venus OS gateway. Use this before building a collection of hand-maintained sensors.
Use hand-configured MQTT only for niche D-Bus paths, custom transformations, or integration work the built-in connector does not cover. Victron MQTT topic names include the VRM portal ID and a device instance; the modern broker does not retain all values, so discovery and refresh behaviour matter. Use Modbus TCP when you need a deliberately small, documented set of registers for Home Assistant or for a PLC/industrial controller, and can manage unit IDs, data types and scaling.
Monitoring and controlling an energy system are different risk classes. Begin with read-only sensors. Switching inverter modes, battery charge limits or ESS setpoints should be considered only if the hardware, firmware, safety design and Victron configuration explicitly support them. Home Assistant automations are not a substitute for battery-management, grid-protection or inverter interlocks.
The three practical integration routes
| Route | Data source and configuration | Best fit | Principal limitation |
|---|---|---|---|
| Built-in Victron GX integration | Home Assistant connects to the GX device MQTT service; device/entity discovery through the UI | Most current Home Assistant installations | Entities are rate-limited to updates no more frequently than every 30 seconds; exact controls depend on installed equipment |
| Manual MQTT | Subscribe to Victron N/… topics, request values via R/… and transform JSON payloads into sensors | Advanced users needing a D-Bus value not exposed by the built-in integration | Topic discovery, keep-alives, device instances and unavailable values must be managed |
| Modbus TCP | Home Assistant or another client polls documented Victron registers from the GX gateway | Fixed telemetry points, PLC integration, predictable register mapping | Requires correct unit ID, address, register version, signedness, scaling and polling management |
| VRM cloud or API | Victron cloud service rather than a local GX protocol | Off-site analytics and historical reports when internet is available | Cloud and internet dependencies; not equivalent to local push telemetry |
All three local methods require a GX gateway or a supported installation running Venus OS. A MultiPlus, SmartSolar MPPT or SmartShunt on its own is not automatically an MQTT or Modbus TCP server. It must be presented to the GX system using a compatible communication interface. See our Cerbo GX versus Raspberry Pi Venus OS gateway comparison for the hardware choice.
What data is actually available?
The GX aggregates measurements from its connected Victron ecosystem. A correctly commissioned ESS may expose whole-system power flows; a battery monitor can contribute state of charge; a PV charge controller provides solar charging power; a supported energy meterAliExpress price can report grid exchange. If the physical meter is missing or a particular device has not been assigned the correct system role, the integration cannot invent that missing measurement.
| Metric | Where it may originate | How to treat it in Home Assistant |
|---|---|---|
| Battery state of charge (%) | BMS, SmartShunt, BMV or inverter/charger calculation | A state measurement, not an energy consumption counter |
| Battery voltage, current and power | Battery monitor, BMS or GX system aggregation | Instantaneous electrical telemetry; verify sign convention |
| PV charging power (W) | Victron MPPT / solar charger | DC production; not always equal to AC solar inverter output |
| AC PV inverter power (W) | Supported grid-tied PV inverter or dedicated meter | AC-side generation; may coexist with DC MPPT generation |
| Grid import/export power (W) | Grid meter and system aggregate | Signed instantaneous grid power; check direction under known load |
| Cumulative import/export energy (kWh) | Meters or suitable lifetime counters | Prefer these for Energy Dashboard; verify reset, sign and unit |
| ESS target, charge limit, mode | Supported Venus OS control interfaces | Control entities may change operating behaviour; limit automation permissions |
A common setup error is to mix DC PV charging, AC PV generation, battery discharge and grid import as though all were independent energy supplies. For example, battery discharge is an internal energy flow; adding it to grid import without considering the home boundary can double-count consumption. Draw a one-line diagram before mapping entities to the Energy Dashboard.
Option 1: the built-in Victron GX integration — recommended first
Home Assistant introduced its Victron GX integration in release 2026.5. The official integration documentation describes a local MQTT push integration with automatic discovery of supported Victron components. The current documentation states that entities update when new values arrive, but not more frequently than every 30 seconds. For dashboard and energy history work this is often acceptable, although it is not appropriate to assume sub-second control-loop behaviour.
- Check Home Assistant version: the native Victron GX integration is available from 2026.5; earlier installations may need an upgrade or an alternative.
- Confirm the GX system: check that the Cerbo GX or Venus OS gateway has discovered the inverter, battery, MPPT and energy meterAliExpress price, with sensible measurements shown locally.
- Enable local access on the GX: in newer menus open Settings → Integrations → MQTT Access. Older Venus OS releases may label it under Services; refer to the manual for the installed version.
- Check network security: record the GX IP or hostname and its local-network security profile. The integration distinguishes unsecured and secured MQTT connections.
- Add the integration: in Home Assistant open Settings → Devices & services → Add integration → Victron GX, or accept its discovery prompt, then follow the credentials and connection options.
- Audit the entities: compare battery SOC, PV power, grid power and inverter mode with the GX local console, including a known-load test.
- Enable only useful entities: select cumulative kWh sensors for the Energy Dashboard where available; exclude noisy diagnostics from long-term Recorder storage if they add no value.
According to the Home Assistant documentation, the standard connection may use MQTT port 1883 for an unsecured local connection or 8883 for a secured connection; whether credentials and SSL are needed depends on the GX Local Network Security Profile. These settings are not interchangeable. Do not open either port on the public internet.
Does the official integration provide control as well as monitoring?
Yes, on supported configurations. Besides read-only sensors, the published integration offers some number, select, switch, time and button entities. Examples listed by Home Assistant include selected ESS setpoints, minimum SOC settings, inverter modes, EV charger settings and supported relays. The list of visible controls is conditional on the underlying devices and firmware; absence of a control does not prove the integration is broken.
Use a separate risk policy for writing. A grid setpoint or minimum-SOC update can affect electricity import/export or energy availability. A setting that is technically writable is not automatically suitable for a Home Assistant automation. Before allowing changes, verify Victron documentation, warranty and installer constraints, the role of ESS/DESS and BMS protections, what happens after Home Assistant goes offline, and whether the automation could compete with another controller.
| Control example | Why it needs care | Safer first step |
|---|---|---|
| ESS grid setpoint | Influences import/export target; grid and system constraints still apply | Monitor power and compare expected versus measured flow before enabling writes |
| Minimum battery SOC | Changes available storage reserve and may alter overnight backup margin | Document reserve policy and review with installer |
| Inverter operating mode | Can affect power delivery or charging availability | Avoid automatic mode switching until fail-safe behaviour is understood |
| EV charging current/mode | Touches a high-power appliance with its own interlocks and limits | Observe native EVSE state and use supported control paths only |
| Generator relay or start logic | May start machinery with physical safety implications | Preserve hardwired protections and manufacturer-specific start logic |
Option 2: raw local MQTT for custom sensors
Victron publishes the GX D-Bus state into MQTT through its local broker. The data topic convention is N/<portal-id>/<service>/<device-instance>/<dbus-path>. Typical JSON payloads look like {"value": 52.8}. A device-instance number is not necessarily the same as a Modbus unit ID. Never copy a sample device instance from somebody else’s system and assume it identifies your battery.
In the modern dbus-flashmq implementation, values are not generally retained in the broker. If you subscribe to a topic and see nothing, send an MQTT read request to R/<portal-id>/keepalive to prompt publication. The keep-alive period described by Victron is 60 seconds; repeated refreshes can use its suppress-republish option, but a complete first publication is valuable when discovering devices. These are implementation details of the manual approach, not steps required to configure Home Assistant’s built-in integration.
# Illustrative diagnostics on a trusted LAN with mosquitto-clients installed.
# Replace the values; check your GX security profile first.
mosquitto_sub -h 192.168.1.50 -t 'N/YOUR_PORTAL_ID/#' -v
# In a separate terminal:
mosquitto_pub -h 192.168.1.50 -t 'R/YOUR_PORTAL_ID/keepalive' -m ''
These commands apply only to an MQTT broker that accepts the chosen connection. On secured installations, configure the correct TLS certificate and credentials rather than disabling security. The portal ID is an identifier used in the MQTT namespace, not your Home Assistant user name. Topic payloads may contain a JSON null value for an unavailable measurement; an empty payload can indicate that the corresponding D-Bus device disappeared.
Manual MQTT-to-Home Assistant sensor example
If you already use the Home Assistant MQTT integration and need one specific Victron value, a manual sensor can subscribe to a confirmed topic. The example below is deliberately an illustration; replace the portal ID, instance and path after discovering them on your GX. This does not configure a standalone Mosquitto add-on to bridge the GX broker; Home Assistant must actually be connected to the appropriate broker, or you must provide a reliable MQTT bridge. Do not configure multiple unrelated broker connections with the same assumptions.
# Illustration only — requires an MQTT integration connected to the GX broker
# and a real discovered MQTT topic. Do not use the literal portal ID below.
mqtt:
sensor:
- name: "Victron DC battery voltage (example)"
unique_id: victron_example_dc_battery_voltage
state_topic: "N/YOUR_PORTAL_ID/system/0/Dc/Battery/Voltage"
value_template: >-
{% if value_json.value is defined and value_json.value is not none %}
{{ value_json.value }}
{% else %}
{{ none }}
{% endif %}
unit_of_measurement: "V"
device_class: voltage
state_class: measurement
The exact D-Bus path, device instance and meaning must be checked before deployment. It is easy to display a plausible but different voltage (for example inverter DC bus voltage versus battery terminal voltage). In a production system, also design reconnection handling, sensor availability, keep-alive management and data-quality checks. If the native integration already exposes a suitable entity, creating the same sensor again simply adds maintenance and duplication.
Option 3: Modbus TCP for precise register selection
Modbus TCP exposes GX and connected-device values through a conventional request/response protocol. It is particularly useful when a PLC, building-management system or specialised Home Assistant template expects a fixed documented register. Enable the server on the GX under Settings → Integrations → Modbus TCP Server on current firmware; check Access permissions and prefer read-only when you only need telemetry. Older firmware may show different menu labels.
The device normally listens on TCP port 502. Each request specifies a unit ID to select the system service or connected equipment, and a register address for the data point. Victron’s GX manual advises using unit ID 100 for com.victronenergy.system, rather than unit ID 0, because some Modbus clients do not support zero. Other devices have their own unit IDs: look them up under Available services on the GX and in the current official register list.
| Modbus term | Victron-specific meaning | Common error |
|---|---|---|
| GX host/IP | Device running Venus OS and Modbus TCP server | Connecting to the inverter IP rather than the GX gateway |
| TCP port | Normally 502 for Modbus TCP | Confusing Modbus RTU serial connections with Modbus TCP |
| Unit ID | System 100 or a discovered connected-device ID | Using another user’s MPPT instance number as a unit ID |
| Register address | Documented register within selected service | One-based register notation or wrong zero-based client offset |
| Signedness/data width | Integer format defined in register list | Negative power appearing as a very large positive value |
| Scale factor | Register-list scaling for the actual firmware mapping | Treating 2302 as 2302 V instead of scaled 230.2 V |
| Polling frequency | How often Home Assistant reads data | Excessive polling or simultaneous clients overwhelming the gateway |
Do not publish a universal battery-power register number in a configuration guide without also specifying the required Venus OS mapping version, unit ID, datatype, scaling and definition of the value. Victron updates its register mapping, and a register valid for com.victronenergy.system may be invalid for a specific battery monitor. Use the currently linked Modbus register spreadsheet on Victron’s whitepapers/download pages, then verify the returned value against the GX interface.
Home Assistant Modbus YAML: connection skeleton
This is a connection pattern, not a working battery/solar sensor until you add a verified register. The official Home Assistant Modbus integration supports TCP clients and per-sensor configuration. Never guess an address, format or scale just to make a configuration parse successfully.
# Replace IP and add sensors only after consulting the current Victron register list.
modbus:
- name: victron_gx
type: tcp
host: 192.168.1.50
port: 502
# sensors:
# - name: "Verified system metric"
# slave: 100
# address: REGISTER_FROM_CURRENT_VICTRON_MAPPING
# input_type: holding
# data_type: int16 # Confirm actual type before enabling
# scale: 1 # Replace with documented conversion
The commented lines are intentionally not ready-to-deploy YAML. The correct data_type syntax can vary with your Home Assistant version; consult the live Home Assistant Modbus documentation. This avoids the common trap of copying an attractive example that silently reports a wrong physical quantity.
Local MQTT vs Modbus TCP: speed, accuracy and outages
| Decision factor | Victron GX native integration | Manual MQTT | Modbus TCP |
|---|---|---|---|
| Configuration labour | Low; UI setup and entity selection | High; topics, bridge, templates and liveness | Medium to high; mapping, registers, types and polling |
| Transport | Local MQTT push | Local MQTT push | LAN request/response polling |
| Entity update behaviour | Home Assistant documents no more than one update per 30 seconds | Depends on GX notifications and custom pipeline | Determined by poll interval and gateway response |
| Multi-device discovery | Automatic for supported devices | Requires subscriptions/discovery logic | Inspect GX available services and mapping |
| Controls | Exposes selected supported control entities | Possible at protocol level, not automatically safe | Writable registers exist; configure read-only for monitoring |
| Outage behaviour | No new HA values if LAN/GX/HA is down | Topic updates missed while disconnected unless application handles recovery | Polls stop during outage; resumes with current values |
| Long-term energy history | Requires HA Recorder and suitable energy counters | Requires correct kWh counter or verified integration | Prefer durable cumulative kWh register if supported |
The native integration’s 30-second entity limit matters if you want to plot fast transients, but it does not make its data intrinsically less accurate. Meter accuracy is determined by the measurement hardware and wiring. Conversely, polling a wrong Modbus register every second merely produces a precise stream of incorrect data. For dashboards, focus on meter placement, coherent sign conventions and reliable cumulative energy readings first.
Getting Victron measurements into the Energy Dashboard
Home Assistant’s Energy Dashboard expects compatible energy entities (typically kWh counters), not arbitrary instantaneous W sensors. Some Victron entities represent power, some energy today, some lifetime totals and others state of charge. Check each entity’s unit, device class and state class in Developer Tools. A daily-reset PV-yield counter is not automatically interchangeable with a lifetime total_increasing production counter; handling its midnight reset needs care.
- Grid: use actual grid import and export energy at the correct metering boundary; do not mix a net signed power sensor with separate per-phase totals without understanding the billing meter.
- Solar: map gross PV production measured at the correct AC/DC boundary; avoid counting MPPT DC yield and grid-tie AC PV yield twice.
- Battery: distinguish charge, discharge and state of charge. SOC (%) is not kWh and is not an energy counter.
- House load: cross-check the flow equation for your actual topology; meters downstream of the inverter may measure only critical loads rather than all house consumption.
- Statistics: monitor for unknown, unavailable, reset and unit-change events before trusting annual costs or payback calculations.
Worked example: why power-flow accounting matters
Assume a house has 3.0 kW of AC demand, 2.0 kW of solar supply and a battery discharging 0.5 kW. If all readings are simultaneous, on the same AC-equivalent boundary and losses are ignored, grid import is approximately 3.0 − 2.0 − 0.5 = 0.5 kW. Entering the battery’s 0.5 kW discharge as additional household consumption would inflate the graph. At a different instant, battery charging could make grid import exceed the actual house load.
This is an illustrative power balance, not a promise that every Victron ESS reports the same signs or that AC/DC conversion is lossless. For an AC-coupled installation, the flows must be measured on the relevant sides of inverter conversion. Validate against a known appliance and the utility meter, then compare an entire billing day rather than a single instantaneous reading.
Security: local does not mean automatically safe
Both MQTT and Modbus TCP normally live on the home LAN. Neither should be forwarded through a router to the public internet. On suitable Venus OS firmware, use the GX local security profile and TLS-capable MQTT access; use a trusted device VLAN or firewall policy and allow Home Assistant to reach only the required port. For Modbus TCP, prefer the GX Read only access-permission setting when available and block untrusted hosts from port 502.
Treat controls on Home Assistant dashboards as privileged, especially inverter operation, generator relays, charge limits and ESS dispatch settings. The monitoring interface should not circumvent the GX/ESS installation design. Remote access should use a properly secured VPN or an approved remote access solution rather than unauthenticated public port forwarding.
Troubleshooting when no entities appear
| Symptom | Likely explanation | Practical check |
|---|---|---|
| Victron GX cannot be discovered | mDNS/network segmentation, hostname or MQTT disabled | Add manually by LAN IP; verify GX MQTT Access and firewall |
| Authentication rejected | Security profile or password does not match | Check GX Local Network Security Profile, SSL and port pair |
| MQTT subscriber sees nothing | No keep-alive initial value publish; wrong portal ID or topic | Observe N/ topics and use read-request on correctly configured local broker |
| Entities exist but show unavailable | Underlying Victron D-Bus device offline or invalid value | Inspect GX device list and null payload handling |
| Modbus exception or zeros | Wrong unit ID/address, unavailable equipment, scaling | Check Available services and exact mapping spreadsheet |
| Power direction seems reversed | CT direction, grid sign convention or wrong service | Verify with known load and compare GX versus utility meter |
| Energy Dashboard rejects entity | Power sensor in W, missing state class or no cumulative kWh | Inspect entity attributes; use supported cumulative energy source |
| Sensor data stops during outage | Home Assistant, network or GX has stopped receiving | Review recovery, counter continuity and database history |
Should you use Node-RED, Signal K or the VRM API instead?
These are useful tools, but they answer different questions. Venus OS Large can run services such as Node-RED and Signal K for advanced on-device automation and marine-style data sharing. They are not required just to get battery and solar sensors into Home Assistant. A VRM API workflow is useful when you need data from an internet-connected remote installation, but it brings authentication, rate considerations and cloud availability into the design. If the goal is a locally maintained Home Assistant dashboard, use the native GX integration unless you have a documented reason not to.
Which integration should you choose?
| Your use case | Recommended starting point | Why |
|---|---|---|
| New Home Assistant installation, recent Venus OS | Built-in Victron GX integration | Discovery, maintained entity mapping and official documentation |
| Need only 3–10 signals for a PLC | Modbus TCP with read-only GX permissions | Deterministic register-selection interface |
| Need an unusual GX D-Bus metric | Manual MQTT with verified topic and liveness management | Access to topic paths not exposed by an existing entity |
| Older Home Assistant installation before 2026.5 | Upgrade where practical, otherwise maintain documented alternative | Native Victron GX integration did not exist in older releases |
| Need sub-30-second graphing of fast transient values | Specialised locally tested pipeline, not native HA GX entities | Native integration intentionally limits update frequency |
| Want to change ESS dispatch automatically | Design and audit control strategy with qualified installer | Interlocks, battery reserve, tariffs and multiple controllers can conflict |
My recommendation: set up the built-in Victron GX integration, keep the critical plant controls managed by the Victron system, and use Home Assistant first for visualisation, alerts and energy history. Reach for manual MQTT only when a needed value is missing; use Modbus TCP when another system genuinely benefits from register-based access. This approach gives readers a useful starting point without creating unnecessary infrastructure.
Frequently asked questions
Do I need Mosquitto on Home Assistant?
No, not merely to use the built-in Victron GX integration. It communicates with the GX device MQTT broker directly. A separately configured MQTT integration or broker/bridge becomes relevant when you are building your own manual MQTT sensor pipeline or joining several brokers.
Can I connect Home Assistant to a MultiPlus without Cerbo GX?
The integration is designed for a GX/Venus OS device that aggregates connected equipment. A MultiPlus without a compatible GX gateway does not become a Victron GX MQTT service just because it is on your network. A Raspberry Pi running the appropriate Venus OS image is an alternative GX gateway, but requires suitable Victron communication adapters.
Is Modbus TCP more accurate than MQTT?
Not by itself. Both often expose values ultimately originating from the same GX D-Bus services. Accuracy depends on actual sensors, measurement topology and conversion factors. Modbus introduces its own risk of wrong register/address/scale; MQTT introduces its own risk of wrong topic/instance or stale values.
Can I run both MQTT and Modbus TCP?
Yes, the GX may expose both services. Doing so does not automatically improve data quality; it often creates duplicated entities and slightly different update timing. Pick one authoritative sensor set for the Energy Dashboard, and reserve the second path for a specific PLC or diagnostic need.
What happens when the internet goes down?
Local communication between a powered GX and Home Assistant can continue on a functioning LAN. Cloud VRM functions depend on internet access. If the LAN or Home Assistant fails, its sensor history will have a gap unless a later valid cumulative meter reading or other data-reconciliation mechanism can restore totals; live power samples cannot be reconstructed perfectly.
Official sources and further reading
- Home Assistant: Victron GX integration (added in 2026.5; MQTT setup, controls and update behaviour)
- Victron Cerbo GX: Configuration, MQTT Access and Modbus TCP Server permissions
- Victron GX Modbus-TCP manual: unit IDs, registers and troubleshooting
- Victron technical whitepapers and Modbus register lists
- Victron dbus-flashmq: MQTT topic format and keep-alives
- Home Assistant Modbus integration and YAML syntax
- Home Assistant Energy Dashboard fundamentals