Trazabilidad de activos con LoRaWAN e IA generativa. Desarrollo de la plataforma de seguimiento con IA generativa

Llegados a este punto, el siguiente paso en el proyecto era el desarrollo de la aplicación web de seguimiento de activos propiamente dicha. Para este proceso utilicé el desarrollo asistido con IA generativa. En concreto, hice uso de Dyad para la generación de código. Las directivas principales fueron las siguientes:

• Desarrollo de un frontal web con capacidad para mostrar en un mapa OpenStreetMap la localización de usuarios que estuvieran haciendo uso de un dispositivo LoRaWAN.
• Cómputo en un backend desplegado en un servidor Debian, sin dependencias con sistemas cloud.
• Establecimiento de una asociación entre usuarios y dispositivos, de tal manera que fuera posible asociar los primeros a los segundos, y guardar un registro histórico de dicha asociación.
• Registro de los gateways que proporcionan información de los dispositivos de la plataforma.
• Capacidad de revisar las actividades de la dupla usuario-dispositivo.
• Registro histórico de mensajes recibidos por la plataforma.
• Uso de MQTT como plataforma de mensajería interna entre el servidor ChirpStack y la aplicación.
• Uso de una base de datos MariaDB.
• Sección de administración para controlar las conexiones con el backend, MQTT y MariaDB.

El proceso de desarrollo fue realizado de manera incremental, proporcionando un primer borrador de la arquitectura y de las funciones solicitadas, para ir ajustando de manera más fina en sucesivas iteraciones, lo que permitía ir evaluando la correcta generación de código por parte de Dyad, así como corregir malas prácticas, errores e introducir mejoras en el sistema.

En este artículo entro en detalle de la arquitectura, las tecnologías y las funcionalidades de la aplicación web desarrollada. La principal característica de la aplicación es que está diseñada para el seguimiento de dispositivos LoRaWAN con capacidades GPS. La plataforma no solo ofrece una visualización en tiempo real, sino también herramientas robustas para la administración de usuarios, dispositivos y gateways, así como un análisis histórico de actividades y mensajes.

Arquitectura del Sistema: Un Enfoque Cliente-Servidor Distribuido

La aplicación concibe bajo un modelo de arquitectura cliente-servidor, donde cada componente desempeña un rol especializado, facilitando la escalabilidad, el mantenimiento y la separación de responsabilidades. Esta estructura se compone de:

• Frontend (Cliente Web): La interfaz de usuario interactiva, accesible mediante un navegador web.
• Backend (Servidor API): El corazón de la lógica de negocio, que orquesta las operaciones de datos y las integraciones externas.
• Base de Datos (MariaDB): El repositorio persistente para todos los datos operativos y de configuración.
• Broker MQTT: Un componente externo crucial para la ingesta de datos en tiempo real desde los dispositivos LoRaWAN, que actúa como canal de comunicaciones de la plataforma con respecto a sus sistemas auxiliares.
• Servidor de Red LoRaWAN: El servidor ChirpStack descrito en capítulos anteriores, que actúa como componente externo. Este despliega una aplicación que permite compartir los mensajes recibidos de los dispositivos por medio de una integración HTTP POST.
• Gateway LoRaWAN: El dispositivo Heltec comentado anteriormente. Hace de interfaz entre el servidor ChirpStack y los dispositivos de campo.
• Dispositivos LoRaWAN: Los dispositivos comentados en otros capítulos. Tanto CubeCell como Dragino.

Esta división permite que el frontend se centre exclusivamente en la experiencia del usuario, mientras que el backend maneja la complejidad de la persistencia de datos, la comunicación con dispositivos y la lógica de negocio, desacoplando así las capas y permitiendo su evolución independiente.

Una acotación con respecto a la integración entre el servidor ChirpStack y el broker MQTT: si bien el propio ChirpStack se apoya en el servidor MQTT para el intercambio de mensajes entre sus diversos componentes, estas comunicaciones hacen uso de mensajes con codificación binaria, que no son directamente utilizables para extraer información de ellos por parte de sistemas externos. Por ello, en mi caso, opté por realizar la integración de la aplicación definida en ChirpStack mediante un POST HTTP. Este post se envía a un servicio definido en Node-RED, que hace de pasarela hacia un topic MQTT específico, que es el consumido por la aplicación de trazabilidad.

En este sentido, otra posibilidad al respecto era hacer uso de una API REST definida en el backend, pero tenía ganas de emplear esta vía de integración, aunque tiene como contrapartida que crea una dependencia con un sistema externo adicional, en este caso, mi servidor Node-RED.

Frontend: Una Experiencia de Usuario Reactiva y Tipada

El cliente web es una Single Page Application (SPA) construida con un stack tecnológico moderno, priorizando la reactividad, la robustez y la eficiencia del desarrollo.

Tecnologías Clave del Frontend

• React & TypeScript: La combinación de React para la construcción declarativa de interfaces y TypeScript para el tipado estático ofrece una base sólida. TypeScript es invaluable en proyectos de esta envergadura, ya que detecta errores en tiempo de compilación, mejora la refactorización y proporciona una documentación implícita del código, lo que se traduce en una mayor mantenibilidad y menos errores en producción.
• Vite: Utilizado como herramienta de construcción, Vite proporciona un entorno de desarrollo extremadamente rápido gracias a su uso de módulos ES nativos y su hot module replacement (HMR) optimizado.
• React Router: Gestiona la navegación declarativa dentro de la SPA, permitiendo rutas anidadas y una experiencia de usuario fluida sin recargas de página completas.
• Shadcn/ui & Tailwind CSS: La interfaz se construye utilizando componentes de Shadcn/ui, que a su vez se basan en Radix UI para la accesibilidad y Tailwind CSS para el estilado. Esta combinación permite un desarrollo ágil de la UI, garantizando un diseño consistente, responsive y altamente personalizable sin la sobrecarga de un framework CSS tradicional. Las clases de Tailwind se aplican directamente en el JSX, lo que facilita la comprensión del estilo de cada componente.
• React Query (TanStack Query): Es la piedra angular para la gestión del estado del servidor. En lugar de manejar manualmente el fetching, caching, sincronización y actualización de datos asíncronos, React Query automatiza estas tareas. Esto se traduce en menos código boilerplate, un rendimiento optimizado (gracias al caching y background refetching), y una mejor experiencia de usuario con estados de carga y error bien gestionados.
• React Map GL (Mapbox GL JS): Para la visualización de datos geoespaciales, se integra Mapbox GL JS a través de su wrapper de React. Esto permite renderizar mapas vectoriales interactivos, añadir marcadores personalizados para dispositivos y gateways, dibujar trayectorias y superponer capas de datos complejos como mapas de calor. La flexibilidad de Mapbox GL JS es crucial para representar la dinámica de los dispositivos LoRaWAN. Se utiliza un estilo de mapa basado en OpenStreetMap para una solución de código abierto.
• Lucide React: Proporciona una colección de iconos SVG ligeros y personalizables, utilizados para representar visualmente usuarios, dispositivos y gateways en el mapa y en las tablas.
• Date-fns: Una biblioteca modular para la manipulación y el formateo de fechas, esencial para presentar los timestamps de los mensajes y actividades de manera legible y localizada.

Estructura de Directorios del Frontend

• src/pages/: Contiene los componentes de nivel superior que corresponden a las rutas principales de la aplicación (e.g., Dashboard.tsx, UserManagement.tsx).
• src/components/: Agrupa componentes reutilizables más pequeños, desde elementos de UI básicos (como Navbar.tsx) hasta componentes complejos (como MapComponent.tsx o TrajectoryLayer.tsx).
• src/services/api.ts: Centraliza todas las llamadas a la API REST del backend, encapsulando la lógica de fetching y el manejo de errores para una interacción limpia con el servidor.
• src/types/index.ts: Define las interfaces TypeScript para todas las entidades de datos (User, Device, Message, Activity, etc.), asegurando la coherencia de los datos entre el frontend y el backend.
• src/lib/utils.ts: Contiene funciones de utilidad generales, como cn para combinar clases de Tailwind de forma condicional.
• src/lib/colors.ts: Mapea clases de color de Tailwind a sus valores hexadecimales correspondientes, permitiendo el uso de colores dinámicos en componentes que requieren valores directos (como las líneas de trayectoria en el mapa).

Backend: El Motor de Datos y Lógica

El backend es un servidor Node.js que expone una API RESTful y se encarga de la ingesta de datos MQTT, la persistencia en MariaDB y la aplicación de la lógica de negocio.

Tecnologías del Backend

• Node.js & Express: Node.js, con su modelo de E/S no bloqueante, es ideal para aplicaciones en tiempo real como esta, que manejan múltiples conexiones concurrentes (API REST, MQTT). Express simplifica la creación de rutas, middleware y la gestión de solicitudes HTTP.
• TypeScript: Al igual que en el frontend, TypeScript aporta robustez al backend, especialmente en la definición de interfaces para los datos que se intercambian con la base de datos y el cliente MQTT.
• MariaDB Client (mariadb): Se utiliza un pool de conexiones para gestionar eficientemente las interacciones con la base de datos, optimizando el rendimiento y la resiliencia. Las consultas se parametrizan para prevenir ataques de inyección SQL.
• MQTT.js: Este cliente MQTT permite al backend suscribirse a topics específicos del broker MQTT. Es el canal principal para recibir los mensajes de uplink de los dispositivos LoRaWAN.
• UUID: Se emplea para generar identificadores únicos universales para todas las entidades (usuarios, dispositivos, mensajes, actividades, etc.), garantizando la unicidad en un entorno distribuido.
• Date-fns: Fundamental para la conversión precisa de timestamps entre formatos Unix (utilizado en la base de datos para eficiencia) e ISO 8601 (utilizado en la API para interoperabilidad y legibilidad). También se usa para cálculos de tiempo, como el umbral de inactividad.

Funcionalidades Clave del Backend

• API RESTful Completa: El backend expone endpoints para todas las operaciones CRUD (Crear, Leer, Actualizar, Eliminar) sobre usuarios, dispositivos, gateways, y para la consulta de mensajes, posiciones y actividades. También incluye endpoints para la gestión de configuraciones (MQTT, MariaDB, App) y para pruebas de conectividad.
• Procesamiento de Mensajes MQTT:
• Ingesta en Tiempo Real: El cliente MQTT se suscribe a un topic configurable (e.g., lorawan/data) para recibir mensajes de uplink.
• Parseo Inteligente: Los mensajes LoRaWAN pueden variar en formato dependiendo del Network Server (The Things Stack, ChirpStack, etc.). El backend implementa una lógica de parseo flexible para extraer campos clave como devEui, timestamp, latitude, longitude, rssi, rumbo, velocidad, altitud y rxInfo (información del gateway). Se manejan múltiples rutas para estos campos para asegurar la compatibilidad.
• Normalización de Datos: Los datos extraídos se normalizan y se convierten a los tipos de datos adecuados (e.g., flotantes para coordenadas, enteros para RSSI, Unix timestamps para fechas).
• Gestión de Actividades de Dispositivos:
• Detección de Actividad: Cada mensaje con datos de posición contribuye a una «actividad».
• Umbral de Inactividad: Un parámetro configurable (activityInactivityThresholdSeconds) define el tiempo máximo (en segundos) que un dispositivo puede estar sin enviar un mensaje antes de que su actividad actual se considere finalizada. Si un nuevo mensaje llega dentro de este umbral, la actividad existente se extiende; de lo contrario, se inicia una nueva actividad.
• Persistencia: Las actividades se almacenan en la tabla activities, registrando el usuario, dispositivo, tiempos de inicio/fin y coordenadas iniciales/finales.
• Auto-creación de Entidades: Si un mensaje MQTT llega de un devEui no registrado, el backend puede crear automáticamente un nuevo dispositivo con un nombre por defecto, simplificando la puesta en marcha.
• Actualización de Gateways: La información de los gateways (última vez visto, coordenadas) se actualiza dinámicamente a partir de los metadatos rxInfo de los mensajes recibidos.

Base de Datos: MariaDB como Almacén de Datos

MariaDB, una bifurcación de MySQL, se utiliza como el sistema de gestión de bases de datos relacionales. Su robustez, rendimiento y compatibilidad con SQL estándar lo hacen ideal para esta aplicación. Las principales tablas son las siguientes:

• users: Almacena la información de los usuarios finales que se están siguiendo (nombre, email, icono, color).
• devices: Registra los dispositivos LoRaWAN por su DevEUI, su nombre y el usuario al que están asociados.
• positions: Almacena cada punto de posición reportado por los dispositivos (DevEUI, latitud, longitud, timestamp).
• messages: Guarda una copia completa de cada mensaje MQTT recibido, incluyendo el payload y metadatos como RSSI y gateway de recepción.
• activities: Representa un periodo de actividad de un dispositivo asociado a un usuario. Contiene la hora de inicio/fin y las coordenadas inicial/final.
• gateways: Registra la información de los gateways LoRaWAN que han reportado mensajes (ID, nombre, ubicación, icono, última vez visto).
• app_config: Almacena la configuración de la aplicación, como la dirección IP/puerto del backend y el umbral de inactividad para las actividades.
• mqtt_config: Guarda los detalles de conexión al broker MQTT (URL, puerto, topic, credenciales).
• mariadb_config: (Para uso interno del backend) Almacena los detalles de conexión a la propia base de datos.

Integración Frontend-Backend: Comunicación Fluida

La comunicación entre el frontend y el backend se realiza a través de la API REST. El frontend utiliza la función getApiBaseUrl() para construir dinámicamente la URL base del backend, que se almacena en localStorage y puede ser configurada por el usuario en la sección de Administración. Durante el desarrollo, vite.config.ts configura un proxy para redirigir las solicitudes /api al backend, evitando problemas de CORS.

Las respuestas de la API se tipan rigurosamente con las interfaces definidas en src/types/index.ts, garantizando la seguridad de los datos. React Query gestiona el ciclo de vida de estas solicitudes, incluyendo la invalidación de caché para mantener la UI sincronizada con los cambios en el servidor.

Interfaces y Secciones de la Aplicación: Una Visión Detallada

La aplicación se estructura en varias secciones, cada una diseñada para una funcionalidad específica y con una interfaz de usuario optimizada.

1. Dashboard

El Dashboard es el centro de control en tiempo real, ofreciendo una visión consolidada del estado de los dispositivos y la red.

• Mapa Interactivo (MapComponent.tsx):
• Visualización de Dispositivos: Muestra la última posición conocida de cada dispositivo como un marcador. Estos marcadores son iconos de Lucide personalizados, cuyo tipo y color se definen en la gestión de usuarios, permitiendo una identificación visual rápida. Al hacer clic, un popup muestra detalles como el usuario asociado, nombre del dispositivo, coordenadas, timestamp y los últimos datos de telemetría (rumbo, velocidad, altitud).
• Visualización de Gateways: Los gateways se representan con iconos específicos (e.g., Antenna) y un color distintivo, mostrando su ubicación y detalles al interactuar con ellos.
• Trayectorias Históricas (TrajectoryLayer.tsx): Para cada dispositivo, se dibuja una línea que representa su trayectoria histórica. La longitud de esta trayectoria es configurable mediante un slider logarítmico, permitiendo al usuario visualizar desde los últimos minutos hasta un historial ilimitado. El color de la trayectoria coincide con el color asignado al usuario.
• Mapa de Calor: Una capa opcional que visualiza la densidad de las posiciones históricas de los dispositivos, útil para identificar áreas de mayor actividad. La opacidad de esta capa es ajustable.
• Control de Capas por Usuario: Un panel lateral permite activar o desactivar la visibilidad de los marcadores y trayectorias de dispositivos asociados a usuarios específicos, facilitando el análisis de subconjuntos de datos.
• Slider de Límite Temporal de Trayectoria: Un control deslizante con una escala logarítmica que permite al usuario ajustar el periodo de tiempo para el cual se muestran las trayectorias de los dispositivos. Los valores van desde «Sin trayectoria» (0 horas) hasta «Ilimitado», con puntos intermedios que representan minutos, horas, días, meses o años.
• Tablas de Resumen:
• Últimas Posiciones: Muestra las 5 posiciones más recientes de dispositivos únicos, con actualizaciones en tiempo real.
• Dispositivos Activos: Lista todos los dispositivos registrados y la última vez que se recibió un mensaje de ellos, formateado con date-fns (e.g., «hace 5 minutos»).
• Últimos Mensajes Recibidos: Una tabla que muestra los 10 mensajes LoRaWAN más recientes, incluyendo detalles como el usuario, dispositivo, gateway, coordenadas, rumbo, velocidad, altitud, RSSI y timestamp.

