Topics y enrutamiento de dispositivos

Estructura de topics MQTT y enrutamiento por Device ID en Kilo IoT — marcadores de posición de patrones, pestañas Mapping/Topic y guardado en dos pasos.

Esta página cubre cómo el servidor Kilo IoT resuelve un mensaje MQTT entrante hacia un Gemelo Digital específico: la estructura de los tópicos entrantes, la Tópico de ID del dispositivo semántica del patrón del campo, las subpestañas internas Mapeo/Tópico, la coincidencia byte por byte entre la entrada del ID del dispositivo y el segmento del tópico a nivel de dispositivo, y el flujo de guardado en dos pasos que requiere la pestaña Mapeo. Lee esto antes de registrar dispositivos MQTT en implementaciones de producción — la mayoría de los tickets de soporte de "dispositivo registrado pero sin telemetría" se resuelven con uno de los patrones documentados aquí.

Forma del tópico después del procesamiento del lado del broker

El broker de la plataforma expone los mensajes MQTT entrantes con un prefijo con ámbito de conector. Para Cloud MQTT, el prefijo es el prefijo de tópico del conector (iot/{org}/{connection}). Para External MQTT, el puente saliente de la plataforma vuelve a publicar los mensajes entrantes de tu broker en un espacio de nombres interno; se preserva la forma del tópico a nivel de dispositivo.

Después de eliminar internamente el prefijo, el tópico visto para el enrutamiento del dispositivo es el segmento a nivel de dispositivo:

Cloud MQTT:    plant-3/line-a/EM-4492/data         (después de eliminar el prefijo)
External MQTT: plant-3/line-a/EM-4492/data         (después de eliminar el espacio de nombres del puente)

El campo Tópico de ID del dispositivo describe solo esta forma a nivel de dispositivo. El manejo del prefijo del conector es interno a la plataforma; el operador no lo configura.

Construcción del Tópico de ID del dispositivo

Tópico MQTT para el ID del dispositivo en la pestaña Conexión del dispositivo no es un cuadro de texto libre — es un generador de segmentos. El prefijo de tópico del conector ya está en su lugar y bloqueado, y agregas un segmento a la vez con el + botón. Cada segmento es de uno de dos tipos:

Segmento	Qué hace
Segmento de texto	Una parte literal del tópico, escrita tal cual — metros, line-a, SENSOR. Coincide exactamente con el tópico entrante.
ID del dispositivo	Marca el segmento cuyo valor es es el identificador del dispositivo. Se requiere exactamente uno, y el valor encontrado en esa posición se compara con el ID del dispositivo campo anterior.

Una Vista previa resuelta debajo del generador muestra el tópico completo que el patrón produce para este dispositivo, para que puedas compararlo con lo que realmente envía tu publicador antes de guardar. Arrastra la ficha ID del dispositivo para moverla a otra posición.

De dónde obtener el ID del dispositivo junto al generador decide de dónde se lee el identificador — Tópico (la posición que marcaste) es la opción habitual.

Ejemplos de formas de tópico y los segmentos que agregar después del prefijo:

Tópico de publicación	Segmentos
plant-3/line-a/EM-4492/data	plant-3 · line-a · ID del dispositivo · data
tasmota/PlugKitchen/SENSOR	tasmota · ID del dispositivo · SENSOR
zigbee2mqtt/LivingRoomSensor	zigbee2mqtt · ID del dispositivo
home/sensors/esp-kitchen/data	home · sensors · ID del dispositivo · data

Para formas de tópico industriales anidadas como Sparkplug B (spBv1.0/{group}/DDATA/{node}/{device}), agrega el contexto jerárquico como segmentos de texto y coloca el ID del dispositivo en el segmento que identifica de forma única el registro del dispositivo que se está registrando.

La entrada del ID del dispositivo debe coincidir byte por byte con el segmento extraído

El campo ID del dispositivo en el registro del dispositivo almacena el identificador canónico que la plataforma busca en el segmento ID del dispositivo. La coincidencia es byte por byte: distingue mayúsculas y minúsculas, distingue espacios en blanco y distingue unicode.

Un patrón que atrapa frecuentemente a los integradores: la entrada del ID del dispositivo elimina los espacios en blanco al guardar. Un dispositivo que publica en plant-3/line-a/EM 4492/data (con un espacio en el ID del dispositivo) no coincidirá con un ID del dispositivo escrito como EM 4492 — la entrada se normaliza a EM4492 (o se recorta parcialmente; no se garantiza el comportamiento exacto). La discrepancia es silenciosa — no aparece ningún error al guardar y no aparece ningún error cuando llega la telemetría. La pestaña Mapeo simplemente permanece vacía.

La recomendación en implementaciones de producción: evita por completo los espacios en blanco en los identificadores de dispositivo. Usa guiones (EM-4492), guiones bajos (EM_4492), o sin separador (EM4492). Elijas lo que elijas, el lado de publicación y el campo ID del dispositivo deben producir exactamente la misma cadena.

La pestaña Mapeo tiene dos subpestañas

Cuando abres la pestaña Mapeo de un dispositivo, la interfaz muestra una pestaña externa etiquetada Mapeo que contiene dos subpestañas: Tópico y Mapeo. Al seleccionar la pestaña externa, se abre la Tópico subpestaña de forma predeterminada.

• Subpestaña Tópico — Tópico de ID del dispositivo, De dónde obtener el ID del dispositivo, Ruta del payload del ID del dispositivo (cuando la fuente es Payload), Tópicos de telemetría (definiciones de métricas por tópico para esquemas de publicación de una métrica por tópico).

• Subpestaña Mapeo — filas de clave del conector que vinculan las claves del payload con las métricas normalizadas.

Un dispositivo registrado sin visitar la subpestaña interna Mapeo tiene configuración de Tópico pero no asignaciones de métricas — así que aunque la coincidencia de tópicos tenga éxito y Últimos datos recibidos se actualice, el registro del dispositivo no contiene telemetría. Haz clic Después en la parte inferior de la subpestaña Tópico o haz clic en la Mapeo etiqueta interna para llegar a las filas por clave.

Tópicos de telemetría: cuándo configurarlos

La Tópicos de telemetría Las filas de la subpestaña Tópico son para esquemas de publicación en los que cada métrica tiene su propio tópico MQTT — por ejemplo, un puente PLC que publica potencia en meters/{deviceId}/power, voltaje en meters/{deviceId}/voltage, corriente en meters/{deviceId}/current, cada una con un único valor numérico como payload.

Para esquemas modernos de publicación JSON plano — Zigbee2MQTT, Tasmota con un objeto SENSOR, firmware personalizado que emite un objeto de estado JSON — no se necesitan filas de Tópicos de telemetría. La plataforma analiza automáticamente cada clave en el payload JSON y las expone como candidatas de Clave del conector. Los objetos anidados se aplanan a rutas con notación de puntos ({"vibration": {"rms": 0.42}} se convierte en vibration.rms).

Configura filas de Tópicos de telemetría solo cuando realmente tengas una publicación de un tópico por métrica o cuando quieras anular el analizador automático para una forma de tópico específica.

Desplegable de clave del conector: el flujo de guardado en dos pasos

La Clave del conector columna es un desplegable. Las opciones del desplegable se obtienen de las claves del payload realmente recibidas del dispositivo — no de una entrada de texto libre.

Para un dispositivo nuevo sin tráfico histórico, el desplegable está vacío. La plataforma todavía no sabe qué envía el dispositivo, así que no tiene nada con lo que rellenar las opciones. Esto es intencional, pero significa que el flujo de registro es en dos pasos:

Paso 1:

1. Agrega una fila de Mapeo por cada métrica que produzca el dispositivo.

2. Selecciona el Clave normalizada del desplegable de plantillas. Usa + Agregar nueva métrica para crear una nueva plantilla de sensor si es necesario. (El modal se encarga de crear tanto el nombre normalizado como la plantilla de sensor — crear previamente nombres desde la pestaña Métricas es opcional.)

3. para la métrica. Tipo de dato (Estado informado, Telemetría o Metadatos del dispositivo — ver abajo).

4. Deja Clave del conector vacío.

5. Guarda el registro del dispositivo.

Paso 2:

1. Confirma que el dispositivo está publicando — para un dispositivo puenteado por Z2M, que el puente esté en ejecución y que el dispositivo haya informado al menos una vez. Para un puente PLC, que el proceso del puente esté publicando datos.

2. Vuelve a abrir el registro del dispositivo. El Clave del conector desplegable ahora enumera las claves recibidas del dispositivo.

3. Asocia una clave del payload a cada fila de Mapeo.

4. Guarda de nuevo.

Las publicaciones posteriores de las claves asignadas fluyen a la pestaña Registros.

Estado informado vs Telemetría vs Metadatos del dispositivo

La Tipo de dato el desplegable clasifica cada métrica:

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

• Telemetría — mediciones de solo lectura. Variables de proceso, lecturas de medidores de energía, valores RMS de vibración, calidad del enlace, mediciones ambientales. El dispositivo observa; no cambia estas.

• Metadatos del dispositivo — valores que describen al propio dispositivo en lugar de su estado operativo. Versión del firmware, modelo de hardware, número de serie, fecha de calibración.

Elige el tipo que coincida con la intención operativa. Estado informado es apropiado para campos de máquina de estados y puntos de ajuste configurables; Telemetría es apropiada para lecturas de sensores y diagnósticos; Metadatos del dispositivo es apropiado para campos estáticos de identidad del dispositivo.

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

El tipo de la plantilla de métrica (Integer, Float, String, Boolean) viene fijado por la plantilla elegida para la clave normalizada. Haz coincidir el tipo de la plantilla con los datos que realmente envía el dispositivo:

• Enumeraciones codificadas como cadena y estados binarios — valores como "OPEN"/"CLOSED", "ON"/"OFF", "running"/"stopped" llegan como cadenas JSON. Asigna un Type String. No selecciones Boolean — dará como resultado valores null. String Type. No selecciones Boolean — dará como resultado valores null.

• Escalares numéricos — Integer o Float, según si el dispositivo produce decimales.

• Texto libre — String.

Para dispositivos puenteados por Zigbee2MQTT, las zigbee2mqtt.io las páginas de dispositivos enumeran cada característica con un tipo — traduce así:

Tipo de característica Z2M	Tipo de métrica	Ejemplo
binario	String	estado ("ON"/"OFF")
numérico	Número	brillo, calidad del enlace
enum	String	comportamiento al encender, modo de color
texto	String	Campos de texto libre

Pestaña Mapeo: columna Valor vs historial de la pestaña Registros

Después del Paso 2 del flujo de guardado:

• La Valor la columna de la pestaña Mapeo se actualiza con el payload más reciente — una instantánea en vivo. Los valores aparecen tan pronto como la coincidencia de tópicos tiene éxito, incluso antes de que todas las claves del conector se hayan poblado.

• La Registros la pestaña es el historial por sensor. Solo se completa con las publicaciones que llegan después después de que las claves del conector se guardan. Las publicaciones anteriores no se normalizan retroactivamente.

Operativamente: después de completar el Paso 2, genera una publicación nueva (un evento de activación del dispositivo, un informe programado, una solicitud de sondeo desde el puente) para confirmar que la pestaña Registros está recibiendo registros. Si el dispositivo solo informa según un horario o cuando cambia de estado, planifica la validación en torno a ese ritmo.

Refinamiento iterativo del mapeo

El mapeo inicial rara vez cubre todos los campos útiles que expone un dispositivo. Los operadores suelen descubrir después del despliegue que el dispositivo publica claves adicionales — campos de diagnóstico del proveedor, valores de estado no documentados, subobjetos anidados con rutas relevantes para la operación. El patrón recomendado es volver a visitar la pestaña Mapeo después de que los datos hayan estado llegando durante un período representativo:

• Inspecciona el Clave del conector desplegable y la Valor columna para ver exactamente qué está publicando el dispositivo en producción.

• Agrega nuevas filas de Mapeo para los campos que ahora la implementación quiere en el Gemelo Digital.

• Establece la Clave normalizada y el tipo de datos apropiados por fila.

• Guarda.

• Genera una publicación nueva para que la pestaña Registros comience a registrar el historial de los campos recién asignados.

Para flotas de dispositivos nominalmente idénticos, realiza este refinamiento en una muestra representativa antes de desplegar los cambios de mapeo al resto de la flota — las revisiones de firmware pueden introducir diferencias sutiles en las claves.

A dónde ir después

• Solución de problemas — recetas de diagnóstico para fallos de coincidencia de tópicos y el patrón de pestaña Registros vacía.

• Puertas de enlace MQTT Edge — patrones para puentes industriales productores de MQTT que alimentan esta canalización de enrutamiento (bajo Puertas de enlace).