Qbus smart home integration, free and open source
Qbus home automation: lights, dimmers, shutters, thermostats and scenes over local MQTT.
Published by LM1LC3N7
- Devices
- Version 0.1.1
- Requires Gladys >=5.0.0
- ★ 0
This integration brings the outputs of your Qbus home automation controllers (CTD 3.x, the wired home automation of the Belgian manufacturer Qbus) into Gladys, over your local network, through the Qbus MQTT gateway and your own MQTT broker. Nothing goes through the Internet.
This integration has never been tested with a real Qbus installation: it follows the protocol of qbusmqttapi, the library Qbus wrote for Home Assistant. Feedback is welcome on the forum. Unofficial, not affiliated with Qbus.
What you get
| Qbus output | In Gladys |
|---|---|
| Relay (on/off) | declared safe: a switch; otherwise a read-only state and "Turn on" / "Turn off" buttons |
| Dimmer (analog) | declared safe: a light (on/off, brightness); otherwise a read-only state and level, and the buttons |
| Colour light (multicolor) | a light: on/off, brightness, colour |
| Shutter, blind | a shutter: open / close / stop, and its position when the controller reports one |
| Thermostat | the room temperature and the setpoint (setpoint commands off by default, see below) |
| Scene | a "Run" push button |
| Gauge | a sensor: temperature, humidity, CO2, light, pressure, power, current, voltage, wind |
| Humidity, ventilation | humidity sensor, CO2 sensor |
| Weather station | outdoor temperature, light, wind, rain |
Not in this version: steppers, the regimes (presets) of thermostats and ventilations, the slats of venetian blinds, the effects of colour lights and the cumulative gauges (energy, water, volume), the flow gauges (gas, gas flow, water flow), the water level and loudness gauges (no unit of Gladys for them). Shutters and thermostats are never switches: a "turn everything off" of a voice assistant or a scene does not reach them.
Relays and dimmers: declare the safe ones
A Qbus relay or dimmer may feed anything: a lamp, but also a circulator, the heat demand of the boiler, an electric heater, a freezer, a sump pump, a garage door pulse, a 0-10 V valve or ventilation speed. A "turn everything off / on" of a voice assistant or a scene reaches every switch and every light. So, by default, a relay or a dimmer is only shown, read only, with "Turn on" / "Turn off" buttons that do nothing until you turn on Allow the "Turn on" / "Turn off" buttons.
List in Outputs declared safe the relays and dimmers that may be switched
off or on at any time (lamps): their ref is the parameter QBUS_OUTPUT of the
device in the Discovery tab (10, 28). Refs are numbered per controller:
a plain ref counts only when the gateway has a single controller. With
several, write serial:ref (000123:10, the serial is the parameter
QBUS_CONTROLLER); a plain ref is then applied nowhere and the status says
so. They then become a switch (relay)
or a light (dimmer). A switch created before an output left the list stays,
shows its state, and refuses commands.
Scenes: a "Run" button starts a scene of the controller as Qbus System Manager defines it. A Qbus scene may also change heating or open things: the setpoint option and ceiling of this integration do not apply to it.
Before you start
- An MQTT broker on your network (Mosquitto, for example the add-on of your NAS, or the broker of the Qbus server).
- The Qbus MQTT gateway (qbusMqttGw), installed and connected to your
Qbus controller and to this broker, as Qbus explains on
iot.qbus.be. It publishes under
cloudapp/QBUSMQTTGW/.... - In Gladys, install the integration from the store.
Configuration
- MQTT broker address: the IP address of the broker (
192.168.1.20, port 1883), ormqtts://address:8883in TLS. - User name and Password: those of the broker, if it asks for them.
The password is kept by Gladys in its database, never shown again, and sent
only to your broker. It never goes into the logs nor into
/data. - Verify the TLS certificate: on by default; turn it off only for a broker with a self-signed certificate on your network.
- Controller serial number: empty for every controller of the gateway, or the serial of one controller (as Qbus System Manager shows it).
- Outputs declared safe and Allow the "Turn on" / "Turn off" buttons: see above.
- Allow setpoint commands: off by default, see below.
- Setpoint ceiling: 24 °C by default (16 to 30 °C).
- Minimum interval between two readings of a measurement: 10 s by default. On/off, positions and setpoints are never delayed.
- Language of the messages: French or English.
Then use Test the connection: it says how many controllers, outputs and devices the gateway has. The devices appear in the Discovery tab of the integration: create the ones you want.
Heating setpoints
The thermostats of Qbus drive the heating. Gladys always shows their temperature and setpoint. Changing a setpoint from Gladys (dashboard, scenes, voice assistants) is refused until you turn on Allow setpoint commands. When it is on:
- the setpoint stays between 5 °C and the ceiling of the configuration (24 °C by default, never above 30 °C), and within the limits the controller declares for the thermostat, by steps of 0.5 °C;
- the integration first reads the thermostat and its controller again, decides on that fresh read only, and checks the option and the ceiling again right before sending;
- the command leaves within 3.5 s of the click or is refused, not sent;
- when the controller does not confirm it in time, Gladys shows "Command sent, without confirmation": check the thermostat a moment later.
Errors and limits
- Never tested with a real device: report on the forum what does not work (with the logs of the integration).
- Credentials refused by the broker: the integration stops and tries again after 15 min, 1 h, 6 h, then every 24 h (kept across restarts). Saving other credentials or Test the connection tries at once.
- Broker unreachable, or refusing for another reason (server unavailable, identifier rejected): a new try every 10 s.
- Size of the messages: the integration ignores a configuration over 2 MB and a state over 64 KB, but only once received; MQTT 3.1.1 allows larger packets. Keep the broker for your home automation (set max_packet_size in Mosquitto if other clients use it).
- A state kept by the broker (retain) is ignored: only the states the gateway sends now count.
- At most 2000 devices (a limit of Gladys): the others are left out and the status says so.
- Gateway offline, controller disconnected: the status says it, the devices show "unreachable" and commands are refused, never queued.
- Gladys accepts 300 states per minute: measurements are spaced, the rest sent first.
Support
Questions and feedback: the Gladys community forum. Source code and issues: https://github.com/LM1LC3N7/gladys-qbus.
Configuration settings
These are the settings Qbus asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your Qbus installation in Gladys | section | No | Reads and controls the outputs of your Qbus controllers (CTD) through the Qbus MQTT gateway (qbusMqttGw) and YOUR MQTT broker, on your local network: relays, dimmers, colour lights, shutters and blinds, thermostats, scenes, and the sensors (gauges, humidity, CO2, weather station). Install and set up the Qbus MQTT gateway with your broker first (see the guide), then type the address of the broker below. Nothing goes through the Internet. Never tested with a real installation. Unofficial, not affiliated with Qbus. |
| MQTT broker address | string | Yes | The broker the Qbus MQTT gateway publishes to: its IP address (port 1883), or mqtts://address:8883 in TLS. |
| User name | string | No | The user of the broker, if it asks for one. |
| Password | secret | No | The password of the broker: kept by Gladys in its database, never shown again, sent only to your broker. |
| Verify the TLS certificate of the broker (mqtts) | boolean | No | Turn off only for a broker with a self-signed certificate on your local network. |
| Controller serial number (optional) | string | No | Empty: every controller of the gateway. Otherwise only this one (as Qbus System Manager shows it, for example 000123). |
| Relays and dimmers | section | No | A Qbus relay or dimmer may feed anything (a lamp, but also a circulator, the boiler, a heater, a freezer, a garage door), and a "turn everything off / on" of a voice assistant or a scene reaches every switch and every light. So a relay or a dimmer is only shown in Gladys, read only, with "Turn on" / "Turn off" buttons, until you declare it safe below: it then becomes a switch (relay) or a light (dimmer). |
| Outputs declared safe | string | No | The refs of the relays and dimmers (parameter QBUS_OUTPUT in the Discovery tab), separated by commas. With several controllers, write serial:ref (parameter QBUS_CONTROLLER, for example 000123:10): a plain ref is then applied nowhere. Only loads that may be switched off or on at any time (a lamp, a socket for a lamp). |
| Allow the "Turn on" / "Turn off" buttons | boolean | No | Off by default: the buttons of the relays and dimmers not declared safe do nothing. On: a press (dashboard, scene) switches the output. |
| Heating setpoints | section | No | The thermostats of Qbus drive the heating. Gladys shows their temperature and setpoint; changing a setpoint from Gladys (dashboard, scenes, voice assistants) is refused until you allow it here, and stays between 5 °C and the ceiling below. |
| Allow setpoint commands | boolean | No | Off by default. On: Gladys may change the setpoints of the thermostats, within the ceiling. |
| Setpoint ceiling (°C) | number | No | No setpoint above this temperature is sent (16 to 30 °C). |
| Minimum interval between two readings of a measurement (s) | number | No | Gauges may publish every second: Gladys keeps the last reading at this pace. On/off, positions and setpoints are never delayed. |
| Language of the messages | select | No |
How to install Qbus in Gladys
- In Gladys, open Integrations: Qbus appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/lm1lc3n7/gladys-qbus:0.1.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/LM1LC3N7/gladys-qbus.
Qbus requires Gladys >=5.0.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Qbus is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by LM1LC3N7, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation