This page is part of archived documentation for openHAB 2.5. Go to the current stable version
# eBUS Binding v1
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 (opens new window)). 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 <Badge type="warn" text="v1"/>
# Valid values are e.g. COM1 for Windows and /dev/ttyS0 or /dev/ttyUSB0 for Linux <Badge type="warn" text="v1"/>
serialPort=COM2
# TCP Hostname and Port <Badge type="warn" text="v1"/>
# Warning: Only use ebus.hostname or ebus.serialPort <Badge type="warn" text="v1"/>
#hostname=myhostname
#port=5000
# Custom parser configuration file <Badge type="warn" text="v1"/>
# This example tries to load a configuration ${openhab_home}/configurations/ebus-config.json <Badge type="warn" text="v1"/>
#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. <Badge type="warn" text="v1"/>
# https://github.com/openhab/openhab/wiki/eBUS-IDs <Badge type="warn" text="v1"/>
#
# >> Deprecated <Badge type="warn" text="v1"/>
#
# >> _vaillant - All older vaillant telegrams (will be merged in other files) <Badge type="warn" text="v1"/>
# >> _wolf-35 - All older Wolf eBUS dst address 0x35 telegrams (will be merged in other files) <Badge type="warn" text="v1"/>
#
# >> Productive <Badge type="warn" text="v1"/>
#
# >> common - Commands from eBUS standard <Badge type="warn" text="v1"/>
# >> vaillant-bai00 - All Vaillant BAI000 telegrams <Badge type="warn" text="v1"/>
# >> vaillant-vrc430 - All Vaillant VRC430 telegrams <Badge type="warn" text="v1"/>
# >> vaillant-vrc470 - All Vaillant VRC470 telegrams <Badge type="warn" text="v1"/>
# >> vaillant-vrc630 - All Vaillant VRC630 telegrams <Badge type="warn" text="v1"/>
# >> vaillant-vr90 - All Vaillant VR90 telegrams <Badge type="warn" text="v1"/>
# >> wolf-cgb2_hc - All boiler Wolf CGB2 heating curve telegrams <Badge type="warn" text="v1"/>
# >> wolf-cgb2 - All boiler Wolf CGB2 telegrams <Badge type="warn" text="v1"/>
# >> wolf-sm1 - All Wolf Solar Module SM1 telegrams <Badge type="warn" text="v1"/>
# >> custom - Use configuration defined by parserUrl <Badge type="warn" text="v1"/>
#
# default uses common and all vendor specified telegrams <Badge type="warn" text="v1"/>
#parsers=common,wolf,testing,custom
# Write all/debug/unknown telegrams to a CSV file in folder {openhab}/etc/ebus <Badge type="warn" text="v1"/>
#record=all,debug,unknown
# Set the sender id of this binding, default is "FF" <Badge type="warn" text="v1"/>
#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 (opens new window) | Standard eBUS commands, Vendor independent |
| Vaillant BAI00 (opens new window) | Vaillant BAI00 |
| Vaillant VRC430 (opens new window) | Vaillant VRC430 controller |
| Vaillant VRC470 (opens new window) | Vaillant VRC470 controller |
| Vaillant VRC630 (opens new window) | Vaillant VRC630 controller |
| Vaillant VR90 (opens new window) | Vaillant VR90 controller |
| Wolf CGB2 (opens new window) | Wolf CGB2 Boiler, used in Heating system Wolf CSZ-2 |
| Wolf CGB2 HC (opens new window) | Wolf CGB2 Boiler (Heating Curve), used in Heating system Wolf CSZ-2 |
| Wolf SM1 (opens new window) | Wolf Solar Module, used in Heating system Wolf CSZ-2 |
You can find a complete list of all supported devices here (opens new window).
# 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 (opens new window) (german language, use translator)
This is an automatic created list of all included configuration files.
- common (opens new window)
- vaillant-bai00 (opens new window)
- vaillant-vr90 (opens new window)
- vaillant-vrc430 (opens new window)
- vaillant-vrc470 (opens new window)
- vaillant-vrc630 (opens new window)
- wolf-cgb2 (opens new window)
- wolf-cgb2_hc (opens new window)
- wolf-sm1 (opens new window)
- _testing (opens new window)
- _vaillant (opens new window)
- _vaillant-vrc470 (opens new window)
- _wolf-35 (opens new window)
- _wolf (opens new window)
- _wolf-test (opens new window)
← DwdUnwetter Ecobee →