Sigfox dispositivos de área amplia y bajo consumo con la plataforma de desarrollo de aplicaciones IoT de Ubidots hacen que sea una solución IoT fácil de integrar, desde el hardware hasta la experiencia del usuario final.

Siguiendo los pasos proporcionados en este tutorial, podrás manejar y enviar un mensaje de downlink a tu dispositivo Sigfox desde Ubidots. Esta integración requerirá el complemento UbiFunctions, una herramienta destacada de la plataforma de desarrollo de aplicaciones IoT de Ubidots que permite a los usuarios crear APIs o endpoints personalizados para sus aplicaciones.

Si deseas aprender cómo gestionar los mensajes de uplink desde el backend de Sigfox a Ubidots, por favor consulta esta guía. :)

Requisitos

Cuenta de Ubidots con UbiFunctions (haz clic para habilitar)
Cuenta de Backend de Sigfox
Cualquier dispositivo Sigfox (con soporte de downlink)

Paso a Paso

Entendiendo los mensajes de Sigfox
Configuración de UbiFunctions
– Código de ejemplo, desglose y explicación
Configurando el callback de Sigfox a Ubidots
Verificando la integración de datos
Resumen

1. Entendiendo los mensajes de Sigfox

Si no estás familiarizado con Sigfox y el backend de Sigfox, te recomendamos que consultes esta Visión general de la tecnología Sigfox antes de continuar con esta guía.

Sigfox permite a los dispositivos realizar comunicaciones bidireccionales, lo que significa que puedes enviar mensajes de uplink y también recibir mensajes de downlink de/para Ubidots.

Un mensaje de Downlink puede ser transmitido en cualquier momento dentro de las limitaciones del número de solicitudes basadas en la suscripción de Sigfox; el plan de conectividad más alto permite 4 mensajes de downlink con un tamaño máximo de 8 bytes.

Basado en esto, se sugiere que las aplicaciones que requieren mensajes de downlink lo hagan de manera esporádica y moderada.

Para enviar un mensaje de Downlink a Ubidots, los datos se procesarán de acuerdo con el siguiente diagrama de flujo de datos:

Para comenzar, el dispositivo Sigfox debe solicitar a la red que se envíe un mensaje de downlink.

En esta solicitud, el dispositivo transmite un mensaje de uplink que contiene una bandera de downlink al backend de Sigfox. Esta bandera en el mensaje de uplink se encarga de solicitar un mensaje de downlink de una plataforma de terceros.

Luego, el backend de Sigfox enviará el mensaje de uplink a Ubidots utilizando un callback configurado para manejar datos en BIDIR (bidireccional) que apunta al endpoint de la API URL generado por la función que crearemos más adelante en este tutorial con el motor UbiFunctions.

En este punto, dado que el uplink se envió con una bandera de uplink, el mismo callback configurado también estará esperando un objeto de datos que se devuelva al dispositivo desde Ubidots. Este objeto de datos contendrá el ID del dispositivo Sigfox y, por lo tanto, sabrá qué hardware recibirá el mensaje.

El Callback de Sigfox es una característica que, cuando se utiliza correctamente, puede retransmitir datos de ida y vuelta de/para Ubidots utilizando una solicitud HTTP.

Para referencia, el cuerpo del callback que configuraremos en este tutorial tendrá la siguiente estructura:

{	"device_id":"{device}"}

Por favor, ten en cuenta que este cuerpo puede ser modificado según sea necesario, basado en los requisitos de tu aplicación.

En este punto, el cuerpo anterior será recibido en el motor UbiFunction proporcionando el ID del dispositivo Sigfox. Con esto, Ubidots identificará qué dispositivo en Ubidots coincide con el ID del dispositivo Sigfox y actualizará automáticamente los datos apropiados. Además, dado que Ubidots puede reconocer y hacer coincidir los IDs de los dispositivos Sigfox con los dispositivos en Ubidots, una sola función podrá actualizar mensajes de uplink y enviar mensajes de downlink de/para múltiples piezas de hardware.

