Optolink Switch/Splitter

Make your Viessmann heating locally available via MQTT and TCP/IP while keeping Optolink/ViCare App & more!

Use this software at your own risk.

🎉 Announcements

• Version 1.4.0.0 ATTENTION: ByteBit Filter made congruent. Now returns raw/hex by default if no scale is given. So set scale to 1 to achieve the same result as in earlier versions without scale.
  now ("MyDatapoint", 0x1234, 3, 'b:2:2', 1), resturns same result as ("MyDatapoint", 0x1234, 3, 'b:2:2'), before.
  now ("MyDatapoint", 0x1234, 3, 'b:2:2'), resturns same result as ("MyDatapoint", 0x1234, 3, 'b:2:2::raw'), before.
  If you use like ("MySensorVal", 0x1234, 3, 'b:0:1', 0.1), nothing needs to be done.

• Version 1.3.0.0 If an issue occurs with Viconnect communication, the main loop gets stopped and everything starts again (protocoll init -> run Viconn reception thread -> main loop).

• Need VS1 / KW protocol support? Use the dedicated branch.

• Explore other feature branches, there might be something useful for you! 😉

📌 Table of Contents

• Introduction
• Software Requirements
• Hardware Requirements
• Installation
• Updating to a new Version
• Connecting Optolink & Vitoconnect
• Command Syntax: MQTT & TCP/IP
• Smart Home Integration (e.g. Home Assistant)
• Questions & Issues
• 3D-Printable Case for Raspberry Pi & USB-TTL Adapter
• Additional Images
• Disclaimer

🚀 Introduction

Key Benefits

• Local Control and Cloud Capability – Allow full local control and datapoint access while retaining the ability of Viessmann Cloud and App access.
• Viessmann Heating/Heat Pump Compatibility – Works with Vitodens, Vitocal, Vitocrossal and most other Optolink featured devices.
• Smart Home Ready – Integrates with Home Assistant, ioBroker, Node-RED or any other system with MQTT Support.
• Supports VS2 and VS1/KW protocols with different branches.
  • The vs1test branch enables VS1/KW protocol support but works only without Vitoconnect.
  • For VS1/KW with Vitoconnect, the viconn-listener is available (currently in beta).

Videos

🎥 Introduction Video (German): Watch on YouTube

📖 Extended Setup Tutorial (German): Rustimation Blog

📁 Software Requirements

• Python (version >= 3.9):
  • pyserial: pip install pyserial
  • MQTT (version >= 2.0): pip install paho-mqtt
• Virtual environments recommended (Guide).

🖥️ Hardware Requirements

• Raspberry Pi or a suitable system.
• Viessmann Optolink-compatible heating (Vitodens, Vitocal, Vitocrossal, etc.).
• Optolink r/w head:
  • Original Viessmann model or self-made.
  • Volkszähler-compatible versions may work if LED distance is adjusted (8€ option).
• To retain ViCare App functionality, use a USB-to-TTL adapter:
  • Recommended: CP2102 chip (Example).
  • Some newer Vitoconnect models may work with FTDI chips.
  • Raspberry Pi UART voltage = 3.3V → Set jumper accordingly!

🛠️ Installation

1. Clone the Repository

git clone https://github.com/philippoo66/optolink-splitter.git
cd optolink-splitter

2. Create Virtual Environment & Install Dependencies

Using a virtual environment is recommended to keep dependencies isolated and avoid conflicts with system-wide packages. More details can be found in this guide.

2.1. Create & activate the virtual environment:

python3 -m venv myvenv
python3 source myvenv/bin/activate  # On Windows use: myvenv\Scripts\activate

2.2. Install required dependencies:

pip install pyserial
pip install paho-mqtt  # Only if MQTT is used

NOTE: After installation, the environment must be activated before running the script.

3. Configure the Settings

Modify settings_ini.py according to your heating (/ datapoints):

• Refer to Wiki | Parameter Addresses, poll_list samples
• Refer to Wiki | ViessData21

4. Run the Script

python3 source myvenv/bin/activate  # Make sure to activate the virtual environment. On Windows use: venv\Scripts\activate
python3 optolinkvs2_switch.py

