Skip to main content

openHAB smart home integration, free and open source

openHAB integration for Gladys Assistant

Bridge to openHAB: import its items (lights, shutters, sensors…) into Gladys and control them.

View on GitHubAll integrations

This integration connects Gladys to your openHAB server and offers its items in the Gladys Discovery tab: lights, switches and plugs, shutters and curtains, temperature setpoints, sensors with their units, contacts, detectors, players and locks. Once a device is added, its states follow openHAB live, and Gladys controls it through openHAB, which keeps its bindings (Zigbee, Z-Wave, KNX, Modbus, cloud…). Move to Gladys at your own pace, or run both side by side. Everything stays on your local network. Unofficial, not affiliated with the openHAB Foundation.

Tested against openHAB 5.0.1 in Docker with virtual items (no binding), not yet on many real installations: feedback is welcome on the GitHub repository.

Requirements​

  • openHAB 4.x or 5.x, reachable from the Gladys machine (same network, or a VPN).
  • An API token of an openHAB user (preferably an administrator: running a rule from a scene needs one). If your openHAB accepts requests without login (its default "implicit user role"), no token is needed.

Configuration​

Address and token​

  1. In openHAB (Main UI), open your profile (bottom left), then Create new API token. Name it "Gladys" and copy the token: openHAB shows it once.
  2. In Gladys, open the integration, Configuration:
    • Address of openHAB: like http://192.168.1.30:8080, or https://openhab.example.org behind a reverse proxy. Not a .local name, not localhost: the integration runs in its own container.
    • API token: paste it. A user name and password work too, only if basic authentication is enabled in openHAB (Settings → API Security).
  3. Click Test the connection: the openHAB version, the number of devices offered and the item types not imported show up.
  4. Open the Discovery tab and add the devices you want. Their values are sent as soon as they are added.

Choosing what to import​

An openHAB installation often has hundreds of items. Gladys offers:

  • only the items of the listed groups, if any (group names or labels, separated by commas, like gGroundFloor, Garden; an item counts when it is in one of them at any depth);
  • only the items carrying one of the listed tags, if any (tags of the item or of its equipment: semantic tags like Lightbulb, Temperature, or your own, like Gladys);
  • never the items listed in Items to leave out (*_Signal, * matches any text).

Group items are never devices themselves: they are the locations and equipments of the semantic model. Only the devices added in Gladys receive states: the others cost nothing.

Locks, garage doors and gates​

By default, locks (items tagged Lock, or points of a Lock equipment), and every item of a garage door, a gate or a door (shutter, impulse switch, strike, opener), tagged so or point of such an equipment, are read-only in Gladys: you see whether they are locked, open or closed, but neither a device, nor a scene, nor a voice assistant linked to Gladys can open them. Tick Allow commands of locks, garage doors and gates to control them (then click "Update" on these devices in the Discovery tab). The scene action that sends a command refuses them too, and refuses a group that holds one of them, while this box is not ticked.

Options​

  • Minimum interval between two values of a sensor: 10 seconds by default. A meter that reports every second is sent to Gladys at this pace. Switches, lights, shutters and detectors are never delayed.
  • Language of the feature names: the words added to the names of secondary features ("Shutter – Position"). French by default.
  • Items watched for the scenes: see the scene trigger below.

What you get​

Devices​

One Gladys device per equipment of the openHAB semantic model, with the features of its points (a lamp with its switch, dimmer and colour); an item outside any equipment is a device of its own. The name is the openHAB label, with its location ("Ceiling lamp (Living room)").

openHAB itemIn Gladys
Switcha switch, or a light (tag Light, light equipment)
Switch tagged Alarm/Status + Smoke, Water…smoke, leak, CO, motion, tamper or vibration detector
Switch tagged Locklocked or not (read-only unless allowed)
Dimmerlight brightness (with on/off when alone)
Dimmer tagged SoundVolumethe volume of a player
Colorlight colour and brightness (with on/off when alone)
Rollershuttera shutter (or a curtain): open, close, stop, position
Rollershutter garage door, gate, dooropen or closed, position (read-only unless allowed)
Contactan opening sensor
Playerplayback state, play, pause, next, previous
Number:Temperature tagged Setpointa thermostat setpoint, within the item's min and max
Number:Temperature, Pressure, Illuminance…temperature, pressure, light, power, energy, voltage, current
volume (gas, water), wind speed, noise, rain intensity
Number in % tagged Humidity, or named batteryhumidity, battery level
Number in ppm tagged CO2a CO2 sensor

String, DateTime, Location, Call, Image and group items are not imported (the connection test lists them); a String can still start a scene (trigger below) or receive a command (scene action). A Number without unit nor meaning is not imported either: give it a dimension (Number:Power) or a semantic tag.

A shutter position follows Gladys: 100 % is open (openHAB says 0 %). A Number:Dimensionless without unit metadata keeps its state in "one" in openHAB (48 % is 0.48): the bridge shows it in the unit of its pattern, like openHAB does.

Dashboard widget​

openHAB: the connection, how the states arrive (event stream or polling), the openHAB version, the devices offered and added, the items followed, and a Reload button that reads the item list again.

Scene triggers​

openHAB item changed: an item listed in Items watched for the scenes changed state, even when it is not added to Gladys (a String, an alarm mode, a doorbell). Filters: the item, and the new state (optional). Variables: item, label, new state, previous state.

Scene actions​

  • Send a command to an openHAB item: any item, any command (ON, OFF, 50, UP, PLAY, a text). Useful for the items Gladys has no feature for, or to start an openHAB rule through a virtual switch.
  • Run an openHAB rule: by its identifier (UID, shown in Settings → Rules); openHAB scenes are rules too. Needs the token of an administrator.

Scene examples​

  • When the openHAB item Alarm_Mode becomes ARMED (watched item), turn off every Gladys light and send a message.
  • At sunset, send DOWN to the openHAB group gShutters (scene action).
  • When the Gladys presence leaves home, run the openHAB rule away_mode.

Troubleshooting​

  • "openHAB refused the access": the token is wrong or was deleted; create a new one. With a user name, basic authentication must be enabled in openHAB.
  • "openHAB is unreachable": check the address from the Gladys machine (curl http://<address>:8080/rest/). A new attempt is made after 5 seconds, then up to every minute.
  • The widget says "Polling": the event stream (/rest/events) does not get through, often because of a reverse proxy buffering it. The states still arrive every 30 seconds; the stream is tried again regularly.
  • An item is missing: run the connection test, it lists the types not imported. Check the groups, tags and exclusions of the configuration.
  • A value shows 100 times too big or too small: the item is a Number:Dimensionless whose pattern says % while openHAB stores it in "one" or the other way round; give it unit metadata in openHAB.
  • Logs: set LOG_LEVEL=debug to see every state and event.

Limits​

  • Developed against openHAB 5.0.1 with virtual items: no binding nor real hardware was used. Feedback welcome.
  • Group items are not devices: a group of lights can still be commanded from a scene action.
  • A thermostat mode, a colour temperature or a fan speed have no openHAB item type of their own: they arrive as Numbers or Dimmers, and are imported as such when they have a unit, or not at all.
  • Renaming an item in openHAB creates another item: the Gladys device must be added again. Moving an item to another equipment changes its Gladys device too.
  • The names of features are fixed when the device is added in Gladys.

Privacy​

The bridge talks only to your openHAB server, on your network. The token (or the password) is stored by Gladys in its configuration and never written to the logs. Nothing is sent to the internet.

Configuration settings​

These are the settings openHAB asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Your openHAB items in GladyssectionNoGladys reads the items of your openHAB server through its REST API and follows their changes live. Create an API token in openHAB (your profile, at the bottom: Create new API token). If your openHAB accepts requests without login, the token can stay empty. The items then show up in the Discovery tab, grouped by equipment of the semantic model: add the ones you want.
Address of openHABstringYesIts IP address and port, as seen from the Gladys machine. Not a .local name, not localhost.
API tokensecretNoEmpty if your openHAB accepts requests without login.
User name (instead of a token)stringNoOnly if basic authentication is enabled in openHAB (API security settings). A token is preferable.
PasswordsecretNo
Only the items of these groupsstringNoGroup names or labels, separated by commas: an item counts when it is in one of them, at any depth. Empty: every item.
Only the items with these tagsstringNoTags of the item or of its equipment, separated by commas (semantic tags like Lightbulb or Temperature, or your own). Empty: every item.
Items to leave outstringNoItem names, separated by commas; * matches any text. Never imported.
Allow commands of locks, garage doors and gatesbooleanNoOff: locks, garage doors and gates show their state, but Gladys cannot open them, from a device, a scene or a voice assistant.
Minimum interval between two values of a sensor (s)numberNoA power meter that reports every second is sent to Gladys at this pace. Switches and detectors are never delayed.
ScenessectionNoItems listed here start the scene trigger "openHAB item changed" at each change of state, even when they are not added to Gladys (a String, a DateTime, an alarm mode…).
Items watched for the scenesstringNoItem names, separated by commas; * matches any text.
Language of the feature namesselectNo

How to install openHAB in Gladys​

  1. In Gladys, open Integrations: openHAB appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-openhab:1.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-openhab.

openHAB requires Gladys >=5.1.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​

openHAB 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 guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on