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. Each file is supposed to describe the messages that may be sent to or by a singular unit on the bus.

All of these files reside in the ebusd configuration directory (see Run). 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 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, templates were introduced and these have to be placed into the file named "_templates.csv".

A template definition consists of the following columns:

• template name
  The name of the template.
• base data type or referenced template names
  The name of the base data type or a list of already defined template names separated by semicolon.
• [divider] or [list of possible values]
  The divider to apply on the numeric base type or a possible values separated by semicolon (in the form "value=name").
• [unit]
  The value unit (e.g. "°C").
• [comment]
  A comment for the template.

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 some common columns and is followed by one or more field definitions.

Message definition

The common message definition columns are:

• [type(s)] - 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 types are available:

• "r": read
  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 name]
  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)
• base data type or list of referenced template names
  The name of the base data type or a list of template names separated by semicolon.
• [divider] or [list of possible values]
  The divider to apply on the numeric base type or a possible values separated by semicolon (in the form "value=name").
• [unit]
  The value unit (e.g. "°C").
• [comment]
  A comment for the type.

Example

type	class	comment	QQ	ZZ	PBSB	ID	field1-name	part	type/templates	divider/values	unit	comment
r1	ehp			08	B509	0D0F00	temp		D2C		°C	temperature
r	ehp			08	B509	0DCD00	tempcal		D2V		K
w	ehp			08	B509	0ECD00	tempcal		D2C		K

Message defaults

Usually, field values can not only be read from a unit but also be written to that unit. 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 the remaining rows in that configuration 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 is the "ID" column: The value of the ID column in the defaults row will be prepended to the ID in the message definition unless the PBSB column is non-empty.
If a defaults row contains one or more fields, these will also be prepended to all fields in the message definition.

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

• "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 denoted minimum length in brackets is also used as default.