4.1. Message definition

A message definition starts with message specific columns and is followed by one or more field definitions, i.e. a single CSV line (without any conditions) in principle looks like this:

message part,fields part

The fields part contains of one or more field definitions separated by a comma.

Since version 3.0 ebusd also supports arbitrary columns on message and field level as long as the column names do not overlap with the other ones listed below. All of those columns are subject to be picked by the preferred language (see --configlang) when the file contains a header defining the column names and the particular column name is suffixed with a dot and the language code, e.g. "COMMENT.en".

Message definition

The message specific part of a message definition consists of these columns:

TYPE,CIRCUIT,NAME,COMMENT,QQ,ZZ,PBSB,ID

The individual columns are these:

• [TYPE[;TYPE]*] - defaults to "r"
  The message type defines the message direction (read or write) as well as the default placement of the fields. Multiple message types can be defined in a single line by using the semicolon as separator.
  The first character (or in some cases the first two characters) determine the message type. The following message types are available:
  • "r": read (default)
    This defines an active master-slave read message that is used to retrieve values from the destination unit.
    The default placement for the fields is the slave data (unless the destination is a master address or the broadcast address, see "part" in field definition).
  • "r1"-"r9": poll
    When appending a digit 1-9 to the normal "read" type, the master-slave read message will be polled in regular intervals. The appended digit is the polling priority, i.e. messages with priority 1 are polled in each poll cycle, priority 2 messages only in every second poll cycle and so on.
  • "w": write
    This defines an active write message that is used to send values to a unit (or to all units using the broadcast destination address). The default placement for the fields is the master data (see "part" in field definition).
  • any other character: update
    All of the remaining characters can be used to define a passive message that ebusd will listen to in order to recognize updates of field values. If the type is suffixed with a "w", the message is treated as write message as mentioned above. Otherwise it is treated as read message.
• [CIRCUIT]
  The circuit of the message (to distinguish several messages with the same name). Optionally, an access level can be added after a "#" separator, e.g. "hotwater#installer". This way, only if the current access level matches "installer", access to the message is allowed.
• NAME
  The name of the message.
• [COMMENT]
  The message comment. This column is subject to be picked by the preferred language when named like e.g. "COMMENT.en" (see --configlang).
• [QQ]
  The master address of the source unit in hex, or empty for any (e.g. "10").
• [ZZ[;ZZ]*]
  The address(es) of the destination unit(s) in hex (e.g. "15" or "FE" for broadcast). When using multiple addresses, the CIRCUIT will automatically be extended with a dot and the address index (e.g. "circuit.0" for the first address when the CIRCUIT was named "circuit"). When omitted, the message can only be used when the destination address is specified during the call (e.g. using the read command).
• PBSB
  The primary and secondary command bytes in hex (e.g. "0700").
• [ID]
  Further ID bytes in hex placed in the first master data bytes (e.g. "040F01"). Together with the primary/secondary command bytes, the destination address, and the optional source address, this forms the unique message ID.
• optional further columns:
  Since version 3.0 ebusd also supports arbitrary columns as long as the column names do not overlap with the other ones listed here. All of those columns are subject to be picked by the preferred language (see COMMENT column).

This message definition part is followed by one or more field definitions as defined below.

Field definition

A singular field definition is quite similar to a template definition (besides of the added "part" column) and consists of the following columns:

The message specific part of a message definition consists of these columns:

FIELD,PART,DATATYPE,DIVIDER/VALUES,UNIT,COMMENT

The individual columns are these:

• [FIELD]
  The name of the field.
• [PART]
  The particular message part to override:
  • "m": master data (default for write messages)
  • "s": slave data (default for read messages)
• DATATYPE: BASETYPE|TEMPLATE[;BASETYPE|TEMPLATE]*
  A list of builtin base data types and/or already defined template names separated by semicolon.
• [DIVIDER/VALUES]: either a DIVIDER or VALUE=NAME[;VALUE=NAME]*
  This is expected for the column when there was no file header or the file header stated the column like this. In case the column value contains an equal sign, it will be treated as VALUES column (see below). Otherwise it will be treated as DIVIDER column (see below). The two parts of this column may also be specified separately by using a file header defining the column names DIVIDIER and VALUES separately, see below.
• [DIVIDER] (only with file header)
  The divider to apply on the numeric base type. Use a negative value for reciprocal divider (e.g. a factor of two would be noted as "-2").
• [VALUES] (only with file header): VALUE=NAME[;VALUE=NAME]* or =VALUE or ==VALUE
  The list of name/value associations separated by semicolon (value either in decimal or starting with "0x" for hex) or a constant value (or a verified constant value when starting with "==", which will lead to an error message during decoding when the value read was not equal to the value specified). This column is subject to be picked by the preferred language, see COMMENT column below.
• [UNIT]
  The value unit (e.g. "°C"). This column is subject to be picked by the preferred language, see COMMENT column below.
• [COMMENT]
  A comment for the field. This column is subject to be picked by the preferred language when named like e.g. "COMMENT.en" (see --configlang).
• optional further columns:
  Since version 3.0 ebusd also supports arbitrary columns as long as the column names do not overlap with the other ones listed here. All of those columns are subject to be picked by the preferred language (see COMMENT column).

Example

type	circuit	name	comment	QQ	ZZ	PBSB	ID	field1	part	type/templates	divider/values	unit	comment	field2	part	type/templates	divider/values	unit	comment
r1	ehp	brinetemp			08	B509	0D0F00	temp		D2C		°C	temperature	sensor		UCH	0=ok;85=circuit;170=cutoff		sensor status
r	ehp	brinetempcal			08	B509	0DCD00	calibration		D2C		K
w	ehp	brinetempcal			08	B509	0ECD00	calibration		D2C		K
Download CSV

Message chaining

In some cases it might be necessary to split a single field up into several messages, e.g. when a string is longer than a message usually is allowed to be (16 data bytes), or when the first part of a field appears in one message and the second part in another.

In order to define a message consisting of more than one part (i.e. a chain of messages), the ID column of the message definition can be used for that. In addition to the regular use, the ID column also supports a list of values separated by semicolon.

This is best explained in an example. Assume you've recognized that two messages on the bus together deliver the values you're interested in:

10 08 B5 09 01 24 / 04 30 31 32 33
10 08 B5 09 01 25 / 04 34 35 36 37

Using a regular message definition, this could be done like this:

type	circuit	name	comment	QQ	ZZ	PBSB	ID	field1	part	type
r	ehp	first			08	B509	24	prefix		STR:4
r	ehp	second			08	B509	25	suffix		STR:4

This would enable you to retrieve both parts separately with the following calls and results:

user@host:~$ ebusctl read -c ehp first
0123

user@host:~$ ebusctl read -c ehp second
4567

Now, lets combine both parts into a single read command (and let ebusd do the work of connecting both together). This has to be defined for the given example in a single message like this:

type	circuit	name	comment	QQ	ZZ	PBSB	ID	field1	part	type
r	ehp	both			08	B509	24;25	all		STR:8

Now we're able to retrieve both parts simultaneously with the following single call:

user@host:~$ ebusctl read -c ehp both
01234567

In the background, ebusd issues two reads on the bus with the two messages shown above and afterwards combines the read results to a single one which is then interpreted by the message definition fields.

This can also be used in write direction. For this, ebusd needs to know how long each part of the message on the bus has to be. This is done by appending the number of bytes to be added to the master data part of each message with a separating colon, e.g. use "24:4;25:4" for the example above.