For automatic startup, set up a service. See the Wiki Guide.

Updating to a new Version

If you want to update your installation to a new version, the recommended way is to

• make a backup copy of your current installation (folder)
• from the new version repo, clone all files except settings_ini.py into your original folder (replace existing files)
• check the version log for added or changed entries in the settings_ini and apply (only) those changes to your existing settings_ini.py

Even though I promise to note required changes carefully in the version log from now on, after an update it is always a good practice to start the splitter once in the console (python optolinkvs2_switch.py, remember to run your virtual environment) since in the console you get quite detailed error messages if some would be wrong or missing.

🔌 Connecting Optolink & Vitoconnect

Parallel use with Vitoconnect / ViCare App

• Ensure the serial port is enabled and serial console is disabled (Guide).
• CP2102 Interface:
  • Cross RX/TX lines.
  • Set voltage jumper to 3.3V.
  • Use ttyAMA0 instead of ttyS0 for Raspberry Pi 3+ (Details).

Vitoconnect Interfaces

Vitoconnect 100 OPTO1

To ensure proper communication with the system, follow the power-on sequence exactly:

1. Connect all wires and plugs to the Raspberry Pi and Vitoconnect.
2. Power on the Raspberry Pi.
3. Run the script and wait for the prompt: awaiting VS2....
4. Power on Vitoconnect 100 OPTO1.

Vitoconnect OPTO2

The startup sequence for this device is not critical, as it will automatically reconnect without issues.

🧾 Command Syntax: MQTT & TCP/IP

Optolink Splitter can connect to an MQTT Broker for sending commands and receiving responses. Alternatively, a direct TCP/IP connection (e.g. using PuTTY) can be established to interact with the application directly. For more details on the command syntax, see the Wiki | Command Syntax Overview or go directly to the section on MQTT and TCP/IP requests.

• read ambient temperature, scaled with sign:

  • cmnd = read;0x0800;2;0.1;true
  • resp: 1;2048;8.2

• read DeviceIdent as raw:

  • cmnd = read;0xf8;8
  • resp: 1;248;20CB1FC900000114

• write hotwater temperature setpoint:

  • cmnd = write;0x6300;1;45
  • resp: 1;25344;45

Important Note for TCP/IP Connections:
When using PuTTY or similar software for a TCP/IP connection, the session must be closed by sending exit as a string, as PuTTY does not appear to send the FIN flag to properly terminate the session when closing.

🏠 Smart Home Integration (e.g. Home Assistant)

Optolink Splitter seamlessly integrates into your smart home setup via MQTT, allowing you to monitor and control your Viessmann heating system using platforms like Home Assistant, ioBroker, or Node-RED. All available heating system data can be visualized in dashboards, automated with custom rules, and integrated into broader smart home routines. With Optolink Splitter’s command-sending capability, you can locally adjust heating modes, temperature setpoints, or pump states directly from your favorite smart home system.

For detailed Home Assistant integration instructions, see the Wiki | Home Assistant Integration of Optolink‐Splitter.

Below are examples of how this integration looks in different smart home environments:

Heating System Overview in Home Assistant (Built with a Picture Entity Card)

Details

Another Heating System Overview in Home Assistant & Command Buttons

⁉️ Questions & Issues

• Discussions & contact: GitHub Discussions
• Bug reports: GitHub Issues

🖨️ 3D-Printable Case for Raspberry Pi & USB-TTL Adapter

A compact and practical 3D-printable case designed for Raspberry Pi 2 & 3 including a CP2102 USB-TTL adapter mount. A version for Raspberry Pi 4 may be available in the future. Special thanks to Kristian!

Raspberry Pi 2/3 Case with CP2102 UART Board Holder

📸 Additional Images (MQTT, Visualization)

Datapoints in settings_ini.py & MQTT Explorer monitoring

Data visualisation

📝 Disclaimer

This software is not affiliated with, endorsed by, or associated with Viessmann in any way. The terms Vitoconnect, Optolink, Vitocal, ViCare, etc. refer to Viessmann products and technologies. All product and brand names mentioned belong to their respective owners.
It is provided as-is, without any warranties or guarantees. The authors assume no liability for any issues arising from its use.