Sigfox dispositivos de área amplia y bajo consumo con la plataforma de desarrollo de aplicaciones IoT de Ubidots facilitan una solución IoT simple de integrar, desde el hardware hasta la experiencia del usuario final. Aplicaciones construidas en Ubidots para rastrear y monitorear activos (coches, autobuses, basureros, o incluso tu bolsa de golf) a través de largas distancias.

Al completar este tutorial, siguiendo cada paso de cerca, podrás comunicar datos desde el backend de Sigfox a Ubidots cuando los datos puedan ser utilizados como una solución. Esta integración requerirá el complemento de UbiFunctions, una herramienta de características de la plataforma de desarrollo de aplicaciones IoT de Ubidots que permite a los usuarios crear una API o endpoint personalizado para su aplicación.

Requisitos

Cuenta de Ubidots con una licencia de IoT Entrepreneur o superior.
Cuenta de Backend de Sigfox
Cualquier dispositivo Sigfox (Ya transmitiendo datos al Backend de Sigfox)

1. Entendiendo los Mensajes de Sigfox

Si no estás familiarizado con Sigfox y el Backend de Sigfox, te recomendamos revisar esta Descripción General de la Tecnología Sigfox antes de continuar con esta guía.

Comencemos observando la estructura de los mensajes de un dispositivo Sigfox. Como ya sabes, la red Sigfox permite enviar (uplink) hasta 12 bytes por mensaje con un número máximo de 140 mensajes por día.

En este punto, es importante aclarar que los dispositivos Sigfox transmiten datos en diferentes estructuras de carga útil dependiendo del fabricante del dispositivo. Se sugiere revisar la hoja de datos proporcionada por el fabricante para entender la carga útil codificada y su estructura, y cómo debe ser decodificada antes de ser publicada en Ubidots.

Para fines de prueba, supongamos que tu dispositivo Sigfox va a enviar los datos utilizando la siguiente estructura de carga útil de ejemplo a Ubidots:

Datos de ejemplo del Dispositivo Sigfox: 4fc1b6c81cc23c5514

¿Dónde están los bytes? ¿Y cómo entendemos la carga útil?

0x4F - Temperatura - Bytes #0 (1 byte)
0xC1B6C81C - Latitud - Bytes #1 - #4 (4 bytes)
0xC23C5514 - Longitud - Bytes #5 - #9 (4 bytes)

Total de bytes = 9

Si aún no lo ves, déjame resaltar que el dispositivo está enviando datos de temperatura y coordenadas a Ubidots. Estos datos son interpretados, entendidos y decodificados de manera segura por el backend de Sigfox.

Ahora, suponiendo que los datos anteriores son recibidos en el Backend de Sigfox, es hora de configurar un Callback. El Callback de Sigfox es la función que, cuando se utiliza correctamente, puede retransmitir datos a Ubidots Cloud utilizando el protocolo HTTP.

Para esta guía, vamos a enviar parámetros básicos como el id del dispositivo y los datos recibidos en bytes a Ubidots. Luego, utilizando la función UbiFunctions, se parseará y decodificará la estructura de carga útil en una estructura de datos compatible con Ubidots. Ahora, basado en esto, el cuerpo del callback debería tener la siguiente estructura:

{  "device_id": "{device}",  "data":"{data}"}

Ahora, con un entendimiento básico de una carga útil de Sigfox, veamos cómo configurar la UbiFunction para decodificar la carga útil proveniente de Sigfox, además de cómo configurar el callback en el backend de Sigfox para asegurar que los datos lleguen de manera segura a tu cuenta de Ubidots.

2. Configuración de UbiFunctions

NOTA IMPORTANTE: Esta guía asume que tu Dispositivo Sigfox es capaz de transmitir datos al Backend de Sigfox.

Nota: Una UbiFunction es una función en la nube de Node.js o Python que se ejecuta cuando se realiza una solicitud GET o POST en la URL de la función, como se ilustra a continuación.

1. Ve al módulo de UbiFunctions accediendo a tu cuenta de Ubidots –> Dispositivos –> Funciones.

