Repository files navigation

If you are interested in more/other details, do not hesitate to consult this series of blog articles (french)Domotiser son chauffage avec Home Assistant.

Hardware related information is at:./hardware_reversing/.

Any help in filling in the gaps isVERY welcome.

In an ethical world we wouldn't have to spend so much time trying to reverse this kind of proprietary protocols.If you don't think it's appropriate, if you don't have the energy to do this tedious/time-consuming/ work,or if you don't want to buy the overpriced devices sold by these companies, then you should considerto go with manufacturers who respect your right to repair/modify what you own without ruining yourself.

And you would be wise to do so.

This project took aLOT of time in reverse engineering, making the integration with Home Assistant,including documentation & tests.If it has been useful to you in any way, saving you time and hopefully energy or money for your home,you can consider the followingdonation links or at leastadd a star to the project.Any participation is appreciated because it means that the time invested was not in vain.

1EB6dc6YULzHR4TMqLi5fomZ6wmdP3N5cW

Some links to understand the interest of these data and their organization.

• Message-definition
• Defaults
• Builtin-data-types
• Field-templates

Put the.csv files into a directory, then launchebusd with--configpath argument.

Example of command used to launch ebusd daemon:

ebusd -d 192.168.1.65:3333 --latency=200000 --configpath=/path_to_your_config_files/ --enablehex --receivetimeout=100 --sendretries=2

Logs will be generated into/var/log/ebusd.log.

Monitor unknown messages:

watch -n 3 -d ./build/src/tools/ebusctl grab result

See the Readme here:./home_assistant_integration/.

Here is a quick usage example. Keep in mind thatread queries return cached values by default (see-m setting of ebusctl).Raw hex queries are not concerned by caching issues.

Turn on the heating (winter mode/ability to heat water in heaters if you prefer):

$ ebusctl write -c boiler heating_status on# or$ ebusctl hex 3c 2020 03 0120 01

Activate the heating of the water (command sent by thermostat for example):

$ ebusctl write -c boiler z1_heating_activation on# or$ ebusctl hex 3c 2020 03 1919 01

In SRA mode with an external temp probe, read the computed temp for the first 3 zones:

$ ebusctl read -c boiler hot_water_target_temp_143.4;58.0;58.0# or$ ebusctl hex 3c 2000 02 6197

Now, increase the offset of temp starting the computed temp:

$ ebusctl write -c boiler z1_thermoreg_offset 6

Check the modification:

$ ebusctl read -c boiler hot_water_target_temp_149.4;58.0;58.0

*: 2010 command may be for values that should not be modified by a device and thatshould be accepted by another.i.e calculated/measured/status values (current temp measured, boiler status,settings change counter, computed target temp, heat request status).2020 commands may be for values that can be modified on the device and accepted by another.

**: Timer programs protocol is described below

Note: Naming is subject to change.Note: In case of multiple values, there is 1 value per zone (z1, z2, etc.).

*: Yes, the boiler life time value is accessible in read AND write modes...

• packets are emitted every minute
• there are 14 different packets
• the rotation of packets occurs every 14 minutes
• the usable field is alternated every minute
• there are 2 different fields per program
• each usable field is composed of 24 nibbles/quartet, so 12 bytes, it covers 12 hours with a precision of 30 min

Packets dump (packets are ordered by reception time):

Prog 1000000000000555555555555    => Heating enabled from 6h to 12h555555555555555555550000    => Heating enabled from 12h to 22hProg 2000000000000555500000000    => Heating enabled from 6h to 8h555500000055555555550000    => Heating enabled from 12h to 14h, then from 17h to 22hProg 3000000000000555500000000    => Heating enabled from 6h to 8h000000005555555555550000    => Heating enabled from 16h to 22hDefault prog000000000000004055150000    => ???000000000000000000000000    => no heating

• Appearance/disappearance packets always go through 3 repetitions.

• The order of appearance plays no role since they can be deleted in any order.However, an error masks the previous one on the display.

• Unknown errors (not supported by the boiler) are displayed as---, and cannot(for now?) be removed unless a bus reset command is sent.However, they do not prevent further testing of other errors.

• Some errors are silent because they are not displayed. For example, disconnecting the externaltemperature sensor always triggers an error (0xec). On the other hand, disconnectingit when the control mode is 3 or 4 (external sensor required) will generate an additionalerror0x0c, code114, which is displayed this time.

• The resolution command is made of the error code, followed by a default byte.

• The minimal trigger command is made of the error code, followed by the default byte + a flag value.

• You can generate/replay errors by broadcasting them, not just by touching the hardware(which is very useful for reversing).In this way, the following command will generate a411 error (z1 missing ambient probe)on the boiler display :

  ~/ebusd/build/src/tools/ebusctl hex fe20040469030061

However, to remove it, you need to use its resolution command :

~/ebusd/build/src/tools/ebusctl hex fe200403690100

Any packet error consists of:

QQ,ZZ,PBSB,SS,XX,YY,00,ZZ

• QQ: src address
• ZZ: dest address
• PBSB: command bytes, always 2004 here
• SS: packet length in bytes
• XX: error code (which we want to map with the code displayed on the boiler)
• YY: zone flags (see below)
• 00: spacer ?
• ZZ: specific error codes sent by the boiler but not mandatory to define an error=> redundant data ?

Each bit in YY byte has a signification. The LSB seems to be always set when a zone is concerned.

Here is a table with all the zone flags deducted from packet sniffing operations :

The XX and YY bytes, for a missing ambient probe on z1 (error 411)and z2 (error 412) will be :

XX: 0x69                                       <= code for "missing ambient probe" errorYY: zone_enable + z1 + z2 = 1 + 2 + 4 = 0x07

Thus, the minimal trigger command will be :

fe2004026907

The resolution command is the YY byte without the flags, but it's still an error related to some zones,so thezone_enable flag must be set :

fe2004026901

In fact, other bytes are present after YY such as ZZ sequence; but they are not mandatoryto trigger and resolute errors.

Steps to reverse the protocol:

• Disconnect ambient probe from eBus if there is one ;
• Set the thermoregulation type (command ids c079,c07a,c07b,c07c,c07d,c07e)to a mode that require it (4) for the various zones (z1 to z6) ;
• Wait for packets in ebusd logs ;
• Switch the thermoregulation type to 0 or 1 for a zone and wait for the resolution packet

# Trigger missing ambient probe z1 (411) by switching c079 to mode 4~/ebusd/build/src/tools/ebusctl hex fe202003c0790400:44:57.863     37fe200404 6903006100:44:57.985     37fe200404 6903006100:45:27.857     37fe200404 69030061# Resolution by switching to mode 0~/ebusd/build/src/tools/ebusctl hex fe202003c0790000:49:15.420     37fe200403 69010000:49:17.620     37fe200403 69010000:49:27.642     37fe200403 690100# Trigger missing ambient probe z2 (412) by switching c07a to mode 4~/ebusd/build/src/tools/ebusctl hex fe202003c07a0400:55:03.297     37fe200404 6905006200:55:07.301     37fe200404 6905006200:55:27.314     37fe200404 69050062# Resolution by switching to mode 1~/ebusd/build/src/tools/ebusctl hex fe202003c07a0100:55:56.450     37fe200403 69010000:55:57.279     37fe200403 69010000:57:27.213     37fe200403 690100# Trigger missing ambient probe z3 (413) by switching c07b to mode 4~/ebusd/build/src/tools/ebusctl hex fe202003c07b040:58:44.920      37fe200404 690900630:58:47.124      37fe200404 690900630:59:27.108      37fe200404 69090063# Resolution by switching to mode 1~/ebusd/build/src/tools/ebusctl hex fe202003c07b0101:00:28.030     37fe200403 69010001:00:37.280     37fe200403 69010001:01:27.235     37fe200403 690100

Trigger missing ambient probe errors for z4 + z5 + z6 + z3 + z2 + z1 via the previously showed commands.

See:Bruteforce the errors to discover their corresponding codes.

See the Readme here:./home_assistant_integration/.

*: Zone error : variations for each zone are not displayed

Missing codes for Mira C Green (not supported?) : '302', '305', '307'

Just use the interactive scripthere.It can be adapted with the displayed expected codes from the boiler documentation.Feel free to modify the settings of the script (i.e. the variablesEBUSCTL_BIN_PATH, LOG_FILE, EXPECTED_ERRORS).

Every boiler owner should run this program to obtain the error codes for your equipment.These are quite specific, and this procedure remains necessary until a database is built up.

