Interfacing Vitovalor 300-P with a Raspberry Pi

I want to integrate my new Viessmann Vitovalor 300-P fuel cell heating into my home automation. For this, I use the Optolink interface, vcontrold from the openv community, and create my own configuration files from several sources.

If you want to skip the introduction bla-bla, you may directly go to

• Building the OptoLink connector
• Setting up vcontrold on a Raspberry Pi
• The Vitovalor-specific XML configuration files

My New Fuel Cell Heating

Since a few weeks its in my cellar: A brand new heating that sports a fuel cell module! Top notch! Its a Vitovalor 300-P by Viessmann. And of course I want to integrate this into my home automation! The heating comes with a LAN interface which connects it to Viessmann’s cloud service. This already allows me to use a smartphone to control the heating from abroad, and also offers a very detailed glance into every system parameter and measurement from the vitodata-website (very cool!), but there is no API to use for my own interfacing and purposes.

However, the heating features an OptoLink interface, which is basically an infrared (860 nm receiver, 880 nm sender) serial interface with a standard UART, using 4800 baud, 8bits, even parity and two stop bits with no handshake (4800,8,E,2). And since this is kind of a standard interface for nearly any Viessman heating since at least a decade, other enthusiasts have already done all the hard work to figure out how to interface with such heatings – mainly the openv project (mostly in German – sorry). Many, many thanks for their efforts and the great wiki pages and software!

There exists a simple and cheap circuit for interfacing with Raspberry Pi’s UART, and the vcontrold daemon that does all the communication with the heating, providing a concise command line interface via telnet for access from other programs. Really good work!

So, what remains to be done? Well, while OptoLink is kind of established, each and every Viessmann heating speaks its own dialect. vcontrold accepts an XML file that defines all commands the individual heating model understands; and here’s my todo: I need to work out the specifics of Vitovalor 300-P with its Vitotronic 200 RF HO1E control unit. Many commands are identical across a lot of heatings, but others are behaving differently for each model or exist just for one or a few models.

But first:

Building the OptoLink Connector

You can of course buy an original Viessmann Optolink cable, which does include an UART to USB bridge, but that sets you back by about 60 € – and where’s the fun? So I decided to build one myself, following the instructions for the Raspberry Pi UART interface from openv.

There is mainly one challange when building your own interface: The “V”. The V-shaped gap between sender and receiver is the only mechanical reference, and the original cable has a matching V-shaped protrusion to fit into the gap (Click here for an image of the original cable and the V shaped protrusion). Of course the best way would to 3D-print your own (and people have), but since I lack a 3D printer, I had to get creative.

First, I was lucky to find a plastic housing that nearly perfectly fit into the rectangular hole in front of the interface: A box that contained spring bars for wrist watches. It measures about 24 × 36 × 6 mm, which is slightly too broad, so you’ve to cut away the left and right flank. Perhaps you can find one at your local watchmakers or jewelers shop if you face the same task.

The transparant housing allowed to use a permanent marker to copy the V shape onto the plastic. Along these lines, I applied hot glue (several layers – 3D printing for the poor ), which then, using a sharp paper knife, I cut into the required V shape. Worked nicely on first try! The plastic gets rather scratched, but who cares…

Next, the openv article warns you that, if not properly shielded, there may be cross-talk between sender and receiver. So I added heat shrink tube to the holes for the receiver and sender, fixating it with superglue (The image only shows one hole covered, but the second also received shrink tube. In the image you can also see the cut away flanks of the box that otherwise would make it too broad to fit).

Openv strongly suggests a specific type of photo transistor and IR emitter diode, since others had problems with stray light or insufficient light transmission. While I was able to get the exact photo transistor, the IR LED is out of production. I searched for an IR LED with similar optical characteristics, and found IRL 81 A, wich as a side effect is much easier to fit into the confined space due to its form factor (click here for an image).

This LED requires a slightly different resistor. Also, because I had some issues due to the very long cable (about 10 m) I attached, I reduced the base resistor at the LED driver. So, here’s the part list and approximate cost:

Parts list

About 3.50 € as compared to 60.- € for the genuine article – a bargain

The circuit

Assembling it All

There is not much space for all the parts to go into. Other makers have just used larger housings, but the Vitovalor has a sliding door in front of the Optolink, and since I later want to close it in the end (hiding my ugly result…), I lacked that freedom. So I cut a small strip of hole matrix board that fits exactly into the long side of the box:

Putting two wires into one hole and in three cases using “free flying soldering”, I was able to cram everything onto this:

Not the tidiest bit of circuit, but works! However, in retrospect I might have fared better cutting a second strip, putting one on the top of the box, the other at the bottom. Might have made the alignment of the optical parts easier. If you have the possibility to etch a PCB, I’d recommend to go for this SMD version – is much nicer!

Finally, I cut a hole into the box for the cable, attached it to the circuit, crammed everything into the box and closed the box with tape at the edges. Then I attached the whole thing into the Optolink at the heating:

Works like a charm!

At the Raspberry, the pin assignments are:

Setting up vcontrold on the Raspberry Pi

I was tempted to just refer to the openv wiki page, but since it is in German, I give the translated instructions here – as tested by me with Raspbian Stretch.

Prerequisites

You’ll need a few packages:

sudo apt-get install subversion automake autoconf telnet libxml2-dev

Set up Serial Port

Since Raspberry Pi 3 the serial port assignments changed a bit. The “real” UART is assigned/reserved for Bluetooth. However, we need it for the interface. Also, we do not want the linux console to clutter the interface.

/boot/config.txt should contain these two lines:

enable_uart=1
dtoverlay=pi3-miniuart-bt

and /boot/cmdline.txt should not contain console=serial0,115200 (or something similar). A reboot is required for this taking effect.

A more complete explanation can be found on this Raspberry foundation page.

Getting the Source Code, Compiling, Installation

This just takes a few minutes – no need to cross compile on a more powerful PC.

cd ~
mkdir openv
cd openv
svn checkout svn://svn.code.sf.net/p/vcontrold/code/trunk vcontrold-code
cd vcontrold-code/vcontrold
chmod +x auto-build.sh
./auto-build.sh
./configure
make
sudo make install

After that, in /usr/local/bin there should be vcontrold, vclient and vsim.

Create and Edit /etc/vcontrold.xml

First, create a config directory and copy the template config files from the source into it:

sudo mkdir /etc/vcontrold
sudo cp ~/openv/vcontrold-code/xml-32/xml/vito.xml /etc/vcontrold/
sudo cp ~/openv/vcontrold-code/xml-32/xml/vcontrold.xml /etc/vcontrold/

Modify the unix section of /etc/vcontrold.xml:

In section tty, change the interface to the Raspberry UART /dev/ttyAMA0.

In section net, add the IP ranges or addresses you’d like to access the data from.

Insert the device ID for your heating – the Vitovalor is 20E3. Other IDs you may find here (old Wiki page – will soon migrate). If your ID is not in the list and in case your heating also comes with access to the vitodata-server, go there to the heating, choose “Diagnostics”, open the device group and look for the ZE-ID. This is E3 for the Vitovalor, which means 20E3 as vcontrold ID.

<unix>
   <config>
      <serial>
         <tty>/dev/ttyAMA0</tty>
      </serial>
      <net>
         <port>3002</port>
         <allow ip='127.0.0.1'/>
         <allow ip='192.168.0.0/24'/>
      </net>
      <logging>
         <file>/tmp/vcontrold.log</file>
         <syslog>y</syslog>
         <debug>y</debug>
      </logging>
      <device ID="20E3"/>
   </config>
</unix>

Test

Try if the daemon comes up properly using vcontrold -n. This should open a telnet server on port 3002. Otherwise look into /tmp/vcontrold.log – this is often helpful for troubleshooting, also later when trying to figure out the commands.

Init-Script for vcontrold Autostart on Boot

Copy this script below to /etc/init.d/vcontrol – this is just copied from the opnev wiki page – all credits go there, or to be more precise to Michael Pucher (thanks a lot!). Then register the script:

cd /etc/init.d/
sudo chmod u+x vcontrol
sudo update-rc.d vcontrol start 99 2 3 4 5 . stop 99 0 1 6 .

And that’s it.

Using vcontrold

To access the heating via vcontrold, connect via telnet:

telnet localhost 3002

You’ll see a prompt. help will show you all available commands – in German… But the most interesting is the command commands – it shows all commands that you can send to the heating. Be aware that this is all at your own risk! As far as I understand, most of all is reverse engineered, and thus prone to errors that – worst case – might damage your heating! There is no official Viessmann support for the openv/vcontrold project.

