4. Configuration

Introduction

The messages on the eBUS and their content highly depend on the addressed bus participant. In order to convert these binary messages to/from human readable values, the structure of each message needs to be defined. This is done in CSV files as described below.

A set of historically grown configuration files can be found here: ebusd-configuration

Files

The overall message configuration can be split up into several files and each file is supposed to describe the messages that may be sent to or by a singular device on the bus.

All of these files reside in the ebusd configuration directory (see Message configuration). Each ".csv" file in that directory will be read by the daemon during start-up (and re-read on request ).

There is one special file named "_templates.csv", which is supposed to contain field template definitions, that may be used elsewhere. All other CSV files contain message definitions or defaults for messages.

Templates

In order to avoid repeating identical message structure definitions over and over again, field templates were introduced and these have to be placed into the file named "_templates.csv".

A field template definition consists of the following columns:

• TEMPLATE
  The name of the field template.
• TYPE or TEMPLATE[;TEMPLATE]*
  The name of the base data type or a list of already defined template names separated by semicolon.
• [DIVIDER] or [VALUE=NAME][;VALUE=NAME]*
  The divider to apply on the numeric base type or a list of name/value associations separated by semicolon.
• [UNIT]
  The value unit (e.g. "°C").
• [COMMENT]
  A comment for the field.

Example

name	type/templates	divider/values	unit	comment
temp	D2C		°C	temperature
sensor	UCH	0=ok;85=circuit		sensor status
tempsensor	temp;sensor
calibration	D2C		K

Messages

A message definition starts with message specific columns and is followed by one or more field definitions.

Message definition

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

• [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 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.

• [CLASS]
  The class of the message (to distinguish several messages with the same name).

• NAME
  The name of the message.

• [COMMENT]
  The message comment.

• [QQ]
  The master address of the source unit in hex, or empty for any (e.g. "10").

• ZZ
  The address of the destination unit in hex (e.g. "15" or "FE" for broadcast).

• 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.

This message definition part is followed by one or more field defintions 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:

• [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)
• TYPE or TEMPLATE[;TEMPLATE]*
  The name of the base data type or a list of referenced template names separated by semicolon.
• [DIVIDER] or [VALUE=NAME][;VALUE=NAME]*
  The divider to apply on the numeric base type or a list of name/value associations separated by semicolon.
• [UNIT]
  The value unit (e.g. "°C").
• [COMMENT]
  A comment for the field.

Example

type	class	name	comment	QQ	ZZ	PBSB	ID	field1 name	part	type/templates	divider/values	unit	comment	field2 name	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

Message defaults

Usually, field values can not only be read from a device but also be written to that device. In order to avoid duplicate message definitions, defaults can be used.

A row starting with a star symbol "*" in front of a message type defines the defaults for further rows in that file. The defaults will then be used for blank columns of a message definition with that message type (ignoring the poll priority).

One exception to this generic approach is the "ID" column: The value of the ID column in a defaults row will be prepended to the ID column in message definitions of that type having an empty PBSB column.

Fields part of a defaults row will be prepended to the fields of a message definition of that type.

Example

Scanning

For scanning, the eBUS identification message with PB=07h and SB=04h is used. For each slave answering to this message, all messages with the class "scan" defined in any of the loaded configuration files are initiated as well and appended to the scan result with a semicolon as separator.

For this particular kind of message, the "ZZ" field may be empty in the configuration file, since it will be filled with the slave address during the scan.

Base data types

The base data types supported by the daemon all have a name built of three alphanumeric characters.
Many of these types have a fixed length binary representation (i.e. the number of bytes "on the wire"). For types with flexible length, the desired width can simply be appended after a colon, e.g. "HEX:4" would be four hex bytes.
For the bit types "BI0"-"BI7" the length suffix is the number of bits, whereas for all other types it is the number of bytes.

The following base data types are available (fixed or flexible lenght as noted in brackets):

• "IGN": ignored data (1-16 bytes)
• "STR": character string filled up with space, e.g. "Hello " (1-16 bytes)
• "HEX": hex digit string separated by space, e.g. "0a 1b 2c 3d" (1-16 bytes)
• "BDA": BCD date (binary representation starting with day and including weekday, Sunday=0x06, 4 bytes)
• "BDA:3": BCD date (binary representation starting with day and excluding weekday, 3 bytes)
• "HDA": BCD date (binary representation starting with day and including weekday, Sunday=0x07, 4 bytes)
• "BTI": BCD time as "hh:mm:ss" (binary representation starting with seconds, 3 bytes)
• "HTI": time as "hh:mm:ss" (binary representation starting with hours, 3 bytes)
• "VTI": time as "hh:mm:ss" (binary representation starting with seconds, 3 bytes)
• "HTM": time as "hh:mm" (binary representation starting with hours, 2 bytes)
• "TTM": truncated time as "hh:m0" (multiple of 10 minutes, 1 byte)
• "BDY": weekday as "Mon"-"Sun" (Sunday=0x06, 1 byte)
• "HDY": weekday as "Mon"-"Sun" (Sunday=0x07, 1 byte)
• "BCD": unsigned BCD, 0-99 (1 byte)
• "PIN": unsigned BCD, 0000-9999 (2 bytes)
• "UCH": unsigned integer, 0-254 (1 byte)
• "SCH": signed integer, -127 - +127 (1 byte)
• "D1B": signed integer, -127 - +127 (1 byte)
• "D1C": unsigned number, 0.0-100.0 (fraction 1/2, divisor 2, 1 byte)
• "UIN": unsigned integer, 0-65534 (2 bytes)
• "SIN": signed integer, -32767 - +32767 (2 bytes)
• "FLT": signed number, -32.767 - +32.767 (fraction 1/1000, divisor 1000, 2 bytes)
• "D2B": signed number, -127.99 - +127.99 (fraction 1/256, divisor 256, 2 bytes)
• "D2C": signed number, -2047.9 - +2047.9 (fraction 1/16, divisor 16, 2 bytes)
• "ULG": unsigned integer, 0-4294967294 (4 bytes)
• "SLG": signed integer, -2147483647 - +2147483647 (4 bytes)
• "BI0" - "BI7": bit 0-7 (1-7 bits)

The minimum length noted in brackets is also used as default length.