How-To : Install and Run VelServ - a Velbus TCP Gateway

for issues with homeassistant:


this is a bit dependant on what th errors exactly is


Just a thought, maybe @cereal can confirm.

Are homeAssistant & VelServ fighting for the same TTY port?

The service file I wrote for VelServ will attempt to restart every few seconds of it can’t connect to TTY port.

My thought is that HA is connecting to the TTY port before VelServ can grab it.

@MDAR Thank you for the work on the server & the installation script! Can I take it and save a copy on gitlab, obviously with keeping all authors as authors? Alternatively I can assist with the process of setting up a git repo (very easy). The reason is that the link to is already dead, rest of the code is on webpage (you change domain or move server and we have a problem). Keeping the code on gitlab makes it more future proof to some extent. It’s also easier to keep versions tagged, make releases, etc. It also allows external contributors to submit code amendments.

Also, is there a licence attached? Am I allowed to modify the code? :stuck_out_tongue_winking_eye:

P.S. I just become an owner of tiny working velbus installation :heart_eyes: and openHAB integration is most likely a next step.

1 Like


Thanks for the compliment.

I didn’t know the link to @jeroends code is broken, I’m sure he’ll chime in and help.

I’ve been thinking about doing something like this for a long time, not just for this script, but for all the things I’ve / we’ve created over the years.

For example, the openHAB template files I’ve created have evolved over the years, as the binding has matured.


There’s some more work to be done on it in the future, which will need magic that I’m just not capable of (at this point, although happy to learn how to add modules and functionality to the binding, if someone is willing to teach me).

I totally appreciate that developing the binding is a labour of love, which has to happen in people’s own time.

That said, with so many people now using the binding maybe it’s time to put a bounty on it?

What are people’s thoughts on this?

I haven’t attached a license to my small efforts, can you suggest an appropriate one that enables people to amend and develop?

If you / we can setup a GitHub / GitLab repository, I assume we can assign multiple administrators?

As you suggest with web servers, I’d hate the project to suffer if one person got “hit by a bus”.

Can we continue privately and update this (and other threads) with the links?

1 Like

Someone already did it :slight_smile: GitHub - jeroends/velserv: A TCP to Velbus gateway for Linux

I normally use GPLv3

We can have multiple admins, maintaneers, developers with different access level, no problem.

P.S. github is more popular, but it was taken over by Microsoft, so I moved my stuff to gitlab.

“someone” you say…

Maybe it was our very own @jeroends :grin:

My script pulls updates from that site anyway.

Excellent, I’m happy to use whatever you suggest, as it’s all new to me anyway.

1 Like

Happy to be admin as well on it … RZomerman (Roelf Zomerman) · GitHub


velserv is idd already on github since a few years :slight_smile: . That’s the reason I did not repair my little server anymore (will be repaired someday, but other priorities).
I’m not that formiliar with licenses, but as already stated in the code: if you want to change something: let me know because I’d like to have my name associated to it (as it was the last +/-13 years already).
I’d like to avoid having x version of the code, so the only code I support (and is the original code) is on my github (with backups on my PC). If you want to update the code, make it better: certainly be my guest! I’ve already some upgrades in my mind, but since the code is still doing it’s thing and my time that I could spend on it is limited (3 kids, pretty busy job and other projects) those aren’t implemented.



I’m running HA (HAOS 12.1) on an RPi 3 and all my integrations (Velbus, Philips Hue, Zigbee devices) run flawlessly. Home assistant is using the serial connection (USB) from the VMBRSUSB module for the integration of all my Velbus entities. For convenience, I don’t want to swap this USB connection to a PC in order to access VelbusLink, so I was thinking of setting up velserv or the Velbus TCP snap package mentioned next to my HA. What would be the easiest and most robust set-up? Can I install the snap package on my already existing HAOS and will this run out-of-the-box?

1 Like

Hello and welcome to the community.


YES, this is the easiest and most robust solution.

The only thing to watch for is changing the /dev/serial/ references.

In HA that needs to change to tls: password @ IP_Address_of_RPi:27015

and I would recommend changing the /dev/serial/ttyUSB to something like /dev/serial/by-id/velleman_VMB1USB

The script I created for installing the SNAP package will do this for you.

1 Like

Maybe I should rephrase my question. I’m currently using the operating system, which makes it apparently not possible to execute apt commands. I will probably need to install HA on another OS to install the SNAP package? Which OS is best recommended for my RPi running only HA?


That should be okay, it’s based on Debian.

As long as you can get to an OS level command prompt, you should be able to install Snap on the root.

@cereal was talking about creating a Docker specially for Velbus-tcp

Maybe that’s something you can use?

If a separate machine is your only option (which I’m sure it isn’t), any small machine with a Debian OS will do the trick.

I’ve got an image for a BeagleBone black if you want it.

@csoete I didn’t have time to proofread my own step-by-step instruction, but if you hit any problems check this: Installing OpenHAB – Velbus binding – Core Dump
I use OpenHAB, so I can’t tell what system is the best, but HAOS 12.1 is the officiad HA system, so why look for something else if you only want to run HA?
We can help with the velbus-tcp, even manual install is an option. Ot the MDAR script. If it doesn’t work - come back - I did some debugging, it’s very easy when you’re guided. Some details will be different on your system than on mine, so the below is only an example.

Make sure your system detects the bridge

openhabian@openhabian:~ $ lsusb 
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 003: ID 10cf:0b1b Velleman Components, Inc. VMB1USB Velbus USB interface
Bus 001 Device 002: ID 2109:3431 VIA Labs, Inc. Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Check if you have it in the udev tree:

openhabian@openhabian:~ $ udevadm info  -n /dev/ttyACM0 | grep Velbus
E: ID_USB_MODEL=VMB1USB_Velbus_USB_interface
E: ID_USB_MODEL_ENC=VMB1USB\x20Velbus\x20USB\x20interface
E: ID_USB_SERIAL=Velleman_Projects_VMB1USB_Velbus_USB_interface

Check that the velbus-tcp works:

openhabian@openhabian:~ $ systemctl status velserv
● velserv.service - Velserv
     Loaded: loaded (/etc/systemd/system/velserv.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2024-03-17 18:41:45 CET; 24h ago
    Process: 731 ExecStart=/opt/velserv/velserv -d /dev/serial/by-path/platform-fd500000.pcie-pci-0000:01:00.0-usb-0:1.3:1.0 -p 6000 (code=exited, status=0/SUCCESS)
    Process: 746 ExecStartPost=/bin/bash -c /bin/touch /var/log/velserv.log (code=exited, status=0/SUCCESS)
    Process: 764 ExecStartPost=/bin/bash -c /bin/echo Velserv Started $(date) >> /var/log/velserv.log (code=exited, status=0/SUCCESS)
    Process: 789 ExecStartPost=/bin/bash -c /bin/pidof velserv >> /var/log/velserv.log (code=exited, status=0/SUCCESS)
   Main PID: 742 (velserv)
      Tasks: 4 (limit: 4531)
        CPU: 4.607s
     CGroup: /system.slice/velserv.service
             └─742 /opt/velserv/velserv -d /dev/serial/by-path/platform-fd500000.pcie-pci-0000:01:00.0-usb-0:1.3:1.0 -p 6000

Mar 17 18:41:45 openhabian systemd[1]: Starting Velserv...
Mar 17 18:41:45 openhabian systemd[1]: Started Velserv.


That’s VelServ

Rather than the Snap Velbus-TCP package

But you are on the right lines.

One interesting note that I have requested that the Velbus-TCP snap package follows is that when VelServ fails (mainly due to the absence / removal of the USB connection), the Service fails and it reported.

however, if the Snap package fails, it will never tell you, nor will it recover automatically.

snap status velbus-tcp

snap get velbus-tcp -d to get the connection details

snap restart velbus-tcp

1 Like

I gained access to the OS-level CLI with the login command. Similarly, the install of the snap Velbus-TCP package also fails here due to apt not being found. I did some research and apparently my OS (Home Assistant OS 12.1) is buildroot which means it is not possible to install packages. This is based on:

Which means I’ll probably have to install HA on top of another OS (possibly debian based), which is a shame because I liked having the ease-of-use installation of HAOS.

1 Like

If I understand how it’s made, you’d have to make changes to the container, that’s a different story. Is the HA forum providing any help?

P.S. Looks like the ease of installation comes with a price tag. Removed flexibility…


if you want something like this you have to build an addon, its on my todo list, but no idea when i will get it finished.

1 Like

Thank you all for your replies, I have since advanced a bunch.
However, I still have some difficulties connecting my RPi server through VelbusLink.
I’m currently running Home Assistant Container on a Raspberry Pi 3B using the (Raspberry Pi Lite) OS:

Operating System: Debian GNU/Linux 11 (bullseye)
Kernel: Linux 6.1.21-v8+
Architecture: arm64

I then ran the following Docker run command which set up Home assistant on the following internal LAN url: http://harpi.local:8123/ (harpi.local being the hostname of my RPi):

sudo docker run -d \
--name homeassistant \ 
--privileged \ 
--restart=unless-stopped \
-e TZ=Europe/Brussels \
-v /config/ha:/config \
-v /run/dbus:/run/dbus:ro \
--network=host \
--device=/dev/ttyUSB0:/dev/ttyUSB0 \
--device=/dev/ttyACM0:/dev/ACM0 \

Note that USB0 is the connection to my Sonoff_Zigbee_3.0_USB_Dongle_Plus and ACM0 is my Velleman VMB1USB interface.

I can access HA perfectly and all integrations (Zigbee dongle and Velbus USB) show up, meaning the mounting in Docker was done successfully. I then installed the velbus-tcp snap package using MDARs script:

mkdir /opt/velbus-tcp
cd /opt/velbus-tcp
wget -O /opt/velbus-tcp/

This was also executed successfully and gave me this output:

Velbus-TCP is now running with these settings
        "logging": {
                "output": "stream",
                "type": "info"
        "ntp": {
                "enabled": true,
                "synctime": ""
        "serial": {
                "autodiscover": false,
                "port": "/dev/serial/by-id/usb-Velleman_Projects_VMB1USB_Velbus_USB_interface-if00"
        "tcp": {
                "auth": "true,false",
                "authkey": "velbus,",
                "cert": "/var/snap/velbus-tcp/common/certificate.pem",
                "host": ",",
                "pk": "/var/snap/velbus-tcp/common/privkey.pem",
                "port": "27015,6000",
                "relay": "true,true",
                "ssl": "true,false"

Now I want to connect to VelbusLink on other devices within the network using the network connection (TCP/IP) using the following Server details:

Host address: harpi.local
Port: 27015
Authentication key:
TLS/SSL connection: Unchecked
Remember password (unsafe): Unchecked

I think I’m connected to the gateway when I press “Finish”. However, I can’t seem to find any modules as it instantly gives me an error when pressing the “Scan” button:

An unexpected error occured, we've disconnected you from the bus.

Does anyone have a solution for this or encountered this error? I hope I provided enough details to replicate my setup.

Nevermind, I did not see that an authentication key was set during MDARs script. I now connect using:

Host address: harpi.local
Port: 27015
Authentication key: velbus
TLS/SSL connection: Checked
Remember password (unsafe): Unchecked

I can now interact with my modules using VelbusLink. Should I still mount the VMB1USB interface using the docker run command (–device) or connect via the integration on HA?

For a TCP/IP device:

Is it even useful to mount the Velbus USB port in my Docker container?

Congratulations :partying_face:

I’m glad you’ve got it all working.

I know very little about dockers and HA, I find them all far too confusing.

However, I would say that you’re right, there is little point in mounting the Velbus port for the HA docker, in fact probably risking some misconfiguration.