Estructura de topics MQTT hogar inteligente: guía

Una buena estructura de topics MQTT para el hogar inteligente marca la diferencia entre automatizaciones que se entienden de un vistazo y una maraña de topics sensor1/temp2 que nadie recuerda. En esta guía obtendrás un esquema habitación/dispositivo/propiedad listo para usar, entenderás por qué los topics de comando y de estado deben estar separados y verás cómo encajan los retained messages, la disponibilidad y los comodines en un broker real.

Por qué el diseño de topics importa antes del décimo dispositivo

Con tres dispositivos, cualquier nomenclatura sirve. Cuando llegas a treinta, los nombres de los topics determinan lo fácil que es:

suscribirse a "todo lo de la cocina" o a "todas las temperaturas de la casa" con un único comodín,
añadir un dispositivo nuevo sin editar todas las automatizaciones,
saber si un mensaje es una petición o un hecho,
ver en un explorador de topics lo que está ocurriendo realmente.

MQTT no impone ninguna estructura. Los topics son simples cadenas UTF-8 separadas por /, y el broker compara las suscripciones con ellas. Esa libertad es precisamente la razón por la que necesitas una convención. Si los fundamentos de cómo enruta el broker estos mensajes son nuevos para ti, empieza por qué hace un broker MQTT.

El esquema recomendado: casa, habitación, dispositivo, propiedad

Un esquema que escala bien para la mayoría de las viviendas es:

<home>/<room>/<device>/<property>[/set]

Ejemplos:

home1/kitchen/ceiling-light/power            state: "ON" or "OFF" (retained)
home1/kitchen/ceiling-light/power/set        command: "ON", "OFF", "TOGGLE"
home1/kitchen/ceiling-light/brightness       state: 0-100 (retained)
home1/kitchen/ceiling-light/brightness/set   command: 0-100
home1/livingroom/climate/temperature         state: 21.6 (retained)
home1/livingroom/climate/humidity            state: 48 (retained)
home1/garage/door/state                      state: "open", "closed", "opening" (retained)
home1/garage/door/state/set                  command: "OPEN", "CLOSE"
home1/garage/door/availability               "online" or "offline" (retained, last will)

Por qué funciona este orden:

Nivel	Propósito	Ejemplo de comodín
`home`	Separa ubicaciones (casa, apartamento de vacaciones, casa de los padres)	`home1/#`
`room`	Coincide con cómo piensan y hablan las personas	`home1/kitchen/#`
`device`	Un dispositivo físico o lógico	`home1/+/climate/#`
`property`	Un valor o una capacidad	`home1/+/+/temperature`
Sufijo `set`	Marca un comando, no un hecho	`home1/+/+/+/set`

Mantén la profundidad en cinco niveles o menos. Los árboles profundos son más difíciles de escribir y, en cualquier caso, el servidor MQTT público gratuito limita los topics a ocho niveles, un techo razonable para una vivienda.

Topics de comando frente a topics de estado en una estructura de topics MQTT para el hogar inteligente

La regla más importante de todas: nunca uses el mismo topic para comandos y estado.

Si una luz escucha e informa en home1/kitchen/ceiling-light/power, un dashboard que publique ON verá su propio mensaje de vuelta, no podrá saber si la luz se ha encendido de verdad, y un comando ON retenido volverá a encender la luz cada vez que el dispositivo se reconecte, incluso después de que alguien la haya apagado en el interruptor de la pared.

Con topics separados el flujo es inequívoco:

El dashboard publica ON en .../power/set (sin retener).
El dispositivo conmuta el relé.
El dispositivo publica ON en .../power con el indicador retain.
Todos los suscriptores, incluido el dashboard, se actualizan a partir del topic de estado.

El topic de estado se convierte en la única fuente de verdad. Los comandos son peticiones que pueden fallar; los estados son hechos que confirma el dispositivo.

Retén el estado, nunca los comandos

Los retained messages permiten que un cliente recién conectado vea de inmediato el estado actual. Es exactamente lo que quieres para los estados y la disponibilidad, y exactamente lo que no quieres para los comandos. Un OPEN retenido en el topic de comandos de una puerta de garaje es una puerta que se abre sola después de cada corte de luz. Nuestro tutorial del abridor de puerta de garaje MQTT muestra este patrón en un proyecto donde equivocarse tiene consecuencias reales.

Elige el QoS según el tipo de topic

Los estados de los sensores van bien con QoS 0 o 1; una temperatura perdida se sustituye por la siguiente. Los comandos deberían usar QoS 1 para que se entreguen al menos una vez, y los dispositivos deberían tratar los comandos repetidos como idempotentes (ON dos veces sigue siendo encendido). Para conocer las ventajas e inconvenientes, consulta los niveles de QoS de MQTT explicados.

Disponibilidad y last will

Cada dispositivo debería publicar un topic availability. Fíjalo en online (retenido) tras conectarse y configura un mensaje de last will offline (retenido) en el mismo topic. Si el dispositivo pierde la alimentación o el Wi-Fi, el broker publica el will en su nombre, y los dashboards pueden mostrar el dispositivo atenuado en lugar de presentar un valor obsoleto como actual.

// ESP32 con PubSubClient: last will al conectar y después anunciar online
const char* AVAIL = "home1/garage/door/availability";
if (mqtt.connect(clientId, user, pass, AVAIL, 1, true, "offline")) {
  mqtt.publish(AVAIL, "online", true);
  mqtt.subscribe("home1/garage/door/state/set", 1);
}

Convenciones de payload

La estructura de topics y el formato del payload van de la mano. Elige un enfoque y úsalo en todas partes:

Un valor por topic (.../temperature = 21.6) es sencillo, funciona con cualquier herramienta y hace que los comodines sean muy potentes.
JSON por dispositivo (.../climate = {"temperature":21.6,"humidity":48}) reduce el número de mensajes y mantiene coherentes los valores relacionados.

Muchas viviendas usan ambos: JSON para dispositivos multisensor de Zigbee2MQTT o ESPHome y valores sueltos para los dispositivos caseros. Si usas JSON, documenta las claves e incluye las unidades en el nombre de la clave (temp_c) o en una nota del esquema. Evita mezclar 21.6, "21.6" y "21.6 C" entre dispositivos.

Reglas de nomenclatura que ahorran disgustos

Usa minúsculas y nombres separados por guiones: ceiling-light, no Ceiling Light.
Sin espacios, sin # ni + en los nombres y sin / inicial (crea un primer nivel vacío).
Nombra las habitaciones como lo hacen las personas, pero evita nombres que cambien (toms-room resulta incómodo cuando Tom se va de casa; bedroom-2 perdura).
Nombra los dispositivos por su función, no por marca o modelo, para poder sustituir el hardware sin renombrar.
Reserva un prefijo de nivel superior para los topics del sistema, como home1/system/backup-status.
Nunca pongas secretos, códigos de puerta ni datos personales en los nombres de topic; los topics son visibles para cualquier suscriptor con comodines que coincidan.

Integrar los topics de otros ecosistemas

No controlarás todos los nombres de topic. Zigbee2MQTT publica bajo zigbee2mqtt/<friendly_name>, Tasmota usa los prefijos stat/, tele/ y cmnd/, y el descubrimiento de Home Assistant usa homeassistant/<component>/<id>/config. No luches contra estas convenciones. En su lugar:

Da a los dispositivos nombres descriptivos que sigan tu patrón habitación/dispositivo, por ejemplo kitchen/ceiling-light en Zigbee2MQTT, de modo que sus topics pasen a ser zigbee2mqtt/kitchen/ceiling-light.
Mantén tus propios dispositivos caseros bajo tu raíz home1/.
Deja que Home Assistant convierta todo en entidades mediante el descubrimiento MQTT.

Nuestra guía de configuración de Zigbee2MQTT muestra cómo los nombres descriptivos se traducen en topics.

Prueba el esquema en un broker público

Puedes probar la estructura sin hardware. Usa un prefijo aleatorio para que tus topics no choquen con los de nadie más:

# Terminal 1: observa toda la casa
mosquitto_sub -h broker.connectmq.com -p 1883 -i watch-h7q2 -t "connectmq/demo/h7q2/home1/#" -v

# Terminal 2: una luz informa de su estado retenido y luego un dashboard envía un comando
mosquitto_pub -h broker.connectmq.com -p 1883 -i light-h7q2 -r -q 1 \
  -t connectmq/demo/h7q2/home1/kitchen/ceiling-light/power -m ON
mosquitto_pub -h broker.connectmq.com -p 1883 -i dash-h7q2 -q 1 \
  -t connectmq/demo/h7q2/home1/kitchen/ceiling-light/power/set -m OFF

# Todas las temperaturas de la casa, cualquier habitación, cualquier dispositivo
mosquitto_sub -h broker.connectmq.com -p 1883 -i temps-h7q2 -t "connectmq/demo/h7q2/home1/+/+/temperature" -v

El prefijo de la demo añade tres niveles, otro motivo más para mantener poco profundo tu propio árbol. El área pública es legible por todo el mundo, así que úsala solo para experimentar con la estructura y prototipos, no para los datos de tu vivienda real. Cuando pases a un broker privado puedes eliminar el prefijo de la demo y empezar en home1/.

Checklist de la estructura de topics del hogar inteligente

Cada dispositivo sigue <home>/<room>/<device>/<property>.
Los comandos usan el sufijo /set y nunca se retienen.
Los estados se retienen y los publica el dispositivo después de actuar.
Cada dispositivo tiene un topic availability con last will.
Los nombres están en minúsculas, con guiones y basados en la función.
El formato de payload está documentado y es coherente.
La profundidad de los topics se mantiene en cinco niveles o menos.

Tu hogar en un broker privado

Una estructura de topics solo se mantiene limpia si el broker en el que vive es seguro y fiable. ConnectMQ ofrece un broker MQTT gestionado con TLS en el puerto 8883, credenciales generadas y un explorador de topics en vivo en el que tu árbol de habitaciones y dispositivos es fácil de recorrer. Si estás decidiendo entre alojarlo tú mismo o usar un broker MQTT en la nube, piensa en el acceso remoto, los certificados y las actualizaciones. Para más proyectos de hogar y edificios, consulta la guía de automatización IoT. En edificios inteligentes, el mismo esquema habitación/dispositivo/propiedad se traduce de forma directa a un gemelo digital 3D que muestra cada estancia con su estado en vivo.

Empieza con ConnectMQ

Crea un broker Serverless gratuito en app.connectmq.com, sin tarjeta de crédito, copia tus credenciales generadas y publica tus primeros topics home1/. El explorador de topics en vivo de ConnectMQ muestra toda tu casa como un árbol en cuestión de segundos.

Preguntas frecuentes

¿Deben empezar los topics con una barra?

No. Una barra inicial crea un primer nivel vacío, lo cual es válido pero confuso y fácil de escribir mal. Empieza con el nombre de tu vivienda o ubicación.

¿Es mejor usar un topic JSON por dispositivo o un topic por valor?

Ambos funcionan. Un valor por topic es lo más sencillo para comodines y dispositivos caseros; JSON por dispositivo encaja con dispositivos multisensor. Elige uno por tipo de dispositivo y documéntalo.

¿Por qué se enciende sola mi luz después de un reinicio?

Probablemente retuviste un mensaje de comando. Bórralo publicando un mensaje retenido vacío en el topic de comandos y, a partir de ahora, retén solo los topics de estado.

¿Cuántos niveles de topic debería usar un hogar inteligente?

Cuatro o cinco son más que suficientes: casa, habitación, dispositivo, propiedad y un sufijo set opcional. Los árboles más profundos añaden escritura y poco valor.

Estructura de topics MQTT para el hogar inteligente: buenas prácticas para habitaciones, dispositivos y comandos