air-Q Smart-Home-Integration, kostenlos und Open Source
Unofficial connector: your air-Q air quality sensors, read on the local network.
Veröffentlicht von LM1LC3N7
- Geräte
- Version 0.1.1
- Erfordert Gladys >=5.1.0
- ★ 0
Info
Die Dokumentation dieser Integration wird von ihrem Autor geschrieben und ist bisher nur auf Englisch verfügbar.
Unofficial connector, not affiliated with Corant GmbH. It brings into Gladys the values of your air-Q air quality sensors, read directly on your local network: no cloud, no account, no subscription.
This integration has never been tested with a real air-Q. It follows aioairq, the Python library of the maker that Home Assistant uses. Please report what you see on the Gladys forum.
What you get
One device per air-Q, named after the name you gave it in the air-Q app, with the values your model measures (a value the device does not send is simply not created):
| Sensor in Gladys | air-Q field | Unit |
|---|---|---|
| CO2 | co2 | ppm |
| VOC | tvoc | ppb |
| VOC (ion sensor) | tvoc_ionsc | ppb |
| PM2.5, PM10 | pm2_5, pm10 | µg/m³ |
| Carbon monoxide | co | ppm |
| Nitrogen dioxide | no2 | µg/m³ |
| Ozone | o3 | µg/m³ |
| Sulphur dioxide | so2 | µg/m³ |
| Formaldehyde | ch2o_M10 | µg/m³ |
| Temperature | temperature | °C |
| Humidity | humidity | % |
| Pressure | pressure | hPa |
| Noise, noise (peak) | sound, sound_max | dB(A) |
- The air-Q gives carbon monoxide in mg/m³; Gladys knows only ppm for it, so the value is converted (× 0.873, at 25 °C and normal pressure).
- Not in Gladys yet, because Gladys has no category for them: radon, oxygen, PM1, the particle counts, absolute humidity, the "health" and "performance" indexes, the virus and mold indexes, the dew point (a temperature that would skew the room temperature), the rarer gases of the air-Q Science. See TODO.md.
- A sensor that is still warming up after a restart of the air-Q sends no value for a while: its feature stays, the value comes back by itself.
- The names of the sensors are in English; rename them when you create them if you wish.
Installation
- Give the air-Q a fixed IP address in your router (DHCP reservation):
the integration reaches it by its address. Inside the container of the
integration, mDNS names (
<id>_air-q.local) are usually not resolved. - Install the integration from the Gladys catalog (Gladys 5.1 or newer).
- In the Configuration screen, enter the address and the device password of the air-Q, and save. Up to three air-Q.
- Click Test the air-Q: the message shows the main values of each one.
- Open the Discovery tab and add the devices. Their values arrive as soon as they are created.
Configuration
- Address: the IPv4 address of the air-Q (
192.168.1.50), optionally with a port, or its host name; the 5-character id printed on the device is turned into<id>_air-q.local, as aioairq does, for a network that resolves mDNS names. A path, an IPv6 address or credentials are refused. - Password: the device password set in the air-Q app (
airqsetupout of the box: change it in the app). It is kept by Gladys in its database (in clear, like every secret field of Gladys) and never shown again in the configuration screen. It never leaves the integration: the air-Q protects its answers with AES-256 and a key taken from this password, and the integration only uses it to open them. It is never written in the logs nor under/data. - Values: averaged (smoothed by the air-Q, the default of its app and of Home Assistant) or momentary.
- Read interval: 2 minutes by default, 1 to 60.
How often the air-Q is read
- One request per air-Q at each interval:
GET /average(or/data), preceded byGET /config(the id and the name of the device) at the first read and after any failure, since the address may then lead to another air-Q. - Never faster than the interval, counted from the last request sent: not by the test button, a reconnection to Gladys, a saved configuration nor a restart of the container. Only a new address or a new password is read at once. Before the interval has passed, the test button shows the last values and the time of the next possible read.
- Read only: the integration never writes to the air-Q (no configuration change, no blink, no restart).
- The values belong to the device that measured them: each answer carries the id of the air-Q; if another air-Q now answers at the address (two devices that swapped their addresses in the router), nothing is published until its id is read again, and then under its own device.
- A failure (no answer, another HTTP status, an answer that is not the one of an air-Q) is tried again at the next interval, never sooner.
- When the air-Q answers 429 or a 5xx (busy, restarting), it is left
alone for the
Retry-Afterdelay it gives, else 5 minutes, then 10, 20...; always between 1 minute and 6 hours, and never shorter than the interval. - When the password does not fit (the answer cannot be opened), the reads of that air-Q stop and the status says so; one new try every 6 hours (the test button may try as soon as the interval has passed), until you change the password.
- The instant of the last request, the pauses, the refusals and the id, name
and sensors of each air-Q (not secret) survive a reconnection to Gladys
and a restart of the container: they are kept in a file under
/data, never the password. Only while a password is refused, the file keeps a salted fingerprint (scrypt) of that wrong password, so that after a restart a new password is tried at once; it is erased by the first read that works, so nothing in the file can confirm a working password. A new password is tried at once while the integration runs; one changed while the container was stopped waits at most one interval. After a restart, the Discovery tab keeps showing the devices until the next read. - An answer larger than 256 KB, or slower than 10 seconds, is abandoned.
Troubleshooting
- "password refused": check the device password in the air-Q app (it is the password of the device, not the one of your air-Q account).
- "no answer": check the address (fixed IP), that the air-Q is on the same network as Gladys and that its Wi-Fi is not switched off by the night mode.
- "not an air-Q answer": the address points to another device.
- "same air-Q as another address": two addresses lead to the same device; keep one.
- Logs: the level is set with the
LOG_LEVELvariable.
Privacy
Everything stays on your local network: the integration talks only to the addresses you enter, over HTTP (the air-Q has no HTTPS), and its answers are protected by the device itself. No cloud, no account.
Credits
Built after aioairq (Apache-2.0,
Corant GmbH, the maker of the air-Q), the library of Home Assistant's air-Q
integration: the protection of the local API, the routes, the fields and the
handling of the values are ported to JavaScript. Its notice is in
THIRD_PARTY_NOTICES.md. air-Q is a trademark of its owner; this connector
is free and unofficial.
Konfigurationseinstellungen
Diese Einstellungen fragt air-Q in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| air-Q in Gladys | section | Nein | Unofficial connector, not affiliated with Corant GmbH. It reads your air-Q sensors directly on your local network (no cloud, no account): CO2, VOC, PM2.5, PM10, the gases your model measures (CO, NO2, O3, SO2, formaldehyde), temperature, humidity, pressure and noise. Read only: nothing is ever changed on the device. Enter the IP address of each air-Q (a fixed address in your router is best) and its device password. Never tested with a real air-Q yet. |
| air-Q address | string | Nein | Its IPv4 address on your network (or its host name, or the 5-character id printed on the device when your network resolves mDNS names). |
| air-Q password | secret | Nein | The device password, set in the air-Q app ("airqsetup" out of the box). Kept by Gladys in its database, never shown again; it never leaves the integration: it only opens the answers of the air-Q. |
| Values | select | Nein | Averaged (smoothed by the air-Q, as in its app) or momentary values. |
| Read interval (minutes) | number | Nein | One request per air-Q each time (two when its id is checked again). Nothing reads an air-Q sooner, not even the test button or a restart. |
| More air-Q (optional) | section | Nein | Up to three air-Q, each with its own address and password. |
| Second air-Q: address | string | Nein | |
| Second air-Q: password | secret | Nein | Kept by Gladys in its database, never shown again; it never leaves the integration. |
| Third air-Q: address | string | Nein | |
| Third air-Q: password | secret | Nein | Kept by Gladys in its database, never shown again; it never leaves the integration. |
So installierst du air-Q in Gladys
- Öffne in Gladys Integrationen: air-Q erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/lm1lc3n7/gladys-air-q:0.1.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/LM1LC3N7/gladys-air-q.
air-Q benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.
Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.
Über externe Integrationen
air-Q ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von LM1LC3N7 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.
- Alle Integrationen durchsuchen, native und aus der Community
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation