Tutorial del binding MQTT de openHAB: bridge de broker, things genéricos y reglas

El binding MQTT de openHAB convierte cualquier topic MQTT en canales que puedes vincular a items, mostrar en dashboards y usar en reglas. En este tutorial conectarás openHAB a un broker externo, definirás things MQTT genéricos para un sensor y un interruptor, interpretarás payloads JSON, publicarás comandos desde reglas y reforzarás la configuración con TLS y credenciales.

Cómo se organiza el binding MQTT de openHAB

openHAB modela MQTT en dos capas. El bridge de broker (mqtt:broker) es la conexión: host, puerto, TLS, client ID y credenciales. Debajo se sitúan los things, cada uno de los cuales describe un dispositivo por sus topics. El tipo de thing más flexible es el thing MQTT genérico (mqtt:topic), en el que declaras cada canal y los topics de estado y de comandos que usa. Después, los items se vinculan a esos canales exactamente igual que con cualquier otro binding.

Un único bridge de broker puede dar servicio a cientos de things y usa una sola conexión MQTT. Eso importa en planes con cuota de conexiones: openHAB cuenta como un cliente, por muchos dispositivos que modele.

Instala el binding desde Settings > Add-on Store > Bindings > MQTT Binding. Si tus dispositivos envían JSON, instala también JSONPath Transformation en la sección de transformaciones.

Conectar openHAB a un broker MQTT

Puedes crear el bridge en la UI (Things > + > MQTT Binding > MQTT Broker) o en un archivo .things. La configuración en texto es más fácil de compartir y respaldar, así que este tutorial la usa. Crea conf/things/mqtt.things:

Bridge mqtt:broker:connectmq "ConnectMQ Broker" [
    host="broker.connectmq.com",
    port=1883,
    secure=false,
    clientID="openhab-r4t8w1",
    lwtTopic="connectmq/demo/r4t8w1/openhab/status",
    lwtMessage="offline",
    lwtRetain=true,
    birthTopic="connectmq/demo/r4t8w1/openhab/status",
    birthMessage="online",
    birthRetain=true
] {
    Thing topic greenhouse "Greenhouse Sensor" {
    Channels:
        Type number : temperature "Temperature" [
            stateTopic="connectmq/demo/r4t8w1/greenhouse/telemetry",
            transformationPattern="JSONPATH:$.temp",
            unit="°C"
        ]
        Type number : humidity "Humidity" [
            stateTopic="connectmq/demo/r4t8w1/greenhouse/telemetry",
            transformationPattern="JSONPATH:$.hum",
            unit="%"
        ]
        Type switch : fan "Vent Fan" [
            stateTopic="connectmq/demo/r4t8w1/greenhouse/fan/state",
            commandTopic="connectmq/demo/r4t8w1/greenhouse/fan/set",
            on="ON",
            off="OFF"
        ]
        Type contact : door "Door" [
            stateTopic="connectmq/demo/r4t8w1/greenhouse/door",
            on="OPEN",
            off="CLOSED"
        ]
    }
}

Esto se conecta de forma anónima al servidor MQTT público gratuito, pensado solo para pruebas. Sustituye r4t8w1 por tu propia cadena aleatoria, porque el área pública es compartida y cualquiera puede leerla. El client ID no puede estar vacío y debe ser único; reutilizar uno que ya tiene otro cliente hará que ambas conexiones se caigan una y otra vez.

Revisa Settings > Things: el bridge debería pasar a ONLINE en pocos segundos, seguido del thing del invernadero.

Vincular items

Crea conf/items/greenhouse.items:

Number:Temperature GH_Temperature "Temperature [%.1f °C]" <temperature> { channel="mqtt:topic:connectmq:greenhouse:temperature" }
Number:Dimensionless GH_Humidity "Humidity [%.0f %%]" <humidity> { channel="mqtt:topic:connectmq:greenhouse:humidity" }
Switch GH_Fan "Vent Fan" <fan> { channel="mqtt:topic:connectmq:greenhouse:fan" }
Contact GH_Door "Door [%s]" <door> { channel="mqtt:topic:connectmq:greenhouse:door" }

Fíjate en el patrón del UID del canal: mqtt:topic:<bridge id>:<thing id>:<channel id>. Una errata ahí es el motivo más habitual de que un item se quede en NULL.

Probar los canales MQTT de openHAB

Simula el dispositivo desde un terminal:

