{"id":38554899,"url":"https://github.com/f18m/viessmann-optolink2mqtt","last_synced_at":"2026-01-30T00:23:59.024Z","repository":{"id":332595485,"uuid":"1134293953","full_name":"f18m/viessmann-optolink2mqtt","owner":"f18m","description":"Open source interface between a Viessmann device (heat pump, gas heater, etc) and MQTT","archived":false,"fork":false,"pushed_at":"2026-01-16T23:45:29.000Z","size":647,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-17T17:46:51.652Z","etag":null,"topics":["automation","home","homeassistant","mqtt","optolink","viessmann"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/f18m.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-14T14:21:58.000Z","updated_at":"2026-01-16T23:45:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/f18m/viessmann-optolink2mqtt","commit_stats":null,"previous_names":["f18m/viessmann-optolink2mqtt"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/f18m/viessmann-optolink2mqtt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f18m%2Fviessmann-optolink2mqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f18m%2Fviessmann-optolink2mqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f18m%2Fviessmann-optolink2mqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f18m%2Fviessmann-optolink2mqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/f18m","download_url":"https://codeload.github.com/f18m/viessmann-optolink2mqtt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f18m%2Fviessmann-optolink2mqtt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28565877,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T08:53:44.001Z","status":"ssl_error","status_checked_at":"2026-01-19T08:52:40.245Z","response_time":67,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","home","homeassistant","mqtt","optolink","viessmann"],"created_at":"2026-01-17T07:41:09.938Z","updated_at":"2026-01-30T00:23:59.017Z","avatar_url":"https://github.com/f18m.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GitHub Tag](https://img.shields.io/github/v/tag/f18m/viessmann-optolink2mqtt)](https://github.com/f18m/viessmann-optolink2mqtt/releases)\n[![PyPI - Version](https://img.shields.io/pypi/v/viessmann-optolink2mqtt)](https://pypi.org/project/viessmann-optolink2mqtt/)\n\n# viessmann-optolink2mqtt\n\nThis project provides an open source interface between a [Viessmann](https://en.wikipedia.org/wiki/Viessmann) device (heat pump, gas heater, etc) and \n[MQTT](https://en.wikipedia.org/wiki/MQTT).\n\n\u003e [!IMPORTANT]\n\u003e This project is an independent work and is not associated with, sponsored by, or connected to the Viessmann company in any manner. Viessmann and all related trademarks, product names, and device names are trademarks or registered trademarks of Viessmann and remain the exclusive property of Viessmann.\n\n\n## What is Optolink?\n\nSome Viessmann devices (at least those manufactured before roughly year 2014) expose an optical interface\nfor communication with external devices named \"_Optolink_\".\n\nThis interface is typically located in the Vitotronic panel and officially supports a connection to the\n[VitoConnect](https://www.viessmann.co.uk/en/products/control-system-and-connectivity/vitoconnect.html)\ndevice.\nOn the other hand such interface also allows tinkerers to read and write registers of the Viessmann devices\nto e.g. read telemetry data (temperatures, status of internal parts, etc) and write settings\n(e.g. heating mode, target temperatures, etc).\n\nThis project allows you to take control of your Viessmann device by hooking into the Optolink interface\nand sending all data to a local MQTT server, so that all your data is local and is never transiting \nthe cloud of any vendor.\n\n\n## Architecture\n\n\u003cimg title=\"Setup\" alt=\"Architecture\" src=\"docs/architecture.png\"\u003e\n\n## Hardware Required\n\n* A Single Board Computer (SBC) which is capable of running Python and has a USB-A connector\n  (if you plan to use the original Viessmann Optolink USB cable). A typical choice is the [Raspberry](https://www.raspberrypi.com/products/raspberry-pi-5/); myself I've been using the [OLinuXino A64](https://www.olimex.com/Products/OLinuXino/A64/A64-OLinuXino/) as (slightly cheaper) alternative.\n* The Optolink-to-USB cable to read/write on the Optolink interface; you have two main options: a) buy the original Viessmann cable on specialized shops such as [https://www.loebbeshop.de/](https://www.loebbeshop.de/); see exact item [here](https://www.loebbeshop.de/viessmann/ersatzteil/anschlussleitung-usb-optolink-fuer-vitoconnetc-artikel-7856059/) or b) build your own cable, more details available from other tinkerers like [MyVitotronicLogger](https://github.com/Ixtalo/MyVitotronicLogger) or at [Optolink splitter readme](https://github.com/philippoo66/optolink-splitter)\n\n\n## Software features\n\nThis project main features are:\n\n* Written to be reliable and **run 24/7**: careful exception handling, reconnects automatically to the MQTT broker in case of transient network issues, automatically re-establishes serial port connection in case of failures, etc.\n* **Easy declarative configuration**: configure all aspects of your Viessmann device from a single YAML config file (easy to backup and/or version in `git`); no need to hand-write HomeAssistant MQTT entity definitions!\nAll config parameters have a clear name and associated documentation.\n* **Read and write support**: allows both to read from your Viessmann device and also to set writable registers to e.g. change heating mode, change target temperatures, etc.\n* **HomeAssistant friendly**: although this project can be used with _any_ home automation platform; it provides a number of features that make it very HomeAssistant friendly: in particular MQTT discovery messages make it possible to magically have all your Viessmann entities appear in HomeAssistant.\n* **Easy installation** via Pypi and docker and easy **upgrades**\n\nWhat this project does NOT have at this time:\n* Compatibility with the VitoConnect: if you are interested in that I suggest you to look at the [Optolink Splitter](https://github.com/philippoo66/optolink-splitter) or [Optolink Bridge](https://github.com/kristian/optolink-bridge/)\n\n\n## Installation\n\nThis project supports 2 main installation methods: PyPi and Docker.\nBoth methods are meant to be used from a Linux Operating system which has the USB/DIY cable attached\n(see \"Hardware\" section above).\n\n### Pypi package\n\n```sh\npython3 -m venv optolink2mqtt-venv\nsource optolink2mqtt-venv/bin/activate\npip install viessmann-optolink2mqtt\n\noptolink2mqtt --help\n```\n\n### Docker\n\nWhen using Docker you will need to provide the YAML config file path in the `docker run` command and \nalso provide the name of the serial port (e.g. `/dev/ttyUSB0` in the following example):\n\n```sh\ndocker run -d -v \u003cyour config file\u003e:/etc/optolink2mqtt/optolink2mqtt.yaml \\\n    --device=/dev/ttyUSB0 \\\n    --hostname $(hostname) \\\n    --name optolink2mqtt \\\n    --restart=unless-stopped \\\n    ghcr.io/f18m/optolink2mqtt:latest\n\ndocker logs -f optolink2mqtt\n```\n\nPlease note that the `--restart=unless-stopped` makes sure that the optolink2mqtt docker will \nbe restarted after a reboot.\n\nThe docker image of optolink2mqtt supports 3 main architectures: `amd64`, `armv7` and `arm64`.\n\n### Serial port naming\n\nSomething you might notice running this project on certain HW platforms is that sometimes\ndue to errors on the USB bus the Linux kernel might force your Optolink-to-USB adapter\nto reinitialize and when this happens the device might change its name e.g. from `/dev/ttyUSB0` \nto `/dev/ttyUSB1`.\nIf your config file is referencing `/dev/ttyUSB0`, then optolink2mqtt will stop working.\nTo prevent this, the best approach is to setup a a [udev](https://en.wikipedia.org/wiki/Udev) rule \nthat would create a symbolic link to the Optolink-to-USB device:\n\n1. Use `lsusb` utility to find out all details on your Optolink-to-USB cable. Mine appears as:\n\n```\nBus 002 Device 006: ID 1a86:7523 QinHeng Electronics CH340 serial converter\n```\n\nThe portion after `ID` is the `vendor ID` colon `product ID`. In my case `1a86` is the `vendor ID` and `7523` is the `product ID`.\n\n2. Create the udev rule:\n\n```sh\nsudo nano /etc/udev/rules.d/99_optolink_usb.rules\n```\n\nand copy-paste there a line containing a reference to the same `vendor ID` and `product ID` that appeared in the `lsusb` output:\n\n```\nSUBSYSTEM==\"tty\", ATTRS{idVendor}==\"1a86\", ATTRS{idProduct}==\"7523\", SYMLINK+=\"optolinkUSB\"\n```\n\n3. Unplug and plug again your Optolink cable\n\n4. Use in the  [optolink2mqtt.yaml](./optolink2mqtt.yaml) config file the symlink `/dev/optolinkUSB` as\nserial port name. Also remember to use `--device=/dev/optolinkUSB` in your `docker run` command if you're using Docker.\n\n\n## Configuration file\n\nThis software accepts a declarative configuration in YAML format.\nPlease look at the [optolink2mqtt.yaml](./optolink2mqtt.yaml) file as reference source for the syntax.\n\n\n## How to discover register addresses\n\nTO BE WRITTEN\n\n\n## HomeAssistant Integration\n\nThis project allows a very easy integration with [HomeAssistant](https://www.home-assistant.io/).\nIt's enough to populae the `ha_discovery` section of each register defined in the [configuration file](./optolink2mqtt.yaml)\nwith some metadata specific for each sensor, to get the sensor automatically appear inside your HomeAssistant:\n\n\u003cimg title=\"HA integration\" alt=\"HA integration\" src=\"docs/home_assistant_mqtt_device.png\"\u003e\n\nThis makes it possible to build in your HomeAssistant dashboard visual representation of your Viessmann device.\nE.g.. for my heat pump I was able to build the following dashboard:\n\n\u003cimg title=\"HA dashboard\" alt=\"HA dashboard\" src=\"docs/home_assistant_dashboard2.png\"\u003e\n\n\n## Labelling of the HW\n\nMost likely your Viessmann device will stay around for a lot of time (many years hopefully), \nand so will do the SBC that connects it to your home automation platform.\nFor this reason I suggest to provide some documentation for what is running on your SBC.\nA simple approach I like is to print a QR code pointing at this page and stick it physically on the SBC,\nto make it obvious to anybody inspecting it where to find the docs.\n\nHere you can find a QR code I produced with the optimal [miniQR code generator](https://mini-qr-code-generator.vercel.app/):\n\n\u003cimg title=\"QRCode\" alt=\"QRCode\" src=\"docs/qr-code.png\"\u003e\n\n\n## Roadmap\n\nI plan to add \n\n* Prometheus support to export health stats (errors on the Optolink interface, network errors, etc)\n\nIf you are looking for a specific feature, let me know by opening an [issue](https://github.com/f18m/viessmann-optolink2mqtt/issues).\n\n## Related projects\n\n* [Optolink Splitter](https://github.com/philippoo66/optolink-splitter): this is the original project that inspired this one\n* [Optolink Bridge](https://github.com/kristian/optolink-bridge/): inspired from the \"Optolink Splitter\"; requires you to own a VitoConnect device and allows you to setup a \"man in the middle\" device\n* [openv vcontrold](https://github.com/openv/vcontrold): seems abandoned but contains a C-based implementation of the VS1 and VS2 protocols apparently. Its [wiki](https://github.com/openv/openv/wiki/) has plenty of details although in German\n* [VitoWiFi](https://github.com/bertmelis/VitoWiFi): a C++ implementation of VS1 (KW) and VS2 (P300) Optolink protocols, for use on ESP microcontrollers but also Linux systems\n\n* [FloorHeatingController](https://github.com/f18m/floor-heating-controller): firmware for a controller of floor heating valves, to help replace physical thermostat with HomeAssistant virtual thermostats\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff18m%2Fviessmann-optolink2mqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ff18m%2Fviessmann-optolink2mqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff18m%2Fviessmann-optolink2mqtt/lists"}