Tutorial del binding MQTT de openHAB: broker, Things y canales

El binding MQTT de openHAB conecta openHAB con cualquier broker MQTT en dos capas: un Thing broker (un bridge que mantiene la conexión: host, puerto, TLS, credenciales) y uno o varios Generic MQTT Things debajo, cuyos canales asignan topics concretos a Items de openHAB. Instala el binding, añade el broker, añade un Thing con un canal por valor, enlaza los Items, y cada mensaje en esos topics actualizará tus Items, mientras que los comandos de la interfaz o de las reglas se publican de vuelta.

Este tutorial recorre tanto la configuración por interfaz como por archivos de texto, muestra cómo procesar payloads JSON y cómo verificar cada salto desde la línea de comandos.

Requisitos previos

• openHAB 4.x o posterior con el MQTT Binding instalado (Settings → Add-on Store → Bindings → MQTT).
• El add-on JSONPath Transformation si tus dispositivos envían JSON (la mayoría lo hace).
• Un broker. openHAB no incluye ninguno, así que ejecuta Mosquitto en local o usa un broker alojado. Los ejemplos usan broker.connectmq.com con TLS en el puerto 8883 y topics de prueba bajo testmqtt/openhab/....

Paso 1: el Thing bridge del broker

En la interfaz ve a Settings → Things → + → MQTT Binding → MQTT Broker y rellena:

Deja desactivado el pinning de certificado y de clave pública cuando tu broker use un certificado público que se renueva automáticamente: el pinning guarda el primer certificado que ve y falla cuando el broker lo rota. Si necesitas depurar la parte TLS, consulta cómo probar una conexión TLS.

El Thing broker debería pasar a ONLINE en pocos segundos. Si muestra OFFLINE - COMMUNICATION_ERROR, el detalle de estado contiene el motivo, normalmente un desajuste puerto/TLS o credenciales incorrectas.

También puedes configurar un Last Will (lwtTopic, lwtMessage), además de mensajes de nacimiento y de apagado, para que otros sistemas sepan si openHAB está conectado; es útil cuando un dashboard o Node-RED dependen de él.

Paso 2: un Generic MQTT Thing y sus canales

Añade un Generic MQTT Thing, elige el broker como bridge y añade canales en la pestaña Channels. Cada canal tiene un tipo y, como mínimo, un state topic:

Los parámetros de canal importantes:

• State Topic: openHAB se suscribe aquí y actualiza el Item.
• Command Topic: openHAB publica aquí cuando el Item recibe un comando. Usa un topic distinto del state topic (por ejemplo .../set); si no, tus propios comandos vuelven como actualizaciones de estado.
• Incoming Value Transformations: por ejemplo JSONPATH:$.temperature.
• Outgoing Value Format: una cadena de formato como %s o {"state":"%s"} para envolver los comandos en JSON.
• Retained: publica los comandos como mensajes retenidos; lee mensajes retenidos antes de activarlo.
• Custom On/Open Value y Custom Off/Closed Value: asignan payloads del dispositivo como 1/0 o true/false.
• Is Command (postCommand): trata los valores entrantes como comandos en lugar de actualizaciones de estado, para que disparen otros bindings y reglas.

La misma configuración en archivos de texto

Para tenerlo en control de versiones, define el broker y los Things en un archivo .things:

Bridge mqtt:broker:connectmq "ConnectMQ broker" [
    host="broker.connectmq.com", port=8883, secure=true,
    certificatepin=false, publickeypin=false,
    protocol="TCP", mqttVersion="V5",
    clientID="openhab-home", username="username", password="password",
    keepAlive=60, qos=1
] {
    Thing topic livingroom "Living room" [
        availabilityTopic="testmqtt/openhab/livingroom/status",
        payloadAvailable="online", payloadNotAvailable="offline"
    ] {
        Channels:
            Type number : temperature "Temperature" [
                stateTopic="testmqtt/openhab/livingroom/sensor",
                transformationPattern="JSONPATH:$.temperature", unit="°C" ]
            Type number : humidity "Humidity" [
                stateTopic="testmqtt/openhab/livingroom/sensor",
                transformationPattern="JSONPATH:$.humidity", unit="%" ]
            Type switch : lamp "Lamp" [
                stateTopic="testmqtt/openhab/livingroom/lamp/state",
                commandTopic="testmqtt/openhab/livingroom/lamp/set",
                on="ON", off="OFF" ]
            Type trigger : button "Wall button" [
                stateTopic="testmqtt/openhab/livingroom/button" ]
    }
}

