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 LIQUID_VOLUME NONE PERCENTAGE POWER TEMPERATURE TIME VOLTAGE	<ALL> CUMULATIVE INSTANTANEOUS NONE	<ALL> Battery EV Charging Station Grid Inverter Liquid Tank PV Inverter Solar Charger System Temperature	<ALL> ENUM FLOAT INT INT_DEFAULT_0		<ALL> EvChargerMode GenericOnOff InverterMode InverterOverloadAlarmEnum InverterState TemperatureStatus TemperatureType
N/+/system/+/Ac/Grid/NumberOfPhases	system_grid_phases	Grid phases		SENSOR	NONE	INSTANTANEOUS	Grid	INT_DEFAULT_0
N/+/grid/+/Ac/{phase}/Voltage	grid_voltage_{phase}	Grid voltage on {phase}	V	SENSOR	VOLTAGE	INSTANTANEOUS	Grid	FLOAT	1
N/+/grid/+/Ac/{phase}/Current	grid_current_{phase}	Grid current on {phase}	A	SENSOR	CURRENT	INSTANTANEOUS	Grid	FLOAT	1
N/+/grid/+/Ac/{phase}/Power	grid_power_{phase}	Grid power on {phase}	W	SENSOR	POWER	INSTANTANEOUS	Grid	FLOAT	1
N/+/grid/+/Ac/{phase}/Energy/Forward	grid_energy_forward_{phase}	Grid consumption on {phase}	kWh	SENSOR	ENERGY	CUMULATIVE	Grid	FLOAT	1
N/+/grid/+/Ac/{phase}/Energy/Reverse	grid_energy_reverse_{phase}	Grid feed-in on {phase}	kWh	SENSOR	ENERGY	CUMULATIVE	Grid	FLOAT	1
N/+/grid/+/Ac/PENVoltage	grid_voltage_pen	Grid voltage on PEN	V	SENSOR	VOLTAGE	INSTANTANEOUS	Grid	FLOAT	1
N/+/grid/+/Ac/N/Current	grid_current_n	Grid current on N	A	SENSOR	CURRENT	INSTANTANEOUS	Grid	FLOAT	1
N/+/grid/+/Ac/Frequency	grid_frequency	Grid frequency	Hz	SENSOR	FREQUENCY	INSTANTANEOUS	Grid	FLOAT	2
N/+/grid/+/Ac/{phase}/VoltageLineToLine	grid_voltage_{phase}_{next_phase}	Grid voltage {phase} to {next_phase}	V	SENSOR	VOLTAGE	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	solarcharger_voltage	DC Bus voltage	V	SENSOR	VOLTAGE	INSTANTANEOUS	Solar Charger	FLOAT	1
N/+/solarcharger/+/Dc/0/Current	solarcharger_current	DC current	A	SENSOR	CURRENT	INSTANTANEOUS	Solar Charger	FLOAT	1
N/+/solarcharger/+/Yield/Power	solarcharger_power	Power	W	SENSOR	POWER	INSTANTANEOUS	Solar Charger	FLOAT	1
N/+/solarcharger/+/Yield/User	solarcharger_yield_total	Total Yield	kWh	SENSOR	ENERGY	CUMULATIVE	Solar Charger	FLOAT	1
N/+/solarcharger/+/History/Daily/0/Yield	solarcharger_yield_today	Yield Today	kWh	SENSOR	ENERGY	CUMULATIVE	Solar Charger	FLOAT	1
N/+/solarcharger/+/History/Daily/1/Yield	solarcharger_yield_yesterday	Yield Yesterday	kWh	SENSOR	ENERGY	CUMULATIVE	Solar Charger	FLOAT	1
N/+/solarcharger/+/History/Daily/0/MaxPower	solarcharger_max_power_today	Max Power Today	W	SENSOR	POWER	INSTANTANEOUS	Solar Charger	FLOAT	1
N/+/solarcharger/+/History/Daily/1/MaxPower	solarcharger_max_power_yesterday	Max Power Yesterday	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/+/History/AutomaticSyncs	battery_automatic_syncs	Automatic syncs	count	SENSOR	NONE	CUMULATIVE	Battery	INT
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	Battery charge	%	SENSOR	PERCENTAGE	INSTANTANEOUS	Battery	FLOAT	1
N/+/battery/+/System/MinCellVoltage	battery_min_cell_voltage	Battery minimum cell voltage	V	SENSOR	VOLTAGE	INSTANTANEOUS	Battery	FLOAT	3
N/+/battery/+/System/MaxCellVoltage	battery_max_cell_voltage	Battery maximum cell voltage	V	SENSOR	VOLTAGE	INSTANTANEOUS	Battery	FLOAT	3
N/+/battery/+/TimeToGo	battery_time_to_go	Battery time to go	s	SENSOR	TIME	INSTANTANEOUS	Battery	INT
N/+/vebus/+/Mode	inverter_mode	Inverter mode		SELECT	NONE	NONE	Inverter	ENUM		InverterMode
N/+/vebus/+/State	inverter_state	Inverter state		SENSOR	NONE	NONE	Inverter	ENUM		InverterState
N/+/vebus/+/Ac/ActiveIn/{phase}/P	inverter_input_power_{phase}	Inverter input power {phase}	W	SENSOR	POWER	INSTANTANEOUS	Inverter	FLOAT	1
N/+/vebus/+/Ac/ActiveIn/{phase}/F	inverter_input_frequency_{phase}	Inverter input frequency {phase}	Hz	SENSOR	FREQUENCY	INSTANTANEOUS	Inverter	FLOAT	1
N/+/vebus/+/Ac/ActiveIn/{phase}/S	inverter_input_apparent_power_{phase}	Inverter input apparent power {phase}	VA	SENSOR	POWER	INSTANTANEOUS	Inverter	FLOAT	1
N/+/vebus/+/Ac/Out/{phase}/P	inverter_output_power_{phase}	Inverter output power {phase}	W	SENSOR	POWER	INSTANTANEOUS	Inverter	FLOAT	1
N/+/vebus/+/Ac/Out/{phase}/F	inverter_output_frequency_{phase}	Inverter output frequency {phase}	Hz	SENSOR	FREQUENCY	INSTANTANEOUS	Inverter	FLOAT	1
N/+/vebus/+/Ac/Out/{phase}/S	inverter_output_apparent_power_{phase}	Inverter output apparent power {phase}	VA	SENSOR	POWER	INSTANTANEOUS	Inverter	FLOAT	1
N/+/vebus/+/Connected	inverter_connected	Inverter connected		BINARY_SENSOR	NONE	NONE	Inverter	ENUM		GenericOnOff
N/+/vebus/+/Alarms/Overload	inverter_alarm_overload	Inverter overload alarm		SENSOR	NONE	NONE	Inverter	ENUM		InverterOverloadAlarmEnum
N/+/vebus/+/Ac/ActiveIn/CurrentLimit	inverter_current_limit	Inverter current limit	A	NUMBER	CURRENT	INSTANTANEOUS	Inverter	INT			0	RangeType.DYNAMIC
N/+/system/+/Ac/ConsumptionOnOutput/{phase}/Power	system_critical_loads_{phase}	Critical loads on {phase}	W	SENSOR	POWER	INSTANTANEOUS	System	FLOAT	1
N/+/system/+/Ac/ConsumptionOnInput/{phase}/Power	system_ac_loads_{phase}	AC loads on {phase}	W	SENSOR	POWER	INSTANTANEOUS	System	FLOAT	1
N/+/system/+/Dc/System/Power	system_dc_consumption	DC Consumption	W	SENSOR	POWER	INSTANTANEOUS	System	FLOAT	1
N/+/system/+/Relay/0/State	system_relay_1	Relay 1 state		SWITCH	NONE	NONE	System	ENUM		GenericOnOff
N/+/system/+/Relay/1/State	system_relay_2	Relay 2 state		SWITCH	NONE	NONE	System	ENUM		GenericOnOff
N/+/system/+/Ac/Genset/{phase}/Power	system_generator_load_{phase}	Genset Load {phase}	W	SENSOR	POWER	INSTANTANEOUS	System	FLOAT	1
N/+/system/+/Ac/Grid/{phase}/Power	system_grid_power_{phase}	Grid Power {phase}	W	SENSOR	POWER	INSTANTANEOUS	System	FLOAT	1
N/+/evcharger/+/Mode	evcharger_mode	EV charger mode		SELECT	NONE	NONE	EV Charging Station	ENUM		EvChargerMode
N/+/evcharger/+/StartStop	evcharger_charge	EV charger charge		SWITCH	NONE	NONE	EV Charging Station	ENUM		GenericOnOff
N/+/evcharger/+/Connected	evcharger_connected	EV charger connected		BINARY_SENSOR	NONE	NONE	EV Charging Station	ENUM		GenericOnOff
N/+/evcharger/+/Current	evcharger_current	EV charger current	A	SENSOR	CURRENT	INSTANTANEOUS	EV Charging Station	FLOAT	1
N/+/evcharger/+/Ac/{phase}/Power	evcharger_power_{phase}	EV charger power {phase}	W	SENSOR	POWER	INSTANTANEOUS	EV Charging Station	FLOAT	1
N/+/evcharger/+/SetCurrent	evcharger_set_current	EV charger set current	A	NUMBER	CURRENT	INSTANTANEOUS	EV Charging Station	INT			0	16
N/+/pvinverter/+/Ac/{phase}/Voltage	pvinverter_voltage_{phase}	Voltage {phase}	V	SENSOR	VOLTAGE	INSTANTANEOUS	PV Inverter	FLOAT	1
N/+/pvinverter/+/Ac/{phase}/Current	pvinverter_current_{phase}	Current {phase}	A	SENSOR	CURRENT	INSTANTANEOUS	PV Inverter	FLOAT	1
N/+/pvinverter/+/Ac/Power	pvinverter_power_total	Power Total	W	SENSOR	POWER	INSTANTANEOUS	PV Inverter	FLOAT	1
N/+/pvinverter/+/Ac/{phase}/Power	pvinverter_power_{phase}	Power {phase}	W	SENSOR	POWER	INSTANTANEOUS	PV Inverter	FLOAT	1
N/+/pvinverter/+/Ac/Energy/Forward	pvinverter_yield_total	Total Yield	kWh	SENSOR	ENERGY	CUMULATIVE	PV Inverter	FLOAT	1
N/+/pvinverter/+/Ac/{phase}/Energy/Forward	pvinverter_yield_{phase}	Yield {phase}	kWh	SENSOR	ENERGY	CUMULATIVE	PV Inverter	FLOAT	1
N/+/temperature/+/Temperature	temperature_temperature	Temperature	°C	SENSOR	TEMPERATURE	INSTANTANEOUS	Temperature	FLOAT	1
N/+/temperature/+/Status	temperature_status	Temperature sensor status		SENSOR	NONE	NONE	Temperature	ENUM		TemperatureStatus
N/+/temperature/+/TemperatureType	temperature_type	Temperature sensor type		SENSOR	NONE	NONE	Temperature	ENUM		TemperatureType
N/+/temperature/+/Offset	temperature_offset	Temperature offset	°C	NUMBER	TEMPERATURE	INSTANTANEOUS	Temperature	FLOAT	1
N/+/temperature/+/Scale	temperature_scale	Temperature scale factor		NUMBER	NONE	INSTANTANEOUS	Temperature	FLOAT	2
N/+/tank/+/Level	tank_level	Level	%	SENSOR	PERCENTAGE	INSTANTANEOUS	Liquid Tank	INT
N/+/tank/+/Remaining	tank_remaining	Remaining	m3	SENSOR	LIQUID_VOLUME	INSTANTANEOUS	Liquid Tank	INT
N/+/tank/+/Temperature	tank_temperature	Temperature	°C	SENSOR	TEMPERATURE	INSTANTANEOUS	Liquid Tank	INT

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.

DeviceType

Id	Value	Display Name
UNKNOWN	unknown	Unknown Device
SYSTEM	system	System
SOLAR_CHARGER	solarcharger	Solar Charger
INVERTER	inverter	Inverter
BATTERY	battery	Battery
GRID	grid	Grid
VEBUS	vebus	VE.Bus
EVCHARGER	evcharger	EV Charging Station
PVINVERTER	pvinverter	PV Inverter
TEMPERATURE	temperature	Temperature
GENERATOR	generator	Generator
TANK	tank	Liquid Tank

EvChargerMode

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

FluidType

Id	Value	Display Name
Fuel	0	Fuel
FreshWater	1	Fresh Water
WasteWater	2	Waste Water
LiveWell	3	Live Well
Oil	4	Oil
BlackWater	5	Black water (sewage)
Gasoline	6	Gasoline
Diesel	7	Diesel
LPG	8	Liquid Petroleum Gas (LPG)
LNG	9	Liquid Natural Gas (LNG)
HydraulicOil	10	Hydraulic oil
RawWater	11	Raw water

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

InverterOverloadAlarmEnum

Id	Value	Display Name
NoAlarm	0	No Alarm
Warning	1	Warning
Alarm	2	Alarm

InverterState

Id	Value	Display Name
Off	0	Off
LowPower	1	Low Power
Fault	2	Fault
Bulk	3	Bulk
Absorption	4	Absorption
Float	5	Float
Storage	6	Storage
Equalize	7	Equalize
Passthrough	8	Passthrough
Inverting	9	Inverting
PowerAssist	10	Power Assist
PowerSupply	11	Power Supply
Sustain	244	Sustain
ExternalControl	252	External Control

TemperatureStatus

Id	Value	Display Name
Ok	0	Ok
Disconnected	1	Disconnected
ShortCircuited	2	Short circuited
ReversePolarity	3	Reverse polarity
Unknown	4	Unknown

TemperatureType

Id	Value	Display Name
Battery	0	Battery
Fridge	1	Fridge
Generic	2	Generic
Room	3	Room
Outdoor	4	Outdoor
WaterHeater	5	Water Heater
Freezer	6	Freezer

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.