Add support for 720-based regulators

[burmistrzak]

This PR is a superset of #482, including register definitions for the following regulator models:

• 15.720
• 15.basv
• 15.basv2
• 15.basv3
• 15.ctls2
• 15.ctlv2
• 15.ctlv3
• 15.bass

If you have one of the aforementioned devices, feel free to give this unified configuration a try and report back!
There're still a few unsupported devices at the moment, specifically:

• 15.ctlv*
• 15.ctls*
• 15.ctls3
• 15.bass2
• 15.bass3

*might not exist..?

In case you own one of them, please comment below with your setup details!

I also have incorporated (hopefully) all the recent discoveries made by @stadid, @chrizzzp & @jonesPD. 🤝
A fork of the CDN repo with pre-compiled definitions is available in English and German.

Testing & Validation

1. Clone the CDN fork from https://github.com/burmistrzak/ebus.github.io
2. Checkout dev branch (should be default)
3. Set EBUSD_CONFIGPATH to <MOUNTPOINT>/ebus.github.io/dev/en
4. Set EBUSD_MQTTVAR to e.g.:
   filter-direction=r|u|^w,filter-circuit=^bas*$,filter-non-circuit=^hmu*$,filter-name=^*,filter-non-name=^Z2|^Z3|^Hc2|^Hc3 (adjust to match your system)
5. Restart ebusd container (or service).
6. Check entities in HA and/or MQTT.
7. Look out for errors and report them below.

[d3vi1]

Also, does anyone know a good way to determine whether a VR92 is available? Ideally, how many are configured as well. 😅 Don't have one, so need your input here.

I believe that when we talk to the regulator on ebus, we actually talk to the "Radio receiver unit". If you look at the screen of the regulator you see the following ebus components:
Control (08.05)
Radio receiver unit (05.07)
Heat generator 1 (08.06)
(...)
If you were to look at what ebusd sees, you have:
address 03: master #11
address 04: slave #25, scanned "MF=Vaillant;ID=NETX3;SW=0128;HW=0404", loaded "vaillant/04.netx3.csv"
address 08: slave #11, scanned "MF=Vaillant;ID=BAI00;SW=0806;HW=7603", loaded "vaillant/08.bai.csv"
address 10: master #2
address 15: slave #2, scanned "MF=Vaillant;ID=BASV2;SW=0507;HW=1704", loaded "vaillant/15.basv.csv"
address 26: slave, scanned "MF=Vaillant;ID=VR_71;SW=0100;HW=5904", loaded "vaillant/26.vr_71.csv"
address 31: master #8, ebusd
address 36: slave #8, ebusd
address f1: master #10
address f6: slave #10, scanned "MF=Vaillant;ID=NETX3;SW=0128;HW=0404", loaded "vaillant/f6.netx3.csv"
address ff: master #25

So the BASV2, SW=0507 is actually presented on the bus by the Radio receiver unit. I also believe that it has some sort of register windows to see whatever is hiding behind it (VRC720f/2, VR92f), etc. And I am actively digging into this. I want to extract for each slot of the radio unit the list of SN, PN, ID, HW, MF, etc. This actually might explain why some devices show up twice on the bus (for example SensoNET and NETX3 gateways).

[burmistrzak]

@d3vi1 Yeah, we're indeed talking to the wireless base station and not to the regulator unit on the wall. But keep digging!

At this point, it might be easier to just dump the entire firmware from one of these things. 😊
Fair warning though, especially the newer embedded Vaillant devices are more secure. They seemingly learned their lesson from the original eBUS database leak.

[burmistrzak]

@chrizzzp I think we can use HydraulicScheme to determine which registers should be available/displayed.
Validation via individual scheme plan and/or simulator. Thoughts?

[stadid]

@d3vi1

So the BASV2, SW=0507 is actually presented on the bus by the Radio receiver unit. I also believe that it has some sort of register windows to see whatever is hiding behind it (VRC720f/2, VR92f), etc.

If we consider reliability of the system control it make no sense to replace physical bus with radio channel which is not so reliable. Just consider what happens if radio communication is interrupted. System just hangs without the controller.

One of the possibilities is that wireless base station working as "controller without display" and wireless part is just external display with the controls.
Also base station connects to VR92F units. For them wireless link reliability is not that critical as system control just lose temperature data from the assigned zone. If my assumptions are correct VR92F units most probably would not be seen from the wired bus, as they are "virtually" connected to VRC720/f

[stadid]

Also, does anyone know a good way to determine whether a VR92 is available? Ideally, how many are configured as well. 😅
Don't have one, so need your input here.

I know at least two working options:

First one is to scan the bus for devices with VR_92 id (suitable for wired controller setups)
Second is to iterate through controller all 9 zones corresponding registers responsible for VR92 unit assignment.
If numeric value is > 2 it means that zone assigned to the VR92 unit with specified address (does not guarantee that corresponding VR92 is on the bus, but in this case you'll receive controller error 1192-1195.)
0 = no assignment
1 = VRC720 itself
2 = VR92 addr 1
....
5 = VR92 addr 4

error	description
1192	Communication error to remote control with address 1
1193	Communication error to remote control with address 2
1194	Communication error to remote control with address 3
1195	Communication error to remote control with address 4

[burmistrzak]

Second is to iterate through controller all 9 zones corresponding registers responsible for VR92 unit assignment.

@stadid Hmm, you mean Z*RoomZoneMapping?

Edit: We don't have nine zones defined yet... 😅 You sure about that?

[stadid]

@stadid Hmm, you mean Z*RoomZoneMapping?

Yes, it's the register responsible for zone mapping.

Edit: We don't have nine zones defined yet... 😅

OK. I think I can help you ))))

Go to https://github.com/stadid/webcontrol

Into the releases section download any Webcontrol update package zip file (for example, the newest one: Webcontrol_CU_2026_01_31.zip)

In this archive you'll find another archive named ebusd_config.zip
In the ebusd_config.zip you'll find config files for 9 zones/circuits (old format) for VRC720.

It's not in sync with @jonesPD repository, as I specifically created it for Webcontrol project and it's not updated for a while, but You'll get a clue how to address additional Zones / Circuits.

Of topic:
In my personal opinion TSP format maybe cool and optimizing a lot of things, but the final text representation is absolutely not "human readable friendly". The old format which I am using in my project is much more comprehensive for the attentive researcher.))) It helped me a lot to extend current 3 zone/ circuit config as you understand the register "address space" and address shift for repeating patterns.

[burmistrzak]

@stadid Thank you!
I checked Vaillant's planning guidelines and up to nine circuits are indeed possible with multiple heat sources (i.e. hybrid systems). Such a setup would require HydraulicScheme be set to 16.

[stadid]

@burmistrzak

Thank you!

You are welcome)))

with multiple heat sources (i.e. hybrid systems).

Not only hybrid, but also heaters cascade

UPD: also I've seen working setups where some HC/Zones were just skipped (left inactive), while installers configured the system.
So with 9 zones/circuits we should be on par with the Vaillant native remote control app)))

[burmistrzak]

@stadid According to docs, you need one FM5 and three FM3 to get these nine circuits.
Do we have FM3Config registers already?

[chrizzzp]

@chrizzzp I think we can use HydraulicScheme to determine which registers should be available/displayed. Validation via individual scheme plan and/or simulator. Thoughts?

Sounds like a lot of work/testing (and who really wants to play with the hydraulic scheme?), but in principle yes, it should be feasible.

[chrizzzp]

@burmistrzak

All in Wh (Watt hours).

@chrizzzp Huh, seems to be an outlier then. Everything else is in kWh. Should we convert and keep everything in kWh?

I agree, kWh is the more adequate unit (but maybe should not be rounded). However, the actual values come in Wh, which makes sense only for a few minor energy consumptions (e.g. regulators, mixers...) and daily values (which are also available from the 'EnStat' values besides monthly and annual data, but have been left out in the PR because then we would have to generate an endless number of definitions, although @filippz has created a script for that).

Edit: Also shouldn't EnStatElectricalSumSystem be named PrEnergySum and EnStatSolarHotWaterSystem something like PrEnergySumSolarHwc?

Well, the 'EnStat' values come from a completely different address range (b516) than the 'PrEnergy' values (b524) and so far seem to be 'universal' for all devices, while the b524 energy values are not. E.g. for HP units the 'PrEnergyFuel' values do not exist (for obvious reasons), but the respective 'EnStat' values can always be read (just return 0 energy). So the b516 values could represent the 'original' energy data, while 'PrEnergy' values are selected 'mirrors'. That's why I suggested the 'EnStat' prefix to differentiate them from the b524 energy values. But I'm always happy to adjust nomenclature...

[stadid]

@burmistrzak

Do we have FM3Config registers already?

As far as I know - it still not found.
It could be somewhere in the address space near FM5 config.

@chrizzzp
Just a guess - could it be 2E00 ?

or

FM5Config is reusable - depending on the modules connected to the system it could contain FM3 or FM5 config. I've checked manual for vRC720 but from it its unclear as only in one configuration this option becomes active (in the VRC720 simulator FM5 config option got replaced with the FM3 config option if you select 2 circuits/zones).

Unfortunately I can't test it as I do not have appropriate system.

[burmistrzak]

Unfortunately I can't test it as I do not have appropriate system.

@stadid Same here.
Btw. is there a register that tells us how many/which Hc/zones are active?