Para habilitar la capacidad de downlink, necesitarás seguir la lógica de progresión a continuación para codificar la función en el motor UbiFunctions:

Obtener el valor deseado de Ubidots para ser enviado al dispositivo Sigfox.
Codificar el valor obtenido en el tipo de dato adecuado (HEX).
Devolver el mensaje de downlink esperado al backend de Sigfox.

El mensaje esperado del backend de Sigfox es:

{  '##{{deviceId}}': {	'downlinkData':##{{data}} }}

Como se mencionó anteriormente, los datos devueltos proporcionados por UbiFunction son el ID del dispositivo Sigfox (para saber a qué pieza de hardware se enviará el mensaje), además de los datos deseados que se asignarán desde el mensaje de downlink.

Nota importante: todos los pasos de este tutorial deben seguirse para que el mensaje de downlink sea recibido por el backend de Sigfox.

Para aclarar la comprensión de los mensajes de downlink de Sigfox, por favor consulta el video a continuación

Para una explicación técnica del mensaje de downlink de Sigfox, consulta esta guía.

Ahora, con una comprensión básica de cómo se necesita crear el mensaje de downlink, veamos cómo configurar la UbiFunction para OBTENER un valor de Ubidots, codificar el valor esperado en el tipo de dato soportado y devolver los datos esperados por el Backend de Ubidots.

2. Configuración de UbiFunctions

NOTA IMPORTANTE: Este guía asume que tu dispositivo Sigfox es capaz de enviar mensajes de uplink al backend de Sigfox con una bandera solicitando un mensaje de downlink.

Nota: una UbiFunction es una función en la nube de Node.js 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. Crea una UbiFunction accediendo a tu cuenta de Ubidots –> Gestión de 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 sin ninguna configuración. Necesitarás configurar la función para que funcione mejor para tus necesidades. La función de ejemplo no funcionará con Sigfox.

Las configuraciones predeterminadas para la función son las siguientes:

Para comenzar, asigna el nombre deseado para tu UbiFunction. Recomendamos usar el formato "Marca-Referencia", es decir, "Sigfox-Suntech", "Sigfox-Oyster" o "Sigfox-Thinxtra". Además, es aconsejable relacionar el nombre con qué tipo de mensaje se está activando; por ejemplo, "downlink" puede colocarse al final del nombre de nuestra función: "Sigfox-Suntech-downlink."

Para este tutorial, la función se titulará "Sigfox-Device-Downlink."

4. Selecciona POST como Método HTTP y NodeJS 8 como Runtime. Con estos parámetros incluidos, la configuración resultante de tu función se verá como sigue:

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

Para desplegar la UbiFunction haz clic en "Hazlo en vivo":

Ahora, la URL del endpoint resultante construida por el motor UbidFunctions y alojada de forma privada para tu aplicación Ubidots se verá algo así:

NOTA IMPORTANTE: Este URL Endpoint resultante es importante porque es el endpoint al que dirigirás tu callback de Sigfox para enviar el mensaje de uplink que solicita el mensaje de downlink. Si esto es confuso, por favor mira este video explicativo.

Como habrás notado, la URL del endpoint resultante generada por la UbiFunction es:

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

Donde, ubidots-tutorial es tu nombre de usuario de Ubidots y sigfox-device-downlink es el Nombre asignado a la función dentro del motor UbiFunctions.

Guarda la URL del endpoint de la API para ser utilizada y asignada más tarde en la configuración del Callback de Sigfox.

– Desglose y explicación del código de ejemplo

5. Borra el código predeterminado ubicado en el editor de UbiFunction, luego copia y pega el siguiente código de ejemplo reemplazando el código predeterminado. Después de pegar, asegúrate de asignar los siguientes parámetros donde se indica en el código de ejemplo para tu función:

TOKEN de Ubidots
Etiqueta del Dispositivo del dispositivo en Ubidots donde se encuentra la variable deseada.
Etiqueta de la Variable de la variable (último valor) deseada para responder al backend de Sigfox.

var request = require('request-promise');/* Asigna tu TOKEN de Ubidots */var TOKEN = "BBFF-Rfcgaxns6HlVb155WA0RhSY85xNDmB";/* Etiqueta del Dispositivo donde se encuentra la variable deseada  */var DEVICE_LABEL = "my-device";/* Etiqueta de la Variable deseada para obtener datos (último valor) */var VARIABLE_LABEL = "status";/************************************************** *                RUTINA PRINCIPAL                    *  **************************************************/async function main(params) {      /* Guarda el ID del dispositivo del Dispositivo Sigfox */    var device_id = params.device_id;    console.log("Recuperando último valor");    /* Solicitud GET a Ubidots - Recuperar último valor */    var var_last_value = await ubidotsGetRequest(DEVICE_LABEL, VARIABLE_LABEL);    /* Codifica el último valor recibido a HEX */    var hex_value = Buffer.from([var_last_value]).toString('hex');    /* Completa los 8 bytes de datos de downlink */    var downlinkData = (Array(16).join('0') + hex_value).slice(-16);    /* Mensajes de depuración */    console.log("Último valor de la variable: " + var_last_value);    console.log("Último valor en HEX: " + hex_value);    console.log("Datos de Downlink a ser enviados: " + downlinkData);    console.log("Activando mensaje de downlink");    /* Devuelve los Datos de Downlink a la Nube de Sigfox*/    return downLink(device_id, downlinkData);}/************************************************** *                 RUTINAS AUXILIARES                   *  **************************************************//*    Construye el Mensaje de Downlink a ser enviado a la Nube de Sigfox    - device_id: ID del Dispositivo Sigfox    - downlinkDaTa: Valor deseado a ser enviado como Mensaje de Downlink*/async function downLink(device_id, downLinkData) {    // Devuelve datos a SIGFOX - codificando los datos de retorno para depuración    var data = {};    data[device_id] = { "downlinkData": downLinkData };    return data;}/*    Construye y maneja una solicitud HTTP GET a Ubidots    - deviceLabel: Etiqueta del Dispositivo donde se encuentra la variable deseada     - variable Label: Etiqueta de la Variable deseada para obtener datos (último valor)*/async function ubidotsGetRequest(deviceLabel, variableLabel) {    var options = {        url: 'https://industrial.api.ubidots.com/api/v1.6/devices/' + deviceLabel + '/' + variableLabel + '/lv',        headers: {            "x-auth-token": TOKEN        },         json: true    };    return await request.get(options);}

1. La rutina principal se encarga de recibir los datos de uplink iniciales del backend de Sigfox. Como ya habrás visto, a continuación, el argumento de la rutina principal es el params. Este argumento contendrá el cuerpo del callback configurado en el backend de Sigfox.

async function main(params) {    // Recibe y analiza los datos a ser publicados en Ubidots}

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

{  "device_id": "{device}"}

Por favor, ten en cuenta que este cuerpo puede ser modificado para ajustarse a los requisitos de tu aplicación.

Ahora, dentro de la rutina principal del código de ejemplo proporcionado, necesitamos gestionar los datos que se devolverán al hardware de Sigfox como un mensaje de downlink desde Ubidots.

2. La siguiente porción del código de ejemplo toma el parámetro device_id recibido del Callback de Sigfox y los asigna como variables temporales en el motor UbiFunctions. Estas variables de shell se utilizan solo para ejecutar la función.

    /* Guarda el ID del dispositivo del Dispositivo Sigfox */    var device_id = params.device_id;

Aquí podemos ver que la clave device_id recibida en el objeto params se está asignando a una variable llamada device_id.

La variable device_id es un identificador único (ID del Dispositivo Sigfox) por dispositivo, asignado por el backend de Sigfox, y se basa en el hardware subyacente que maneja el mensaje. En este caso, el device id se relacionará directamente con el hardware que se pretende manejar los datos de downlink.

3. La idea del mensaje de downlink es informar un valor proporcionado por una variable en Ubidots. Por ejemplo, el último estado de una máquina puede ser enviado de vuelta como un downlink al hardware de Sigfox. Basado en esto, la siguiente porción de código se encarga de construir y enviar una solicitud HTTP GET a Ubidots para obtener el último valor de la variable que se enviará de vuelta al hardware como un downlink:

    console.log("Recuperando último valor");    /* Solicitud GET a Ubidots - Recuperar último valor */    var var_last_value = await ubidotsGetRequest(DEVICE_LABEL, VARIABLE_LABEL);

Puedes encontrar simplemente el método ubidotsGetRequest() después de la función principal:

/*    Construye y maneja una solicitud HTTP GET a Ubidots    - deviceLabel: Etiqueta del Dispositivo donde se encuentra la variable deseada     - variable Label: Etiqueta de la Variable deseada para obtener datos (último valor)*/async function ubidotsGetRequest(deviceLabel, variableLabel) {    var options = {        url: 'https://industrial.api.ubidots.com/api/v1.6/devices/' + deviceLabel + '/' + variableLabel + '/lv',        headers: {            "x-auth-token": TOKEN        },         json: true    };    return await request.get(options);}

3.1. El último valor obtenido necesita ser codificado en un tipo de dato permitido para que Ubidots lo entienda, que es HEX. La siguiente línea de código tomará el último valor de la variable asignada (var_last_value) para codificar el resultado decimal como un HEX:

    /* Codifica el último valor recibido a HEX */    var hex_value = Buffer.from([var_last_value]).toString('hex');

3.2. Ahora, con el último valor de la variable de Ubidots codificado en HEX, necesitamos asignar el valor como una respuesta de 8 bytes. Para esto, se utiliza la siguiente porción de código:

    /* Completa los 8 bytes de datos de downlink */    var downlinkData = (Array(16).join('0') + hex_value).slice(-16);

Aquí hay un ejemplo de cómo se ve una transformación codificada de decimal a HEX:

Antes de completar la respuesta de 8 bytes - hex_value = 01
Después de completar la respuesta de 8 bytes - downlinkData = 0000000000000001

3.3. [OPCIONAL] Si lo deseas, puedes descomentar la siguiente porción de código para depurar y verificar los valores que se están codificando y completando:

    /* Mensajes de depuración */    /*     console.log("Último valor de la variable: " + var_last_value);    console.log("Último valor en HEX: " + hex_value);    console.log("Datos de Downlink a ser enviados: " + downlinkData);    */

4. Ahora, con los datos deseados codificados en el formato y tamaño adecuados, el código devolverá la respuesta esperada al backend de Sigfox. Para devolver los datos esperados, se utiliza el método donwLink():

    console.log("Activando mensaje de downlink");    /* Devuelve los Datos de Downlink a la Nube de Sigfox*/    return downLink(device_id, downlinkData);

Donde el método downLink() se encarga de construir la respuesta esperada que es:

{  '##{{deviceId}}': {	'downlinkData':##{{data}} }}

Puedes encontrar simplemente el método downLink() después de la rutina principal:

/*    Construye el Mensaje de Downlink a ser enviado a la Nube de Sigfox    - device_id: ID del Dispositivo Sigfox    - downlinkDaTa: Valor deseado a ser enviado como Mensaje de Downlink*/async function downLink(device_id, downLinkData) {    // Devuelve datos a SIGFOX - codificando los datos de retorno para depuración    var data = {};    data[device_id] = { "downlinkData": downLinkData };    return data;}

En este punto, si tu código está configurado correctamente, obtendrás la respuesta esperada por el backend de Sigfox en la consola de UbiFunction:

{  "2BF076": {    "downlinkData": "0000000000000001"  }}

5. Ahora que tienes una mejor idea de lo que está haciendo el código proporcionado. Es momento de guardar los cambios realizados y desplegarlo. Para hacerlo, simplemente presiona "Hazlo en vivo."

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

3. Configurando el callback de Sigfox a Ubidots

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

Los Callbacks de Sigfox utilizan solicitudes HTTP para transmitir datos de manera bidireccional con Ubidots. En este caso, vamos a mostrar cómo configurar el Callback de Sigfox para transmitir datos de Ubidots a Dispositivos Sigfox utilizando el motor UbiFunctions discutido anteriormente.

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. Edita el Tipo de Dispositivo presionando la pestaña editar ubicada en la esquina superior derecha de la página:

Configura el callback como Downlink:

Para guardar los cambios presiona "Ok".

4. 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:

En este punto, se necesita un nuevo callback. Para crear un nuevo callback, selecciona "Nuevo"

Selecciona "Callback personalizado":

Luego, en la siguiente ventana completa la información requerida con los siguientes parámetros para configurar el callback con tu UbiFunction creada anteriormente.

Tipo: DATA - BIDIR
Canal: URL
Configuración de carga 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-downlink

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

{  "device_id": "{device}"}

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

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

5. Por defecto, el callback BIDIR estará inactivo después de su creación. Por favor, actívalo seleccionando la casilla de verificación Downlink:

Cuando esté activado:

Ahora tu callback está listo y habilitado para manejar datos de Ubidots a Dispositivos Sigfox. En este punto, los datos serán solicitados por el Dispositivo Sigfox y el motor UbiFunction (paso anterior) devolverá la respuesta esperada que contiene los datos deseados para ser utilizados como mensaje de downlink.

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 configurados, podrás activar mensajes de downlink de Ubidots a tu Dispositivo Sigfox.

En este caso, el dispositivo enviará un mensaje de uplink solicitando el mensaje de downlink a Ubidots. Para verificar si el mensaje fue activado correctamente por el motor UbiFunction, simplemente presiona el ícono de "sobre" ubicado en la barra de control de la función que deseas rastrear. Esto mostrará los registros y ejecuciones de tu función.

En este punto, podrás ver (ver imagen a continuación):

El último valor de la variable
El último valor de la variable en HEX
Los datos de downlink a ser devueltos
Mensaje de acción exitoso

Finalmente, los resultados enviados al backend de Sigfox serán:

{    "2BF066":{        "downlinkData":"0000000000000001"    }}

Para confirmar que el mensaje de downlink fue recibido, selecciona "mensajes" en la pestaña ID del Dispositivo:

En la sección mensajes podrás ver el mensaje de uplink solicitando el downlink, además del mensaje de downlink recibido:

Mensaje de uplink solicitando el mensaje de downlink:

Mensaje de downlink recibido:

En este punto, tu hardware de Sigfox mostrará los datos recibidos en el mensaje de downlink. A continuación, puedes ver los registros proporcionados por el dispositivo previamente configurado:

Ahora es tu turno de enviar y recibir datos utilizando el backend de Sigfox. :)

5. Resumen

Con esto, tu Callback de Sigfox está listo y la UbiFunction está transmitiendo correctamente datos de Ubidots a tus Dispositivos Sigfox. Ahora es momento de desarrollar tu aplicación con las herramientas de desarrollo y despliegue de aplicaciones IoT de Ubidots.

Comienza con Ubidots hoy

Ubidots es una plataforma de desarrollo de aplicaciones de Internet de las Cosas (IoT) que empodera a los integradores de sistemas e innovadores para lanzar aplicaciones de control, monitoreo y automatización que convierten los datos de los sensores en información procesable. Contratar un equipo de ingeniería para fusionar el mundo físico con un mundo digital y crear una aplicación IoT que funcione y se vea bien es costoso tanto en tiempo como en dinero, así que Ubidots lo hizo por ti. Ubidots existe como un recurso eficiente y económico para desarrollar aplicaciones IoT basadas en la nube privada e integrar soluciones basadas en datos en empresas e investigaciones para impulsar decisiones y mejorar nuestra economía laboral.

Otros usuarios también encontraron útil: