Saltar al contenido principal

Integración domótica Velbus, gratuita y de código abierto

Integración Velbus para Gladys Assistant

Velbus home automation (relays, dimmers, blinds, thermostats) via a network gateway.

Ver en GitHubTodas las integraciones
info

La documentación de esta integración la escribe su autor y, por ahora, solo está disponible en inglés.

This integration connects a Velbus home automation bus to Gladys Assistant, locally on your network, through a network gateway: a Signum (TLS, with its password) or a TCP gateway (velserv, a USB interface shared by a TCP server...).

Never tested with a real installation. The protocol comes from the velbus-aio library (the one of the Home Assistant Velbus integration), ported to JavaScript and checked against a simulated bus only. Try it first while at home and report what goes wrong.

Unofficial integration, not affiliated with Velbus.

What you need​

  • A Velbus installation with a network gateway that Gladys can reach:
    • a Signum (VMBSIG): choose "Signum (TLS)";
    • or a TCP gateway: a VMBRSUSB / VMB1USB shared on the network by a program such as velserv or python-velbus-tcp: choose "TCP gateway".
  • A USB interface plugged directly into the Gladys machine is not supported.
  • This integration opens one connection only to the gateway. Whether your gateway also accepts VelbusLink or Home Assistant at the same time depends on the gateway (not checked).

What you get​

The integration scans the bus (a request to each address, 1 to 254, about 20 seconds) at its first connection, then reads the names and the states of the modules. The devices show in the Discovery tab, one device per channel, named after the module (the names set in VelbusLink).

  • Relays (VMB4RYLD, VMB1RYNO, VMB4RYNO-20...): a switch by default, a light or a read-only state for the relays you list in "Relays: lights and read only" (see "Relays and voice assistants" below). The "Output" relay (channel 18) of the VMBEL and VMBGP-20 panels is always read only.
  • Dimmers (VMB4DC, VMBDMI, VMB1DM, VMB4LEDPWM-20...): a light with its brightness. Turning it on brings back the last level when the module can.
  • Blinds (VMB1BLE, VMB2BLE, VMB1BLS, VMB2BLE-10/-20, VMB1BL, VMB2BL): a shutter (open, close, stop) and, on the modules that report it, its position (100 = open in Gladys). A blind is never a switch: a "turn everything off" does not move it.
  • Thermostats (VMBGP1/2/4, VMBGPO, VMBEL1/2/4, VMB1TS...): the temperature, the set point, the mode (comfort, day, night, frost protection), heating or cooling, and whether it runs. Changing them from Gladys is off by default (see below).
  • Modules with a temperature sensor but no thermostat: the temperature.
  • Push buttons (VMBGP*, VMB8PB, VMB6IN, VMBEL*...): no device, a scene trigger "Velbus push button" with the module address (hexadecimal, as in VelbusLink: 2 upper-case hexadecimal digits, e.g. 1A or 05, never 1a nor the decimal 26: Gladys compares it as written), the channel and the action (pressed, held, released). Leave a field empty to match any value. The scene gets module, channel, action and name.

Not supported in this version: DALI modules (VMBDALI), counters, analog inputs, the meteo station, the PIR sensors as motion sensors, the LEDs of the buttons, the edge lighting of the VMBEL panels, the memo texts, the clock.

Configuration​

  1. Address of the gateway: the IP address (or name) of the Signum or of the TCP gateway. Give it a fixed address in your router.
  2. Port: 27015 unless your gateway uses another one.
  3. Kind of gateway: "Signum (TLS)" or "TCP gateway (plain)".
  4. Signum password (Signum only, if it asks for one): a secret field, kept by Gladys in its database, never shown again in the interface, sent only to the gateway, never written in the logs. It is only sent over TLS: with "TCP gateway" it is never sent (the status says so).
  5. Signum certificate fingerprint (optional, recommended with a password): connect a first time without the password; the integration writes the SHA-256 fingerprint of the Signum certificate in its logs. Copy it here, then enter the password: from then on, a gateway with another certificate gets no password and the connection stops, and the status shows both fingerprints.
  6. Relays: lights and read only (optional), for example 1A-1, 1A-3:light, 2B-2:readonly (address in hexadecimal, channel, kind; no kind = light). Changing the kind of a relay already created in Gladys adds a new feature and keeps the old one (and its history): delete the old one by hand if you no longer want it.
  7. Allow changing the thermostats from Gladys: off by default.
  8. Language of the names: French or English (used when a module gives no name).

The Test the connection button connects at once when no connection is in progress, else waits for the one in progress and for the scan, and tells how many modules and channels were found (and which modules are not supported).

Scan in the Discovery tab scans the bus again (new modules, a module moved to another address). A reconnection does not scan again: it reads the states of the known modules.

Relays and voice assistants​

A relay shown as a switch or a light obeys every command Gladys relays: Google Home, Alexa, the MCP ("turn off the switches of the living room"), HomeKit, and the scenes acting on switches or lights. Some relays must never be switched off that way: a pump, the ventilation, the heating, a freezer, a door strike, a valve, or the virtual relays used by the Velbus programs.

For each of them: add it as readonly in "Relays: lights and read only" (e.g. 2B-2:readonly), save, then delete its old switch or light feature in Gladys (the integration keeps a feature you created, and refuses any command on a read-only relay, the old feature included: "read only, nothing was sent"). The relay then shows its state only.

How commands work​

  • A command is written on the bus within 3.5 s of the request, or refused with "nothing was sent" (bus too busy, gateway not connected).
  • The integration then waits for the module to confirm it (a status of that channel on the bus) until 4.5 s. Without it, the command is reported "sent, without confirmation" and the channel is read again two seconds later: it is never reported "not sent".
  • The commands of a channel are written one at a time, but a command never waits for the confirmation of the one before: a stop is written at once while a blind is still moving. The scan never delays a command; a command refused while the scan keeps the bus busy says so.
  • Every command is written in the integration logs.