El UID del canal es mqtt:topic:connectmq:livingroom:<canal>. Enlaza los Items con él:

Number:Temperature   LivingRoom_Temperature "Temperature [%.1f %unit%]" { channel="mqtt:topic:connectmq:livingroom:temperature" }
Number:Dimensionless LivingRoom_Humidity    "Humidity [%.0f %%]"        { channel="mqtt:topic:connectmq:livingroom:humidity" }
Switch               LivingRoom_Lamp        "Lamp"                      { channel="mqtt:topic:connectmq:livingroom:lamp" }

Dos canales comparten un state topic y extraen campos JSON distintos: el patrón habitual para dispositivos multisensor. El availabilityTopic marca el Thing como OFFLINE cuando se dispara el Last Will del dispositivo.

Publicar desde reglas

El Thing broker expone una acción publishMQTT, práctica para notificaciones o para hablar con dispositivos que no tienen Thing:

rule "Publish lamp changes as an event"
when
    Item LivingRoom_Lamp changed
then
    val mqtt = getActions("mqtt", "mqtt:broker:connectmq")
    mqtt.publishMQTT("testmqtt/openhab/events/lamp", newState.toString, false)
end

rule "Wall button pressed"
when
    Channel "mqtt:topic:connectmq:livingroom:button" triggered
then
    LivingRoom_Lamp.sendCommand(if (LivingRoom_Lamp.state == ON) OFF else ON)
end

Para escuchas genéricas, añade un canal Publish trigger en el propio Thing broker: su state topic admite comodines (testmqtt/openhab/+/event) y las reglas reciben topic#payload como evento.

Prueba cada salto

Entrada: publica una lectura de sensor simulada y observa cómo cambian los Items:

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'testmqtt/openhab/livingroom/sensor' -m '{"temperature": 21.5, "humidity": 48}'

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'testmqtt/openhab/livingroom/status' -m online -r

events.log (/var/log/openhab/events.log en los paquetes de Linux) debería mostrar Item 'LivingRoom_Temperature' changed from NULL to 21.5 °C.

Salida: suscríbete al command topic y conmuta el switch en la interfaz o desde la consola de openHAB:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/openhab/#' -v

# en otra shell: openhab-cli console, y luego
openhab> openhab:send LivingRoom_Lamp ON

Deberías ver testmqtt/openhab/livingroom/lamp/set ON. Si prefieres el navegador, el cliente MQTT online sirve igual de bien en ambos sentidos.

Ver el tráfico MQTT de openHAB en el navegador

Si no pasa nada, sube el nivel de log en la consola con log:set DEBUG org.openhab.binding.mqtt y log:set DEBUG org.openhab.core.io.transport.mqtt. Hallazgos típicos: el Item está enlazado a otro UID de canal, el JSONPath no coincide (el valor se queda en NULL y se registra un aviso de transformación) o el topic difiere en un carácter; pega ambos en el topic matcher para comprobarlo.

Autodescubrimiento: Homie y Home Assistant

El binding también entiende dos convenciones de descubrimiento. Los dispositivos que se anuncian con la convención Homie o con Home Assistant MQTT discovery (Tasmota, ESPHome, Zigbee2MQTT con discovery activado) aparecen en la Inbox de openHAB con sus canales ya creados. Eso ahorra escribir, pero los Generic Things siguen siendo la opción más predecible para firmware propio y para dispositivos como Shelly o Zigbee2MQTT cuando quieres control total sobre los nombres de los topics. Elijas lo que elijas, un diseño de topics coherente para el hogar inteligente mantiene corta la configuración de canales.

El binding MQTT de openHAB es sencillo en cuanto encajan las dos capas: un Thing broker por conexión, Generic MQTT Things con un canal por valor e Items enlazados a canales. Empieza con un solo canal, compruébalo con mosquitto_pub y events.log y después añade el resto de la casa.

Preguntas frecuentes