eBUS Binding

The eBUS binding allows you to control your heating system. The eBUS protocol is used by heating system vendors like Wolf, Vaillant, Kromschröder etc. You can read temperatures, pump performance, gas consumption etc.

 ┌────────┐                       serial/usb (rs232) ┌──────┐
 │        │  serial (eBUS)  ┌───┐ or ethernet        │ ──── │
 │        │<--------------->│ X │<------------------>│ :    │
 │  ◊◊◊◊  │                 └───┘                    └──────┘
 └────────┘
Heating Unit             eBUS Adapter              openHAB Server

To access your heating system you either need an eBUS interface. You can buy a ready interface or solder your own circuit (examples: eBUS Wiki). A simple read-only interface can be build with an Arduino device.

Binding Configuration

The binding can be configured in the file services/ebus.cfg.

Property Default Required Description
serialPort   if connecing via serial port Serial port of eBUS interface. Do not use as well as hostname/port.
hostname   if connecting via network TCP host name or IP address of eBUS interface. Do not use as well as serialPort.
port   if connecting via network TCP port of eBUS interface, 5000 for example
parseUrl     Custom parser configuration file
parsers     One or more parsers for you eBUS device, separated by commas. You can find the latest devices below or on the wiki page. List of productive parsers as of this writing: common, vaillant-bai00, vaillant-vrc430, vaillant-vrc470, vaillant-vrc630, vaillant-vr90, wolf-cgb2_hc, wolf-cgb2, wolf-sm1, custom
record     Comma-separated list of telegram types (all,debug,unknown) to write to a CSV file in folder {openhab}/etc/ebus
senderId FF No Set the sender id of this binding

Example

# Serial port of eBUS interface
# Valid values are e.g. COM1 for Windows and /dev/ttyS0 or /dev/ttyUSB0 for Linux
serialPort=COM2

# TCP Hostname and Port
# Warning: Only use ebus.hostname or ebus.serialPort
#hostname=myhostname
#port=5000

# Custom parser configuration file
# This example tries to load a configuration ${openhab_home}/configurations/ebus-config.json
#parserUrl=platform:/base/../configurations/ebus-config.json

# Define one or more parsers for you eBUS device. You can find the latest devices below or on the wiki page.
# https://github.com/openhab/openhab/wiki/eBUS-IDs
#
# >> Deprecated
#
# >> _vaillant - All older vaillant telegrams (will be merged in other files)
# >> _wolf-35 - All older Wolf eBUS dst address 0x35 telegrams (will be merged in other files)
#
# >> Productive
#
# >> common -  Commands from eBUS standard
# >> vaillant-bai00 - All Vaillant BAI000 telegrams
# >> vaillant-vrc430 - All Vaillant VRC430 telegrams
# >> vaillant-vrc470 - All Vaillant VRC470 telegrams
# >> vaillant-vrc630 - All Vaillant VRC630 telegrams
# >> vaillant-vr90 - All Vaillant VR90 telegrams
# >> wolf-cgb2_hc - All boiler Wolf CGB2 heating curve  telegrams
# >> wolf-cgb2 - All boiler Wolf CGB2 telegrams
# >> wolf-sm1 - All Wolf Solar Module SM1 telegrams
# >> custom - Use configuration defined by parserUrl
#
# default uses common and all vendor specified telegrams
#parsers=common,wolf,testing,custom

# Write all/debug/unknown telegrams to a CSV file in folder {openhab}/etc/ebus
#record=all,debug,unknown

# Set the sender id of this binding, default is "FF"
#senderId=FF

A sample configuration could look like:

serialPort=COM2
parsers=common,wolf

Items Configuration

The syntax for the eBUS binding configuration string is explained here:

ID’s

The binding uses unique ID’s to identifiy eBUS telegrams from the internal database. The ID has a hierarchical structure and is in each case separated by a dot.

<command-class>.<command-id>.<value>
ID Part Description
<command-class> Groups multiple commands to logical class like heating, boiler, solar etc.
<command-id> This is the identifier for the command
<value> The name of a result value, only required if the telegram contains more than one value

