Victron GX

The Victron GX Integration integration connects to Victron Energy GX devices using MQTT, providing real-time monitoring and control of your Victron system, including inverters, solar chargers, battery systems, grid meters, and EV chargers.

Supported devices

This integration supports Victron Energy devices that run Venus OS and have MQTT enabled, including:

• Cerbo GX
• Venus GX
• Color Control GX
• MultiPlus inverters
• Quattro inverters
• Solar charge controllers
• Battery monitors
• EV charging stations

Prerequisites

• A Victron Energy GX device running Venus OS with MQTT enabled.
• Network connectivity between your Home Assistant instance and the Victron device.
• For secured installations: The MQTT password configured on your Victron device.

Configuration

To add the Victron GX hub to your Home Assistant instance, use this My button:

Victron GX can be auto-discovered by Home Assistant. If an instance was found, it will be shown as Discovered. You can then set it up right away.

When setting up the integration manually, you need to provide connection details based on your Victron device’s security profile.

On the Victron device, go to Settings > General and check the Local Network Security Profile setting. This can be Unsecured, Weak, or Secured. If set to Weak or Secured, you must have specified a password when configuring this option.

Reauthentication

If your MQTT password changes or the security profile on your Victron device is updated, Home Assistant prompts you to re-authenticate:

1. Go to Settings > Devices & services and find the Victron GX integration. It will show a Re-authenticate message.
2. Select the Reconfigure button or the Re-authenticate prompt.
3. Enter your updated Password.
4. Select Submit.

On success, the integration reloads automatically.

Data updates

Entities are updated only when new values are received from the device, but no more frequently than every 30 seconds.

Supported functionality

The integration automatically discovers and creates entities for all supported Victron devices on your system. The exact entities available depend on your specific Victron hardware configuration.

Entities

The Victron GX integration provides the following types of entities:

Sensors

Read-only sensors for monitoring system metrics, such as:

• Battery voltage, current, power, temperature, and state of charge
• Solar panel voltage, current, power, and daily yield
• Grid voltage, current, power, and energy consumption
• Inverter input and output power, frequency, and state
• EV charger status, power, and session energy

Binary sensors

Status indicators for various system states, such as:

• Alarms and warnings
• Connection status
• Relay states

Numbers

Adjustable numeric settings for fine-tuning device parameters, such as:

• Battery charge current limits
• Grid setpoint for ESS
• Minimum state of charge limits
• EV charger current limits

Selects

Configurable options for controlling device behavior, such as:

• Inverter mode (on, off, charger only, inverter only)
• Solar charger mode
• Relay function configuration
• EV charger charge mode (auto, manual, or scheduled charge)
• ESS mode (optimized with or without phase compensation, or external control)
• DESS mode (auto/VRM, buy, sell, off, or Node-RED)
• ESS schedule charge slot days

Device trackers

GPS-equipped Victron devices (such as those with a built-in or connected GPS module) are exposed as device tracker entities, providing:

• Latitude and longitude
• Altitude, course, and speed (when available)

Switches

Toggle controls for enabling or disabling device functions, such as:

• EV charger start/stop
• Generator auto-start and manual start
• Generator quiet hours and conditional start triggers (SoC, temperature, voltage)
• ESS disable charge and disable feed-in
• ESS battery-only critical loads and schedule charge slot enabled
• Relay states on GX devices, Multi RS, and solar chargers
• Digital input inversion and switchable output states
• PV DC overvoltage feed-in
• VE.Bus PowerAssist, ignore AC input, and grid lost alarm settings

Times

Configurable time-of-day settings, such as:

• ESS BatteryLife schedule charge start times

Known limitations

• The integration receives updates through MQTT push, but limits entity updates to at most once every 30 seconds. This means rapidly changing values may appear with a short delay.

Examples

Send a notification when the battery is low

You can use this automation to receive a notification when your battery state of charge drops below a certain threshold. Replace sensor.battery_soc with your actual battery charge entity.

automation:
  - alias: "Notify when battery is low"
    triggers:
      - trigger: numeric_state
        entity_id: sensor.battery_soc
        below: 20
    actions:
      - action: notify.notify
        data:
          title: "Low battery warning"
          message: >
            Your Victron battery charge is at
            {{ states('sensor.battery_soc') }}%.

Troubleshooting

Cannot connect

Symptom: Connection fails during setup

Description

The integration cannot establish a connection to your Victron device.

Resolution

To resolve this issue, try the following steps:

1. Verify your Victron device is powered on and connected to your network.

2. Check that the hostname or IP address is correct.

3. Ensure that MQTT is enabled on your Victron device.

4. Test connectivity from Home Assistant by opening a terminal and running:

   nc -zv <VICTRON_IP> <MQTT_PORT>
   

   Replace <VICTRON_IP> with your device’s IP address and <MQTT_PORT> with the MQTT port (usually 1883 or 8883). If you get a timeout or error, there is a network connectivity issue.

5. If Venus OS is rooted (SSH access enabled):

   • Use port 8883
   • Enable SSL
   • Use username root
   • Use the password you defined to protect the instance

Authentication failed

Symptom: Authentication error during setup

Description

The credentials provided are incorrect.

Resolution

1. Double-check the username and password if authentication is enabled.
2. These are device credentials configured on the Victron device, not VRM portal credentials.
3. Verify the security profile setting on your Victron device under Settings > General > Local Network Security Profile.

No sensors appear

Symptom: Integration sets up but no entities are created

Description

The integration cannot discover or create entities from MQTT topics.

Resolution

1. Verify that MQTT topics are being published by your Victron device.
2. Check the Home Assistant logs under Settings > System > Logs for any error messages.
3. Ensure the MQTT service on the Victron device is running and configured correctly.
4. Try increasing the Elevated tracing option in the integration settings for more detailed logging.

Removing the integration

This integration follows standard integration removal.

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. From the list of devices, select the integration instance you want to remove.
3. Next to the entry, select the three dots menu. Then, select Delete.