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 one particular 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).

In case the "--scanconfig" option is enabled, only the files residing directly in the configuration directory are read during startup. Further files in subdirectories are then loaded after scanning new slaves seen on the eBUS. The subdirectory needs to match the manufacturer name (all lower case) and the configuration file name determines for which slave, identification, software, and/or hardware version it is suitable.

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 repetitions of identical field definitions, the field templates were introduced. These have to be placed into a file named "_templates.csv" (either directly in the configuration directory or a subdirectory in which case the templates are only valid for message definitions in that subdirectory).

A field template definition consists of the following columns:

• TEMPLATE[:FIELDNAME]
  The name of the template, optionally followed by the field name that will be used when the template is referenced by a message definition.
• DATATYPE|TEMPLATE[;DATATYPE|TEMPLATE]*
  A list of base data types and/or 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 (value either in decimal or starting with "0x" for hex).
• [UNIT]
  The value unit (e.g. "°C").
• [COMMENT]
  A comment for the field.

Example

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

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

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

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)
• DATATYPE|TEMPLATE[;DATATYPE|TEMPLATE]*
  A list of base data types and/or 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 (value either in decimal or starting with "0x" for hex).
• [UNIT]
  The value unit (e.g. "°C").
• [COMMENT]
  A comment for the field.

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

The example from the previous paragraph can be further reduced using defaults and templates like this:

type	circuit	name	comment	QQ	ZZ	PBSB	ID	field1	part	type/templates
*r	ehp				08	B509	0D
*w	ehp				08	B509	0E
r1		brinetemp					0F00			tempsensor
r;w		brinetempcal					CD00			calibration
Download CSV

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 CIRCUIT "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" column 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": hex date (binary representation starting with day and including weekday, Sunday=0x07, 4 bytes)
• "HDA:3": hex date (binary representation starting with day and excluding weekday, 3 bytes)
• "BTI": BCD time as "hh:mm:ss" (binary representation starting with seconds, 3 bytes)
• "HTI": hex time as "hh:mm:ss" (binary representation starting with hours, 3 bytes)
• "VTI": hex time as "hh:mm:ss" (binary representation starting with seconds, 3 bytes)
• "HTM": hex time as "hh:mm" (binary representation starting with hours, 2 bytes)
• "VTM": hex time as "hh:mm" (binary representation starting with minutes, 2 bytes)
• "TTM": truncated time as "hh:m0" (multiple of 10 minutes, 1 byte)
• "TTH": truncated time as "hh:m0" (multiple of 30 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)
• "BCD:2": unsigned BCD, 0-9999 (2 bytes)
• "BCD:3": unsigned BCD, 0-999999 (3 bytes)
• "BCD:4": unsigned BCD, 0-99999999 (4 bytes)
• "HCD": unsigned BCD hex, 0-99999999 (each BCD byte converted to hex, 4 bytes)
• "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.

Probing the configuration

Once the configuration files are prepared, the daemon should be called with the command line option "--checkconfig" in order to check the configuration files for validity. With this option, ebusd will not fork into background and not open any device or network port, but only probe the files, print out problems to stdout and terminate.

In addition to that, when using the command line option "--dumpconfig" the daemon will check the configuration files and on success print all message definitions in CSV configuration file format with all templates resolved to the final value.