Conector MQTT

Integra dispositivos compatibles con MQTT en Kilo IoT — Cloud MQTT (broker aprovisionado por la plataforma) o External MQTT (tu puente).

El conector MQTT te permite incorporar cualquier dispositivo compatible con MQTT al Kilo IoT Server sin pasar por LoRaWAN. PLCs de fábrica, controladores HVAC, medidores de energía de edificios, pasarelas edge que producen MQTT (puentes Modbus-a-MQTT, BACnet-a-MQTT, OPC-UA-a-MQTT) y sensores con firmware personalizado que ya publican datos por MQTT pueden conectarse directamente. Una vez conectados, sus datos fluyen por la misma canalización de normalización, activan el mismo motor de reglas y aparecen en los mismos paneles que cualquier otro dispositivo del servidor.

Hay dos variantes disponibles:

Variante	Cómo se proporciona el broker	Límite	Lo mejor para
MQTT externo	Tu propio broker — alojado en la nube, en local o en una red de instalaciones, siempre que la plataforma pueda الوصول إليه	Hasta 10 por organización	Conectar infraestructura existente que ya publica a MQTT
Cloud MQTT	Proporcionado por la plataforma — el servidor ofrece un punto final de broker dedicado y credenciales por conector	Ilimitado	Nuevas implementaciones, pilotos y sitios remotos donde quieres ingesta MQTT sin operar tú mismo la infraestructura del broker

Usa MQTT externo cuando ya tengas un broker en funcionamiento. Usa MQTT en la nube cuando quieras que la plataforma proporcione uno: tú le das un nombre al conector y la plataforma aprovisiona el resto.

Alcance. Esta documentación cubre la ingesta de telemetría MQTT y el mapeo de dispositivos. El envío de comandos en sentido contrario — controlar un dispositivo conectado con downlinks — se configura por dispositivo en Comandos del dispositivo.

En esta sección

• Qué es MQTT — Introducción al protocolo para ingenieros nuevos en MQTT o para refrescar el modelo.

• Cloud MQTT — Aprovisionar un broker gestionado por la plataforma para un conector.

• MQTT externo — Conectar un broker existente, incluida la accesibilidad de red, la autenticación y la verificación.

• Tópicos y enrutamiento de dispositivos — Cómo trabajan juntos los patrones de tópico, la extracción del ID de dispositivo y la pestaña Mapping. Léelo antes de registrar dispositivos.

• Solución de problemas — Diagnosticar problemas de conexión, coincidencia de tópicos y de la pestaña Logs.

Para la parte de hardware/pasarela edge de la integración — puentes Modbus, BACnet, OPC-UA, Sparkplug B y Zigbee2MQTT que publican MQTT en el conector — consulta Pasarelas edge MQTT en Gateways.

---

Añadir un conector MQTT externo

1. Vaya a Conectores en la barra lateral.

2. Haz clic en Añadir conector.

3. Selecciona MQTT externo desde el tipo de conector menú desplegable.

4. Rellena el formulario de configuración:

   Campo	Obligatorio	Detalles
   Nombre	Sí	Nombre visible de este conector
   URL del broker	Sí	URL completa con esquema y puerto. El broker debe ser accesible por red desde la plataforma — un broker accesible solo en una red local aislada no se conectará. Esquemas aceptados: mqtt://, mqtts://, tcp://, ssl://. Ejemplo: mqtts://broker.facility.example.com:8883

5. Elige un método de autenticación de las pestañas:

   Método	Qué rellenar
   Anónimo	No se requieren credenciales
   Básica	Nombre de usuario y contraseña (la contraseña tiene un conmutador mostrar/ocultar)
   Certificado	Tres botones de carga de archivos: Certificado CA, Certificado de cliente, Clave privada. Sube cada archivo — no pegues contenido PEM
   Token JWT	Campo de token (mostrar/ocultar + copiar). El token es la credencial JWT requerida. En el formulario aparece un campo de carga de certificado — es opcional; la plataforma envía solo el token para la autenticación JWT

6. Haz clic en Añade.

El conector aparece en la tabla de conectores. Haz clic en su fila para abrir la página de detalle del conector.

---

Añadir un conector MQTT en la nube

1. Vaya a Conectores en la barra lateral.

2. Haz clic en Añadir conector.

3. Selecciona Cloud MQTT desde el tipo de conector menú desplegable.

4. Introduce un Nombre para el conector.

5. Haz clic en Añade.

La plataforma aprovisiona un punto final de broker dedicado y muestra las credenciales generadas:

Credencial	Detalles
URL del broker	El punto final MQTT gestionado. Cópialo usando el botón de copiar.
Prefijo del tema	Todos los mensajes publicados en este conector deben usar este prefijo. Mantiene tus datos organizados bajo el espacio de nombres asignado al conector. Cópialo usando el botón de copiar.
Nombre de usuario	Asignado automáticamente. Cópialo usando el botón de copiar.
Contraseña	Se muestra una sola vez. Cópialo inmediatamente. Si se pierde, rota las credenciales desde la configuración del conector — los dispositivos deberán reconfigurarse con la nueva contraseña. En modo edición, hay disponible un botón de regenerar.

Conectar dispositivos a MQTT en la nube

Configura tus dispositivos o el software de la pasarela para publicar en el punto final proporcionado. Detalles clave antes de conectar:

• La URL del broker es el punto final completo — cópiala exactamente como se muestra. Usa MQTTS (TLS) en el puerto 1884. Configura tus dispositivos en consecuencia; este no es el puerto estándar 1883.

• Todos los tópicos publicados deben comenzar con el prefijo del tópico. El tópico completo al que publica tu dispositivo es {Prefijo del tópico}/{tópico del dispositivo} — por ejemplo, si el prefijo es iot/abc123/xyz789 y tu dispositivo publica lecturas de potencia, podrías publicar en iot/abc123/xyz789/EM-4492/power.

• Las plantillas de enrutamiento en el dispositivo no incluyen el prefijo. Al configurar el Device ID Topic en la pestaña Topic, introduce solo la parte de nivel de dispositivo — por ejemplo {{deviceId}}/power. La plataforma elimina el prefijo antes de enrutar.

No se requiere infraestructura de broker de tu parte — la plataforma gestiona el broker.

---

Registrar un dispositivo en MQTT

Cada dispositivo que publica a través de un conector MQTT debe registrarse individualmente. El registro asigna la estructura de tópicos MQTT y el formato de carga útil al modelo de dispositivo del servidor.

1. Desde la página de detalle del conector, haz clic en Añadir dispositivo — o navega a Dispositivos → Registro de dispositivos y selecciona este conector.

2. Completa los campos estándar del dispositivo (nombre, conector, plantilla).

Device ID = segmento del tópico, byte por byte. Lo que sea que introduzcas como identificador del dispositivo debe coincidir exactamente con el segmento del tópico a nivel de dispositivo que publica tu hardware. El campo Device ID elimina los espacios en blanco, por lo que identificadores como EM 4492 no coincidirán silenciosamente con un dispositivo que publica en EM-4492. Usa exactamente la misma cadena en el registro del dispositivo y en el lado que publica; la capitalización se conserva y es significativa.

1. El dispositivo se abre con una pestaña Mapping . Dentro de Mapping hay dos subpestañas: Topic (donde la plataforma aprende cómo encontrar el dispositivo en el flujo de tópicos) y Mapping (donde asignas las claves de la carga útil a métricas normalizadas). Seleccionar Mapping abre primero la subpestaña Topic ; haz clic en Siguiente o en la etiqueta interna Mapping para llegar a las filas por clave.

Pestaña Topic

La pestaña Topic le indica al conector dónde encontrar el identificador del dispositivo en cada mensaje MQTT y qué tópicos transportan datos de telemetría.

Device ID Topic (obligatorio)

El patrón de tópico MQTT al que publica este dispositivo. Usa {{deviceId}} para marcar el segmento del tópico que contiene el identificador del dispositivo.