List of ID’s

ID’s Description
Common Standard eBUS commands, Vendor independent
Vaillant BAI00 Vaillant BAI00
Vaillant VRC430 Vaillant VRC430 controller
Vaillant VRC470 Vaillant VRC470 controller
Vaillant VRC630 Vaillant VRC630 controller
Vaillant VR90 Vaillant VR90 controller
Wolf CGB2 Wolf CGB2 Boiler, used in Heating system Wolf CSZ-2
Wolf CGB2 HC Wolf CGB2 Boiler (Heating Curve), used in Heating system Wolf CSZ-2
Wolf SM1 Wolf Solar Module, used in Heating system Wolf CSZ-2

You can find a complete list of all supported devices here.

Parameters

This binding allows you to combine a set of parameters to get/set or request values on your heating system.

If you only want to read a value, you just need to set the parameters id. You can find a list above.

Sometimes more than one bus participant will send telegrams with given id. To filter the telegrams you can use the properties dst (destination address) and src (source address).

Reading parameters

ebus="id:<id>"
ebus="id:<id>, src:<src>"
Parameter Description
id Defined to read a value from eBUS. Sometimes you can access the same value with different ids with different precisions.
dst Filter telegrams for a specified destination eBUS address (hex string).
src Filter telegrams for a specified source eBUS address (hex string).

Writing parameter

ebus="id:<id>, dst:<dst>, refresh:<refresh>"
ebus="id:<id>, dst:<dst>, refresh:<refresh>, set:<set>"

ebus="id:<id>, cmd:<cmd>, dst:<dst>, refresh:<refresh>"
ebus="id:<id>, cmd:<cmd>, dst:<dst>, refresh:<refresh>, set:<set>"
ebus="id:<id>, dst:<dst>, refresh:<refresh>, set:<set>"
Parameter Description
id Defined to read a value from eBUS. This normally also identifies a request-command for polling.
cmd Defines the request-command that should be send on refresh interval. Normally this parameter is not needed, because parameter id also identifies the configuration.
refresh Sends the request-command every n seconds (polling), requires parameter id or if not similar cmd.
set Defines a value that should be set. This requires special set commands.
dst Filter telegrams for a specified destination eBUS address (hex string).
src Filter telegrams for a specified source eBUS address (hex string).

Normally you send a request and expects an answer from a bus participant. But this binding works asynchronous, hence you can get return values only indirectly by using the read parameters. By this way you can update one or more items with only one command because a telegram can contain multiple values.

You should look at the examples below to understand the different cases.

The binding tries to send a commando up to five times before it cancels a request. You only get a short warning in the log. So this is fire-and-forget.

Set value

To set a value you have to use the parameter set. But you need special commands that accepts setting values. You can only set one value per item (binding/openhab limitation).

Polling

On some systems it is required to request answers from bus participants regularly. In this case you can use the parameter refresh to send the request-command or RAW data automatically every n seconds. You must add parameter cmd if it is not similar to parameter id.

RAW data

It is also possible to send a raw eBUS telegram directly without any programmatic help. You have to write the telegram as hex string like FF 08 50 22 03 CC 9A 01 00. The last byte will be automatic replaced by a valid checksum if it not the sync byte FF.

You should use this parameter only in special cases and prefer cmd instead.

Parameter Description
cmd This allows you to send a command to the eBUS.
set Set a value id from a setter command
dst Define the destination eBUS address as hex value for the telegram.
src Defines the source eBUS address as hex value for the telegram. Or default value FF would be used. You can overwrite this inf ebus.cfg.
refresh If you set a refresh interval (sec.) the command will be automatic send via eBUS. This is usually used to poll data from your system.
data Instead of the cmd parameter you can send a raw telegram as hex string. The last byte will be replaced by the calculated crc value if is not FF.
data-{STATE} Same as parameter data, but is only send on the specified state of the item. As example you can define a switch item with data-ON and data-OFF to send two different telegrams per state.

Examples

Receive values from eBUS

