Lightwave Smart smart home integration, free and open source
Lightwave Smart lights, sockets, sensors and radiator valves (UK) via the Lightwave cloud API.
Published by LM1LC3N7
- Devices
- Version 0.1.2
- Requires Gladys >=5.1.0
- ★ 0
Shows and commands in Gladys the Lightwave Smart devices of your Lightwave account (United Kingdom; Link Plus hub, generation 1 "Connect" and generation 2 "Smart" devices), through the public API of Lightwave.
Never tested with a real account. The integration talks to the public API that Lightwave opens to every account (
publicapi.lightwaverf.com), written from the lightwave2 library and its Home Assistant integration, and tested with made-up answers only. Lightwave may change the API. Not affiliated with Lightwave.
What you get
One Gladys device per Lightwave "feature set" (a light, a socket, a radiator valve…), 500 at most:
| Lightwave device | Gladys features |
|---|---|
Light, dimmer (a dimLevel) | On/Off (light/binary), Brightness (0 to 100), Power in W when the device reports it |
Socket, relay, switch (a switch without level) | On/Off (switch/binary), Power in W when reported |
| Radiator valve (TRV) | Temperature (°C), Target temperature (°C), Heating now (see below), Battery (%) |
Thermostat, boiler or heating relay (heatState) | Temperature, Target temperature, Mode (off / heating), Heating now (1 = call for heat) |
| Window or door sensor | Window (0 = open, 1 = closed, Gladys' opening sensor), Battery |
| Movement sensor | Movement (1 = yes), Battery |
- Brightness: 0 turns the light off; any other value sets the level then turns the light on (two requests, as the Lightwave app does).
- Target temperature and Mode "heating": refused until you turn on Allow the heating commands in the configuration. A target is also refused below 5 °C or above the Highest target temperature of the configuration (25 °C by default, 40 °C at most: Lightwave's own limit); it is never brought within the bounds.
- Heating now (read only):
valveLevelabove 0 for a radiator valve (Lightwave may also use this value for the valve presets: to confirm on a real valve), the call for heat for a thermostat. - Not shown in this version: the Link Plus hub, three-way relays (blinds,
garage doors), the LED colours, the physical button events, the button
lock (
protection), the cumulative energy (Wh) of the sockets, the signal strength, the illuminance of the sensors.
Lights (light/binary) and sockets or relays (switch/binary) are ordinary
Gladys commands: an "everything off" of Gladys, of a voice assistant or of a
scene turns them off too. Do not wire a relay to something that must never be
cut from Gladys (a freezer, a gate motor): leave it out of Gladys.
Turning the heating off
Mode "off" of a thermostat and 5 °C of a radiator valve (or of a thermostat) are the protective commands. They are held back neither by the heating option, nor by a pause after a 429 or a 403, nor by the new tries after an error, nor by the other commands of the device: a command of the same device still waiting is cancelled, and one already on its way makes the "off" leave again once it is answered. After a restart of the integration they work before the first read (the integration keeps the identifiers of the heating devices). Without a bearer token they first get one. They are then checked by a read: a read that still shows the device heating sends them again (3 times at most) and the status says so.
They can still fail, and Gladys then shows the cause:
- the tokens were refused by Lightwave (no token to send them with; a refusal met by the "off" itself stops the integration as a read would);
- the token endpoint answered unexpectedly less than a minute ago (it is asked again once a minute at most);
- the device was never read by this integration (no identifier kept);
- after new tokens, before the first read: the device is not in the homes of the account now configured (one read of the list of homes checks it; a new token of the same account works at once);
- the token endpoint or the API does not answer, or refuses (401 on a token just issued, 403, 404, 429 on the write itself);
- the command could not leave within 4.3 seconds ("not sent yet": it leaves as soon as possible, check the device);
- an error after it left (5xx, no answer): "sent, without confirmation";
- an invalid value.
Setup
- Sign in to my.lightwaverf.com, open the API page of your account and create an API token and a refresh token (Lightwave calls them "basic" token and "refresh" token).
- In Gladys, install the Lightwave Smart integration from the store, paste the two tokens, save.
- Open the Discovery tab and add the devices.
The two fields are secret fields: Gladys keeps them in its database (in
clear, as any configuration value, and in its backups), never shows them
again, and the integration sends them only to Lightwave
(auth.lightwaverf.com). The API token identifies your account; the refresh
token is exchanged for a bearer token that lives as long as Lightwave
says and is kept in memory only.
The refresh token changes
Per lightwave2, Lightwave gives a new refresh token with every bearer token, and the one used is then spent (to confirm on a real account). The integration keeps the new one in the Gladys configuration by itself (one hidden value beside the field: the token Lightwave gave last, with a hash of the one you pasted, never that one itself), so a restart or a renewal uses the right one without you doing anything. The pasted field stays as you left it; paste a new refresh token only when the status asks for it.
If Gladys could not save the new token (Gladys unreachable at that moment), the status says so: the token is kept in memory and saved again at the next read. Do not restart the integration before the status is back to normal, or the new token is lost and the status asks for another one.
Refresh
The feature values are read every 60 seconds by default (30 to 300, Refresh interval), one request per 150 features, 10 requests at most (beyond, each cycle goes on where the previous one stopped); the hierarchy (the homes of the account and their devices) is read once an hour, one request per home plus one for the list. A home that fails to be read keeps its last devices, marked "unreachable", with their last values not sent again; it is tried again 5 minutes later, without stopping the reads of the other homes. One read request that fails marks only its own devices unreachable. A value older than twice the interval (10 minutes at least) is never sent to Gladys again, not even after an outage, an update of the device or a reconnection to Gladys.
A command leaves at once; the value sent is shown at once, the devices commanded are read again 2 seconds later in one request, and a slightly late read does not undo the commanded value (15 seconds). A target or a mode that a read still contradicts after 15 seconds is said in the status ("not applied"); it is not sent again by itself. The commands of one device go one after the other. Gladys waits 5 seconds for the answer: a command that has not left 3 seconds after the click (queue, token renewal in progress, slow network) is refused without having been sent; a command sent but slow is answered at 4.3 seconds and its effect shows afterwards.
The Test the connection button renews the bearer token if needed and reads the devices once, but not sooner than the interval after the last read (it then tells when the next read comes), and at most once every 30 seconds.
Troubleshooting
- API token or refresh token refused (HTTP 400 or 401 of the token
endpoint with an OAuth error such as
invalid_grant): the integration stops, even after a restart, and does not try again by itself (a spent refresh token stays spent, and new tries could lock the account). Generate a new refresh token on the API page, paste it, save: one new try at once. - Unexpected answer of the token endpoint (any other answer: a 403, a page of a proxy…): the tokens are probably still good; the integration stops until you click Test the connection or save the configuration.
- Bearer token refused by the API (HTTP 401): a token older than 10 minutes is renewed once and the request sent again. A token just issued that the API refuses is not renewed again (it would spend a refresh token each time): new tries after 2 then 4 minutes without a new token, the devices marked unreachable, then a stop at the third refusal, lifted by the button, a save of the configuration or new tokens. A 401 on a command that is not protective never renews from the command: the command fails, the next cycle renews.
- Too many requests (HTTP 429): a pause of 1 minute to 6 hours
(Lightwave's
Retry-After, 15 minutes without it) for the reads, the commands that are not protective and the button, kept after a restart or a reconnection to Gladys. - HTTP 403 of the reads: a one-hour pause of the same paths. A 403 of a command is that command refused, nothing else.
- Lightwave unavailable (5xx, network, bad answer): new tries after 1, 2, 5, 10, then every 15 minutes, not sooner than the interval.
Limits
- Public API: Lightwave may change it or limit its use.
- No live updates (the webhooks of the public API need a public URL): one read every 30 to 300 seconds. Gen 1 devices do not report their state by themselves: a change made on the wall switch may take a cycle to show.
- One Lightwave account per Gladys, ten homes, 500 devices at most.
- No three-way relays, LED colours, button events, energy index nor settings in this version.
- Never tested with a real account: please report what you see on the GitHub repository (without your tokens).
Privacy
The integration keeps in /data/lightwave-state.json (readable by its own
container only): a random salt, the end of a pause, the time of the last read
attempt, a stop on refused tokens tied to a salted fingerprint of the two
tokens, and the Lightwave identifiers of the mode and target features of the
heating devices of the account (to turn them off after a restart; never
used with another account (checked against the homes of the account when
the tokens change), kept while the device is in Gladys). Never a token: the bearer
token lives in memory, the refresh token in the Gladys configuration. The
device and feature ids of Lightwave are the identifiers of the Gladys
devices. Nothing is sent anywhere but to Lightwave.
Configuration settings
These are the settings Lightwave Smart asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your Lightwave account | section | No | Shows the Lightwave Smart devices of your account (Link Plus hub, generations 1 and 2) in Gladys: lights and dimmers, sockets and relays (on/off), radiator valves and thermostats (temperature, target, mode, heating state), window and movement sensors, battery, power in watts. Open the "API" page of my.lightwaverf.com, create an API token and a refresh token, paste them here and save, then add the devices from the Discovery tab. Read every 60 seconds; the heating commands (except "off" and 5 °C) are off until you allow them below. Public API of Lightwave, never tested with a real account. Not affiliated with Lightwave. |
| API token | secret | Yes | The "API token" (basic) of the API page of my.lightwaverf.com. Kept by Gladys in its database, never shown again, sent only to Lightwave (auth.lightwaverf.com). |
| Refresh token | secret | Yes | The "refresh token" of the same page. Per lightwave2, Lightwave gives a new one at each renewal; the integration keeps it in the Gladys configuration by itself. Paste a new one only if the status asks for it. |
| Refresh interval (s) | number | No | Seconds between two reads of the devices (30 to 300): one request per 150 features each time, plus one per home every hour. |
| Allow the heating commands | boolean | No | Off by default: any other target temperature than 5 °C and the "heating" mode are refused. "Off" and 5 °C are not held back by this option nor by a pause; they can still fail (refused tokens, Lightwave errors: see the guide). |
| Highest target temperature (°C) | number | No | A target above it is refused (5 to 40 °C, 25 by default; Lightwave accepts up to 40). |
| Language of the feature names | select | No | Used for the feature names of the devices added from now on, and for the command errors. |
How to install Lightwave Smart in Gladys
- In Gladys, open Integrations: Lightwave Smart appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/lm1lc3n7/gladys-lightwave:0.1.2), 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-lightwave.
Lightwave Smart 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
Lightwave Smart 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