• Installation:

  $ pip install --user (--break-system-packages) argparse colorama

  Use --break-system-packages if you know what you are doingand not working inside a virtual env.

• Usage:

$ ./bruteforce_errors.py -husage: bruteforce_errors.py [-h] {find_errors,analysis} ...options:-h, --help              show thishelp message andexitsubcommands:{find_errors,analysis}    find_errors         Broadcast errors& waitsfor the user to enter the                        code displayed on the boiler. Results are storedin                        the log file definedin LOG_FILE. User can skip the                        current code or quit at any time. Each error code is                        reset before the next test. If the reset is not                        effective, a bus reset can be triggered.    analysis            Display missing& extra codes vs the expected ones                        definedin EXPECTED_ERRORS; Output mapped errorsfor                        ebusd config file: _templates.csv.

$ ./bruteforce_errors.py find_errors -husage: bruteforce_errors.py find_errors [-h] [-s START] [-e END]options:  -h, --help            show thishelp message andexit  -s START, --start START                        Start valuefor code search (0<= val<= 255) (default: 0)  -e END, --end END     End valuefor code search (0<= val<= 255) (default: 128)

For example, to analyze the results of a boiler interrogation:

$ ./bruteforce_errors.py analysisMissing codes: ['302', '305', '307', '411', '412', '413']Excess codes: ['---', '102', '109', '111', '120', '121', ...]CSV template string: 0=101;1=102;2=1P1;3=1P2;4=1P3;5=104;6=107;7=1P4;8=1P4;...

Missing codes, are expected codes from your user manual but not found/functional ;excess codes are codes that are not in the user manual but are supported by the hardware.

The CSV template string can be used as it is in the ebusd config file (_templates.csv).

Use the interactive scripthere.Take the time to read the comments and adapt the script to your needs!

If you're looking for a register that manages an option you can read/modifyon your boiler control panel, then this script is for you.

LikeCheat Engine, by successive iterations and pruning, you'll be able to identify the register.

The script is mainly made to search for registers like the very important1919,which is used to switch the boiler ON/OFF from a thermostat for the Mira C Green boiler.

This register seems to be sent only by an eBus thermostatand it stays at 0 without it.The boiler doesn't broadcast its status.

People without "smart" thermostat (i.e. people that only have a thermostat withdry contact connected to the TA1 pins of the boiler's motherboard)can't guess the register without such a bruteforce script.

General process:

• With some "read" iterations you will find registers that have changed(ex: Those that have a value of 0 when the boiler is off, and that havea value of 1 when it's on). The script can be modified to adopt another behaviour.

• Then, "write" tests can be started. Multiple registers are testeduntil the boiler responds. The interactive script will help you to find theunique triggering register.

Installation:

$ pip install --user (--break-system-packages) colorama

Use --break-system-packages if you know what you are doingand not working inside a virtual env.

TODO: help needed; See Issue#3.

• Handshake study of new device on the bus in order to emulate it with a custom one.
• Packet dissections for missing ids. For example:

37fe2020 0c c079 01 c07a 01 c07b 01 c07c 01            z1 heat thermoregulation selection37fe2020 0c c07d 01 c07e 01 c07f 01 c279 0a            ^z5     ^z6     ^z7     ^z1 heat room temp influence37fe2020 0c c27a 0a c27b 0a c27c 0a c27d 0a            ^z2     ^z3     ^z4     ^z5 heat room temp influence37fe2020 0c c27e 0a c27f 0a c679 03 c67a 03            ^z6     ^z7     ^z1 ??  ^z2 ??37fe2020 0c c67b 03 c67c 03 c67d 03 c67e 03            ^z3     ^z4     ^z5 ??  ^z6 ??37fe2020 0c c67f 03 c979 06 c97a 06 c97b 06            ^z7     ^z1     ^z2 ??  ^z3 ??37fe2020 0c c97c 06 c97d 06 c97e 06 c97f 06            ^z4     ^z5     ^z6 ??  ^z7 ??

• https://github.com/wrongisthenewright/ebusd-configuration-ariston-bridgenet
• https://github.com/komw/ariston-bus-bridgenet-ebusd
• john30/ebusd-configuration#103
• john30/ebusd-configuration#27

Released under the GPL (General Public License).