Creating the Vitovalor-specific XML for vcontrold

The protocols implemented by the Viessmann heatings use address-value pairs. Some are read-only, others allow read/write operations. The vito.xml file contains the necessary definitions of addresses, values and units, along with the commands to get or set the values. The units vito.xml refers to are then defined in vcontrold.xml. While many addresses are the same across many Viessmann models, some are model-specific, or – worst case – have different meanings with different models.

Data Sources

It is not that easy to come by the addresses for a specific model. The following sources I used:

• The vito.xml files available in the openv pages (currently the old links, migration in progress):
  • Universal vito.xml
  • two more
  • the vito.xml included in the vcontrold source
• Coding lists from the manual and vitodata
• The datapoint lists for Vitogate 200 KNX – you must try to find someone at Viessmann who is willing to provide them. The page refers you to your local Viessmann sales agency, and indeed I got my list from them. Even if you do not use the Vitogate, the datapoint lists contain the right addresses.
• Educated guesses (there are some repeating patterns in the addresses which allow you to guess others) and trial-and-error

Totally not helpful was the Viessmann Community – the general idea is nice, but the people there are really reluctant to offer anything beyond simple information.

Educated Guessing of Addresses

There are some repeating patterns in the addresses with regard to the heat circuits/mixers. Often the first byte is indicating the heat circuit, the second the actual function. As an example:

0x2323 allows you to get/set the operation mode for heat circuit 1.
0x3323 does the same for heat circuit 2, and
0x4323 for heat circuit 3.

So, whenever you stumble across a working address 0x23??, it is worth to also try 0x33?? and 0x43??.

Here’s my list of “first bytes” I worked out for the three heat circuits:

Then, there are sometimes patterns in the second byte for heat circuits, and it seems to me that they are identical within the range of a first bye. An example:

0x0896, 0x0898 and 0x089A get the room temperatures for heat circuit 1, 2 and 3. And:
0x080A, 0x080C and 0x080E get the flow line temperatures for heat circuit 1, 2 and 3.

So I assumed (successfully) that within 0x08 any heat-circuit specific second byte may be used for the next heat circuit by adding an offset of 2 to it.

Here are the offsets I figured out (to be taken with a grain of salt – the statistics behind these assumptions are weak):

Addresses Derived from Coding Lists

Both in the operation manual and in the vitodata server there are listings of the “Codings”. These give a single byte value in hex, so the aussmption is that these are part of an address. Matching a few addresses from existing vito.xml and the manual seem to confirm this. It looks like

• Codings that are not connected to a heat circuit go by address 0x77XX, where XX is the coding byte
• Codings that are assigned to heat circuits go by the addresses 0x27XX, 0x37XX and 0x47XX for heat circuit 1, 2 and 3, where again XX is the coding byte

I am currently testing this assumption, will update here as soon as I’m clear about it.

Completeness Check

The vitodata server shows zillions of parameters that the heating provides upon request. My guess is that all these parameters should be available via Optolink also. This said, I am far away from being complete, and most likely will never be.

For me, completeness will be achieved, if I can set all temperatures, set all operation modes, and read all temperatures, operation hours and power values. Especially the enrgy manager, which provides real-time data of my power consumption and production, I want to read out with high frequency.

When it comes to involved devices, in my case these components are in one way or another part of the data acquisition:

• Vitovalor 300-P (obviously)
• Vitotronic 200 RF (type HO1E)
• Vitocom 300 LAN3
• Saia PCD ALE3 M-BUS energy”manager” (Basically a two-way power meter)

All parts are the standard setup of the Vitovalor 300-P, i.e. if you get one, you should have the same setup.

Results

Below you’ll find my XML files – also vcontrold.xml needed adjustment for missing units. This is currently work in progress, and while this sentence is here, I am constantly improving the files. Again: Use these files at your own rsik! Currently I’d strongly recommend to only use the get commands, not the set commands, which may be totally wrong in some cases.

Known Issues

• Effective target temperatures currently yield nonsense results (unit conversion?)
• External room temperatures are unchecked because I don’t have external temperature sensors in my rooms
• Solar values are unchecked since I have no solar devices
• Modulation degree and relative device power are yet unchecked
• All set functions untested

Download Links

Last update: Nov. 19^th, 2017

• vito.xml
• vcontrold.xml

Appendix: Currently Implemented Functions

to be continued