Ejemplo: Si tu medidor de energía publica en facility/meters/EM-4492/power, introduce:

facility/meters/{{deviceId}}/power

El servidor extrae EM-4492 de ese segmento y enruta todos los mensajes coincidentes al Digital Twin de este dispositivo.

Dónde obtener el ID del dispositivo

• Topic (predeterminado) — El ID se extrae del segmento {{deviceId}} del tópico.

• Carga útil — El ID se toma de un campo dentro de la carga útil JSON. Cuando se selecciona, el campo Ruta de carga útil del Device ID se vuelve obligatorio.

Ruta de carga útil del Device ID (se muestra cuando la fuente = Carga útil)

Una ruta con notación de puntos hacia el campo del ID del dispositivo dentro de la carga útil JSON.

Ejemplo: Para una carga útil {"device": {"id": "EM-4492"}, "power": 4.2}, introduce:

device.id

Tópicos de telemetría (opcional)

Las filas de tópico de telemetría definen cómo se extraen las mediciones individuales de los mensajes MQTT. Son opcionales.

Para dispositivos que publican una carga útil JSON plana en un solo tópico — como sistemas de gestión de edificios o PLCs que publican un objeto de estado — puedes omitir esta sección por completo. El servidor analiza automáticamente todas las claves de la carga útil JSON, incluidos los objetos anidados, que se aplanan en rutas con notación de puntos (por ejemplo, {"device": {"temperature": 22.5}} se vuelve accesible como device.temperature). La pestaña Mapping sigue siendo necesaria — cada clave de carga útil necesita una fila correspondiente con una Connector Key coincidente para convertirse en una métrica normalizada de la plataforma. Añade filas de tópico de telemetría solo cuando necesites un control explícito por tópico: por ejemplo, cuando los valores de la métrica están incrustados en la ruta del tópico en lugar de en la carga útil, o cuando quieras renombrar métricas específicas.

Campo	Detalles
Tópico MQTT para telemetría	Patrón de tópico para esta fila de métrica, usando {{deviceId}} placeholder
Connector Key	Nombra la clave de origen que llega desde MQTT. Esta clave debe coincidir con lo que publica el dispositivo. La Connector Key no crea por sí sola una métrica de la plataforma — la pestaña Mapping es donde se vincula a una métrica normalizada.

Añadir nuevo tópico — añade una fila de tópico de telemetría.

Aplicar todo — usa el patrón de tópico de ID de dispositivo como prefijo para generar plantillas de tópico de telemetría para las filas que ya tienen rellenada una Connector Key. Genera patrones por tópico basados en el tópico de ID de dispositivo — no copia literalmente el valor del tópico de ID de dispositivo.

Referencia de placeholders

Placeholder	Dónde se usa	Qué hace
{{deviceId}}	Device ID Topic, plantillas de tópico de telemetría	Marca el segmento del tópico que contiene el identificador del dispositivo
{{value}}	Plantillas de tópico de telemetría	Marca un segmento del tópico cuyo contenido es el propio valor de la medición — por ejemplo, meters/EM-4492/230.5 dónde 230.5 es la lectura. No uses {{value}} para segmentos de tópico que nombran la métrica (como potencia o voltaje) — si el segmento es una etiqueta en lugar de un valor, usa en su lugar el enfoque estilo carga útil

---

Pestaña Mapping

La pestaña Mapping vincula los datos MQTT entrantes con métricas normalizadas de la plataforma. Aquí es donde los valores brutos del dispositivo se convierten en datos de sensores consultables en el Digital Twin.

La Connector Key en la pestaña Mapping debe coincidir con la clave publicada en el mensaje MQTT (o la Connector Key definida en la pestaña Topic). Sin coincidencia, los datos se ignoran silenciosamente — el texto de ayuda encima de la tabla lo confirma: "Si el campo Connector key no está rellenado, los datos serán ignorados."

La tabla tiene 8 columnas:

