Una forma de registrar los datos que transmite un dispositivo en Home Assistant es mediante la subscripción al mensaje MQTT correspondiente a la trama LoRaWAN.
En la sección anterior se describe la forma de enviar los datos por LoRaWAN. mediante la subscripción al mensaje MQTT desde Home Assistant donde se registra y muestra el dato.
Para añadir el dispositivo a Home Assitant, se añade en el archivo de configuración las características del dispositivo y el mensaje MQTT al que se debe conectar. Esto se realiza editando el archivo de dispositivos con la intrucción:
Los datos de sensor/acción se ordenan en una trama LoRa en forma de bytes antes de la transmisión. Se pretende minimizar la cantidad de bytes usados por mensaje, siguiendo la directiva LoRa de mensajes de corta duración.
Un mensaje se puede simplificar, por ejemplo un "ON"/"OFF" presentado en LoRa puede ser 1 "o" 0, que es tan solo un bit. Los mensajes se administran por ChirpStack y los puede traducir nuevamente en mensajes "ON"/"OFF" para ser actualizados en un Broker como Home Assistant.
Un ejemplo básico de instrucciones para un dispositivo genérico permite presentar el uso de librerías LoRaWAN de HELTEC.
Trama de datos en dispositivo
Los datos son enviados en una trama como un tren de bits escritos en orden. Por ejemplo, en el dispositivo se tiene los valores de contador1, contador2 y unalectura como datos a ser transmitidos, por lo que se plantea el siguiente esquema:
Las instrucciones en el IDE arduino para el ejemplo de la trama de datos Sigue el mismo orden.
//orden de trama appDataSize = 4 //AppDataSize max value is 64 appData[0] = contador1; //0x01; appData[1] = contador2; appData[2] = highByte(unalectura); appData[3] = lowByte(unalectura);
// mostrar en puerto USB Serial.println(contador1); Serial.println(contador2); Serial.println(unalectura); }
En casos particulares hay que ajustar la trama de acuerdo a las lecturas de sensores o información que se requiera transmitir
Trama de datos en ChirpStack application - server
La trama de datos llega en binario hasta el componente application-server y de forma predeterminada se presenta en formato Base64.
Para leer los datos se puede usar el convertidor en línea o utilizar un decodificador/codificador con instrucciones en JavaScript.
https://v2.cryptii.com/base64/decimal
En ChirpStack en la sección Device-profiles/codec se puede escribir un decodificador para la trama de datos y reconstruirlo en la forma con las variables originales.
para el ejemplo presentado y siguiendo el esquema inicial, las instrucciones en JavaScript son:
function Decode(fPort, bytes, variables) {
var contador1 = bytes[0];
var contador2 = bytes[1];
var unalectura = (bytes[2] << 8) |(bytes[3]);
var appData = {'contador1':contador1, 'contador2':contador2, 'unalectura': unalectura}
return appData;
}
Con lo que en Chirpstack se obtiene para datos del dispositivo de una trama en particular:
Para capturar los datos en un broker, por ejemplo Home Assistant, se puede usar el mensaje MQTT del application-server. Es posible leer las tramas MQTT de application-server o integrar las plataformas entre si por medio de "integration"
Lecturas de mensajes MQTT
Para observar la estructura del mensaje se realiza una subscripción al mensaje MQTT de la aplicación para un dispositivo:
Para añadir un dispositivo en el Broker ChirpStack, el ejemplo básico envía una trama solo para leer los datos de niveles de señal RSSI y SNR.
1. Application Service Profile
El perfil de servicio en la aplicación se asigna un nombre acorde a la aplicación que la usará.
se ingresan los parámetros requeridos, por simplicidad solo se añade un nombre. Ejemplo:
2. Device Profile
El perfil de dispositivos describe la forma de conexión y autenticación de un grupo de dispositivos.
Por ejemplo, si los dispositivos autentican por medio de OTTA/ABP, si se incluirán dispositivos clase B, clase C y las instrucciones para codificar o decodificar los datos del dispositivo (CODEC).
La aplicación agrupa dispositivos que realizan funciones semejantes, mediante el perfil del dispositivo, donde se encuentra también el CODEC de los datos.
Se asigna un nombre y una descripción de lo que va a realizar con los dispositivos:
para finalmente registrar la aplicación
4. Añadir dispositivos a la aplicación
Hay que crear cada dispositivo con identificadores únicos y autenticar en la red.
los primeros datos corresponden a nombre y nombre y descripción.
El identificador único de dispositivo: Device EUI es primordial para la conexión por OTAA. El Device EUI se puede generar con el botón mostrado en la pantalla y se usa en la programación del dispositivo.
El perfil del dispositivo se selecciona desde la pestaña y se despliegan las opciones.
los parámetros para OTAA se pueden visualizar, generar en la pestaña correspondiente. Hay un botón para visualizar el que se esté usando, o en otro caso se puede generar para usar en la programación del dispositivo.
Si el dispositivo no ha sido conectado al menos una vez, la pestaña de activación aparece vacía. Para obtener los datos de activación es necesario realizar al menos un intento de conexión, con lo que la ventana llena los datos para completar la programación del dispositivo.
Para observar los datos de activación debe usar el botón de visualización en la parte derecha de la ventana.
Los intentos de conexión se pueden visualizar en la pestaña de LoRaWAN Frames
mientras que los datos recibidos se observan en la pestaña de Device Data
Hay que considerar que la primera vez que se conecta el dispositivo, la autenticación puede llevar algunos intentos, por lo que hay que esperar para que se comiencen a recibir los datos, a pesar que las tramas LoRaWAN si se registran en el programa.
5. Instrucciones Arduino IDE ejemplo básico
Los datos para la configuración del dispositivo se obtienen en el proceso descrito anteriormente, por lo que es necesario actualizar los datos.
En el caso de dispositivos HELTEC es necesario obtener los datos de licencia que se encuentran al inicio de las instrucciones. La licencia de cada dispositivo se puede revisar en: https://resource.heltec.cn/search/
/* * HelTec Automation(TM) LoRaWAN 1.0.2 OTAA example use OTAA, CLASS A * Solo ESP32+LoRa series boards con licencia http://www.heltec.cn/search/); *https://github.com/HelTecAutomation/ESP32_LoRaWAN
*/
#include<ESP32_LoRaWAN.h>#include"Arduino.h"/*licencia Heltec ESP32 LoRaWan http://resource.heltec.cn/searchuint32_t license[4] = {0xBE21335B, 0xAEC3C5CE, 0xCC0A1CF4, 0xB836F981};
/* OTAA parametros uint8_t DevEui[] = { 0x01, 0x20, 0x08, 0x93, 0xdf, 0x80, 0x37, 0x74 };
uint8_t AppEui[] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };
uint8_t AppKey[] = { 0x05, 0x8e, 0xeb, 0xff, 0x24, 0xf1, 0x01, 0x84, 0xd0, 0x07, 0xbe, 0xd4, 0x65, 0xe7, 0x6b, 0xb5 };
/* ABP parametros uint32_t DevAddr = ( uint32_t )0x0174b1fd;
uint8_t NwkSKey[] = { 0xc1, 0x45, 0x31, 0x28, 0x5f, 0xb2, 0x56, 0x3b, 0x9d, 0x5f, 0x27, 0x15, 0xed, 0x3a, 0x0e, 0xbc};
uint8_t AppSKey[] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};
//LoraWan channelsmask, default channels 0-7/uint16_tuserChannelsMask[6]={ 0x00FF,0x0000,0x0000,0x0000,0x0000,0x0000 };
DeviceClass_t loraWanClass = CLASS_A; /*Soporte de A and C uint32_tappTxDutyCycle = 15000; /*15000; en [ms] booloverTheAirActivation = true; /*OTAA or ABP boolloraWanAdr = true; /*ADR enable boolisTxConfirmed = true; /*confirmed or unconfirmed messages uint8_tappPort = 2; /* Application port /* reintentos de transmisión, en caso de no recibir ack uint8_tconfirmedNbTrials = 8;
/* Seleccionado de Arduino IDE tools uint8_t debugLevel = LoRaWAN_DEBUG_LEVEL;
LoRaMacRegion_t loraWanRegion = ACTIVE_REGION;
// variables de sensor/actuadorbyte contador1 = 0;
uint8_t contador2 = 0;
int unalectura = 221;
voidsetup(){
Serial.begin(115200);
while (!Serial);
SPI.begin(SCK,MISO,MOSI,SS);
Mcu.init(SS,RST_LoRa,DIO0,DIO1,license);
deviceState = DEVICE_STATE_INIT;
}
voidloop(){
switch( deviceState ) {
case DEVICE_STATE_INIT: {
LoRaWAN.init(loraWanClass,loraWanRegion);
break;
}
case DEVICE_STATE_JOIN: {
LoRaWAN.join();
break;
}
case DEVICE_STATE_SEND: {
prepareTxFrame( appPort );
LoRaWAN.send(loraWanClass);
deviceState = DEVICE_STATE_CYCLE;
break;
}
case DEVICE_STATE_CYCLE: {
// Schedule next packet transmission
txDutyCycleTime = appTxDutyCycle +randr( -APP_TX_DUTYCYCLE_RND,
APP_TX_DUTYCYCLE_RND );
LoRaWAN.cycle(txDutyCycleTime);
deviceState = DEVICE_STATE_SLEEP;
break;
}
case DEVICE_STATE_SLEEP: {
LoRaWAN.sleep(loraWanClass,debugLevel);
break;
}
default: {
deviceState = DEVICE_STATE_INIT;
break;
}
}
}
staticvoid prepareTxFrame( uint8_t port ){
contador1 = contador1 + 1;
contador2 = contador2 - 1;
//orden de trama
appDataSize = 4 //AppDataSize max value is 64
appData[0] = contador1; //0x01;
appData[1] = contador2;
appData[2] = highByte(unalectura);
appData[3] = lowByte(unalectura);
// mostrar en puerto USB
Serial.println(contador1);
Serial.println(contador2);
Serial.println(unalectura);
}
dsn="postgres://chirpstack_as:dbpassword@localhost/chirpstack_as?sslmode=disable"
marshaler="json"<
# JWT secret used for api authentication / authorization
# You could generate this by executing 'openssl rand -base64 32' for example
jwt_secret="------------------"
Para revisar el estado o reiniciar el componente, se usa el la instrucción:
sudo systemctl status chirpstack-application-server
sudo systemctl restart chirpstack-application-server
De encontrarse todo en funcionamiento, debe ser posible acceder a la versión web de Chirpstack en la dirección IP y puerto (8080)
El network-server es el componente que se dedica a revisar los mensajes duplicados en la red, ya sea por re-intentos de transmisión desde un mismo dispositivo o por recepción de mensajes en más de un gateway.
Además de encargarse de la autenticación , capa MAC, comunicación con el componente de aplicaciones y gestión de colas de mensajes de envió hacia dispositivos.
Base de datos de mensajes
Para manejar los mensajes es necesario disponer de una base de datos. PostgreSQL es la base de datos predeterminada.
En caso de no disponer de la base de datos, la puede instalar siguiendo las instrucciones en:
Usada para guardar los datos de cada sesión , datos no persistentes, de duplicación y meta-data.
sudo apt install redis-server
Instalación de ChirpStack-network-server
Semejante al componente anterior, se añaden las referencias del repositorio de los archivos de instalación para ejecutar luego el proceso de instalación.
[general]
log_level=4
[postgresql]
dsn="postgres://chirpstack_ns:dbpassword@localhost/chirpstack_ns?sslmode=disable"
[network_server.band]
name="US915"
cambiar a comentario la seccion:
# Extra channel configuration.
Revisar el detalle de la línea dsn, pues el usuario al final de la línea vienen escrito con doble _ns_ns.
Añadir al final del archivo los datos de usuario y contraseña para el servicio MQTT
Para revisar el estado del componente se usa el la instrucción:
sudo systemctl status chirpstack-network-server
sudo systemctl restart chirpstack-network-server
debiendo obtener una respuesta semejante a
Para revisar el historial de actividad (log) y verificar operatividad
Es el componente que convierte el protocolo LoRa-packet-forwarder en el formato de datos de ChirpStack-network-server que es el siguiente componente.
Para la gestión de mensajes se usa un servidor MQTT existente y previamente configurado. Si no se dispone de uno, se puede instalar y configurar siguiendo las instrucciones de MQTT – Mosquitto instalar
Instalación de ChirpStack-gateway-bridge v4.x
Las instrucciones para Raspberry OS se encuentran simplificadas, las primeras son para acceder al repositorio de instalación y la siguiente para instalar el componente.
La conexión al servidor MQTT se configura en el archivo, para el ejemplo se ha mantenido la simplicidad al no requerir usuario y contraseña para interactuar con Mosquitto. Recuerde cambiar esta situación una vez que esten terminadas todas las configuraciones y se ha probado la operatividad del mismo.
# Integration configuration.
[integration]
# Payload marshaler.
#
# This defines how the MQTT payloads are encoded. Valid options are:
# * protobuf: Protobuf encoding
# * json: JSON encoding (easier for debugging, but less compact than 'protobuf')
marshaler="json"
# MQTT integration configuration.
[integration.mqtt]
# Event topic template.
event_topic_template="gateway/{{ .GatewayID }}/event/{{ .EventType }}"
# Command topic template.
command_topic_template="gateway/{{ .GatewayID }}/command/#"
# MQTT authentication.
[integration.mqtt.auth]
# Type defines the MQTT authentication type to use.
#
# Set this to the name of one of the sections below.
type="generic"
# Generic MQTT authentication.
[integration.mqtt.auth.generic]
# MQTT server (e.g. scheme://host:port where scheme is tcp, ssl or ws)
server= "tcp:///127.0.0.1:1883"
#"tcp://127.0.0.1:1883"
# Connect with the given username (optional)
username=""
# Connect with the given password (optional)
password=""
Para revisar el estado del componente se usa la instrucción
sudo systemctl status chirpstack-gateway-bridge
en el caso de que se requiera reiniciar el componente
sudo systemctl restart chirpstack-gateway-bridge
El estado del gateway-bridge será semejante a:
Mensajes en MQTT-Mosquitto
Los eventos y mensajes MQTT son semejantes a lo mostrado, revisando todos los mensajes que llegan a Mosquitto: se puede usar la instrucción.
Para leer los contenidos de la configuración desde MQTT será necesario cambiar al formato a "json" en el archivo de configuración del gateway bridge.
Los estados de los mensajes en formato json se observan en la imagen.
mientras en formato "protobuf" se observa de la siguiente manera:
Observe que en ambas situaciones es posible leer solo los valores correspondientes a los parámetros de transmisión, sin embargo los datos de usuario permanecen ilegibles.
Para integrar esta red a IOT en esquema abierto se ha seleccionado como gestor de gateways a ChirpStack, pues se integra a la gestión de paquetes y al gestor de mensajes MQTT versión Mosquitto.
De esta forma se genera un punto intermedio para integrar las conexiones con otros brokers de forma simplificada.
Dado que el servidor MQTT es parte del IOT Esquema Abierto, las instrucciones de instalación y configuración ya se encuentran descritas en:
Durante la implementación realizada, no se disponía del adaptador por lo que se probó construir un adaptador usando una placa perforada, teniendo los mismos resultados que con la placa de HELTEC.
El Kit de conexión del fabricante como referencia se muestra a continuacion:
Para el módulo HT-M01, el fabricante Heltec publicó una aplicación para gestionar los paquetes denominado packet-forwarder, encargada de reenviar los paquetes a un administrador de gateways.
Los datos recibidos por el módulo gateway son reenviados por SPI o el puerto USB hacia la red local o internet usando el aplicativo instalado en un Raspberry Pi.
En las pruebas con USB se encontró que para reiniciar el módulo HT-M01 es necesario presionar el botón Reset, mientras que en el modo SPI se podía realizar de forma remota, por lo que se prefiere configurar el modo SPI.
Activar interface SPI
En Raspberry OS la interface SPI requiere activarse para su uso con la siguiente instrucción:
sudo raspi-config
Que permite seleccionar de una ventana las opciones de interface
para luego activar SPI
Conexión mediante SPI
Las instrucciones paso a paso se describen más adelante, para la ultima instrucción hay que tener disponible la configuración de región. Para el caso de Ecuador es US915.
Cada instrucción se debe realizar en secuencia, el el penúltimo paso se obtiene el Gateway _id, que será usado para registrar el mini gateway en el servidor de red y aplicaciones.
Nota 2026-03: En Raspbian OS se recomienda usar un nombre de usuario diferente de "pi", por lo que se deben ajustar las direcciones en las instrucciones al usuario en las ultimas instrucciones.
En el directorio "lorasdk" Edite el archivo "install.sh" y "lrgateway.service" para evitar errores de donde se encuentra el archivo. Por ejemplo en install.sh, se editan las líneas con sudo nano install.sh
actualizado los archivos, se puede continuar con las correcciones en los directorios:
# This package will create a "lrgateway" service in Raspberry Pi cd /home/pi/lora/lora_gateway make clean all cd /home/pi/lora/packet_forwarder make clean all cd /home/pi/lora/lorasdk chmod +x install.sh ./install.sh #Run the script. After the script is run, it will create a # service named "lrgateway". The purpose is to make the lora driver # and data forwarding program run automatically at startup. sudo cp -f /home/pi/lora/lorasdk/global_conf_US915.json /home/pi/lora/packet_forwarder/lora_pkt_fwd/global_conf.json #the "global_conf_US915.json" may need change to your need.
Cambios para Raspberry pi OS Trixie 2026-03
En la versión Bookworm y Trixie, las instrucciones para manejar GPIOs han migrado a pinctrl, por lo que se debe actualizar el archivo /lora/packet_forwarder/lora_pkt_fwd.sh
# Force bypassing auto update of Gateway_ID in JSON conf file IOT_SK_GWID_UPDATE=true
# The reset pin of SX1301 is wired with RPi GPIO2 IOT_SK_SX1301_RESET_PIN=17
# set GPIO 17 as output echo "out" #> /sys/class/gpio/gpio$IOT_SK_SX1301_RESET_PIN/direction; WAIT_GPIO
# write output for SX1301 reset pinctrl set 17 op dh WAIT_GPIO pinctrl get 17 echo "1" #> /sys/class/gpio/gpio$IOT_SK_SX1301_RESET_PIN/value; WAIT_GPIO pinctrl set 17 op dl pinctrl get 17 WAIT_GPIO echo "0" #> /sys/class/gpio/gpio$IOT_SK_SX1301_RESET_PIN/value; WAIT_GPIO # set GPIO 17 as input pinctrl set 17 ip pinctrl get 17 WAIT_GPIO echo "in" #> /sys/class/gpio/gpio$IOT_SK_SX1301_RESET_PIN/direction; WAIT_GPIO }
iot_sk_term() { echo "iot_sk_term" # cleanup GPIO 17 pinctrl get 17 echo " term reiniciando" if [ -d /sys/class/gpio/gpio$IOT_SK_SX1301_RESET_PIN ] then pinctrl get 17 echo " iot_sk_term en if "$IOT_SK_SX1301_RESET_PIN" ..." #> /sys/class/gpio/unexport; WAIT_GPIO fi }
Conexión al puerto USB
Las instrucciones son muy semejantes al proceso anterior, para la ultima instrucción hay que tener disponible la configuración de región. Para el caso de Ecuador es US915.
Cada instrucción se debe realizar en secuencia, el el penúltimo paso se obtiene el Gateway _id, que será usado para registrar el mini gateway en el servidor de red y aplicaciones
Si el módulo fue instalado en el proceso anterior, no es necesario ejecutar esta sección
mkdir lora
cd lora
sudo apt-get update
sudo apt-get install git
git clone https://github.com/Lora-net/picoGW_hal.git
git clone https://github.com/Lora-net/picoGW_packet_forwarder.git
git clone https://github.com/HelTecAutomation/picolorasdk.git
cd /home/pi/lora/picoGW_hal
make clean all
cd /home/pi/lora/picoGW_packet_forwarder
make clean all
cd /home/pi/lora/picolorasdk
chmod +x install.sh
./install.sh
#Run this script will create a service named "lrgateway". The purpose is to make the lora driver and data forwarding program run automatically at startup.
sudo cp -f /home/pi/lora/picolorasdk/global_conf_US915.json /home/pi/lora/picoGW_packet_forwarder/lora_pkt_fwd/global_conf.json
#Put the configuration file on the specified path
Estado de Packet-forwarder
Las instrucciones de instalación se encuentran en:
HT-M01 Mini LoRa Gateway Quick Start. Heltec.org. Revisado Septiembre 2023
El archivo local contiene la identificación del gateway obtenida luego de ejecutar la línea ./install.sh del proceso anterior. El archivo global contiene la información de la región y las frecuencias usadas.
El archivo "global_conf.json" se configura el servidor donde se encuentra el gateway-bridge usando el parámetro "server_address". Si se encuentra en el mismo Raspberry Pi que el Packet-forwarder se usa "localhost", sino con la dirección IP respectiva. También hay que actualizar los parámetros para el "gateway_ID" obtenido al final del proceso al instalar el packet-forwarder.
"gateway_conf": {
"gateway_ID": "3532363324003700",
/* change with default server address/ports, or overwrite in local_conf.json */
"server_address": "192.168.10.50",
"serv_port_up": 1700,
"serv_port_down": 1700,
/* adjust the following parameters for your network */
"keepalive_interval": 10,
"stat_interval": 30,
"push_timeout_ms": 100,
/* forward only valid packets */
"forward_crc_valid": true,
"forward_crc_error": false,
"forward_crc_disabled": false
}
Conexión a TTN
El archivo "global_conf.json" se configura para un servidor TTN de la regíon, revisar los datos apropiador para "gateway_ID" y "server_address".
"gateway_conf": {
"gateway_ID": "3532363324003700",
/* change with default server address/ports, or overwrite in local_conf.json */
"server_address": "router.us.thethings.network",
"serv_port_up": 1700,
"serv_port_down": 1700,
/* adjust the following parameters for your network */
"keepalive_interval": 10,
"stat_interval": 30,
"push_timeout_ms": 100,
/* forward only valid packets */
"forward_crc_valid": true,
"forward_crc_error": false,
"forward_crc_disabled": false
}
El esquema abierto para un gateway LoRa de bajo costo, desagrega e interconecta componentes de hardware y software.
El mini-gateway es modular, el componente de software para la gestión de gateways y paquete de datos se implementa sobre un Raspberry Pi, conectado por Ethernet a la red local y con dirección IP fija.
En el manejo de software se prioriza integrar la gestión de dispositivos usando mensajes MQTT y de esta manera simplificar la integración al broker del esquema IoT general.
Componentes
El punto de partida la propuesta es gateway entre LoRa y Ethernet/Wifi. El fabricante Heltec presenta un "mini-Gateway" con el Módulo HT-M01. El módulo de hardware se conecta por medio del software "Packet-forwarder" (en un Raspbery Pi) hacia un administrador de gateways que puede estar en la red local (ChirpStack) o en la nube (The Things Network).
La conexión del módulo HT-M01 se puede realizar con SPI usando una placa de conexión hacia el Raspberry Pi. Si no se tiene la placa, también se la puede construir siguiendo las instrucciones en:
El proceso de instalación del Raspberry Pi se encuentra descrito en la Raspberry Pi OS-Instalar.
Packet-forwarder se instala siguiendo las instrucciones del fabricante.
Inicialmente se usó USB como conexión del módulo Heltec HT-M01, luego se usó SPI solo para comprobar las modalidades de implementación. Se utiliza SPI en la versión de operación regular.
Conexión entre componentes
módulo Heltec HT-M01 y Raspberry, SPI o USB
Ethernet desde la Raspberry Pi , usando dirección fija
La conexión Ethernet facilita la comunicación con el esquema existente y en operación, facilitando la ubicación de los componentes de software en otros "servidores" en los Raspberry Pi.
Hardware con Raspberry pi Zero y adaptador Ethernet
Para el caso de usar mas de un Gateway LoRa con Raspberry Pi Zero que no tiene conector Ethernet, se requiere un adaptador USB a Ethernet.
Algunos adaptadores USB a Ethernet "económicos" tienen la misma dirección Mac que al utilizar varios en una red local (todos en el mismo segmento) genera inconvenientes en la comunicación.
La dirección MAC se puede revisar con la instrucción:
