Ubidots y The Things Industries se han asociado para crear una integración preconfigurada, que permite a los usuarios enviar fácilmente datos de sensores desde el servidor de red de The Things Stack a Ubidots utilizando plugins.
Este plugin está optimizado para decodificar automáticamente el esquema JSON de The Things Stack v3 Uplink (analizando elementos como los metadatos de gateways para que no tengas que hacerlo), y aun así permite la personalización completa del decodificador utilizando NodeJS.
Requisitos
Una cuenta activa de Ubidots. Este plugin también está disponible para nuestros usuarios gratuitos de STEM 😎
Una cuenta activa de The Things Stack.
1. Creando un Plugin TTS
Un plugin TTS es una función sin servidor que expone una URL de Endpoint HTTP privada optimizada para decodificar los payloads JSON uplink de The Things Stack. Cada vez que se recibe una solicitud HTTP POST en dicha URL, se ejecutará una función de decodificación predefinida.
Para crear tu URL de endpoint HTTP privada:
En tu cuenta de Ubidots, ve a la pestaña "Dispositivos", haz clic en "Plugins", luego haz clic en el ícono "+" para crear un nuevo Plugin. Busca el Plugin TTS y haz clic en él:
2. Aparecerán las instrucciones del plugin. Haz clic en el ícono "Siguiente", luego revisa los parámetros de entrada:
Tipo de dispositivo Ubidots: Se creará un tipo de dispositivo de Ubidots y se vinculará a este plugin. Esto te permite realizar cambios masivos en todos los dispositivos que reciben datos a través de este plugin.
Token de Ubidots: Selecciona el token de Ubidots que deseas utilizar para este plugin. Recomendamos crear un nuevo token dedicado únicamente a este plugin, en caso de que necesites aumentar su límite de tasa en el futuro.
3. Termina el proceso y aparecerá un nuevo plugin en la lista de Plugins:
4. Haz clic en el plugin TTS recién creado, haz clic en la pestaña "Decodificador", y copia la "URL del Endpoint HTTPs". La estructura de la URL es la siguiente:
https://dataplugin.ubidots.com/api/web-hook/<PLUGIN-ID>
5. Finalmente, ve a tu cuenta de The Things Stack, haz clic en la Aplicación deseada luego en "Integraciones" => "Webhooks", luego haz clic en "Agregar webhook" => "Ubidots" y completa estos campos:
ID de Webhook: Elige un nombre para tu webhook.
ID de Plugin: Identificador único (
<PLUGIN-ID>) que se encuentra en la URL HTTPS de tu plugin.Token de Ubidots: Token utilizado para autenticar las solicitudes API de Ubidots.
Finalmente, el webhook debería verse algo así:
2. Decodificación de payloads de dispositivos conectados a TTS
Después de crear un plugin TTS y hacer clic en él, verás una pestaña llamada "Decodificador" que contiene una "Función de Decodificación" que puedes editar a tu gusto para decodificar tus tramas de datos.
Por defecto, verás un decodificador de ejemplo preconfigurado que realiza lo siguiente:
Registra RSSI y SNR en una variable de Ubidots; una para cada gateway que recibe una señal de tu dispositivo.
Registra un Contador de tramas y un Puerto en variables de Ubidots.
Si se encuentra, la clave JSON "uplink_message.decoded_payload" se enviará tal como está a Ubidots, asumiendo que tiene un formato compatible con Ubidots. Si no, entonces se puede utilizar un decodificador personalizado para decodificar la trama base64 enviada en "uplink_message.frm_payload".
Ubidots creará automáticamente un dispositivo cada vez que se reciba un payload de un nuevo dispositivo. Esto te ahorra la necesidad de crear manualmente cientos o miles de dispositivos, o copiar y pegar DevEUI's de una plataforma a la otra.
Aquí te mostramos cómo se asigna un payload JSON de TTS a un dispositivo Ubidots y sus variables:
Ten en cuenta que puedes cambiar algunas, pero no todas las asignaciones anteriores:
2.1. Asignación de datos que SE PUEDE editar desde la función de decodificación:
Metadatos del gateway: Puedes optar por eliminar los datos no deseados del gateway, como SNR o RSSI.
Variables: Puedes optar por eliminar variables o incluso crear nuevas utilizando NodeJS 10 (ver bibliotecas compatibles).
Marca de tiempo: Puedes optar por ignorar la marca de tiempo "received_at" del payload y hacer que la API de Ubidots asigne una automáticamente al recibirla.
2.2. Asignación de datos que NO SE PUEDE editar en la función de decodificación:
Etiqueta y nombre del dispositivo: El plugin siempre utiliza el "device_id" de TTS como etiqueta del dispositivo en Ubidots. Al crearse, Ubidots heredará el nombre del dispositivo de la etiqueta del dispositivo, pero puedes cambiar el nombre más tarde.
Propiedades del dispositivo: El plugin siempre utiliza estas claves como propiedades del dispositivo en Ubidots: "end_device_ids.application_ids.application_id", "end_device_ids.dev_eui", y "end_device_ids.dev_addr".
Si deseas tener control sobre estos, es posible que desees crear tu propia UbiFunction en su lugar.
3. Editando el tipo de dispositivo del plugin
Se creará un tipo de dispositivo de Ubidots y se vinculará a este plugin. Esto te permite realizar cambios masivos en todos los dispositivos que reciben datos a través de este plugin.
Por ejemplo, imaginemos que editaste la función de decodificación para generar dos variables: Temperatura y Presión. Por defecto, estas variables contendrán colores e íconos predeterminados, y no tendrán unidades. Si deseas que cada dispositivo futuro tenga una configuración automática y personalizada para estas variables, entonces querrás cambiar el tipo de dispositivo:
4. Solución de problemas
La mejor manera de probar el plugin es haciendo una solicitud HTTP al URL del plugin. Simplemente toma el payload JSON de muestra a continuación y envíalo en una solicitud HTTP POST utilizando un cliente HTTP de tu elección (Postman o similar). Asegúrate de agregar el encabezado "Content-Type:application/json":
Payload JSON de TTS de ejemplo:
{
"correlation_ids":[],
"end_device_ids":{
"application_ids":{
"application_id":"ubidots-playground"
},
"dev_addr":"26083CC4",
"dev_eui":"AC1F09FFFE01454E",
"device_id":"wisblock-environment",
"join_eui":"0000000000000000"
},
"received_at":"2021-03-22T17:08:02.041790248Z",
"uplink_message":{
"consumed_airtime":"0.061696s",
"f_cnt":240909,
"f_port":2,
"frm_payload":"AQmKGcgAAUxNAAHd8Q==",
"received_at":"2021-03-22T17:08:01.828644502Z",
"rx_metadata":[
{
"channel_index":4,
"channel_rssi":-62,
"gateway_ids":{
"eui":"B827EBFFFE2175FD",
"gateway_id":"rak7246g-ubidots-hq"
},
"rssi":-62,
"snr":9.8,
"timestamp":4278810051,
"uplink_token":"CiEKHwoTcmFrNzI0NmctdWJpZG90cy1ocRIIuCfr//4hdf0Qw+ul+A8aDAjxneOCBhC48cKKAyC4g9Dnw/dV"
},
{
"channel_index":4,
"channel_rssi":-35,
"gateway_ids":{
"eui":"008000000000A4CA",
"gateway_id":"ubidots-hq"
},
"rssi":-35,
"snr":10,
"time":"2020-01-12T21:40:15.686786Z",
"timestamp":610171251,
"uplink_token":"ChgKFgoKdWJpZG90cy1ocRIIAIAAAAAApMoQ8/L5ogIaDAjxneOCBhC4w5yRAyC40qmI4fRc"
}
],
"session_key_id":"AXc7ndbOC6RWaEc9jlbTOA==",
"settings":{
"coding_rate":"4/5",
"data_rate":{
"lora":{
"bandwidth":125000,
"spreading_factor":7
}
},
"data_rate_index":3,
"frequency":"904700000",
"timestamp":4278810051
}
}
}Envía el payload anterior en una solicitud HTTP POST a la URL del Plugin:
Ten en cuenta que la primera vez que se ejecuta el plugin, puede tardar unos segundos en responder. Para verificar los registros del plugin, ve al plugin, haz clic en la sección de "registros" y deberías ver una lista de las últimas ejecuciones.