Columna	Tipo	Detalles
Clave normalizada	Desplegable	Selecciona entre plantillas de sensores; incluye una opción "+ Añadir nueva métrica"
Unidad	Solo lectura	Derivada de la plantilla seleccionada
Tipo	Solo lectura	Entero, Flotante, Cadena o Booleano — derivado de la plantilla
Tipo de datos	Desplegable	Estado informado, Telemetría o Metadatos del dispositivo
Clave del conector	Desplegable	Enumera las claves recibidas de la carga útil de este dispositivo. Vacío hasta que llegue al menos una publicación
Valor	Solo lectura	Valor vivo actual recibido del broker
Última actualización	Solo lectura	Marca temporal del valor recibido más recientemente
Acciones	Icono	El icono de papelera elimina la fila

Añadir clave — añade una nueva fila de mapeo vacía.

Estado informado vs Telemetría

El Tipo de datos el desplegable distingue dos categorías operativas:

• Estado informado — propiedades controlables del dispositivo cuyo valor actual publica el dispositivo. El punto de ajuste de un controlador HVAC, el estado de encendido/apagado de un actuador inteligente, el estado abierto/cerrado de una válvula. Son valores que el dispositivo también puede recibir órdenes para cambiar.

• Telemetría — mediciones de solo lectura. Sondas de temperatura, lecturas de medidores de energía, valores RMS de vibración, calidad del enlace. Son observaciones que el dispositivo hace sobre sí mismo o su entorno.

Elige el tipo que se ajuste a la intención operativa del valor. Estado informado es apropiado para campos de máquina de estados y puntos de ajuste configurables; Telemetría es apropiado para lecturas de sensores y diagnósticos.

El desplegable Connector Key está vacío hasta que el dispositivo publique una vez

El Clave del conector la columna es un desplegable poblado con claves de carga útil realmente recibidas del dispositivo — no es un campo de texto libre. Antes de que llegue la primera publicación, el desplegable está vacío y las filas no se pueden completar.

Por tanto, registrar un dispositivo MQTT es un flujo de trabajo en dos pasos:

1. Añade una fila por métrica, selecciona la Clave normalizada del desplegable de plantillas (o usa + Añadir nueva métrica para crear una), establece la Tipo de datosy deja la Clave del conector vacía.

2. Haz clic en Guardar. Se guarda el registro del dispositivo.

3. Confirma que el dispositivo está publicando — para una pasarela edge que produce MQTT, que el proceso de la pasarela esté en ejecución y que el dispositivo haya emitido al menos un mensaje.

4. Vuelve a abrir el dispositivo. El desplegable Clave del conector ahora lista las claves recibidas en las publicaciones más recientes.

5. Asocia una clave a cada fila de mapeo.

6. Haz clic en Guardar de nuevo.

Columna Value de la pestaña Mapping vs historial de la pestaña Logs

La columna Valor de la pestaña Mapping refleja la carga útil más reciente — una instantánea en vivo. Los valores aparecen aquí en cuanto la coincidencia de tópicos tiene éxito, incluso antes de que se rellenen las Connector keys.

El Registros la pestaña es el historial por sensor. Solo se rellena con publicaciones que llegan después de que se guarden las Connector keys. Después de la segunda pasada del flujo de trabajo anterior, genera una nueva publicación (un despertar por evento del dispositivo, un informe programado o, para pasarelas de desarrollo, una solicitud de sondeo) para confirmar que la pestaña Logs está recibiendo registros.

El mapeo es iterativo: vuelve a revisarlo cuando lleguen datos

El mapeo MQTT no es una operación de una sola vez. El registro inicial suele basarse en la expectativa del operador sobre lo que el dispositivo o la pasarela edge publicarán; la primera carga útil real suele revelar claves adicionales — campos de diagnóstico definidos por el proveedor, campos de estado no documentados, objetos anidados con subrutas útiles. Considera la pestaña Mapping como un lugar al que volver:

1. Después de que los datos en vivo hayan estado llegando durante un período representativo, vuelve a abrir el registro del dispositivo.

2. Inspecciona el Clave del conector desplegable y la Valor columna para ver qué está publicando realmente el dispositivo.

3. Añade filas de Mapping para los campos que la implementación quiera seguir ahora (un campo de diagnóstico para mantenimiento predictivo, un campo de estado que se volvió relevante operativamente, una submétrica anidada de vibración, etc.).

4. Elige la Clave normalizada y el Tipo de datos adecuados para cada nueva fila.

5. Guarda.

6. Dispara una nueva publicación para que la pestaña Logs empiece a recopilar historial de las nuevas asignaciones.

Este refinamiento iterativo es el flujo de trabajo esperado, especialmente para flotas mixtas de varios proveedores donde los esquemas de carga útil varían sutilmente entre revisiones de firmware de dispositivos nominalmente idénticos.

Traducción de tipo de carga útil → tipo de métrica

Cuando un dispositivo publica un estado enumerado como cadena (por ejemplo, un actuador publicando "OPEN"/"CLOSED"o un campo state de Zigbee con "ON"/"OFF"), el valor llega como una cadena, aunque el tipo conceptual sea binario. Asigna estos al Cadena Tipo en la plantilla de métrica, no a Booleano. Seleccionar Booleano para una enumeración codificada como cadena dará como resultado valores nulos.

Para dispositivos puenteados con Zigbee2MQTT específicamente, las páginas de dispositivos de zigbee2mqtt.io enumeran cada característica con un tipo — traduce de la siguiente manera:

Tipo de característica Z2M	Tipo de métrica	Notas
binary	Cadena	Los valores son "ON"/"OFF" cadenas, no booleanos
numeric	Número	Rangos numéricos asignados directamente
enum	Cadena	Los valores enumerados llegan como cadenas
texto	Cadena	Texto libre

Cómo descubrir qué claves publica un dispositivo

La pestaña Mapping no detecta las claves automáticamente. Tres métodos de descubrimiento, en orden de practicidad:

1. La documentación del dispositivo o la ficha técnica del proveedor. Los dispositivos industriales suelen venir con un esquema de carga útil o un catálogo de tópicos.

2. Para dispositivos puenteados con Zigbee2MQTT, la página del dispositivo en https://www.zigbee2mqtt.io/devices/{modelId}.html enumera el conjunto Exposes. Ten en cuenta que las cargas útiles reales pueden incluir claves que no están en la página del dispositivo — confía en la carga útil en vivo por encima de la documentación cuando difieran.

3. Suscríbete al broker e inspecciona la carga útil en vivo — mosquitto_sub en el broker (o en la pestaña Logs una vez que se resuelva al menos una fila de mapeo) muestra directamente la carga útil JSON. Cada clave de nivel superior es una Connector Key válida.

---

Resultados esperados

Después de que el conector esté configurado y los dispositivos registrados:

• La fila del conector en la Conectores página muestra Último dato recibido actualizándose a medida que llegan los mensajes.

• El Dispositivos conectados el conteo refleja los dispositivos registrados.

• El Digital Twin de cada dispositivo se actualiza con la telemetría entrante — visible en la página de detalle del dispositivo y en los paneles.

• Las condiciones del motor de reglas que hacen referencia a estas métricas del dispositivo se evalúan en tiempo real.

---

Solución de problemas

Una breve lista — consulta Solución de problemas para recetas de diagnóstico que cubren fallos de autenticación, desajustes de certificados, el patrón de pestaña Logs vacía y herramientas de verificación.

No llegan datos después de la conexión:

• Para MQTT externo: verifica el esquema de la URL del broker (mqtt://, mqtts://, tcp://, o ssl://), confirma que el broker sea accesible desde Internet pública (Kilo IoT Server se conecta hacia tu broker) y vuelve a comprobar las credenciales.

• Para TLS (autenticación con certificado): verifica que el certificado CA coincida con la cadena de certificados del broker y que el certificado de cliente y la clave privada formen un par coincidente.

• Para MQTT en la nube: confirma que tus dispositivos estén publicando en la URL del Broker y en el prefijo del tópico correctos, y que el nombre de usuario y la contraseña sean correctos. Si se perdió la contraseña, rótala desde la configuración del conector.

El dispositivo está registrado pero no aparecen datos:

• Compara el Device ID Topic registrado con el tópico exacto al que publica el dispositivo. Los tópicos distinguen mayúsculas y minúsculas y deben coincidir exactamente.

• Confirma que el {{deviceId}} posicionamiento del placeholder

• se alinea con el segmento real del ID del dispositivo en el tópico.

• Confirma que el campo Device ID sea idéntico byte por byte al segmento a nivel de dispositivo — los espacios en blanco se eliminan en la entrada y rompen la coincidencia.

Columna Value de la pestaña Mapping actualiza pero la pestaña Logs está vacía: Este es el patrón más común cuando las Connector keys se guardan después de que llegó la publicación más reciente. La pestaña Logs solo se rellena con publicaciones recibidas después Se guardan las Connector keys. Dispara una nueva publicación — un despertar del dispositivo, un informe programado o un /get sondeo para pasarelas de desarrollo — y la pestaña Logs se rellenará.

Valores de métrica faltantes o mostrando claves incorrectas:

• Comprueba que la Connector Key en la pestaña Mapping coincida exactamente con la clave en la carga útil MQTT (distingue mayúsculas y minúsculas).

• Si dependes del análisis automático de JSON (sin tópicos de telemetría definidos): la plataforma aplana toda la carga útil JSON, incluidos los objetos anidados, en claves con notación de puntos — por ejemplo, {"device": {"temperature": 22.5}} se vuelve accesible como device.temperature. Usa estas rutas con notación de puntos en la columna Connector Key de la pestaña Mapping.

Contraseña de MQTT en la nube perdida: La contraseña no se puede recuperar después de su creación. Rota las credenciales desde la configuración del conector y reconfigura los dispositivos con la nueva contraseña.

Fallo al guardar el dispositivo en un conector MQTT en la nube: Si falla el guardado de un dispositivo en un conector MQTT en la nube, contacta con soporte. Soporte puede ayudar a completar el registro mediante la ruta compatible asistida por API.

---

Ejemplos operativos

PLC de fábrica — telemetría por tópico: Un PLC publica mediciones discretas en tópicos MQTT separados en un broker de planta (mqtts://plc-broker.plant.example.com:8883). Conector MQTT externo, autenticación con nombre de usuario/contraseña. Device ID Topic: plant/line-a/{{deviceId}}/data. Una fila de tópico de telemetría por cada medición (cycle_time, reject_count, temperature). Cada fila se asigna a una métrica normalizada de la plataforma en la pestaña Mapping.

Sistema HVAC de edificio — carga útil JSON plana: Un sistema de gestión de edificios publica un objeto de estado JSON por dispositivo en un solo tópico. La carga útil es JSON plano, por lo que no se necesitan filas de tópico de telemetría — todas las claves se analizan automáticamente. El ID del dispositivo está en el segmento del tópico. La pestaña Mapping asigna cada clave JSON a la métrica normalizada adecuada.

Nueva implementación en sitio — MQTT en la nube: Un sitio remoto de instalaciones necesita ingesta MQTT pero el equipo no quiere operar un broker. Se crea un conector MQTT en la nube; la plataforma aprovisiona un punto final de broker. Los medidores de energía y los sensores ambientales se configuran para publicar en el punto final y prefijo de tópico proporcionados. Sin infraestructura de broker que gestionar — la plataforma se encarga.

Sistema de submedición de energía: Los medidores de energía publican lecturas individuales (kWh, kW, voltaje, corriente) en tópicos separados. Las filas de tópico de telemetría asignan cada tópico a una Connector Key con nombre. La pestaña Mapping vincula cada Connector Key con métricas normalizadas de la plataforma. Todas las lecturas se agregan en un solo Digital Twin del dispositivo.

---

Qué sigue

• Registro de dispositivos — Completar el registro del dispositivo y la configuración del Digital Twin.

• Conectores — Resumen de todos los tipos de conectores.