Saltar al contenido principal

Integración domótica The Things Network, gratuita y de código abierto

Integración The Things Network para Gladys Assistant

Unofficial connector: your LoRaWAN sensors from The Things Network / The Things Stack.

Ver en GitHubTodas las integraciones
info

La documentación de esta integración la escribe su autor y, por ahora, solo está disponible en inglés.

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.

  1. Open the console (for example https://eu1.cloud.thethings.network/console) and your application.
  2. Menu Integrations > Storage Integration.
  3. 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​

  1. In the application: API keys > Add API key.
  2. Give it only the Read application traffic (uplink and downlink) right.
  3. 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 (eu1 for Europe). For a The Things Stack Cloud tenant or your own server, choose Other server and enter its host name (HTTPS only, for example mytenant.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).

MeasureRecognized field names (case, _ and Cayenne channel number ignored)Unit in Gladys
Temperaturetemperature, temp, TempC, TempC_SHT, TempC_DS, air_temperature, soil_temperature, water_temperature...°C (-50 to 125)
Humidityhumidity, hum, Hum_SHT, relative_humidity, air_humidity, rh%
Pressurebarometric_pressure, barometer, air_pressure, baro (300 to 1100 hPa); pressure alone: 850 to 1100 hPahPa (a value in Pa is converted)
Lightilluminance, luminosity, lux, light, light_intensity, ILL_lxlux
CO2co2, co2_ppm, carbon_dioxideppm
Particlespm25, pm2_5, pm10µg/m³
Batterybattery_level, battery_percent, battery or bat: whole numbers from 6 to 100 (then 0 to 100)%
Battery voltageBatV, battery_voltage, vbat; in mV: battery_mv, bat_mvV
Distancedistance_mm, distance_cm, distance_m (a distance without unit is ignored)mm, cm, m
Soil moisturesoil_moisture, moisture, water_soil, vwc%
Windwind_speed (m/s), wind_speed_kmhm/s, km/h
UVuv, uv_indexUV index
Water leakleak, water_leak, leakage (true/false or a whole number: 1 and above = detected)detected or not
Motionmotion, 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.

Parámetros de configuración​

Estos son los parámetros que The Things Network te pide en su pantalla de configuración en Gladys.

ParámetroTipoObligatorioDescripción
Your LoRaWAN applicationsectionNoUnofficial 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.
ClusterselectNoThe cluster of your application, shown in the address of the console (eu1 for Europe).
Other serverstringNoOnly with "Other server": the host name of your The Things Stack (Cloud tenant or your own server), reached over HTTPS.
Application IDstringNoThe ID of the application in the console (lower case letters, digits and dashes).
API keysecretNoAn 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)numberNoOne 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.

Cómo instalar The Things Network en Gladys​

  1. En Gladys, abre Integraciones: The Things Network aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
  2. Haz clic en Instalar. Gladys descarga la imagen Docker (ghcr.io/lm1lc3n7/gladys-things-network:0.1.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración).
  3. Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
  4. También puedes instalarla directamente desde la URL de su repositorio: https://github.com/LM1LC3N7/gladys-things-network.

The Things Network requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.

¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.

Sobre las integraciones externas​

The Things Network es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene LM1LC3N7, no el equipo principal de Gladys.

Suscríbete a la newsletter de Gladys Assistant

Unos pocos correos al mes sobre nuevas versiones y novedades del proyecto. Enviados por Pierre-Gilles Leymarie, fundador del proyecto. Puedes darte de baja cuando quieras 🙂
Última actualización en