Homebridge MQTT: lleva tus dispositivos MQTT a la app Casa de Apple

La integración Homebridge MQTT te permite controlar sensores, relés y luces caseros desde la app Casa de Apple y con Siri, aunque HomeKit no sepa nada de MQTT. En este tutorial instalarás el plugin mqttthing, asignarás topics a características de HomeKit para un sensor de temperatura, un interruptor, una luz regulable y un sensor de contacto, gestionarás payloads JSON y llevarás la configuración a un broker privado con TLS.

Cómo habla Homebridge con MQTT

Homebridge es un servidor Node.js que emula accesorios HomeKit. Los plugins aportan la lógica real de los dispositivos. El plugin MQTT más usado, homebridge-mqttthing, te permite declarar un accesorio en JSON y asignar cada característica de HomeKit a un topic MQTT: un topic get al que Homebridge se suscribe para obtener el valor actual, y un topic set en el que publica cuando tocas un icono o se lo pides a Siri.

 Apple Home / Siri
        |
   (HomeKit, LAN)
        |
    Homebridge  --  homebridge-mqttthing
        |
   (MQTT over TLS)
        |
   MQTT broker  <-->  ESP32, Tasmota, Zigbee2MQTT, scripts

Como los dispositivos solo hablan con el broker, pueden estar en otra red u otra ubicación. Homebridge solo necesita acceso de salida al broker. Si antes quieres conocer el contexto de este patrón, el artículo sobre qué hace un broker MQTT explica la publicación y la suscripción con palabras sencillas.

Instalar el plugin mqttthing

Si usas la Homebridge UI (la opción por defecto en las imágenes oficiales), abre Plugins, busca mqttthing e instala Homebridge Mqttthing. Desde la línea de comandos en un host de Homebridge:

sudo npm install -g homebridge-mqttthing
sudo hb-service restart

Los accesorios se definen en el array accessories de config.json. La UI incluye un editor basado en formularios para el plugin, pero el JSON en bruto es más claro para aprender, así que los ejemplos siguientes lo usan. Puedes pegarlos en Config > JSON Config.

Un primer accesorio Homebridge MQTT: sensor de temperatura

Empieza con el servidor MQTT público gratuito para ver todo lo que ocurre; úsalo solo para pruebas, nunca para datos reales. Elige una cadena aleatoria (aquí h3m8x2) para mantener tus topics separados dentro del área pública compartida.

{
  "accessory": "mqttthing",
  "type": "temperatureSensor",
  "name": "Greenhouse Temperature",
  "url": "mqtt://broker.connectmq.com:1883",
  "mqttOptions": { "clientId": "hb-gh-temp-h3m8x2" },
  "topics": {
    "getCurrentTemperature": "connectmq/demo/h3m8x2/greenhouse/temperature"
  },
  "logMqtt": true
}

Guarda, reinicia Homebridge y publica una lectura:

mosquitto_pub -h broker.connectmq.com -p 1883 -i sim-h3m8x2 \
  -t 'connectmq/demo/h3m8x2/greenhouse/temperature' -m '23.5' -r

El icono de la app Casa se actualiza en menos de un segundo. El flag -r hace que el mensaje sea retenido, de modo que tras reiniciar Homebridge el último valor se entrega de inmediato en lugar de que el icono muestre "Sin respuesta" hasta la siguiente lectura.

Interruptores y luces con comandos

Los accesorios controlables necesitan un topic get y otro set. Usar topics separados para los comandos y para el estado confirmado es una buena práctica: Homebridge publica la petición, el dispositivo actúa y el dispositivo publica de vuelta su estado real.

{
  "accessory": "mqttthing",
  "type": "switch",
  "name": "Vent Fan",
  "url": "mqtt://broker.connectmq.com:1883",
  "mqttOptions": { "clientId": "hb-fan-h3m8x2" },
  "topics": {
    "getOn": "connectmq/demo/h3m8x2/greenhouse/fan/state",
    "setOn": "connectmq/demo/h3m8x2/greenhouse/fan/set"
  },
  "onValue": "ON",
  "offValue": "OFF"
}

