victron_mqtt

Victron MQTT Documentation

victron_mqtt (C) 2025, tomer-w (https://github.com/tomer-w). For more information see https://github.com/tomer-w/victron_mqtt. This file is part of victron_mqtt. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Victron MQTT Protocol Overview

The Victron MQTT protocol is used by Victron Energy devices to publish and subscribe to real-time data over an MQTT broker. This protocol enables seamless integration of Victron devices—such as inverters, chargers, battery monitors, and solar controllers—into home automation, monitoring, and energy management systems.

How It Works

• MQTT Broker: Victron devices connect to a central MQTT broker (such as Venus OS MQTT or a third-party broker).
• Topics: Each device publishes its data (voltages, currents, states, alarms, etc.) to specific MQTT topics, usually under a common prefix (e.g., victron/).
• Payloads: Data is typically sent as simple values (numbers, strings) or JSON objects, depending on the topic.
• Discovery: Devices and their metrics can be discovered by subscribing to wildcard topics (e.g., victron/+/+/...).

Supported Victron Devices

Note: To use the Victron MQTT protocol, you must have a Cerbo GX, Venus GX, or Color Control GX device (collectively known as GX devices). These GX devices act as gateways, exposing data from connected Victron products via MQTT. Other Victron devices (such as inverters, solar controllers, and battery monitors) do not expose MQTT directly—they must be connected to a GX device, which then publishes their data to the MQTT broker.

• Cerbo GX / Venus GX / Color Control GX (required for MQTT access)
• MultiPlus / Quattro Inverter-Chargers (via GX device)
• BlueSolar / SmartSolar MPPT Solar Charge Controllers (via GX device)
• BMV / SmartShunt Battery Monitors (via GX device)
• Lynx Shunt / Power Distribution Systems (via GX device)
• Other compatible Victron devices (via GX device)

Common MQTT Topics

Each device type publishes to a set of standardized topics. For example:

• victron/+/Dc/0/Voltage – DC voltage readings
• victron/+/Ac/ActiveIn/L1/Power – AC input power
• victron/+/Soc – State of charge
• victron/+/Alarms/LowVoltage – Low voltage alarm status
• ...and many more, as detailed in the table below.

MQTT Topics

Topic	Short ID	Name	Unit	Message Type	Metric Type	Metric Nature	Device Type	Value Type	Precision	Enum	Min	Max
				<ALL> BINARY_SENSOR NUMBER SELECT SENSOR SWITCH	<ALL> CURRENT ELECTRIC_STORAGE_CAPACITY ENERGY FREQUENCY NONE PERCENTAGE POWER TEMPERATURE VOLTAGE	<ALL> CUMULATIVE INSTANTANEOUS NONE	<ALL> BATTERY EVCHARGER GRID INVERTER PVINVERTER SOLAR_CHARGER SYSTEM	<ALL> ENUM FLOAT INT INT_DEFAULT_0		<ALL> EvChargerMode GenericOnOff InverterMode
N/+/system/+/Ac/Grid/NumberOfPhases	system_grid_phases	Grid phases		SENSOR	NONE	INSTANTANEOUS	GRID	INT_DEFAULT_0	0
N/+/grid/+/Ac/+/Voltage	grid_voltage_{phase}	Grid voltage on {phase}	V	SENSOR	VOLTAGE	INSTANTANEOUS	GRID	FLOAT	1
N/+/grid/+/Ac/+/Current	grid_current_{phase}	Grid current on {phase}	A	SENSOR	CURRENT	INSTANTANEOUS	GRID	FLOAT	1
N/+/grid/+/Ac/+/Power	grid_power_{phase}	Grid power on {phase}	W	SENSOR	POWER	INSTANTANEOUS	GRID	FLOAT	1
N/+/grid/+/Ac/Voltage	grid_voltage	Grid voltage	V	SENSOR	VOLTAGE	INSTANTANEOUS	GRID	FLOAT	1
N/+/grid/+/Ac/Current	grid_current	Grid current	A	SENSOR	CURRENT	INSTANTANEOUS	GRID	FLOAT	1
N/+/grid/+/Ac/Power	grid_power	Grid power	W	SENSOR	POWER	INSTANTANEOUS	GRID	FLOAT	1
N/+/grid/+/Ac/Energy/Forward	grid_energy_forward	Grid consumption	kWh	SENSOR	ENERGY	CUMULATIVE	GRID	FLOAT	1
N/+/grid/+/Ac/Energy/Reverse	grid_energy_reverse	Grid feed-in	kWh	SENSOR	ENERGY	CUMULATIVE	GRID	FLOAT	1
N/+/solarcharger/+/Dc/0/Voltage	solar_voltage	DC Bus voltage	V	SENSOR	VOLTAGE	INSTANTANEOUS	SOLAR_CHARGER	FLOAT	1
N/+/solarcharger/+/Dc/0/Current	solar_current	DC current	A	SENSOR	CURRENT	INSTANTANEOUS	SOLAR_CHARGER	FLOAT	1
N/+/solarcharger/+/Yield/Power	solar_power	Power	W	SENSOR	POWER	INSTANTANEOUS	SOLAR_CHARGER	FLOAT	1
N/+/solarcharger/+/Yield/User	solar_yield	Yield	kWh	SENSOR	ENERGY	CUMULATIVE	SOLAR_CHARGER	FLOAT	1
N/+/solarcharger/+/History/Daily/0/MaxPower	solar_max_power	Max Power Today	W	SENSOR	POWER	INSTANTANEOUS	SOLAR_CHARGER	FLOAT	1
N/+/battery/+/Dc/0/Voltage	battery_voltage	Battery voltage	V	SENSOR	VOLTAGE	INSTANTANEOUS	BATTERY	FLOAT	1
N/+/battery/+/Dc/0/Current	battery_current	Battery current	A	SENSOR	CURRENT	INSTANTANEOUS	BATTERY	FLOAT	1
N/+/battery/+/Dc/0/Power	battery_power	Battery power	W	SENSOR	POWER	INSTANTANEOUS	BATTERY	FLOAT	1
N/+/battery/+/Dc/0/Temperature	battery_temperature	Battery temperature	°C	SENSOR	TEMPERATURE	INSTANTANEOUS	BATTERY	FLOAT	1
N/+/battery/+/History/DischargedEnergy	battery_discharged_energy	Discharged energy	kWh	SENSOR	ENERGY	CUMULATIVE	BATTERY	FLOAT	1
N/+/battery/+/History/ChargedEnergy	battery_charged_energy	Charged energy	kWh	SENSOR	ENERGY	CUMULATIVE	BATTERY	FLOAT	1
N/+/battery/+/Capacity	battery_capacity	Battery capacity	Ah	SENSOR	ELECTRIC_STORAGE_CAPACITY	INSTANTANEOUS	BATTERY	FLOAT	1
N/+/battery/+/InstalledCapacity	battery_installed_capacity	Battery installed capacity	Ah	SENSOR	ELECTRIC_STORAGE_CAPACITY	INSTANTANEOUS	BATTERY	FLOAT	1
N/+/battery/+/Soc	battery_soc	SOC	%	SENSOR	PERCENTAGE	INSTANTANEOUS	BATTERY	FLOAT	1
N/+/vebus/+/Mode	inverter_mode	Inverter mode		SELECT	NONE	NONE	INVERTER	ENUM		InverterMode
N/+/vebus/+/Ac/ActiveIn/+/P	inverter_input_power_{phase}	Inverter input power {phase}	W	SENSOR	POWER	INSTANTANEOUS	INVERTER	FLOAT	1
N/+/vebus/+/Ac/ActiveIn/+/F	inverter_input_frequency_{phase}	Inverter input frequency {phase}	Hz	SENSOR	FREQUENCY	INSTANTANEOUS	INVERTER	FLOAT	1
N/+/vebus/+/Ac/ActiveIn/+/S	inverter_input_apparent_power_{phase}	Inverter input apparent power {phase}	VA	SENSOR	POWER	INSTANTANEOUS	INVERTER	FLOAT	1
N/+/vebus/+/Ac/Out/+/P	inverter_output_power_{phase}	Inverter output power {phase}	W	SENSOR	POWER	INSTANTANEOUS	INVERTER	FLOAT	1
N/+/vebus/+/Ac/Out/+/F	inverter_output_frequency_{phase}	Inverter output frequency {phase}	Hz	SENSOR	FREQUENCY	INSTANTANEOUS	INVERTER	FLOAT	1
N/+/vebus/+/Ac/Out/+/S	inverter_output_apparent_power_{phase}	Inverter output frequency {phase}	VA	SENSOR	POWER	INSTANTANEOUS	INVERTER	FLOAT	1
N/+/vebus/+/Connected	inverter_connected	Inverter connected		BINARY_SENSOR	NONE	NONE	INVERTER	ENUM		GenericOnOff
N/+/vebus/+/Ac/ActiveIn/CurrentLimit	inverter_current_limit	Inverter current limit	A	NUMBER	CURRENT	INSTANTANEOUS	INVERTER	INT	0		0	16
N/+/system/+/Ac/ConsumptionOnOutput/+/Power	system_critical_loads_{phase}	Critical loads on {phase}	W	SENSOR	POWER	INSTANTANEOUS	SYSTEM	FLOAT	1
N/+/system/+/Ac/ConsumptionOnInput/+/Power	system_ac_loads_{phase}	AC loads on {phase}	W	SENSOR	POWER	INSTANTANEOUS	SYSTEM	FLOAT	1
N/+/evcharger/+/Mode	evcharger_mode	EV charger mode		SELECT	NONE	NONE	EVCHARGER	ENUM		EvChargerMode
N/+/evcharger/+/StartStop	evcharger_charge	EV charger charge		SWITCH	NONE	NONE	EVCHARGER	ENUM		GenericOnOff
N/+/evcharger/+/Connected	evcharger_connected	EV charger connected		BINARY_SENSOR	NONE	NONE	EVCHARGER	ENUM		GenericOnOff
N/+/evcharger/+/Current	evcharger_current	EV charger current	A	SENSOR	CURRENT	INSTANTANEOUS	EVCHARGER	FLOAT	1
N/+/evcharger/+/Ac/+/Power	evcharger_power_{phase}	EV charger power	W	SENSOR	POWER	INSTANTANEOUS	EVCHARGER	FLOAT	1
N/+/evcharger/+/SetCurrent	evcharger_set_current	EV charger set current	A	NUMBER	CURRENT	INSTANTANEOUS	EVCHARGER	INT	0		0	16
N/+/pvinverter/+/Ac/+/Voltage	solar_voltage_{phase}	Voltage {phase}	V	SENSOR	VOLTAGE	INSTANTANEOUS	PVINVERTER	FLOAT	1
N/+/pvinverter/+/Ac/+/Current	solar_current_{phase}	Current {phase}	A	SENSOR	CURRENT	INSTANTANEOUS	PVINVERTER	FLOAT	1
N/+/pvinverter/+/Ac/Power	solar_power_total	Power Total	W	SENSOR	POWER	INSTANTANEOUS	PVINVERTER	FLOAT	1
N/+/pvinverter/+/Ac/+/Power	solar_power_{phase}	Power {phase}	W	SENSOR	POWER	INSTANTANEOUS	PVINVERTER	FLOAT	1
N/+/pvinverter/+/Ac/Energy/Forward	solar_yield_total	Total Yield	kWh	SENSOR	ENERGY	CUMULATIVE	PVINVERTER	FLOAT	1
N/+/pvinverter/+/Ac/+/Energy/Forward	solar_yield_{phase}	Yield {phase}	kWh	SENSOR	ENERGY	CUMULATIVE	PVINVERTER	FLOAT	1

Enums

Enums represent the possible states or values for certain device properties, such as operational modes, alarm states, or relay statuses. These are useful for interpreting numeric codes in MQTT payloads.

EvChargerMode

Id	Value	Display Name
Manual	0	Manual
Auto	1	Auto
ScheduledCharge	2	Scheduled Charge

GenericOnOff

Id	Value	Display Name
Off	0	Off
On	1	On

InverterMode

Id	Value	Display Name
ChargerOnly	1	Charger Only
InverterOnly	2	Inverter Only
On	3	On
Off	4	Off

Generated by victron-mqtt project © 2025
Not affiliated with Victron Energy. For official documentation, visit Victron Energy Live.

This site is open source. Improve this page.