[burmistrzak]

Also, if anyone wants to do me a favor, open a PR for this branch and add the official Vaillant terminology/name (as seen on the simulator/regulator) for each register as a TypeSpec comment. 🫶

[chrizzzp]

@burmistrzak

@chrizzzp Just a guess - could it be 2E00 ?

or

FM5Config is reusable - depending on the modules connected to the system it could contain FM3 or FM5 config. I've checked manual for vRC720 but from it its unclear as only in one configuration this option becomes active (in the VRC720 simulator FM5 config option got replaced with the FM3 config option if you select 2 circuits/zones).

Unfortunately I can't test it as I do not have appropriate system.

hex 15b52406020000002f00
0603002f000200

hex 15b52406020000002e00
00

I only have FM5, no FM3. So, it's probably not 2e00.

The manual says you always need an FM5 to connect additional FM3(s) and there is no additional configuration for the FM3(s) documented. So FM5config seems to specify mostly the presence of the solar circuit (with 1 or 2 storage buffers). The number of HCs/zones added by FM3(s) may be not affected by the FM5config.

[stadid]

@chrizzzp

The manual says you always need an FM5 to connect additional FM3(s) and there is no additional configuration for the FM3(s) documented.

OR

you need to have in the system only 2 zones / 2 circuits covered by single FM3 module.

In this case simulator gives opportunity to change FM3 settings

Try to start simulation with 2 circuits and you get FM3 instead of FM5 (see below)

[stadid]

@burmistrzak , @chrizzzp

Btw. is there a register that tells us how many/which Hc/zones are active?

Not currently found, but possibility of such register(s) is quite high.
When with @chrizzzp and @jonesPD we analyzed controller config for timers it was found that each timer has some "summary" register containing the number of configured time slots for each day of the week.

So why not the similar could exist for zones/circuits ?

[burmistrzak]

@stadid Would make sense...
Has the entire register address space been searched yet?

[chrizzzp]

@burmistrzak

@stadid Would make sense... Has the entire register address space been searched yet?

Well the entire address space probably not, but quite exhaustively leading to many 'unknown' registers as documented by @jonesPD: https://github.com/jonesPD/ebusd-configuration/blob/master/ebusd-2.1.x/en/vaillant/15.ctlv2.csv

Some contain values that don't seem to change during operation but this is what you would expect from configuration settings...

[chrizzzp]

@stadid

OR

you need to have in the system only 2 zones / 2 circuits covered by single FM3 module.

In this case simulator gives opportunity to change FM3 settings

Try to start simulation with 2 circuits and you get FM3 instead of FM5 (see below)

OK, I see what you mean. Two heating circuits seem to be the only case where you don't need an FM5 (and FM3 is sufficient). As soon as you add a solar circuit it will require a FM5...

[burmistrzak]

Two heating circuits seem to be the only case where you don't need an FM5 (and FM3 is sufficient). As soon as you add a solar circuit it will require a FM5...

@chrizzzp That's my understanding as well.
Now we need to find someone with only a FM3 installed... 😅

[scabrero]

Two heating circuits seem to be the only case where you don't need an FM5 (and FM3 is sufficient). As soon as you add a solar circuit it will require a FM5...

@chrizzzp That's my understanding as well. Now we need to find someone with only a FM3 installed... 😅

I do have a GeniaSet Split tower + FM3 / RED3 / VR70 expansion card driving two circuits / zones. Let me know what do you need.

[burmistrzak]

@scabrero Hell yeah! 💪

Please run the following read command:

ebusctl hex 15b52406020000002e00

@chrizzzp Any other suggestions for him to try?

[scabrero]

Please run the following read command:

ebusctl hex 15b52406020000002e00

00

Probably not the right command.

[chrizzzp]

@scabrero

What regulator do you have?

Could you run:
ebusctl info

Please try also:
ebusctl hex 15b52406020000002f00

[scabrero]

@scabrero

What regulator do you have?

SRC 720f/2, identified as Vaillant;BASS2;507;1704

Please try also: ebusctl hex 15b52406020000002f00

hex 15b52406020000002f00
0602002f000300

I also have a SRC921 gateway that polls this register each 1 hour. The value 3 is reported as "moduleConfigurationVR71" by vaillant cloud API. E.g: https://github.com/signalkraft/myPyllant/blob/main/src/myPyllant/tests/data/heatpump_heat_curve/547b5314b17a38830125171aa35b04ad87ef2de6/system.json#L51

I tried to change my FM3 config from 5 to 1 in the regulator itself and the response was the same, so this register must be something else.

Comparing the response to the FM5 one, the first byte might be the number of zones the system can handle. 02 in the case of FM3, 03 in the case of FM5, maybe 05 in the case of FM3+FM5.