HowTos

Creating new message definition files

The most tricky part of an ebusd installation are the message definition files. These files enable ebusd to read and write values (instead of just hex nonsense) from/to other devices on the eBUS.

Luckily for some devices we've already decoded a lot of messages. These can be found in the configuration repository.

Now, when looking at a totally unknown device, the messages have to be decoded manually by guessing their meaning. For this purpose, ebusd supports grabbing unknown messages and reporting them by using the grab command.

Furthermore, the grab result decode command also supports finding the correct data type by emitting all valid values from decoding of each base type in the slave/master data.

Let's use an example. We start by sending a simple grab command to ebusd so that it starts recording unknown messages (which is already automatically activated since version 2.1). A minute later or so, some messages might already be available. We can check this by simply using the grab result which might give us something like this:

1023b5040101 / 091e0300000006000100 = 1
1023b504010d / 050000008000 = 1
1025b5040101 / 09350300000003000100 = 10
1025b504010d / 050000290135 = 10
1050b5040101 / 09150300000081000100 = 6
1050b504010d / 051700710115 = 6

Just for a short reminder, here is the meaning of the bytes shown above:
QQZZPBSBNNDD / NNDD = count
Here, QQ is the source address, ZZ is the destination address, PBSB is the primary and secondary command byte, NN is the number of data bytes DD following, and count is the number of times, the message was seen on the bus.

When looking at the master part of these messages (everything in front of the slash), it is clear that all of them were initiated by the master with the address "10". In the eBUS standard documentation, the master "10" is defined to be a heating controller.

The first two different slave addresses "23" and "25" have no dedicated purpose assigned by the eBUS specification. So at the moment we don't know, what these do. However, the slave address "50" is supposed to be a mixer unit, so we know at least the purpose of this unit.

The remainder of the master part of these messages seems to be repeating itself as there are only two different remainders: "b5040101" and "b504010d". This leads to the assumption, that both of these messages could have the same purpose no matter which slave was addressed.

The two different single master data bytes "01" and "0d" could either be used for distinguishing two totally different messages, or just be a value passed to the slave. When looking at the answer from the slave (the hex values between the slash and the equal sign), it seems obvious that this byte just defines two different messages (as the length of the answer is 9 bytes for the "01" master data and only 5 bytes for the "0d" master data) and so this is a "read" message (whereas it would rather be a "write" when the slave part would only consist of a kind of acknowledge and the master part would carry the actual values).

Now, the primary command byte "b5" tells us, that these messages are specified by Vaillant and are not part of the eBUS standard. Bad luck :-)

Lets continue looking at the messages to the one circuit, we know a little bit of: the mixer (slave address "50"). Now it is a good time to check for all the values that we know this circuit is working with. A mixer usually needs to know the following values in order to adjust the mixer position accordingly:

• desired and actual room temperature
• desired and actual flow temperature
• return temperature
• outside temperature
• operating mode

The desired room temperature in this example is known to be 21 degrees, which is "15" in hex. "15" is part of both these messages:

1050b5040101 / 09150300000081000100
1050b504010d / 051700710115

The remaining data of these messages is unclear at this moment. Now you could either start watching these parts for changes over e.g. a whole day, which might give you a hint what it is. Another approach is to change the known values in the user interface for that circuit and watch for changes in these messages.

This way, you can easily find out, that the byte following the desired room temperature in the "1050b5040101" message is different for each operating mode of the mixer.

When converting these findings to a message defintion, it could look like this:

type	circuit	name	comment	QQ	ZZ	PBSB	ID	field1	part	type	divider/values	unit	comment	field2	part	type	divider/values	unit	comment
r	mixer	temp_mode			50	B504	01	temp		UCH		°C	desired temp.	mode		UCH	1=on;2=off;3=auto;4=eco;5=low		operating mode

Since it seems to be enough to just interpret this message when it occurs on the bus and as this is a "read" kind of message anyway, we don't need to care about the unknown remaining bytes. These are just skipped with this message definition.

Actually, the same information can easily be found for the other two slave addresses. So we can just use the message definition for all of these slaves, as the message structure is the same due to identical lengths and the same fields at identical positions.

The only thing left we need to find out is the circuit types for the two other slaves. Again, from known values in the installation, it can easily be found out that the slave "25" is the hot water circuit (since the temperature field value "35" indicates 53 degrees). The remaining slave "23" seems to be the circulation circuit (found out by switching it on and off in the controller user interface).

The message definition including all three circuits could thus be written like that:

type	circuit	name	comment	QQ	ZZ	PBSB	ID	field1	part	type	divider/values	unit	comment	field2	part	type	divider/values	unit	comment
*rm	mixer				50	B504
*rw	water				25	B504
*rc	circul				23	B504
rm;rw;rc	mixer	temp_mode					01	temp		UCH		°C	desired temp.	mode		UCH	1=on;2=off;3=auto;4=eco;5=low		operating mode