> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-es/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md).
# 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:**
6. 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.
7. Vuelve a abrir el registro del dispositivo. El **Clave del conector** desplegable ahora enumera las claves recibidas del dispositivo.
8. Asocia una clave del payload a cada fila de Mapeo.
9. 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](https://www.zigbee2mqtt.io/supported-devices/) 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](/kilo-docs-es/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md) — 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](/kilo-docs-es/kilo-iot-server/gateways/mqtt-edge-gateways.md) — patrones para puentes industriales productores de MQTT que alimentan esta canalización de enrutamiento (bajo Puertas de enlace).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-es/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
