Gira X1 / HomeServer smart home integration, free and open source

Gira X1 and HomeServer lights, covers and scenes, through the local IoT REST API. Unofficial.
This integration connects your Gira X1, HomeServer or FacilityServer to Gladys through the Gira IoT REST API v2 of the server, on your local network. Unofficial, not affiliated with Gira (Gira Giersiepen GmbH & Co. KG).
Never tested with a real device yet: the integration was written from the official documentation "Gira IoT REST API v2" (Gira, July 2020) and tested against a simulated server. Your feedback is welcome.
Servers
The documentation of Gira lists the Gira X1 (firmware 2.4 or later) and the
Gira HomeServer / FacilityServer (firmware 4.10 or later). The Gira One
server is not in that documentation: it works if it answers the same API
(GDS-REST-API, version 2), which "Test the connection" checks.
What you get
The functions of your project (as set up in the Gira Project Assistant, GPA) are offered in the Discovery tab:
- Switched lights: on/off;
- Dimmers, coloured lights and tunable white lights: on/off and brightness (the colour and the colour temperature are not driven yet);
- Shutters and blinds: open, close, stop, and the position when the function has one (the slats are not driven yet).
The scenes of the server run from the scenes of Gladys, with the scene action Run a Gira scene (see below).
Not offered: heating and cooling, sauna, audio, cameras, links, status values, value transmitters, and the "Trigger" and "Press and hold" functions (they may drive a door opener).
The device ids are the ids (UID) the server gives each function
(function:<uid>): they do not change with a firmware update, and the
documentation of Gira says a UID is never given again soon to something else.
A function deleted and created again in the GPA is a new device.
Configuration
- In the GPA, create a user for Gladys on the server (a dedicated one is best).
- In Gladys, type the IP address of the server, the user name and the
password, and save. Names in
.localdo not resolve in the container. - Click Trust the certificate: the fingerprint of the certificate of the
server is shown, nothing else is sent. To check it, open
https://<address of the server>/in a browser of your network and compare the SHA-256 fingerprint in the details of the certificate. Click again within 2 minutes to trust it: it is trusted from then on (trust on first use), and a different one later stops everything. - Click Test the connection: it checks the API, the user and reads the project.
- Add the devices you want from the Discovery tab.
The password is kept by Gladys in its database, never shown again, sent only
to the server at the address typed, and only on a connection whose
certificate is the trusted one. It registers the client
io.github.lm1lc3n7.gladys-gira with the server (POST /clients), which
gives a token; the token stays in memory only (the server gives the same one
again at the next start of the container). A user name or password refused
by the server is never tried again by itself: the integration waits for new
ones or for a successful "Test the connection" (only a 6-bit mark of the
refused ones is kept in /data, never enough to tell them).
Certificate of the server
The server has a certificate no browser trusts (Gira says so in its documentation). Instead, the integration trusts one certificate: confirmed by your two clicks on Trust the certificate, or typed in the Certificate fingerprint field. Without it, nothing is sent at all. If another certificate shows up (server replaced, certificate renewed, or another device at this address), nothing is sent, not even a stop nor the password, and the status shows the fingerprint seen. To trust it: click Trust the certificate twice, or type this fingerprint in the configuration.
What always leaves, what is off by default
Off by default: Gladys only reads. Three options open the rest:
- Allow switching on and dimming: switch a light on, set a brightness;
- Allow opening covers: open a cover, or move it to a position (any position but fully closed may open it); extend an awning; close a garage door or a gate, and stop those without a "Movement" data point (see below);
- Allow Gira scenes: a scene of the server may switch on anything and open covers or doors.
The option is read again right before sending: turned off while a command waits, the command is refused.
Always leave, whatever the options: turning off a light (a brightness of 0 is a turning off), stopping a cover (but a gate without "Movement", see below), closing a shutter (a position of 0 is a close). No option, no 429 pause, no project being read again, no read or command in flight holds them back. They cancel the commands of the same target still waiting, and the older protective command of the same target: a newer one always wins, and when the older one is already written, the newer one leaves once the server answered it.
Beware: the "Switch" functions (switched lights) may also feed a socket or a pump: a "turn everything off" of Gladys or of a voice assistant turns them off too. List them in Functions not offered if they must never be touched.
Awnings, garage doors and gates
The API of Gira has one kind of function for every cover: it cannot tell a
shutter from an awning or a gate. Tell it in the configuration, with the ids
of the functions (GIRA_FUNCTION in the Discovery):
- Awnings (reversed direction): "close" retracts the awning (up, never held back: what you want before a storm), "open" extends it (needs the opening option); the position is the extension; a stop is a step up (in). Without this, "close" (down, in KNX) extends an awning, for instance in a "strong wind, close every cover" scene.
- Garage doors and gates: closing needs the opening option too (someone may stand under them). A stop is a step, which moves a gate at rest: when the function has a "Movement" data point, it is read first and the stop leaves only if the gate is not shown at rest (not read: in doubt, the stop leaves); without "Movement", stopping a gate needs the opening option too. With the option, this stop goes like every stop: neither a 429 pause, nor a project being read again, nor the start (before the first read of the server), nor a read or a command in flight holds it back; the option is read again before each try and right before sending (turned off meanwhile: nothing sent).
- Functions not offered: never offered nor commanded, not even a stop (a door opener, a pump...); a stop kept before the function was listed is dropped.
When a stop does not leave
A stop does not leave only in these cases:
- user name or password missing or invalid, or refused by the server;
- no trusted certificate, or certificate changed;
- server unreachable, locked (423, while a project is loaded), asking to slow down (429), or the route refused (403; or 401 again after the one new registration that a refused token triggers at once);
- before the configuration is first read from Gladys (container start): it is refused, nothing sent (the address is not known yet);
- the function is in Functions not offered;
- the stop of a gate without "Movement" while the opening option is off (at the click, before a try or right before sending);
- "Movement" read at 0: the function is already at rest, nothing to send (a gate before its first try, a cover before a new try).
What happens then depends on the stop:
- Stopping a cover ("Step-Up-Down") is never sent again once something reached the server: on a cover at rest, each one is a short step (down, up for an awning). When nothing reached the server (refused, too slow, locked), it is tried again about every second, up to about 3 seconds after your click. When the function has "Movement", it is read before each new try: 0, already stopped, given up; 1, sent, and only a read of 1 stretches the tries to 10 seconds; not read (error, too slow), it is as without "Movement": no try after about 3 seconds. Then it is given up. The answer says what happened: done, "Stop not sent yet... up to N s..., then given up", or "Stop not sent... click again". Sent without an answer of the server, it is never sent again ("Sent, without answer"). A stop waiting for a free connection waits 3 seconds at most.
- Closing a cover ("Up-Down") is tried again while nothing reached the server (or the server refused it unexecuted: 423, 429, 401/403), at most 20 seconds after your click, every 5 seconds; on a cover with a position, only after a read of it, once per read: closed or closing, it is done; read more open than when you clicked twice in a row, it was opened by hand meanwhile and the close is dropped. Taken by the server, or sent without an answer, it is done and never sent again (nor after a restart).
- Turning off a light ("OnOff" 0) is kept while nothing reached the
server, also in
/datawith the date of your click, and sent again every 5 seconds, at most 10 minutes after your click (a restart of the container sends it first; older, it is dropped). Taken by the server, it is read back at once, after 2 and 5 seconds (never during a 429 pause); a read started in the 10 seconds after the answer that shows it not applied sends it again (4 sends at most). After these 10 seconds, it is dropped ("taken, not confirmed"): a light switched on by hand afterwards is never switched off again. A switch-off that reached the server is never replayed after a restart. When OnOff cannot be read on the function, it is done once the server took it.
A newer command of the same target, taken by the server, replaces a kept stop. After a restart of the container, the first stop registers the client again before it leaves (its own registration, never waiting for one of the reads). A stop on a data point the server no longer knows (404) is dropped. At most 8 protective requests are open at once (the others wait their turn).
KNX conventions used: "Up-Down" 0 is up and 1 is down; a stop is "Step-Up-Down" 1 (0 for an awning), which stops a moving cover; the position of the server is in percent closed (an awning: percent extended), shown in Gladys in percent open (an awning: extended).
Scenes
- Allow the scenes (option Allow Gira scenes).
- Click List the scenes: it shows the scene functions of the project
with their id, like
a0f1: Evening. - In a scene of Gladys, add the action Run a Gira scene with this id and the scene number (0 to 64), sent as is to the "Execute" data point of a scene set (or "Scene" of a scene extension), as set in the GPA.
A scene is refused when the option is off, when the id is not a scene function of the project, when the project is being read again, and for the same reasons as any other command (server not connected, 429 pause...). Any stop that arrives while a scene waits cancels it.
What a refused command says
A command (other than a stop) leaves within 3.5 seconds or not at all: "nothing sent" says it never left. "Refused by the server" gives its reason; "locked" says a project is being loaded; "Not allowed for this user (403)" that the user lacks this right in the GPA. "Sent, without confirmation" says it left with no answer; "not applied yet" that a read back does not show it yet. In these last two cases, the device is read again after 5 and 20 seconds and its badge says so meanwhile. Opening a cover ("Up-Down") cannot be read back (write only): it is done once the server took it, and the position is read again after 5 and 20 seconds.
Reads
The server cannot reach the container of the integration, so its callbacks
are not used: the integration reads at the chosen interval (60 s by
default, 30 s at least). Each read asks the id of the project (uiconfig/uid)
and, when it changed (GPA download, change in the Gira app), the whole
project again; no command but the stops leaves until it is read. Then the
values of each device created in Gladys, one request at a time (150 per read
at most, in turn beyond). A function whose values are refused (401, 403) is
read again later (twice the interval, doubling up to 1 hour), without
stopping the others.
Never faster: neither the Scan button (which publishes the Discovery again without reading), nor "Test the connection" (which then says when it can test again), nor a restart of the container reads before the interval after the last read; another address, user or password saved reads at once. While the user is refused, "Test the connection" tries at once, once per 10 seconds. During a pause asked by the server (429), neither the Test button nor the reads send a request, the confirmation reads of the stops neither; only the stops leave.
A project of more than 500 functions: only the first 500 are offered, and the status says so.
Known limits
- Colour, colour temperature and slats are not driven yet.
- No live updates: the changes made elsewhere are seen at the next read.
- The scene numbers are sent as typed: check them against your GPA.
Troubleshooting
- "The certificate of the server changed": see above.
- "The Gira server refused the user name or the password": check the user in the GPA, save the right password or click "Test the connection".
- "The server is locked": a project is being loaded from the GPA; it comes back by itself.
- "/data is unreadable": it is read again every 10 seconds (one read at a
time); meanwhile the integration learns and keeps nothing (certificate,
stops), and starts again with what
/dataholds once it is read. Typing the fingerprint of the certificate in the configuration lets it work meanwhile.
Configuration settings
These are the settings Gira X1 / HomeServer asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your Gira server in Gladys | section | No | The lights, dimmers and covers of your Gira X1, HomeServer or FacilityServer (as set up in the Gira Project Assistant) are offered in the Discovery tab; its scenes run from the scenes of Gladys. Everything stays on your local network, through the Gira IoT REST API v2 of the server. Fill in the address and a user of the server, save, click "Trust the certificate" twice, then "Test the connection". Never tested with a real device yet. Unofficial, not affiliated with Gira. |
| Address of the Gira server | string | Yes | The local IP address of your Gira X1 or HomeServer, like 192.168.1.40 (shown in the Gira Project Assistant or in your router). The password is sent to this address only, over its pinned certificate. |
| User name | string | Yes | A user of the Gira server (created in the Gira Project Assistant). A dedicated user for Gladys is best. |
| Password | secret | Yes | The password of this user. Kept by Gladys in its database, never shown again, and sent only to the Gira server at the address above. |
| Certificate fingerprint (optional) | string | No | The SHA-256 fingerprint of the certificate of the server. Empty: confirmed by your two clicks on "Trust the certificate", then checked on every connection (the password never goes to another certificate). |
| Read interval (s) | number | No | How often the states are read (30 to 3600 s), one request per device created. Never faster, even after a restart. |
| Commands | section | No | Off by default: Gladys only reads. Turning off a light and stopping or closing a shutter always leave, whatever the options below. Beware: on an awning, "close" (down, in KNX) extends it, and on a garage door or a gate a close is never held back: list them below. A scene of the server may open covers or doors: it has its own option. |
| Allow switching on and dimming | boolean | No | Off by default. On: Gladys may switch lights on and set their brightness. |
| Allow opening covers | boolean | No | Off by default. On: Gladys may open the covers (extend the awnings listed below) and move them to a position (any position but fully closed may open). Garage doors and gates listed below close only with this option, and those without a Movement data point stop only with it (a stop is a step, which moves a gate at rest). |
| Allow Gira scenes | boolean | No | Off by default: a scene of the server may switch on anything and open covers or doors. On: the scene action "Run a Gira scene" runs them. |
| Functions not offered | string | No | The ids of the functions Gladys must neither offer nor command, not even a stop (GIRA_FUNCTION in the Discovery, like a029), separated by commas. For a door opener, a pump, anything Gladys must not touch. |
| Awnings (reversed direction) | string | No | The ids of the shutter functions that drive an awning, separated by commas. For them, "close" retracts (up, never held back) and "open" extends (needs the opening option); the position is the extension; a stop steps up (in). |
| Garage doors and gates | string | No | The ids of the shutter functions that drive a garage door or a gate, separated by commas. For them, closing needs the opening option too (someone may stand under them); a stop (a step) leaves only when Movement does not show the gate at rest, or, when the function has no Movement, only with the opening option (then like every stop: neither a 429 pause nor a read holds it back). |
| Language of the feature names | select | No | Used for the names of the features of the devices added from now on, and for the refusals. |
How to install Gira X1 / HomeServer in Gladys
- In Gladys, open Integrations: Gira X1 / HomeServer appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/lm1lc3n7/gladys-gira: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-gira.
Gira X1 / HomeServer requires Gladys >=5.3.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
Gira X1 / HomeServer 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