Need official mapping for VE.Bus D-Bus

Modifications
, , , ,
1

Hi everyone,

I am building a local diagnostic/blackbox recorder on a Cerbo GX MK2 for a three-phase VE.Bus system and I am trying to avoid guessing the meaning of several internal VE.Bus D-Bus fields.

System:

  • Cerbo GX MK2
  • Three-phase system with 3 × MultiPlus-II 48/8000/110-100
  • VE.Bus service: com.victronenergy.vebus.ttyS4
  • Devices:
    • /Devices/0 = L1 / master
    • /Devices/1 = L2
    • /Devices/2 = L3

I can see the public Modbus/GX register list and I can decode the normal fields such as:

/VebusError
/State
/Alarms/GridLost
/Alarms/L1/Ripple
/Alarms/L2/Ripple
/Alarms/L3/Ripple
/Devices/x/ExtendStatus/RelayTestOk

However, several very useful D-Bus paths are visible locally on the Cerbo, but I cannot find official documentation for their bit mapping.

The paths I am trying to decode are:

/Devices/x/ExtendStatus/RawFlags0
/Devices/x/ExtendStatus/RawFlags1
/Devices/x/ErrorAndWarningFlags/RawFlags
/Devices/x/ExtendStatus/SwitchoverInfo/Delay
/Devices/x/ExtendStatus/SwitchoverInfo/Connecting
/Devices/x/ExtendStatus/SwitchoverInfo/ErrorFlags
/Devices/x/ExtendStatus/GridRelayReport/Code
/Devices/x/ExtendStatus/GridRelayReport/Count
/Devices/x/InterfaceProtectionLog/0/ErrorFlags
/Devices/x/InterfaceProtectionLog/0/Time
/Devices/x/InterfaceProtectionLog/1..4/ErrorFlags
/Devices/x/InterfaceProtectionLog/1..4/Time
/Devices/x/ExtendStatus/WaitingForRelayTest
/Devices/x/ExtendStatus/RelayTestOk
/Devices/x/ExtendStatus/VeBusNetworkQualityCounter
/Devices/x/Diagnostics/UBatRipple

Observed values during events:

InterfaceProtectionLog/ErrorFlags = 8
InterfaceProtectionLog/ErrorFlags = 16
InterfaceProtectionLog/ErrorFlags = 64
SwitchoverInfo/ErrorFlags = 12
SwitchoverInfo/ErrorFlags = 26
RawFlags0 normal baseline example = 268697648
RawFlags0 during one relay/reconnect incident = 17039408

From testing and community snippets, it looks like the interface/switchover flags may be bitmasks, possibly something like:

1  = RoCoF
4  = FreqLow
8  = VoltageLow
16 = VoltageHigh
64 = PhaseLockLost / PLL / phase issue

But I do not want to rely on guesses. I would like to know the official meaning, especially for:

InterfaceProtectionLog/ErrorFlags
SwitchoverInfo/ErrorFlags
RawFlags0
RawFlags1
GridRelayReport/Code

Example incident:

At one point the system had victron_ac_in_rejected for about 5 minutes while AC-IN voltage was visible and apparently within normal range:

L1 = 247.8 V
L2 = 238.2 V
L3 = 252.1 V
Frequency = 50.10 Hz
VE.Bus Error = 0

The system later accepted AC-IN again after the normal reconnect interval.

In the same general period I saw values like:

L3 InterfaceProtectionLog/ErrorFlags = 64
SwitchoverInfo/ErrorFlags = 26
RelayTestOk = 0 temporarily on one device

Questions:

  1. Is InterfaceProtectionLog/ErrorFlags officially documented anywhere?
  2. Does SwitchoverInfo/ErrorFlags use the same bit mapping as InterfaceProtectionLog/ErrorFlags?
  3. Are the /InterfaceProtectionLog/x/Time values Unix timestamps in UTC?
  4. How should the log slots 0–4 be interpreted? Is slot 0 simply the most recent event per device?
  5. Should old InterfaceProtectionLog entries be ignored as root cause if their timestamp is not close to the current incident?
  6. What exactly does RelayTestOk = 0 mean? Is it “relay test failed”, “relay test not yet passed”, or “currently waiting/reconnecting”?
  7. Is RawFlags0 / RawFlags1 stable enough to decode, or are these internal mk2-dbus implementation details that should only be stored as diagnostic evidence?
  8. Is there an official mapping for GridRelayReport/Code?
  9. For UBatRipple, is /Devices/x/Diagnostics/UBatRipple the actual ripple voltage RMS used for the High DC Ripple alarm?

My goal is not to bypass any grid-code or protection behavior. I only want to build a local diagnostic recorder that can explain events accurately, for example distinguishing between:

real grid outage
grid-code / loss-of-mains rejection
internal reconnect timer
relay/reconnect test still active
High DC Ripple on one VE.Bus phase
stale historical InterfaceProtectionLog entry

If anyone from Victron or someone familiar with mk2-dbus / VE.Bus internals can confirm the mapping or point me to the correct source file/documentation, that would be very helpful.

This all started after something happens and I get an e-mail saying “Grid Lost” and then “Grid Ok”, without actually telling me useful information of what actually caused this. I went through such a rabbit hole so far.

Thanks!

2

You will find some information on the flags registers in the document “communicating with VE-Bus Devices” on the Victron downloads site. Whilst this is primarily aimed at the VEBus / Mk3 communications, the Flag registers will hold their meanings. These are Bitmasks as you suppose.
Unfortunately, this doesn’t include data on the inteface-protection flags.

3

I managed to use dbus-spy and downloaded all the documentation from victron website to get most of what I need. The rawflags are the only one’s that cannot be decoded. This is quite sufficient for now, and covers I believe 90%+ of all scenarios. I could even map the interface-protection-logs. I dont think all of them, but the important ones, such as VoltageHigh, VoltageLow, PhaseLock etc.

4

Oh, that’s great info. I whipped up a quick shell script to dump those logs in readable form:

#!/bin/sh
# dbus path of the multis
device=com.victronenergy.vebus.ttyUSB0
# max device number
maxdev=2

for dev in $(seq 0 $maxdev); do
    echo "### Device $dev ###"
    for log in $(seq 0 4); do
	flags=$(dbus-send --system --print-reply --dest=$device \
			  /Devices/$dev/InterfaceProtectionLog/$log/ErrorFlags \
			  com.victronenergy.BusItem.GetValue \
		    | grep byte | awk '{print $3}')
	time=$(dbus-send --system --print-reply --dest=$device \
			 /Devices/$dev/InterfaceProtectionLog/$log/Time \
			 com.victronenergy.BusItem.GetValue \
		   | grep uint32 | awk '{print $3}')
	[ -z "$flags" ] && break;
	tt=$(date -d @$time)
	fs=""
	if [ $(($flags & 1)) -eq 1 ]; then fs="$fs RoCoF"; fi
	if [ $(($flags & 4)) -eq 4 ]; then fs="$fs FreqLow"; fi
	if [ $(($flags & 8)) -eq 8 ]; then fs="$fs VoltageLow"; fi
	if [ $(($flags & 16)) -eq 16 ]; then fs="$fs VoltageHigh"; fi
	if [ $(($flags & 64)) -eq 64 ]; then fs="$fs PhaseIssue"; fi

	echo "$tt $fs"
    done
    echo
done
5

Awesome. That is exactly what I have. hope thats all the flags. Would really really love to get a mapping of the RawFlags0/RawFlags1 and how they are used in determining causes. Are they in correlation or directly? Hopefully victron reads this and can provide some clarity. I am working on a very upgraded version of the System Blackbox that hopefully will be very usefull for the community. More details in the coming days.

6

@Bufaritza Hello. You been here:? dbus · victronenergy/venus Wiki · GitHub or places like here venus-os_dbus-multiplus-emulator/dbus-multiplus-emulator/dbus-multiplus-emulator.py at master · mr-manuel/venus-os_dbus-multiplus-emulator · GitHub

7

Thanks for the links Biff. Yes, I have mapped everything that is there.
The first one was very usefull, but sadly incomplete. The errorcodes link doesnt go anywhere and it does not have the InterfaceProtectionLogs or RawFlags paths.
The 2nd git you mention does have it, but it does not expose it’s values or meanings. I used all of this anyway and incorprated them into the deterministic engine. I crafted 18 scenarios to simulate various errors or issues so far. Stil in testing phase.