Thermostats​

  • Changing the set point or the mode drives the heating: it is off by default. Once allowed, every Gladys user, every scene and the Gladys app can change them.
  • The option is read again right before every send: unchecked while a command waits, that command stops ("nothing was sent").
  • Before every change, the integration reads the thermostat from the bus and decides on that read, never on what it holds in memory: already at the value, nothing is sent; no answer in time, nothing is sent.
  • Set points are accepted from 5 to 30 °C, in half degrees (the Velbus step). The set point changed is the one of the current mode.
  • The modes: Velbus "comfort" is Gladys Comfort, "night" Night, "safe" Frost protection; Velbus "day" (between night and comfort) has no twin in Gladys and shows as Eco, labelled "Day": asking Eco from Gladys puts the thermostat in "day". When the mode is changed, the thermostat keeps its program state (following its program, manual, or sleep timer), as velbus-aio does.

Connection​

  • After a cut, the new tries are spaced: 10 s, 30 s, 1 min, 2 min, then every 5 minutes.
  • When nothing comes from the bus for 2 minutes, the integration sends a type request to a known module; nothing within 10 s: the connection is cut and opened again.
  • If the gateway closes the connection right after the password, twice in a row, the integration stops and does not try again by itself, even after a restart (a wrong password is not tried in a loop). Fix the password then save, or click "Test the connection". The file /data/velbus-state.json keeps only the place concerned (tls://address:port), never the password.
  • The same goes when the gateway takes the password but sends no Velbus frame within 30 s, twice in a row (wrong password, or not a Velbus gateway), and when the certificate is not the pinned one.
  • The status says "connected to the Velbus bus" only once a Velbus frame came in; until then it says "connected to the gateway".

Known limits​

  • Never tested with a real installation (see above): the frames are the ones velbus-aio documents.
  • A plain TCP gateway carries everything in clear on your network: any device of it can read and send Velbus frames. Prefer a Signum with TLS.
  • Without a pinned fingerprint, the TLS certificate of the Signum is not checked (it is self-signed): a device of your network could pose as the gateway and receive the password. Pin it.
  • Channel names are read in plain ASCII (accents are dropped).
  • The devices are keyed by address and channel: a module moved to another address in VelbusLink gives new devices.

Privacy​

Everything stays on your network: the integration only talks to the gateway.

Licence​

Apache-2.0. Protocol logic ported from velbus-aio (Maikel Punie, Apache-2.0 / MIT): see THIRD_PARTY_NOTICES.md.

Parámetros de configuración​

Estos son los parámetros que Velbus te pide en su pantalla de configuración en Gladys.

ParámetroTipoObligatorioDescripción
Your Velbus bussectionNoFor Velbus installations reached through a network gateway: a Signum (TLS, with its password) or a TCP gateway (velserv, a USB interface shared by a TCP server...). USB directly on Gladys is not supported. The integration scans the bus for the modules: relays and dimmers become lights or switches, blinds become shutters with their position, thermostats show the temperature, the set point and the mode, push buttons become scene triggers. One connection at a time. Never tested with a real installation. Unofficial, not affiliated with Velbus.
Address of the gatewaystringSíThe IP address (or name) of the Signum or of the TCP gateway; give it a fixed address in your router.
PortnumberNo27015 unless your gateway uses another one.
Kind of gatewayselectNoSignum: TLS. A TCP gateway: plain TCP, readable by any device of your network.
Signum passwordsecretNoOnly if your Signum asks for one (its authentication key). Sent only over TLS, never on a plain TCP connection. Kept by Gladys in its database, never shown again, sent only to the gateway, never written in the logs.
Signum certificate fingerprintstringNoOptional, recommended with a password: the SHA-256 fingerprint of the Signum certificate. Connect once without a password: the integration writes the fingerprint in its logs; copy it here, then enter the password. Once set, a gateway with another certificate gets no password and the connection stops (both fingerprints are shown).
Relays: lights and read onlystringNoOptional: by address (hexadecimal, as in VelbusLink) and channel, e.g. "1A-1, 1A-3:light, 2B-2:readonly" (no kind = light). The other relays are switches. A switch or a light obeys Google, Alexa, the MCP ("turn off the switches of the living room") and the scenes: set to readonly every relay that must never be switched off that way (pump, ventilation, heating, freezer, door strike, valve, virtual relays), then delete its old feature in Gladys.
ThermostatssectionNoChanging the set point or the mode of a Velbus thermostat from Gladys drives the heating: it is off by default. Once allowed, every Gladys user, every scene and the Gladys app can change them. The thermostat is read from the bus before each change; every command is written in the integration logs.
Allow changing the thermostats from GladysbooleanNo
Language of the namesselectNoUsed for the names of the devices and features added from now on, when a module gives no name.

Cómo instalar Velbus en Gladys​

  1. En Gladys, abre Integraciones: Velbus aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
  2. Haz clic en Instalar. Gladys descarga la imagen Docker (ghcr.io/lm1lc3n7/gladys-velbus:0.1.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración).
  3. Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
  4. También puedes instalarla directamente desde la URL de su repositorio: https://github.com/LM1LC3N7/gladys-velbus.

Velbus requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.

¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.

Sobre las integraciones externas​

Velbus es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene LM1LC3N7, no el equipo principal de Gladys.

Suscríbete a la newsletter de Gladys Assistant

Unos pocos correos al mes sobre nuevas versiones y novedades del proyecto. Enviados por Pierre-Gilles Leymarie, fundador del proyecto. Puedes darte de baja cuando quieras 🙂
Última actualización en