El dispositivo Kontrolog es un controlador programable para IoT (Internet de las Cosas) diseñado para el control y monitoreo remoto y en tiempo real de diferentes procesos con altos requisitos de seguridad y precisión. Puede conectarse a una HMI táctil para visualización y configuración local.
Los dispositivos Kontrolog cuentan con un módulo de comunicación dual Sigfox/LoRaWAN que les permite enviar datos a Ubidots a través de cualquiera de estas dos redes, dándole un plus en diferentes campos de aplicación, como la industria, la agricultura, la calidad del agua, la automatización del hogar, entre otros.
Siguiendo esta guía podrás conectar el Kontrolog a Ubidots utilizando The Things Network (TTN). Desde allí, podrás realizar, entre otras cosas:
Monitoreo y visualización remota de mediciones actuales, estado de las salidas y registros de variables del sensor, en gráficos y tablas de datos, por hasta 2 años.
Configuración remota de los parámetros del dispositivo.
Gestión de alarmas para variables fuera de rango, niveles de batería y fallos de alimentación AC.
Establecer límites de alarma, eventos de alarma y notificaciones por correo electrónico, SMS, correo de voz, servicio de mensajería Telegram o webhooks.
Requisitos
Cuenta de The Things Network (TTN)
1. Configuración del Kontrolog
El Kontrolog se alimenta mediante un cable de alimentación de dos hilos conectado a sus entradas AC1 y AC2 (mostradas en la imagen a continuación) y conectado a las líneas de 110 - 220 VAC, 50/60 Hz. Alternativamente, la línea AC1 puede ser puenteada a los terminales CM1 y CM2, si deseas utilizar cualquiera de las salidas de relé de 12A: RE1 o RE2 (ten en cuenta que cada salida de 12A utiliza 2 bloques de terminales).
Una vez que el equipo esté alimentado, comenzará su “estado de operación normal”, que se puede reconocer cuando el LED mostrado en la imagen a continuación parpadea cada segundo.
2. Configuración de TTN
2.1. Configuración de callback para mensajes de uplink de LoRaWAN
Registra tu dispositivo Kontrolog en The Things Network y luego, en el menú de la izquierda, selecciona “Integraciones” → “Webhooks”.
Crea un nuevo webhook seleccionando la opción "Agregar Webhooks".
Luego selecciona “Webhook Personalizado”.
Configura el Webhook de la siguiente manera y luego presiona “Guardar Cambios”.
Configuraciones generales:
ID del Webhook: ID asignado por ti.
Formato del Webhook: JSON
Configuraciones del endpoint:
URL base: Esta es la URL generada en la tercera sección de esta guía por el uplink UbiFunction en el campo "HTTPS Endpoint URL”, sin el nombre de la función. La URL resultante debería verse así:
https://parse.ubidots.com/prv/your_ubidots_username
Clave API de Downlink: Información dada en “Clave API de Downlink”, a continuación.
Autenticación de solicitud: Desmarcado.
Mensajes habilitados:
Mensaje de Uplink: Habilitar y agregar la ruta con el nombre de la Uplink UbiFunction que se creará en la tercera sección de esta guía. La URL resultante debería verse así:
/your_ubifunction_name
Ejemplo: /kontrolog-uplink
Todos los demás campos permanecen desmarcados.
Verás esto en la sección “Webhooks”:
2.2. Clave API de Downlink
Para obtener este parámetro, sigue los pasos a continuación:
1. En TTN, ve a la aplicación asociada con tu dispositivo Kontrolog y selecciona “Claves API”.
2. Selecciona la opción “Agregar Clave API”.
3. Configura el webhook de la siguiente manera y luego presiona “Crear Clave API”.
Nombre: El nombre que deseas asignar a la nueva Clave API para mensajes de downlink. Ejemplo: downlink-key.
Derechos:
Conceder todos los derechos actuales y futuros: Deshabilitado.
Conceder derechos individuales: Habilitar y marcar:
“Vincular como Aplicación a un Servidor de Red para intercambio de tráfico, es decir, leer uplink y escribir downlink”.
“Leer tráfico de aplicación (uplink y downlink)”.
4. Aparecerá la siguiente ventana, copia la clave API (después de cerrarla nunca se mostrará de nuevo) y haz clic en “He copiado la clave”.
5. Luego edita y copia esta clave API en tu Webhook → "Clave API de Downlink".
2.3. Formato para carga útil de uplink
1. En TTN, ve a la aplicación asociada con tu dispositivo Kontrolog y selecciona “Formateadores de carga útil” → “Uplink” en el menú de la izquierda.
2. Luego, ingresa la siguiente información en los campos correspondientes:
Tipo de formateador: Formateador JavaScript personalizado
Código del formateador: Copia y pega el siguiente código de función:
function decodeUplink(input) { var data_payload = ""; for(i = 0; i < input.bytes.length; i++){ var chr = input.bytes[i].toString(16); if(chr.length == 1) chr = "0" + chr; data_payload += chr; } return { data: { //data_raw: input.bytes data: data_payload }, warnings: [], errors: [] };}3. Función de Uplink para publicar datos en Ubidots
A continuación se muestra la representación de cómo viaja la información desde un dispositivo Kontrolog a Ubidots a través de la red LoRaWAN:
3.1. Crear la UbiFunction para mensajes de uplink
Para procesar y decodificar los marcos de datos enviados a Ubidots es necesario crear una UbiFunction.
Con este proceso crearás una función que decodifica el propio protocolo de comunicación de Omicron IoT Solutions.
Este protocolo está cargado en el firmware predeterminado del Kontrolog, sin embargo, también tienes la opción de programar por tu cuenta para el Kontrolog utilizando bloques de código proporcionados por Omicron (visita el siguiente enlace para más información).
Si utilizas tu propio protocolo de comunicación, tendrás que crear tu propio decodificador en Ubidots. |
1. Una vez en la página del editor de código de la UbiFunction, elimina el código de muestra y pega el correspondiente a la versión de tu Kontrolog en el siguiente enlace:
2. En el código, reemplaza estos campos:
Token: Un token es una clave única que autoriza las solicitudes enviadas a Ubidots. Para obtener tu token, puedes seguir los pasos que se encuentran en esta guía.
En la función downlink_request , coloca en el campo URL la URL generada por la UbiFunction de downlink en el campo "HTTPS Endpoint URL".
Notas:
Para completar con éxito este paso, debes referirte a la sección “Crear UbiFunction para mensajes de downlink” en esta guía.
Para guardar el código y comenzar a usarlo, haz clic en “hacerlo en vivo” en el menú de la izquierda.
En el código de UbiFunction dado, todas las lecturas de sensores se dividen por 10. Sin embargo, dependiendo del tipo de sensor elegido, puede que sea necesario escalar por 100, o que no sea necesaria la escala (ver Tabla 5).
Por lo tanto, debes ajustar la lectura del sensor en el Dashboard (multiplicar o dividir por 10 u otros), si es necesario.
3.2. Protocolo de comunicaciones para mensajes de Uplink
A continuación se muestra un resumen del protocolo de comunicaciones, si deseas más detalles, por favor contacta a Omicron IoT Solutions. |
El marco de envío de datos para la red LoRaWAN tiene un tamaño estándar de 18 o 20 bytes, dependiendo de si es Kontrolog 9.2 o 9.3. Para esta red, el marco de datos de uplink enviado por el Kontrolog tiene la estructura mostrada en la siguiente tabla.
Tabla 1
Bytes
0 y 1 | Bytes
2, 3, 4 | Bytes
5, 6, 7 | Byte
8 | Byte
9 | Bytes
10 y 11 |
Código de mensaje:
4 Bits
Sensor 1:
12 Bits | Sensor 2: 12 Bits
Sensor 3: 12 Bits | Sensor 4: 12 bits
Sensor 5. 12 bits | Voltaje de batería | Voltaje AC
Voltaje | Corriente AC:
10 bits
Estado de la salida:
6 Bits |
Bytes
12, 13, 14, 15 | Byte
16 | Byte
17 | Bytes
18 y 19 |
Marca de tiempo Unix:
32 bits.
Segundos transcurridos desde 1970 | Mensaje de downlink: 1 bit | Posición de los datos almacenados en memoria:
8 bits | Corriente de salida # 5:
12 bits
(Solo para Kontrolog 9.3) |
Código de mensaje: Código que indica si el mensaje es un mensaje de operación normal o un mensaje de alerta.
Sensor 1 a 5: Valor actual de los sensores conectados a los puertos 1 a 5.
Voltaje de batería, voltaje AC, corriente AC: Voltaje en el puerto de conexión para batería externa de 12 V, voltaje AC suministrado leído por el instrumento de 0 a 255 VAC, y valor de corriente AC leído por el sensor.
Bits de estado: Se indica el estado de las salidas de relé. El bit 0 indica el estado de alarma general, donde 0: no hay alarma activa 1: alguna alarma activa.
Marca de tiempo Unix: Marca de tiempo en segundos transcurridos desde 1970 utilizada para registrar la fecha y hora de los mensajes recibidos en la plataforma, y para almacenar con una marca de tiempo correcta los mensajes respaldados en memoria en caso de pérdida de conexión de red.
Mensaje de downlink: Anuncia que el dispositivo está disponible para recibir mensajes de downlink.
Posición de los datos almacenados en memoria: Posición en memoria de un mensaje respaldado en caso de pérdida de red. Se pueden almacenar hasta 140 mensajes.
Corriente de salida # 5: Valor de la corriente en la salida #5 (4-20mA) escalado por 100.
4. Función de Downlink para obtener datos de Ubidots
4.1. Crear UbiFunction para mensajes de downlink
Para enviar marcos de datos desde Ubidots al dispositivo Kontrolog es necesario crear una UbiFunction.
Con este proceso crearás una función que envía marcos de datos desde Ubidots a los dispositivos Kontrolog, de acuerdo con el propio protocolo de comunicación de Omicron IoT Solutions.
Este protocolo está cargado en el firmware predeterminado del Kontrolog, sin embargo, también tienes la opción de hacer tu propia programación para el Kontrolog utilizando bloques de código proporcionados por Omicron (visita el siguiente enlace para más información).
Si utilizas tu propio protocolo de comunicación, tendrás que crear tu propia función para enviar mensajes de downlink desde Ubidots. |
Una vez en la página del editor de código de la UbiFunction, elimina el código de muestra y luego pega el código que se encuentra aquí y reemplaza este campo:
Token: Un token es una clave única que autoriza las solicitudes enviadas a Ubidots. Para obtener tu token, puedes seguir los pasos dados en este enlace.
Para guardar el código y comenzar a usarlo haz clic en “hacerlo en vivo” en el menú de la izquierda.
4.2. Protocolo de comunicaciones para mensajes de downlink
|
El mensaje de downlink enviado desde el software de aplicación tiene un máximo de 8 bytes y se interpreta de la siguiente manera:
Tabla 2
Byte
0 | Byte
1 | Byte
2 | Bytes
3, 4, 5, 6 | Byte
7 |
Grupo de parámetros | Reservado
(0x00) | Parámetro seleccionado | Datos o valor: 4 Bytes | Nuevo downlink pendiente |
La siguiente tabla muestra los posibles grupos de parámetros que se pueden modificar:
Tabla 3. Grupo de parámetros
Grupo de parámetros | Código hexadecimal | Grupo Seleccionado |
1 | 0x01 | Parámetros de configuración del sensor 1 |
2 | 0x02 | Parámetros de configuración del sensor 2 |
3 | 0x03 | Parámetros de configuración del sensor 3 |
4 | 0x04 | Parámetros de configuración del sensor 4 |
5 | 0x05 | Parámetros de configuración del sensor 5 |
6 | 0x06 | Parámetros de configuración del sensor de batería |
7 | 0x07 | Parámetros de configuración del sensor de voltaje AC |
8 | 0x08 | Parámetros de configuración del sensor de corriente |
11 | 0x0B | Parámetros de configuración para la salida 1 |
12 | 0x0C | Parámetros de configuración para la salida 2 |
13 | 0x0D | Parámetros de configuración para la salida 3 |
14 | 0x0E | Parámetros de configuración para la salida 4 |
15 | 0x0F | Parámetros de configuración para la salida 5 |
20 | 0x14 | Configuraciones generales para el dispositivo Kontrolog |
22 | 0x16 | Configuraciones para el RTC |
4.2.1. Modificación de parámetros del sensor (grupo de parámetros 1 a 8)
Este grupo de mensajes de downlink permite modificar parámetros como:
Límites de alarma,
Retrasos de alarma,
Activar/desactivar un sensor, entre otros.
Consulta las tablas 4 y 5 para conocer los tipos de parámetros que se pueden modificar para las entradas.
Tabla 4. Parámetros del sensor
Parámetros
para sensores | Código hexadecimal | Nombre | Observación |
2 | 0x02 | Tipo de sensor | Tipo de sensor (Ver Tabla 5) |
4 | 0x04 | Habilitar/Deshabilitar Sensor | 1: Sensor Habilitado
0: Sensor Deshabilitado |
5 | 0x05 | Ajuste de lectura (Offset) | Ajuste de lectura (offset) del sensor:
Para ajustar el valor de lectura de un sensor, se puede utilizar una escala lineal, en la forma:
V. Ajustada = ( V. Leída + Offset)*Pendiente. |
6 | 0x06 | Límite de alarma inferior | Límite de alarma inferior |
7 | 0x07 | Límite de alarma superior | Límite de alarma superior |
8 | 0x08 | Retraso de activación de alarma en segundos | Tiempo en segundos para retrasar la activación de la alarma |
9 | 0x09 | Dirección de registro de lectura | Modbus |
10 | 0x0A | Número de registros a leer en Modbus
Resistencia de carga para el sensor de corriente | Modbus: Número de registros a leer.
Para el sensor de corriente solamente:
Resistencia de carga:
60 ohmios para transformador de 30A
36 ohmios para transformador de 50A
18 ohmios para transformador de 100A |
11 | 0x0B | Formato de datos | Formato de registro Modbus
0 : Entero
1 : Entero con un (1) décimo (multiplicado por 10)
2 : Entero con dos (2) décimos (multiplicado por 100)
3 : Flotante (IEEE 754-2008)
4 : Flotante inverso (comienza la transmisión del marco desde el byte menos significativo) |
12 | 0X0C | Pendiente (o escalado) | Valor de pendiente (escalado) del sensor:
Para ajustar el valor de lectura de un sensor, se puede utilizar una escala lineal, en la forma:
V. Ajustada = ( V. Leída + Offset)*Pendiente. |
Tabla 5. Tipos de sensores
Tipo de sensor | Código hexadecimal | Descripción | Resolución
(en décimos) |
1 | 0x01 | Sensor Digital 0/1 | 0 |
2 | 0x02 | Sensor de Corriente 4 - 20mA | 2 |
3 | 0x03 | Sensor de Voltaje 0 - 10V | 2 |
4 | 0x04 | Sensor de Temperatura NTC 10K - 3950 | 1 |
5 | 0x05 | Sensor de Temperatura Ambiental | 1 |
6 | 0x06 | Sensor de Humedad Ambiental | 1 |
7 | 0x07 | Contador de Pulsos Digital 0/1 | 0 |
8 | 0x08 | Valor remoto enviado desde la plataforma | 1 |
9 | 0x09 | Entrada Modbus | 1 |
10 | 0x0A | Entrada de Frecuencia (Entrada N° 5 solamente) | 1 |
Ejemplo:
Queremos modificar el tipo de sensor de la entrada N°1, para configurarlo como un sensor de corriente de 4-20mA.
Para editar los parámetros de configuración del Sensor 1 debes seleccionar “Grupo de Parámetro 1: 0x01”. Luego, en la Tabla 4, verás que el código numérico correspondiente a la configuración “Tipo de Sensor” es 2: 0x02. Finalmente, consulta la Tabla 5 para ver que el código numérico correspondiente al “Sensor de Corriente” de 4-20mA es 2: 0x02.
Tampoco hay más mensajes de downlink acumulados o pendientes de ser descargados ya que solo queríamos configurar una sola configuración.
Entonces:
Grupo de parámetros: 01
Parámetro para sensores: 02
Datos o valor: 00 00 00 00 02
Nuevo downlink pendiente: 00
Por lo tanto, el siguiente marco es enviado por un mensaje de downlink:
0x 01 00 02 00 00 00 02 00
4.2.2. Modificación de parámetros de salida (Grupo de parámetros 11 a 15)
Este grupo de mensajes de downlink permite modificar parámetros como:
Función asignada a una salida,
Variable de control,
Punto de ajuste, entre otros.
Para conocer los tipos de parámetros modificables para las salidas, consulta Tablas 6 a 8
Tabla 6. Parámetros de salida
Parámetros de salida
hexadecimal | Código hexadecimal | Nombre | Observación |
1 | 0x01 | Estado de salida de comando remoto | Cambia el estado de la salida analógica o de relé (1: cerrado, 0: abierto), cuando la función de control de salida está configurada para comandos remotos (Tablas 7 y 8: 0x01). |
2 | 0x02 | Función de control seleccionada | Tipo de actuación de control para la salida,
Ver Tablas 7 y 8. |
3 | 0x03 | Señal de control asignada | 0 : Sin señal de control
1 a 5 : Entradas de sensor 1 a 5 |
4 | 0x04 | Valor del punto de ajuste | Valor deseado para control de
-40.0 a 2047.0 |
5 | 0x05 | Diferencial de control o Histeresis | 0.0 a 20.0, es el rango de control programado alrededor del punto de ajuste. |
6 | 0x06 | Tipo de control
(Invertir salida) | Para la función de control:
0 : Salida normal (enfriamiento)
1 : Salida invertida (calefacción)
Para la función de temporizador:
0 : El temporizador se activa cuando la señal de control es menor que el punto de ajuste.
1 : El temporizador se activa cuando la señal de control es mayor que el punto de ajuste.
Para el contador de eventos:
0:
Si # Pulsos < Punto de ajuste ==> Salida = APAGADO
Si # Pulsos >= Punto de ajuste ==> Salida = ENCENDIDO
1:
Si # Pulsos < Punto de ajuste ==> Salida = ENCENDIDO
Si # Pulsos >= Punto de ajuste ==> Salida = APAGADO |
7 | 0x07 | Tiempo de ciclo ENCENDIDO programado para la salida temporizada
Tiempo de ciclo para el control PID | 1 a 32767 segundos |
8 | 0x08 | Tiempo de ciclo APAGADO programado para la salida temporizada
Tiempo para realizar cálculos de control para el control PID | 0 a 32767 segundos |
9 | 0x09 | Control PID: Acción Proporcional | 0 a 50% |
10 | 0x0A | Control PID: Acción Integral | 0 a 50 |
11 | 0x0B | Control PID: Acción Derivativa | 0 a 50 |
12 | 0x0C | Control PID: Potencia máxima a aplicar en la salida | 10 a 100% |
Tabla 7. Tipos de función de control asignados a una salida digital
Función de control | Código hexadecimal | Descripción |