The Things Network Smart-Home-Integration, kostenlos und Open Source
Unofficial connector: your LoRaWAN sensors from The Things Network / The Things Stack.
Veröffentlicht von LM1LC3N7
- Geräte
- Version 0.1.1
- Erfordert Gladys >=5.1.0
- ★ 0
Die Dokumentation dieser Integration wird von ihrem Autor geschrieben und ist bisher nur auf Englisch verfügbar.
This integration brings into Gladys the last decoded values of the LoRaWAN sensors of an application on The Things Network (the community edition of The Things Stack) or The Things Stack Cloud: temperature, humidity, pressure, light, CO2, particulate matter, soil moisture, wind, UV, distance, battery, water leak and motion.
It reads the official Storage API of The Things Stack, read only: nothing is ever sent to your devices (no downlink), nothing is changed in the console.
Unofficial connector, not affiliated with The Things Industries. The integration has never been tested with a real The Things Network account yet: your feedback is welcome.
1. Activate the Storage Integration (required)
Without it, The Things Stack keeps no message and the integration sees nothing.
- Open the console (for example https://eu1.cloud.thethings.network/console) and your application.
- Menu Integrations > Storage Integration.
- Click Activate Storage Integration.
Only the messages received after the activation are kept, for a limited time that depends on your plan (see the documentation of The Things Stack).
2. A payload formatter for each device
The integration reads the decoded payload (decoded_payload). Each
device (or the application) needs a formatter (Payload formatters >
Uplink): the one of the Device Repository, Cayenne LPP, or your own.
3. Create an API key
- In the application: API keys > Add API key.
- Give it only the Read application traffic (uplink and downlink) right.
- Copy the key (it starts with
NNSXS.): it is not shown again.
4. Configure the integration in Gladys
- Cluster: the one of your application, shown in the address of the
console (
eu1for Europe). For a The Things Stack Cloud tenant or your own server, choose Other server and enter its host name (HTTPS only, for examplemytenant.eu1.cloud.thethings.industries). - Application ID: as shown in the console.
- API key: kept by Gladys in its database, never shown again; sent only to the chosen server, in a header (never in an address), and never written to the logs.
- Read interval: 5 minutes by default (2 to 60). One request per read, for every device of the application.
Then click Test the application: the button shows the last values of each device, the fields ignored and when the next read can happen. The devices show up in the Discovery tab as soon as their first message is read.
Recognized values
A payload formatter may name its fields as it likes. The integration only creates a Gladys feature when it knows what the field measures and in which unit, and only with the units Gladys knows. A value out of bounds is left out (never clamped). Every other field is ignored (the test button lists them).
| Measure | Recognized field names (case, _ and Cayenne channel number ignored) | Unit in Gladys |
|---|---|---|
| Temperature | temperature, temp, TempC, TempC_SHT, TempC_DS, air_temperature, soil_temperature, water_temperature... | °C (-50 to 125) |
| Humidity | humidity, hum, Hum_SHT, relative_humidity, air_humidity, rh | % |
| Pressure | barometric_pressure, barometer, air_pressure, baro (300 to 1100 hPa); pressure alone: 850 to 1100 hPa | hPa (a value in Pa is converted) |
| Light | illuminance, luminosity, lux, light, light_intensity, ILL_lx | lux |
| CO2 | co2, co2_ppm, carbon_dioxide | ppm |
| Particles | pm25, pm2_5, pm10 | µg/m³ |
| Battery | battery_level, battery_percent, battery or bat: whole numbers from 6 to 100 (then 0 to 100) | % |
| Battery voltage | BatV, battery_voltage, vbat; in mV: battery_mv, bat_mv | V |
| Distance | distance_mm, distance_cm, distance_m (a distance without unit is ignored) | mm, cm, m |
| Soil moisture | soil_moisture, moisture, water_soil, vwc | % |
| Wind | wind_speed (m/s), wind_speed_kmh | m/s, km/h |
| UV | uv, uv_index | UV index |
| Water leak | leak, water_leak, leakage (true/false or a whole number: 1 and above = detected) | detected or not |
| Motion | motion, occupancy, pir (true/false or a whole number, e.g. a count of detections: 1 and above = detected) | detected or not |
SenseCAP sensors (Seeed) are read by their types (Air Temperature,
Air Humidity, Light Intensity, Barometric Pressure, UV Index, Wind Speed...) and their battery. A formatter may also declare the unit of its
fields with _sensor_attr, as in Home Assistant:
{"_sensor_attr": {"distance": {"unit": "cm", "device_class": "distance"}}}.
The type and the unit of a field are chosen when it is first read, then never
change (after a loss of /data, the feature already created decides). A
feature already created is never removed from its device.
A bare battery or bat field is ambiguous: some decoders put a rounded
voltage there (3 for 3 V) or the LoRaWAN 0-254 scale. Only a whole number from
6 to 100 is first read as a percentage; once it gave a value above 5 %, values
from 0 to 5 % are read too (a nearly empty battery stays visible). Prefer a decoder that names
battery_level or BatV.
How it works
- Each message is published once, in the order it was received: no value is lost between two reads (a leak 0 -> 1 -> 0 does reach Gladys).
- Scenes: the newest value of each feature, received since the previous read (interval + 2 minutes), is published "live": Gladys then runs the scenes, at the time of the read (so up to one interval after the measure), and the history dates it from the read. For a water leak or a motion, every change of that period is published live, in order. Older messages (catching up after a pause, a refusal or a stop) are published dated when they were received, oldest first: they go to the history without running a scene.
- Bounded catch-up: the messages of the last 6 hours, at most 48 per feature. At the very first start, only those of the last 3 hours.
- A device is identified by its DevEUI (or, without one, by the application and device IDs): a device deleted and created again with another DevEUI under the same ID becomes a new device.
- At most 100 devices (a device silent for 30 days and not created in Gladys is forgotten), 24 values per device and 1000 messages per read. A message over 256 KB is skipped (and counted in the status); an answer over 8 MB is read up to that bound (newest first): the status says so and advises a shorter interval.
- Gladys accepts 300 states per minute: the states leave in batches, within that budget; the rest waits for the next minute.
Errors and pauses
- Key refused (401), missing right (403) or application not found / Storage Integration not activated (404): the reads stop, one new try every 6 hours, or at once when you change the configuration. The status says why.
- Server busy (429 or 5xx): a pause (Retry-After, else 5 minutes doubling each time, from 1 minute to 6 hours).
- Nothing reads faster than the interval: not the test button, a
reconnection nor a restart. The time of the last request, the pauses and
the refusals are kept in
/data(never the key; only while a key is refused, a salted fingerprint of that refused key, erased by the first success).
Limits
- Read only: no downlink, no command.
- GPS positions are not taken over (Gladys has no position feature for a sensor).
- Fields without a known unit (e.g.
analog_in,Work_mode) are ignored.
Credits
The logic of the Storage API and of the payload parsers (default and SenseCAP) is ported from ttn_client (MIT, Angel Nunez Mencias), the library of the Home Assistant The Things Network integration. The Things Network and The Things Stack are trademarks of their owner.
Konfigurationseinstellungen
Diese Einstellungen fragt The Things Network in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Your LoRaWAN application | section | Nein | Unofficial connector, not affiliated with The Things Industries. It reads the last decoded values of the devices of one application through the official Storage API of The Things Stack (The Things Network community edition or The Things Stack Cloud): temperature, humidity, pressure, light, CO2, particulate matter, soil moisture, wind, UV, distance, battery, water leak and motion, when the payload formatter names them. Read only: nothing is ever sent to your devices. Before anything else, activate the Storage Integration of the application in the console (Integrations > Storage Integration), then create an API key with the "Read application traffic" right. Never tested with a real account yet. |
| Cluster | select | Nein | The cluster of your application, shown in the address of the console (eu1 for Europe). |
| Other server | string | Nein | Only with "Other server": the host name of your The Things Stack (Cloud tenant or your own server), reached over HTTPS. |
| Application ID | string | Nein | The ID of the application in the console (lower case letters, digits and dashes). |
| API key | secret | Nein | An API key of the application (it starts with NNSXS.) with the "Read application traffic (uplink and downlink)" right only. Kept by Gladys in its database, never shown again; sent only to the server above. |
| Read interval (minutes) | number | Nein | One request each time, for every device of the application. Nothing reads sooner, not even the test button or a restart. LoRaWAN sensors usually send every 5 to 60 minutes. |
So installierst du The Things Network in Gladys
- Öffne in Gladys Integrationen: The Things Network erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/lm1lc3n7/gladys-things-network: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-things-network.
The Things Network 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
The Things Network 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