NOTA: Si no puedes ver el módulo "Funciones" en el menú de tu cuenta, necesitarás habilitar el complemento de $29/mes en la sección de facturación de tu cuenta.

2. Haz clic en el ícono azul "+" en la esquina superior derecha para crear una nueva función:

3. Por defecto, cada Ubifunction se llena con un código de ejemplo. Ahora necesitas configurar la función para que funcione mejor para tus necesidades.

Las configuraciones predeterminadas para la función son como se muestra a continuación:

Para comenzar, asigna el nombre deseado para tu UbiFunction. Recomendamos usar el formato "Marca-Referencia", es decir, "Sigfox-Suntech", "Sigfox-Oyster" o "Sigfox-Thinxtra". Para este ejemplo, vamos a asignar "Sigfox-Device" como el nombre.

Luego, selecciona POST como Método HTTP, y selecciona entre NodeJS 10, Python 3.6 o Python 3.7 como Runtime. Para este ejemplo, hemos elegido NodeJS 10. Hasta ahora, la configuración de tu función debería verse como sigue:

4. Ahora es el momento de desplegar la UbiFunction para generar la URL del endpoint de la API que se va a utilizar para transmitir los datos desde el Backend de Sigfox a Ubidots.

Para desplegarla, haz clic en "Hacerla activa":

Ahora la URL del endpoint resultante se verá algo así:

NOTA IMPORTANTE: Mantén esta URL Endpoint en tu portapapeles ya que la usarás al configurar el callback de Sigfox.

5. Borrar el código predeterminado ubicado en el editor de UbiFunction, luego copia y pega el siguiente código de ejemplo. Después de pegar, asegúrate de asignar tu TOKEN de Ubidots donde se indica:

var request = require('request-promise');/* Asigna tu TOKEN de Ubidots */var token = "YOUR-UBIDOTS-TOKEN-HERE";var url_Base = "https://industrial.api.ubidots.com";/**************************************************Solicitud POST a Ubidots **************************************************/async function ubidotsPost(token, device_label, data) {var options = {method: 'POST',url: url + '/api/v1.6/devices/' + device_label,body: data,json: true,headers: {'Content-Type': 'application/json','X-Auth-Token': token}};return request.post(options);}/*************************************************** FUNCIÓN PRINCIPAL *+************************************************/async function main(args){console.log(args);/* Guarda el ID del dispositivo del Dispositivo Sigfox */var device_id = args.device_id;/* Guarda los datos recibidos de Sigfox */var buf = new Buffer(args.data, 'hex');/* Analiza los datos entrantes */var temp = buf.readInt8(0); var lat = buf.readFloatBE(1);var lng = buf.readFloatBE(5);/* Descomenta las líneas a continuación para depurar los valores decodificados *//*console.log(temp);console.log(lat);console.log(lng);//* Construye el cuerpo para ser POST en Ubidots */var payload = {"temperature": temp, "position": {"value":"1", "context":{"lat": lat, "lng":lng}}};/* Realiza la solicitud POST a Ubidots */var post_response = await ubidotsPost(url_Base, token, device_id, payload);/* Pasa la respuesta de la API de Ubidots a la respuesta de la función */return post_response;}

– Desglose y Explicación del Código de Ejemplo

1. Primero que todo, necesitamos establecer la función que enviará los datos a Ubidots ejecutando una solicitud HTTP POST. Para esto, utilizaremos ‘request-promise’ que es un cliente de solicitud HTTP simple para NodeJS.

async function ubidotsPost(url, token, device_label, data) {   var options = {      method: 'POST',      url: url + '/api/v1.6/devices/' + device_label,      body: data,      json: true,      headers: {         'Content-Type': 'application/json',         'X-Auth-Token': token      }   };   return request.post(options);}

2. La función principal se encarga de recibir datos del Backend de Sigfox. Como habrás notado, el argumento de la función principal es ‘args’; este argumento contendrá el cuerpo del callback configurado en el Backend de Sigfox.

