Skip to content

4. Configuration

Jump to bottom
John edited this page Feb 14, 2015 · 32 revisions

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

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.

Clone this wiki locally