Configurar un contador de agua en ChirpStack: guía paso a paso para instaladores LoRaWAN

Si instalas hardware LoRaWAN, ChirpStack es probablemente el servidor de red al que ya recurres: es de código abierto, autoalojable y neutral respecto al fabricante. Lo que frena a la mayoría de instaladores no es la capa de radio — es todo lo que viene después de que el dispositivo se une a la red. ¿Cómo aprovisionas un contador de agua de forma limpia, decodificas su payload y haces que las lecturas lleguen a un portal que un gestor de Comunidad sin perfil técnico pueda usar de verdad, sin programar ni mantener un backend?

Esta guía recorre el camino completo: dar de alta un gateway, aprovisionar un contador de agua, configurar el decoder y reenviar los datos mediante un webhook a una plataforma white-label que convierte los uplinks en bruto en un portal de cliente con tu marca. Datakubo se sitúa en esa última capa — es la infraestructura white-label sobre la que construyes tu negocio de monitorización, no un producto vertical terminado — así que aquí nos centramos en el cableado práctico que el instalador hace una vez por despliegue.

Qué necesitas antes de empezar

Un despliegue de contador de agua con ChirpStack tiene cuatro piezas. Tenlas preparadas antes del día de instalación y una visita lleva minutos en lugar de varias vueltas.

Una instancia de ChirpStack (v4). Autoalojada en tu propio servidor o gestionada. Esta guía asume ChirpStack v4, cuyo modelo de aplicación/dispositivo/perfil de dispositivo difiere del de la v3.
Un gateway LoRaWAN con un packet forwarder apuntando a tu instancia de ChirpStack (UDP de Semtech o el ChirpStack Gateway Bridge sobre MQTT).
Un contador de agua LoRaWAN con un payload documentado — de salida de pulsos, ultrasónico o un contador inteligente con conectividad integrada. Necesitas el DevEUI, el AppEUI/JoinEUI y la AppKey que proporciona el fabricante.
Un destino para los datos. Aquí es donde un portal white-label sustituye meses de desarrollo de panel a medida. Datakubo ingiere los webhooks de ChirpStack de forma nativa, así que apuntas ChirpStack a una única URL y los dispositivos aparecen automáticamente.

Paso 1: Da de alta tu gateway en ChirpStack

ChirpStack necesita conocer el gateway antes de aceptar uplinks desde él.

En la interfaz web de ChirpStack, abre Gateways → Add gateway.
Introduce un Nombre descriptivo y el Gateway ID (el EUI impreso en el dispositivo o reportado por su packet forwarder).
Selecciona la Región correcta para tu despliegue (por ejemplo EU868 en España y la mayor parte de Europa).
Guarda y confirma que el gateway muestra una marca de Last seen reciente. Si se queda vacío, el packet forwarder no está llegando a ChirpStack — revisa la dirección del servidor, el puerto y el firewall antes de continuar.

Un único gateway interior en el cuarto técnico de la comunidad suele cubrir toda una urbanización multi-edificio, así que este paso normalmente se hace una vez por ubicación.

Paso 2: Crea un perfil de dispositivo para el contador

Un perfil de dispositivo describe cómo se comporta una clase de dispositivos en la red — su versión de LoRaWAN, los parámetros regionales y, crucialmente, cómo decodificar su payload.

Ve a Device profiles → Add device profile.
Asigna el Nombre (p. ej. "Contador ultrasónico de agua — Fabricante X").
Elige la versión MAC de LoRaWAN y la revisión de parámetros regionales que coincidan con la hoja de datos del fabricante. Un desajuste aquí es la causa más habitual de que un dispositivo se una pero nunca envíe datos útiles.
Deja OTAA activado salvo que el fabricante exija ABP específicamente. OTAA es el valor por defecto más seguro para despliegues en campo.

Volverás a este perfil en el Paso 4 para añadir el codec.

Paso 3: Aprovisiona el contador de agua

Con un perfil listo, da de alta el contador físico.

Crea una Application (p. ej. "Monitorización de agua — Comunidad A") si aún no la tienes. Las aplicaciones son la forma de agrupar dispositivos, y encajan de forma natural con una Comunidad en tu portal.
Dentro de la aplicación, elige Add device.
Introduce el DevEUI del contador, asígnale el perfil de dispositivo del Paso 2 y dale un nombre claro (la ubicación física del contador es una buena convención — "Bloque B — riego").
En OTAA keys, introduce la AppKey suministrada por el fabricante.
Enciende el contador y observa la pestaña LoRaWAN frames del dispositivo. Una unión correcta muestra un JoinRequest seguido de un JoinAccept, y después uplinks al intervalo de reporte del contador (a menudo cada 12 horas en unidades alimentadas por batería).

Paso 4: Decodifica el payload

Los uplinks LoRaWAN en bruto llegan como arrays de bytes compactos. ChirpStack ejecuta un codec en JavaScript para convertir esos bytes en campos con nombre que tu portal puede graficar. La mayoría de fabricantes publican un decoder que puedes pegar; el fragmento siguiente muestra la forma de un decoder mínimo de volumen acumulado.

// Codec de ChirpStack v4 — ejemplo mínimo.
// Parte siempre del decoder publicado por el fabricante; esto solo
// ilustra la forma de salida esperada.
function decodeUplink(input) {
  const bytes = input.bytes;

  // Ejemplo: volumen acumulado de 4 bytes big-endian en litros.
  const litros =
    (bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3];

  return {
    data: {
      // Lectura acumulada en metros cúbicos — el campo que espera tu portal.
      cumulativeFlowM3: litros / 1000,
      battery: bytes[4], // opcional: indicador de batería
    },
  };
}

Pega el decoder en la sección Codec del perfil de dispositivo y guarda. Confirma en la pestaña Events del dispositivo que el siguiente uplink se decodifica en campos legibles. Producir un valor cumulativeFlowM3 es el camino más limpio, porque es el campo canónico que la capa de ingesta lee primero — pero la plataforma también normaliza automáticamente las alternativas habituales (litros, nombres específicos del fabricante), así que rara vez tienes que escribir un decoder desde cero.

Pantalla de integración HTTP de ChirpStack reenviando uplinks decodificados del contador de agua al webhook de un portal white-label

Paso 5: Reenvía los datos con una integración por webhook

Este es el paso que te ahorra construir software. Una integración por webhook le indica a ChirpStack que envíe cada uplink decodificado como una petición HTTP a una URL que tú controlas.

Abre tu Application → Integrations → HTTP.
Configura el Payload encoding en JSON.
En Event endpoint URL(s), pega la URL de ingesta de tu portal. Con Datakubo es un único endpoint de webhook que acepta el formato de eventos de ChirpStack directamente — sin capa de traducción, sin reescribir el decoder.
Guarda. El siguiente uplink se entrega a tu portal y el dispositivo se registra solo en la primera transmisión. No tienes que crear el dispositivo en dos sitios.

Como la plataforma normaliza el payload al llegar (prefiriendo cumulativeFlowM3 y convirtiendo litros a metros cúbicos cuando hace falta), el mismo webhook gestiona contadores de distintos fabricantes sin configuración por fabricante en tu lado.

Paso 6: Convierte las lecturas en un portal listo para el cliente

Una vez que los uplinks fluyen, la capa de plataforma hace el trabajo que de otro modo llevaría meses a un equipo de desarrollo:

Gráficas de consumo que un gestor de Comunidad sin perfil técnico lee de un vistazo — tendencias diarias y mensuales por contador, no recuentos de bytes en bruto.
Detección de anomalías configurable. El motor de alertas compara las lecturas de cada contador con los umbrales que tú defines. Los instaladores de agua suelen configurar reglas de caudal continuo para hacer aflorar una probable fuga, reglas de consumo nocturno para detectar un grifo abierto en una zona común vacía y reglas de desconexión para batería baja o pérdida de conectividad. El motor en sí es agnóstico al vertical — tú configuras las reglas para tu caso de uso.
Autoservicio del Residente. El gestor de la Comunidad invita a un Residente por correo electrónico; a partir de ahí, ese Residente ve únicamente su propio consumo de agua y las alertas de alarma. Ofrecer acceso al usuario final de esta forma es difícil de añadir a un stack IoT genérico, y aquí viene integrado.
Tu marca, tu dominio. El portal lleva tu logo y se ejecuta en tu dominio, de modo que cada gestor de Comunidad que accede ve tu producto — no una herramienta anónima.

Para ver el cuadro completo de cómo encaja la plataforma en el negocio de un instalador — soporte de hardware, gestión multi-cliente y precios — consulta la visión general de la plataforma de monitorización de contadores de agua.

Problemas habituales de configuración y cómo resolverlos

El dispositivo se une pero no aparecen datos en el portal. La unión funciona pero el webhook o el decoder no. Revisa primero la pestaña Events para ver los campos decodificados; si están vacíos, el problema es el codec. Si la decodificación es correcta, vuelve a comprobar la URL de la integración HTTP.

Los uplinks se decodifican con valores erróneos. Casi siempre es un desajuste de orden de bytes o de unidades en el decoder. Confirma el endianness y si el contador reporta litros o metros cúbicos, y deja que la normalización de la plataforma gestione la conversión de unidades.

El dispositivo nunca se une. Vuelve a comprobar el par DevEUI/AppKey contra la hoja del fabricante, confirma que la versión de LoRaWAN del perfil de dispositivo coincide con el hardware y verifica que el Last seen del gateway está al día.

Uplinks intermitentes. Normalmente es cobertura. Una visita previa antes de la instalación — confirmando que el gateway escucha al contador desde su ubicación final — evita vueltas innecesarias.

Por qué esta arquitectura funciona para los instaladores

El valor de combinar ChirpStack con una plataforma white-label es una separación limpia de responsabilidades. ChirpStack se ocupa de la red: gateways, sesiones de dispositivo y decodificación. La plataforma se ocupa de todo lo que toca el cliente: gráficas, alertas, acceso del Residente, marca y gestión multi-cliente de todo tu portfolio. Tú eres dueño de la relación y de los ingresos recurrentes.

No mantienes una base de datos, ni un servicio de alertas, ni un panel. Aprovisionas un contador, apuntas un webhook a una URL y las lecturas aparecen en un portal con tu marca que tus gestores de Comunidad ya entienden. Esa es la diferencia entre un proyecto que tienes que vigilar y un servicio que escala.

Cuando estés listo para conectar tus primeros contadores, parte de la visión general de la plataforma de monitorización de contadores de agua y aprovisiona una Comunidad en unos pocos clics.