Una luz regulable añade la característica de brillo:

{
  "accessory": "mqttthing",
  "type": "lightbulb",
  "name": "Grow Light",
  "url": "mqtt://broker.connectmq.com:1883",
  "mqttOptions": { "clientId": "hb-light-h3m8x2" },
  "topics": {
    "getOn": "connectmq/demo/h3m8x2/greenhouse/light/state",
    "setOn": "connectmq/demo/h3m8x2/greenhouse/light/set",
    "getBrightness": "connectmq/demo/h3m8x2/greenhouse/light/brightness",
    "setBrightness": "connectmq/demo/h3m8x2/greenhouse/light/brightness/set"
  },
  "onValue": "ON",
  "offValue": "OFF"
}

Observa lo que envía Homebridge mientras tocas los iconos:

mosquitto_sub -h broker.connectmq.com -p 1883 -i mon-h3m8x2 \
  -t 'connectmq/demo/h3m8x2/greenhouse/#' -v

Gestionar payloads JSON

Muchos dispositivos publican un único documento JSON con varios valores en lugar de un topic por valor. mqttthing acepta un objeto de topic con una función apply, un breve cuerpo de JavaScript que recibe message y devuelve el valor que se usará.

{
  "accessory": "mqttthing",
  "type": "contactSensor",
  "name": "Greenhouse Door",
  "url": "mqtt://broker.connectmq.com:1883",
  "mqttOptions": { "clientId": "hb-door-h3m8x2" },
  "topics": {
    "getContactSensorState": {
      "topic": "connectmq/demo/h3m8x2/greenhouse/telemetry",
      "apply": "return JSON.parse(message).door === 'open' ? 1 : 0;"
    }
  }
}

El sensor de contacto de HomeKit usa 0 para detectado (cerrado) y 1 para no detectado (abierto); por eso la función asigna open a 1. La misma técnica funciona en los topics set para envolver un comando en JSON, por ejemplo "apply": "return JSON.stringify({state: message});".

Correspondencia de los tipos de dispositivo habituales

El plugin admite muchos más tipos, como puertas de garaje, termostatos, ventiladores y persianas. Cada uno tiene sus propios nombres de características; el README del plugin los enumera todos.

Número de conexiones y client IDs

Cada accesorio de mqttthing abre su propia conexión MQTT. Diez accesorios significan, por tanto, diez clientes en el broker, cada uno con un client ID único. De ello se derivan dos consecuencias:

1. Da a cada accesorio su propio clientId en mqttOptions. Los IDs duplicados hacen que el broker desconecte la sesión anterior, y los accesorios parpadean entre responder y no responder.
2. Cuenta las conexiones frente a tu plan. El plan gratuito Serverless de ConnectMQ permite hasta 25 conexiones simultáneas, suficiente para Homebridge y un número moderado de dispositivos. Las instalaciones más grandes encajan en el plan Serverless de pago, con hasta 1.000.

Si necesitas muchos accesorios sobre una sola conexión, plantéate que Home Assistant o Node-RED gestionen la conexión con el broker y expongan HomeKit a través de sus propios bridges HomeKit.

Producción: TLS y credenciales

Todo lo que hay en el área pública de pruebas lo puede leer cualquiera que adivine el topic, y alguien podría incluso publicar en tus topics set. Antes de controlar equipos reales, crea un broker privado y pasa todos los accesorios a TLS:

{
  "accessory": "mqttthing",
  "type": "switch",
  "name": "Vent Fan",
  "url": "mqtts://broker.connectmq.com:8883",
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD",
  "mqttOptions": { "clientId": "YOUR_CLIENT_ID" },
  "topics": {
    "getOn": "site1/greenhouse/fan/state",
    "setOn": "site1/greenhouse/fan/set"
  },
  "onValue": "ON",
  "offValue": "OFF"
}

Node.js confía de serie en la cadena de Let's Encrypt que usa ConnectMQ, así que no necesitas ningún archivo de CA. En ConnectMQ, los client IDs están vinculados a las credenciales emitidas en el portal, de modo que cuando necesites varias conexiones, emite un juego de credenciales por grupo de accesorios y lleva un registro de qué ID corresponde a cada uno.

Ejecutar mqttthing como child bridge

Homebridge puede ejecutar un plugin como child bridge: un proceso independiente con su propio emparejamiento HomeKit. Activarlo para mqttthing (en los ajustes del plugin, Bridge Settings) tiene dos ventajas prácticas. Un fallo o una definición de accesorio defectuosa ya no tumba todos los demás plugins, y reiniciar el child bridge tras editar topics es más rápido que reiniciar todo Homebridge. Emparejas el child bridge una sola vez en la app Casa y los accesorios que añadas después aparecen automáticamente.

También merece la pena que cada dispositivo publique un topic de disponibilidad retenido con un last will offline. mqttthing puede usarlo mediante el topic getOnline junto con onlineValue y offlineValue, de modo que la app Casa muestra un dispositivo como sin respuesta cuando realmente está desconectado, en lugar de enseñar un valor obsoleto.

Resolución de problemas de Homebridge MQTT

• El accesorio muestra Sin respuesta. No ha llegado ningún valor al topic get desde que se inició Homebridge. Publica el estado retenido desde los dispositivos, o busca erratas en el topic con logMqtt: true.
• El icono vuelve solo a su estado anterior. El dispositivo no publica su nuevo estado en el topic get, o publica un valor que no coincide con onValue.
• Mensajes constantes de reconexión en el log. Client IDs duplicados o credenciales erróneas. Busca Connection refused y el motivo en el log de Homebridge.
• Siri dice que el dispositivo no responde, pero la app funciona. Suele ser un problema del hub de HomeKit (Apple TV o HomePod) más que de MQTT; comprueba que el hub llega a Homebridge en la LAN.

Próximos pasos

Homebridge te resuelve la parte de Apple; los dispositivos siguen necesitando publicar topics sensatos. La guía de ESPHome MQTT muestra cómo crear sensores que publican su estado y aceptan comandos, y el artículo sobre estructura de topics MQTT para el hogar inteligente te ayuda a diseñar topics que sigan siendo manejables. Si Home Assistant funciona junto a Homebridge, consulta Home Assistant con un broker MQTT externo. Para el contexto general de cómo combinar dispositivos y lógica, lee la guía de automatización IoT, y para entender por qué un broker MQTT gestionado supera a un broker en la Raspberry Pi de Homebridge para el acceso remoto, compara allí las opciones.

Conecta Homebridge a ConnectMQ

ConnectMQ da a Homebridge un broker MQTT gestionado privado, protegido con TLS y accesible desde cualquier red, con un explorador de topics en vivo para depurar tus accesorios mientras los configuras. Crea un broker Serverless gratuito en app.connectmq.com, sin tarjeta de crédito, y pega las credenciales generadas en tus accesorios de mqttthing.

Preguntas frecuentes

¿HomeKit admite MQTT de forma nativa?

No. HomeKit usa su propio protocolo de accesorios, así que necesitas un bridge como Homebridge con un plugin MQTT que traduzca entre ambos.

¿Puedo controlar los dispositivos Homebridge MQTT cuando estoy fuera de casa?

Sí, a través de un hub de HomeKit, como siempre. Como los dispositivos hablan con un broker en la nube, pueden estar incluso en una ubicación distinta a la de Homebridge.

¿Por qué mis sensores muestran Sin respuesta tras un reinicio?

Homebridge todavía no ha recibido ningún valor. Publica los mensajes de estado con el flag retain para que el broker entregue el último valor en cuanto Homebridge se suscriba.

¿mqttthing es el único plugin MQTT para Homebridge?

No, pero es el más general. Otros plugins se centran en ecosistemas concretos, como Zigbee2MQTT o Tasmota, y pueden ser más sencillos si solo usas esos dispositivos.