# lectura del sensor (JSON interpretado por JSONPath)
mosquitto_pub -h broker.connectmq.com -p 1883 -i sim-r4t8w1 \
  -t 'connectmq/demo/r4t8w1/greenhouse/telemetry' -m '{"temp":24.6,"hum":71}'

# contacto de la puerta
mosquitto_pub -h broker.connectmq.com -p 1883 -i sim-r4t8w1 \
  -t 'connectmq/demo/r4t8w1/greenhouse/door' -m 'OPEN'

# observar los comandos que envía openHAB
mosquitto_sub -h broker.connectmq.com -p 1883 -i mon-r4t8w1 \
  -t 'connectmq/demo/r4t8w1/greenhouse/fan/set' -v

Activa o desactiva el ventilador en la UI de openHAB y el comando ON u OFF aparecerá en la ventana del suscriptor. Un dispositivo real actuaría en consecuencia y publicaría su nuevo estado en fan/state, que openHAB usa para actualizar el item. Mantener separados los topics de comandos y de estado hace que la UI muestre el estado confirmado y no solo el último clic.

Interpretar JSON y formatear comandos

La mayoría de los dispositivos modernos publican JSON. Además de transformationPattern para los valores entrantes, el thing genérico admite formatBeforePublish para los salientes. Por ejemplo, un regulador que espera {"brightness": 40}:

Type dimmer : lamp "Grow Lamp" [
    stateTopic="connectmq/demo/r4t8w1/greenhouse/lamp/state",
    commandTopic="connectmq/demo/r4t8w1/greenhouse/lamp/set",
    transformationPattern="JSONPATH:$.brightness",
    formatBeforePublish="{\"brightness\": %s}",
    min=0,
    max=100
]

Las transformaciones se pueden encadenar con el carácter ∩ en el patrón si necesitas varios pasos, por ejemplo JSONPath seguido de una búsqueda MAP. Mantén las cadenas cortas; cuando la lógica crece, una regla es más fácil de depurar.

Publicar mensajes MQTT desde reglas de openHAB

Los comandos vinculados a canales cubren la mayoría de las necesidades, pero a veces quieres publicar en un topic arbitrario, por ejemplo para enviar un horario a un controlador. El bridge de broker expone para ello la acción publishMQTT. En un archivo de reglas DSL conf/rules/greenhouse.rules:

rule "Greenhouse overheat"
when
    Item GH_Temperature changed
then
    val temp = (GH_Temperature.state as QuantityType<Number>).toUnit("°C").doubleValue
    if (temp > 30.0 && GH_Fan.state != ON) {
        GH_Fan.sendCommand(ON)
        val mqtt = getActions("mqtt", "mqtt:broker:connectmq")
        mqtt.publishMQTT("connectmq/demo/r4t8w1/greenhouse/event",
            "{\"event\":\"overheat\",\"temp\":" + temp + "}", false)
    }
end

La misma acción está disponible desde reglas en JavaScript mediante actions.get("mqtt", "mqtt:broker:connectmq"). Evita publicar en el mismo topic al que se suscribe un canal, salvo que quieras crear un bucle.

Disparar reglas desde topics sin modelar

Si solo quieres reaccionar a un mensaje sin modelar un item, añade un canal de disparo al bridge:

Bridge mqtt:broker:connectmq "ConnectMQ Broker" [ ... ] {
    Channels:
        Type publishTrigger : alarms "Alarms" [
            stateTopic="connectmq/demo/r4t8w1/+/alarm",
            separator="#"
        ]
}

Una regla disparada por Channel "mqtt:broker:connectmq:alarms" triggered recibe el topic y el payload unidos por el separador, así que una sola regla puede gestionar las alarmas de todos los dispositivos.

Configuración de producción con TLS y credenciales

Antes de conectar dispositivos reales, sal del área pública de pruebas. Crea un broker privado y actualiza el bridge:

Bridge mqtt:broker:connectmq "ConnectMQ Broker" [
    host="broker.connectmq.com",
    port=8883,
    secure=true,
    certificatepin=false,
    publickeypin=false,
    clientID="YOUR_CLIENT_ID",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
    lwtTopic="site1/openhab/status",
    lwtMessage="offline",
    lwtRetain=true
]

El certificado de ConnectMQ lo emite Let's Encrypt, en el que Java confía por defecto, así que no hace falta importar ningún certificado adicional. El certificate pinning se desactiva explícitamente porque los certificados de Let's Encrypt se renuevan cada pocos meses; un certificado fijado haría que el bridge rechazara el broker tras la siguiente renovación. Usa el client ID exactamente como se emitió, ya que está vinculado a las credenciales. Para blindar todo el sistema, lee las buenas prácticas de seguridad MQTT.

Si prefieres ejecutar tu broker en local dentro de la red de openHAB, puedes hacer un bridge con la nube más adelante, pero un broker MQTT gestionado elimina la necesidad de mantener un host de broker aparte y permite que las ubicaciones remotas y los móviles lleguen a los mismos topics.

Mostrar la disponibilidad de los dispositivos

Un thing genérico sigue ONLINE mientras el bridge esté conectado, aunque el dispositivo que hay detrás se quedara sin alimentación hace horas. Para hacerlo visible, haz que cada dispositivo publique un mensaje online retenido al conectarse y define un last will offline retenido. Después, añade los ajustes de disponibilidad al thing:

Thing topic greenhouse "Greenhouse Sensor" [
    availabilityTopic="connectmq/demo/r4t8w1/greenhouse/status",
    payloadAvailable="online",
    payloadNotAvailable="offline"
] {
    // canales como antes
}

Cuando el dispositivo se desconecta, el broker publica su will, openHAB marca el thing como OFFLINE y los items vinculados pasan a UNDEF. Así, las reglas y los dashboards pueden distinguir entre "el sensor marca 0" y "el sensor ha desaparecido", algo muy importante para todo lo que controla calefacción, riego o alarmas.

Lista de comprobación para resolver problemas

1. El bridge se queda en OFFLINE. Comprueba host y puerto, y que secure=true solo se use con el puerto 8883. Busca el código de motivo en openhab.log.
2. El bridge alterna entre ONLINE y OFFLINE. Client ID duplicado; otra instancia de openHAB o una herramienta de pruebas usa el mismo.
3. Thing ONLINE pero item en NULL. UID de canal incorrecto en el item, una errata en el topic o falta el complemento JSONPath. Usa log:set DEBUG org.openhab.binding.mqtt en la consola para ver cada mensaje recibido.
4. El interruptor muestra UNDEF. El payload no coincide exactamente con on u off; los valores distinguen mayúsculas y minúsculas.
5. Los comandos no hacen nada. Asegúrate de que el dispositivo escucha en el topic de comandos y de que no estás publicando en su topic de estado.

Dónde encaja openHAB en un sistema más amplio

openHAB es un consumidor más del broker, no el dueño de los datos. Los nodos ESPHome, los enchufes Tasmota y Zigbee2MQTT pueden publicar todos en el mismo broker, y otras herramientas pueden leer los mismos topics. El tutorial de ESPHome MQTT muestra cómo publicar desde dispositivos configurados en YAML, y Tasmota MQTT trata los enchufes inteligentes flasheados. Para la visión arquitectónica general, consulta la guía de automatización IoT. Y si todavía estás comparando brokers, la introducción al broker MQTT en la nube explica las ventajas e inconvenientes.

Ejecuta openHAB sobre un broker de ConnectMQ

ConnectMQ ofrece un broker privado MQTT 3.1.1 y 5.0 con TLS, credenciales generadas y un explorador de topics en vivo que facilita la depuración de los canales de openHAB. Crea un broker Serverless gratuito en app.connectmq.com sin tarjeta de crédito, pega las credenciales en tu bridge y tus things de openHAB estarán en línea.

Preguntas frecuentes

¿openHAB incluye su propio broker MQTT?

No. Las versiones actuales de openHAB solo incluyen el binding cliente, así que necesitas un broker externo, como una instancia local de Mosquitto o un broker en la nube como ConnectMQ.

¿Puede openHAB usar MQTT 5?

El bridge de broker tiene un parámetro mqttVersion que se puede poner en V5. La versión 3.1.1 sigue siendo la predeterminada y funciona con casi todos los dispositivos.

¿Cuántas conexiones MQTT usa openHAB?

Una por bridge de broker, independientemente de cuántos things genéricos cuelguen de él. Eso lo hace eficiente en planes con límite de conexiones.

¿Por qué mis items se actualizan pero no se envían los comandos?

Probablemente el canal no tiene commandTopic, o el item está vinculado en modo solo lectura. Añade un topic de comandos y confirma con un suscriptor que el mensaje se publica.