Optolink Switch/Splitter

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

Disclaimer

This software is not affiliated with, endorsed by, or associated with Viessmann in any way. The terms Vitoconnect, Optolink, Vitocal and ViCare refer to Viessmann products and technologies. All product and brand names mentioned belong to their respective owners. Use this software at your own risk.

✅ 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.

🎉 Announcements

• Version 1.2.0.0 is out! Check the changelog for details.
• Need VS1 / KW protocol support? Use the dedicated branch.
• Explore other feature branches, there might be something useful for you! 😉

📌 Table of Contents

• System Architecture
• Software Requirements
• Hardware Requirements
• Installation
• Getting Started
• Command Syntax: MQTT & TCP/IP
• Questions & Issues
• Printable Case
• Additional Images

📦 System Architecture

How it Works

• Enables both local monitoring/control and Viessmann's cloud services in parallel.
• Data accessible via MQTT or TCP/IP for smart home integration (e.g. Home Assistant).
• Supports VS2 and VS1/KW protocols with different branches.
  • branch vs1test works as with VS1/KW protocol but only without Vitoconnect.
  • for VS1/KW with Vitoconnect there is the viconn-listener available (beta state).

Overview

Videos

🎥 Introduction Video (German): Watch on YouTube

📖 Extended Setup Tutorial (German): Rustimation Blog

📁 Software Requirements

• Python >= 3.9:
  • pyserial: pip install pyserial
  • MQTT: pip install paho-mqtt version >= 2.0
• 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: venv\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 each time 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

5. 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.

🚀 Getting Started

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

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

⁉️ Questions & Issues

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

Printable Raspberry Pi Case / USB-TTL Case

Raspberry Pi2 and Pi3 case with CP board holder (Possibly for Pi 4 in future). Thanks to Kristian!

📸 Additional Images (MQTT, Home Assistant)

Datapoints in settings_ini.py & MQTT Explorer monitoring

Data visualisation

Heating System Overview implemented in Home Assistant

ref. #67