ebus="id:burner.starts, dst:08"

This item configuration receives the number of firings from the eBUS. This is defined by parameter id. But in this case we only want telegrams with the destination address 0x08. But keep in mind that this a read-only configuration. So we can only receive values that are submitted as broadcast or requested by a device. Optionally you can also filter the source address with the parameter src.

Reading values from eBUS regularly (Polling)

ebus="id:burner.starts, dst:08, src:FF, refresh:60"
ebus="id:burner.starts, cmd:burner.starts, dst:08, src:FF, refresh:60"

This examples (both are do the same) are similar to the previous example, but here we active request this value every 60 seconds from the bus (Polling). If you can read multiple values with one command it’s enough to send the command once. In this example the source address is explicit set to a hex string. If parameter cmd and id are equal you can omit parameter cmd.

Set a value

ebus="id:heating.program_heating_circuit, set:heating.set_program_heating_circuit.program, dst:08"

This example uses the set_program_heating_circuit command to set the value program to a new value.

Send raw telegrams, receive values

ebus="id:burner.starts, data:FF 08 50 22 03 CC 1A 27 00"

In this example we send a raw telegram as hex string instead a already defined command. The last byte is replaced by the calculated crc value if it’s not 0xFF (eBUS sync byte). But you should prefer the cmd parameter.

Send raw telegram by item status

ebus="id:heating.no_of_firing, data-ON:FF 08 50 22 03 CC 1A 27 00, data-OFF:FF 08 50 22 03 CC 0E 00 00"

Similar to the last example, but we use different telegrams per item state. If you use a switch item you can send different telegram for the states ON or OFF.

Example for item configuration

Here is a longer example.

/** Heating **/
Group HeatingUnit                   "Heating"                                             (All)
Group Solar                         "Solar"                                               (All)

Group SOL_Chart1                                                                          (HeatingUnit)
Group SOL_Chart2                                                                          (HeatingUnit)
Group HU_Chart1                                                                           (HeatingUnit)
Group HU_Chart2                                                                           (HeatingUnit)
Number HU_Temp_Warm_Wather          "Hotwater temp.[%.1f °C]"           <temperature>     (HeatingUnit,SOL_Chart1)    { ebus="id:dhw.temp_dhw"}
Number HU_Temp_M_Warm_Wather        "Hotwater min. temp.[%.1f °C]"      <temperature>     (HeatingUnit)               { ebus="id:controller.temp_d_dhw"}
Number HU_Temp_T_Warm_Wather        "Hotwater temp(target)[%.1f °C]"    <temperature>     (HeatingUnit)               { ebus="id:controller2.temp_d_dhw, src:F1"}
Number HU_Temp_Heat_Vessel          "Boiler temp. [%.1f °C]"            <temperature>     (HeatingUnit,HU_Chart1)     { ebus="id:auto_stroker.temp_boiler, src:03"}
Number HU_Temp_T_Heat_Vessel        "Boiler temp. (target) [%.1f °C]"   <temperature>     (HeatingUnit,HU_Chart1)     { ebus="id:controller.temp_d_boiler"}
Number HU_Temp_Heat_Return          "HU. Return [%.1f °C]"              <temperature>     (HeatingUnit,HU_Chart1)     { ebus="id:boiler.temp_return"}
Number HU_Temp_Heat_Exhaust         "Exhaust temp. [%.1f °C]"           <temperature>     (HeatingUnit)               { ebus="id:boiler.temp_exhaust"}
Number HU_Temp_AvgOutdoor           "Avg. temp. outdoor [%.1f °C]"      <temperature>     (HeatingUnit)               { ebus="id:controller2.temp_outside, src:F1"}
Number HU_Temp_Outdoor              "Temp. outdoor [%.1f °C]"           <temperature>     (HeatingUnit)               { ebus="id:controller2.temp_outside, src:03"}
Switch SOL_Status_Pump              "Solar pump"                        <switch>          (Solar,SOL_Chart2)          { ebus="id:solar.solar_data.state_pump"}
Number SOL_Temp_Collector           "Sol. collektor temp. [%.1f °C]"    <temperature>     (Solar,SOL_Chart1)          { ebus="id:solar.solar_data.temp_collector"}
Number SOL_Temp_Return              "Sol. return temp. [%.1f °C]"       <temperature>     (Solar,SOL_Chart1)          { ebus="id:solar.temp_flow"}
Number SOL_Temp_Reservoir           "Sol. store temp. [%.1f °C]"        <temperature>     (Solar,SOL_Chart1)          { ebus="id:solar.solar_data.temp_cylinder"}
Number SOL_Yield_Sum                "Sol. sum yield [%.1f kW/h]"        <bar_chart>       (Solar)                     { ebus="id:solar.solar_yield.yield_total"}
Number SOL_Yield_Day                "Sol. day yield [%.2f kW/h]"        <bar_chart>       (Solar)                     { ebus="id:solar.solar_yield.yield_today"}
Number SOL_Yield_Current            "Current output[%.2f kW]"           <bar_chart>       (Solar,SOL_Chart2)          { ebus="id:solar.solar_yield.output_current"}
Number HU_Performance_Burner        "Unit output [%s %%]"               <bar_chart>       (HeatingUnit)               { ebus="id:boiler.level_modulation"}
Number HU_Performance_Pump          "Pump output[%s %%]"                <bar_chart>       (HeatingUnit)               { ebus="id:heating.modulation_pump"}
Number HU_No_Of_Firing              "No. of Firing[%s]"                 <bar_chart>       (HeatingUnit)               { ebus="id:burner.starts"}
Number HU_Op_Hrs                    "Op. hours unit[%s h]"              <bar_chart>       (HeatingUnit)               { ebus="id:boiler.runtime"}
Switch HU_Status_Alarm              "Alarm [MAP(yesno_de.map):%s]"      <siren>           (HeatingUnit)               { ebus="id:auto_stroker.state_alarm, src:03"}
Switch HU_Status_Fire               "HU. flame [MAP(de.map):%s]"        <gas2>            (HeatingUnit,HU_Chart1)     { ebus="id:auto_stroker.state_flame, src:03"}
Number HU_Status                    "HU. status [%s]"                   <settings>        (HeatingUnit)               { ebus="id:auto_stroker.status_auto_stroker, src:03"}
Number HU_Pressure_System           "System pressue [%.2f bar]"         <temperature>     (HeatingUnit)               { ebus="id:heating.pressure"}
Number HU_FW_Version                "Version[%.2f]"                     <bar_chart>       (HeatingUnit)               { ebus="id:boiler.fw_version"}
Number HU_StatusReq1                "Status Request 1 [MAP(hu_status_request1_de.map):%s]" <temperature> (HeatingUnit) { ebus="id:controller.status_heat_req1"}
Number HU_StatusReq2                "Status Request 2 [MAP(hu_status_request2_de.map):%s]" <temperature> (HeatingUnit) { ebus="id:controller.status_heat_req2"}
Number HU_Program_HC                "Program Heating Circuit [MAP(hu_heat_prog_de.map):%s]" <siren> (HeatingUnit)     { ebus="id:heating.program_heating_circuit, refresh:10, set:heating.set_program_heating_circuit.program"}
Switch HU_Status_Pump               "Pump [%s]"                         <__idea>            (HeatingUnit,HU_Chart1)   { ebus="id:auto_stroker.state_pump, src:03"}

Special loggers for developers

These loggers normally only interesting for developers. This loggers can cause huge log files.

org.openhab.binding.ebus.parser.EBusTelegramParser

This is the standard logger for this binding

org.openhab.binding.ebus.internal.parser.Analyses

This is a special logger to show/analyse the received telegrams

org.openhab.binding.ebus.internal.parser.BruteForce

This is a special logger to show raw telegram data

Custom Parser

You can add your own parser configuration by setting the property ebus:parserUrl in your openhab.cfg file. This is useful if you get new configuratiosn files that are not already included in this binding.

More information here (german language, use translator)

This is an automatic created list of all included configuration files.