2. Gestión de Usuarios (UserManagement.tsx)

Esta sección permite la administración de los usuarios que interactúan con la plataforma o cuyos dispositivos son rastreados.

• Tabla de Usuarios: Presenta un listado paginado de todos los usuarios, con columnas para nombre, email, un previsualizador del icono y su color.
• Formulario Modal (Creación/Edición): Un diálogo modal permite crear nuevos usuarios o editar los existentes. Los campos incluyen nombre, email, y selectores para elegir un icono de Lucide (e.g., Car, Bike) y un color de Tailwind (e.g., blue-600, green-600). Estos atributos visuales son cruciales para la representación en el mapa.
• Operaciones CRUD: Botones para editar y eliminar usuarios, con notificaciones de éxito/error mediante sonner.

3. Gestión de Dispositivos (DeviceManagement.tsx)

Administración de los dispositivos LoRaWAN que envían datos a la plataforma.

• Tabla de Dispositivos: Muestra el ID, DevEUI, nombre y el usuario asociado a cada dispositivo.
• Formulario Modal (Creación/Edición): Permite registrar nuevos dispositivos o modificar los existentes. El campo DevEUI es crítico y debe ser único. Un selector desplegable facilita la asociación de un dispositivo con un usuario existente o su desasociación (null).
• Operaciones CRUD: Funcionalidades completas para añadir, editar y eliminar dispositivos.

4. Gestión de Gateways (GatewayManagement.tsx)

Visualización y edición de la información de los gateways LoRaWAN que reenvían los mensajes de los dispositivos.

• Tabla de Gateways: Lista los gateways por ID, nombre, coordenadas, icono y la última vez que se recibió un mensaje a través de ellos.
• Formulario Modal (Edición): Permite modificar el nombre y el icono de un gateway. Campos como ID, latitud, longitud y última aparición se muestran como solo lectura, ya que se actualizan automáticamente con los datos de los mensajes MQTT.
• Confirmación de Eliminación: Un AlertDialog de Shadcn/ui solicita confirmación antes de eliminar un gateway, advirtiendo sobre posibles restricciones de clave foránea.

5. Historial de Actividades (ActivityHistory.tsx)

Esta sección permite a los usuarios revisar las actividades pasadas de los dispositivos asociados.

• Selección de Usuario y Fecha: Un selector de usuario y un componente Calendar (de Shadcn/ui) permiten filtrar las actividades. El calendario resalta dinámicamente los días en los que el usuario seleccionado tuvo actividad, consultando un endpoint específico del backend (/api/users/:userId/activity-dates).
• Listado de Actividades del Día: Muestra una lista de las actividades registradas para el usuario y la fecha seleccionados, indicando el dispositivo, y las horas de inicio y fin.
• Visualización de Trayectoria en Mapa: Al seleccionar una actividad de la lista, su trayectoria completa se carga y se visualiza en un mapa. Se utilizan marcadores específicos (PlayCircle y StopCircle de Lucide) para indicar el inicio y el fin de la actividad, con popups informativos.
• Exportación GPX: Una funcionalidad clave es la capacidad de exportar la trayectoria de una actividad seleccionada en formato GPX. Esto permite a los usuarios descargar los datos de la ruta para su uso en software de mapeo externo, análisis o archivado. El GPX generado incluye timestamps en formato ISO 8601 UTC.

6. Historial de Mensajes (MessageHistory.tsx)

Una vista tabular exhaustiva de todos los mensajes LoRaWAN recibidos y almacenados.

• Tabla de Datos (@tanstack/react-table): Utiliza react-table para renderizar una tabla de datos eficiente y rica en funcionalidades.
• Columnas Detalladas: Cada fila representa un mensaje, mostrando campos como hora, usuario, dispositivo, DevEUI, gateway, latitud, longitud, rumbo, velocidad, altitud, RSSI y el payload raw.
• Funcionalidades Avanzadas:
• Búsqueda Global: Un campo de entrada permite buscar texto en todas las columnas de la tabla.
• Ordenación por Columnas: Los usuarios pueden ordenar los datos haciendo clic en los encabezados de las columnas.
• Paginación: Controles de paginación completos (primera, anterior, siguiente, última página) y un selector para ajustar el número de filas por página (10, 20, 50, 100).

7. Administración (Administration.tsx)

Esta sección es crítica para la configuración y el mantenimiento del sistema, permitiendo ajustar las integraciones y parámetros operativos.

• Configuración del Backend:
• IP y Puerto: Permite al usuario especificar la dirección IP y el puerto donde se ejecuta el servidor backend. Esta configuración se guarda en localStorage del navegador y en la base de datos del backend (tabla app_config).
• Umbral de Inactividad de Actividad: Un campo numérico para definir el activityInactivityThresholdSeconds. Este valor es crucial para la lógica de agrupación de mensajes en actividades, ya que determina el tiempo máximo sin mensajes para que una actividad se considere finalizada.
• Prueba de Conexión: Un botón permite verificar la conectividad con el backend configurado, mostrando el estado (éxito/error) y un mensaje descriptivo.
• Configuración MQTT:
• Detalles del Broker: Campos para brokerUrl, port, topic, username y password. Esta configuración se guarda en la tabla mqtt_config del backend.
• Prueba de Conexión: Un botón que inicia una conexión de prueba efímera al broker MQTT con la configuración actual, informando sobre el éxito o el fallo. Tras guardar la configuración, el cliente MQTT del backend se reconecta automáticamente con los nuevos parámetros.
• Configuración MariaDB:
• Detalles de la Base de Datos: Campos para host, port, database, user y password. Esta configuración se guarda en la tabla mariadb_config del backend.
• Prueba de Conexión: Un botón para verificar la conectividad con la base de datos MariaDB, esencial para asegurar la persistencia de datos.

Despliegue y Configuración del Entorno

Para la puesta en marcha de la aplicación, se requiere una configuración cuidadosa de ambos componentes, frontend y backend.

Prerrequisitos

• Node.js (v18+)
• npm o Yarn
• Servidor MariaDB
• Broker MQTT (e.g., Mosquitto)
• Token de acceso de Mapbox (para el frontend)

Configuración del Backend

• Variables de Entorno (backend/.env): Se configuran las credenciales de la base de datos (DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_DATABASE) y el puerto del servidor backend (PORT).
• Esquema de Base de Datos: El archivo mariadb_schema.sql se ejecuta para crear la base de datos y todas las tablas necesarias.
• Seeding (npm run seed): Un script de seeding (backend/src/seed.ts) permite poblar la base de datos con datos de prueba iniciales para usuarios, dispositivos, gateways, mensajes y actividades, facilitando el desarrollo y las demostraciones.
• Inicio del Servidor: El servidor se inicia con npm run dev (para desarrollo con recarga automática) o npm start (para producción).

Configuración del Frontend

• Variables de Entorno (.env en la raíz): Se configura el token de acceso de Mapbox (VITE_MAPBOX_ACCESS_TOKEN).
• Construcción: La aplicación se construye con npm run build, generando los archivos estáticos optimizados.
• Despliegue con Systemd (Opcional): Para un despliegue robusto en entornos Linux, se proporciona un ejemplo de archivo de servicio systemd. Este servicio asegura que el frontend se ejecute en segundo plano, se inicie automáticamente al arrancar el sistema y se reinicie en caso de fallos, utilizando npx serve -s dist -l 8083 para servir los archivos estáticos.

Conclusión

La plataforma de seguimiento GPS LoRaWAN representa una solución integral y técnicamente sofisticada para la monitorización de activos en el ámbito IoT. Su arquitectura modular, el uso de tecnologías de vanguardia en frontend y backend, y la cuidadosa implementación de funcionalidades como la gestión de actividades, la visualización de trayectorias y la configuración dinámica de integraciones, la posicionan como una herramienta potente y adaptable. Este proyecto no solo demuestra la viabilidad de construir sistemas complejos con stacks modernos, sino que también ofrece una base sólida para futuras expansiones y personalizaciones en el creciente ecosistema LoRaWAN.