async function main(args) {// Recibir y analizar datos para ser publicados en Ubidots}

RECORDATORIO: El cuerpo de ejemplo del callback será el siguiente:

{ "device_id": "{device}", "data":"{data}"}

Ahora, dentro de la función principal necesitamos gestionar los datos recibidos. Esta parte del código será diferente dependiendo del hardware y su estructura de carga útil.

Suponiendo que nuestros datos de ejemplo (Temp y Coordenadas) están en el Backend de Sigfox, ahora veremos cómo decodificar la carga útil en un formato compatible con Ubidots, utilizando el motor de UbiFunctions para transformar/parsear los datos.

2.1. La porción de código de ejemplo a continuación toma los parámetros recibidos del Callback de Sigfox y asigna el device_id como una variable temporal y los datos hexadecimales como un buffer hexadecimal.

/* Guarda el ID del dispositivo del Dispositivo Sigfox */var device_id = args.device_id; /* Guarda los datos recibidos de Sigfox */var buf = new Buffer(args.data, 'hex')

La variable device_id es un identificador único (ID del Dispositivo Sigfox) por dispositivo, asignado por el backend de Sigfox, y basado en la pieza subyacente de hardware que envía los datos del sensor.

Nota: Dado que el ID de Sigfox es único, se pueden desplegar múltiples dispositivos utilizando la misma UbiFunction, ya que se asignará como la etiqueta del dispositivo en Ubidots.

2.2. Luego, la variable ‘buf’ debe ser analizada para obtener las variables deseadas. Para esto, necesitas dividir los bytes según la hoja de datos del fabricante del dispositivo.

En este caso, la estructura utilizada en este tutorial es:

0x4F - Temperatura - Bytes #0 (1 byte)
0xC1B6C81C - Latitud - Bytes #1 - #4 (4 bytes)
0xC23C5514 - Longitud - Bytes #5 - #9 (4 bytes)

En consecuencia, los bytes deben ser divididos en la siguiente porción del código de ejemplo. Recuerda que dependiendo de tu hardware, aquí es donde tu código reflejará los datos que deseas POSTEAR en la carga útil a Ubidots.

/* Analiza los datos entrantes */var temp = buf.readInt8(0); var lat = buf.readFloatBE(1);var lng = buf.readFloatBE(5);

2.3. [OPCIONAL] Para depurar y verificar las variables decodificadas, por favor descomenta la siguiente porción de código.

/*console.log(temp);console.log(lat);console.log(lng);*/

2.4. Con los valores ya decodificados por UbiFunctions, es hora de construir el cuerpo JSON de la Solicitud HTTP que se va a POSTEAR en tu Cuenta de Ubidots, de acuerdo con nuestra documentación de la API.

Ten en cuenta que, según el hardware de Sigfox utilizado en tu Aplicación, debes modificar la siguiente porción del código de ejemplo para ajustar la etiqueta de la variable y los valores a enviar:

/* Construye el cuerpo para ser POST en Ubidots */var payload = {   "temperature": temp,   "position": {      "value":"1",      "context":{         "lat": lat,         "lng": lng      }   }};

Como habrás notado arriba, el cuerpo contiene una variable llamada temperatura con un valor de "temp", además de una variable llamada posición con las respectivas coordenadas (latitud y longitud) asignadas como el contexto de la variable.

Para más detalles sobre cómo manejar valores, contexto o claves de timestamps, por favor consulta la
Referencia de la API REST de Ubidots.

2.5. Ahora, es momento de llamar a la función ubidotPost, que es la función que ejecutará la solicitud POST, enviando así los datos a tu cuenta de Ubidots.

/* Realiza la solicitud POST a Ubidots */var post_response = await ubidotsPost(url_Base, token, device_id, payload);

2.6. Para finalizar, hablemos sobre la última porción de la función principal. Esta porción de código devolverá el estado de la solicitud:

return post_response;

En este punto, si todo está configurado correctamente, recibirás la siguiente respuesta 201 exitosa:

{ "position":[{"status_code":201}], "temperature":[{"status_code":201}]}

Si obtienes un código de respuesta diferente, consulta nuestra documentación de la API para conocer su significado.

3. Ahora que tienes una mejor idea de lo que hace el código proporcionado, es hora de guardar los cambios y desplegarlo. Para hacerlo, simplemente presiona el botón "Hacerlo activo".

Con los cambios ya guardados, configuremos el Callback de Sigfox para comenzar a recibir los datos en la Nube de Ubidots.

3. Configurando el callback de Sigfox a Ubidots

La gestión de los datos entre Sigfox y Ubidots requiere un "Callback".

El hardware de Sigfox leerá sensores y enviará los valores (mensaje) a una Estación Base de Sigfox para ser reenviados al Backend de Sigfox. En este punto, tus datos ya están en la nube (en internet), así que ahora es momento de hacer que este mensaje sea valioso utilizando una plataforma de habilitación de aplicaciones IoT como Ubidots usando el Callback de Sigfox.

Los Callbacks de Sigfox utilizan solicitudes HTTP para transmitir datos bidireccionalmente con cualquier servicio en la nube. En este caso, vamos a mostrar cómo configurar el Callback de Sigfox para transmitir los datos a Ubidots.

1. Para comenzar, accede al Backend de Sigfox donde el hardware está transmitiendo datos.

2. Ve a la sección Dispositivo y selecciona el Tipo de Dispositivo del dispositivo registrado:

3. A continuación, verifica la información de tu dispositivo y selecciona "CALLBACKS" en el menú del lado izquierdo de la página, como se muestra a continuación:

Los callbacks de Sigfox te permiten reportar datos a un sistema externo como Ubidots. Para configurar un callback a la API de Ubidots, utiliza los siguientes parámetros:

Tipo: DATA - UPLINK
Canal: URL
Configuración de carga útil personalizada: Déjalo en blanco
Patrón de URL: Esta es la URL generada por la UbiFunction en los pasos anteriores

https://parse.ubidots.com/prv/ubidots-tutorials/sigfox-device

Usar método HTTP: POST
Encabezado: Déjalo en blanco
Tipo de Contenido: application/json
Cuerpo:

{  "device_id": "{device}",  "data":"{data}"}

Después de configurar el callback, debería verse así:

NOTA IMPORTANTE: Para evitar problemas de autenticación entre el callback de Sigfox y Ubidots, asegúrate de marcar la opción “ENVIAR SNI”.

Una vez que hayas verificado el callback, presiona "OK".

En este punto, los datos se decodificarán según el código ya configurado en el motor de Ubifunctions, y luego se publicarán los datos en tu cuenta de Ubidots.

NOTA IMPORTANTE DE DESPLIEGUE: Ubidots y Sigfox se comunican a través de URL o Batch URL (utilizado para grandes despliegues). Este tutorial explica el canal estándar de URL. Si tienes una red de sensores a gran escala, por favor contacta a sales@ubidots.com para recibir información adicional sobre integraciones de Batch URL.

4. Verificando la integración de datos

Con la UbiFunction y el Callback de Sigfox ya configurados, después de que el hardware actualice un nuevo valor, notarás que un nuevo dispositivo fue creado automáticamente en tu cuenta de Ubidots. Si el dispositivo ya existe, se actualizará.

Ve a la sección de Dispositivos de tu cuenta de Ubidots y confirma que el(los) nuevo(s) dispositivo(s) fueron creados.

[SUGERENCIA] - ¿No te gusta el ID del Dispositivo Sigfox como el nombre de tu dispositivo en la visualización de Ubidots? ¡No te preocupes! Puedes cambiar el nombre a uno más amigable, pero la etiqueta del dispositivo permanecerá como el ID del Dispositivo Sigfox para nunca confundirte de qué dispositivo se trata. Consulta el Centro de Ayuda de Ubidots para más información sobre Etiquetas de Dispositivos y Cambios de Nombre de Dispositivos.

2. [OPCIONAL] Si lo deseas o necesitas, puedes ver los registros de cada UbiFunction activada. Para encontrar los registros, simplemente presiona el ícono de "sobre" ubicado en la barra de control de la función que deseas rastrear

Como puedes ver a continuación, los registros proporcionan tanto la hora de ejecución como los valores de salida recibidos de la Función.