Tutorial do binding MQTT do openHAB: broker, Things e canais

O binding MQTT do openHAB conecta o openHAB a qualquer broker MQTT em duas camadas: um Thing broker (um bridge que mantém a conexão: host, porta, TLS, credenciais) e um ou mais Generic MQTT Things abaixo dele, cujos canais mapeiam topics específicos para Items do openHAB. Instale o binding, adicione o broker, crie um Thing com um canal por valor, vincule os Items, e cada mensagem nesses topics atualiza seus Items, enquanto comandos da interface ou de regras são publicados de volta.

Este tutorial percorre a configuração pela interface e por arquivos de texto, mostra como interpretar payloads JSON e como verificar cada salto pela linha de comando.

Pré-requisitos

• openHAB 4.x ou mais recente com o MQTT Binding instalado (Settings → Add-on Store → Bindings → MQTT).
• O add-on JSONPath Transformation se seus dispositivos enviam JSON (a maioria envia).
• Um broker. O openHAB não inclui um, então rode o Mosquitto localmente ou use um broker hospedado. Os exemplos usam broker.connectmq.com com TLS na porta 8883 e topics de teste em testmqtt/openhab/....

Passo 1: o Thing bridge do broker

Na interface vá em Settings → Things → + → MQTT Binding → MQTT Broker e preencha:

Deixe o pinning de certificado e de chave pública desligado quando o broker usa um certificado público com renovação automática: o pinning guarda o primeiro certificado que vê e falha quando o broker o troca. Se precisar depurar o lado TLS, veja como testar uma conexão TLS.

O Thing broker deve ficar ONLINE em poucos segundos. Se aparecer OFFLINE - COMMUNICATION_ERROR, o detalhe de status traz o motivo, normalmente uma incompatibilidade porta/TLS ou credenciais erradas.

Você também pode configurar um Last Will (lwtTopic, lwtMessage), além de mensagens de birth e shutdown, para que outros sistemas saibam se o openHAB está conectado; útil quando um dashboard ou o Node-RED depende dele.

Passo 2: um Generic MQTT Thing e seus canais

Adicione um Generic MQTT Thing, escolha o broker como bridge e crie canais na aba Channels. Cada canal tem um tipo e, no mínimo, um state topic:

Os parâmetros de canal mais importantes:

• State Topic: o openHAB assina este topic e atualiza o Item.
• Command Topic: o openHAB publica aqui quando o Item recebe um comando. Use um topic diferente do state topic (por exemplo .../set); caso contrário, seus próprios comandos voltam como atualizações de estado.
• Incoming Value Transformations: por exemplo JSONPATH:$.temperature.
• Outgoing Value Format: uma string de formato como %s ou {"state":"%s"} para envolver os comandos em JSON.
• Retained: publica os comandos como mensagens retidas; leia sobre mensagens retidas antes de ligar.
• Custom On/Open Value e Custom Off/Closed Value: mapeiam payloads do dispositivo como 1/0 ou true/false.
• Is Command (postCommand): trata valores recebidos como comandos em vez de atualizações de estado, para que acionem outros bindings e regras.

A mesma configuração em arquivos de texto

Para controle de versão, defina o broker e os Things em um arquivo .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" ]
    }
}

O UID do canal é mqtt:topic:connectmq:livingroom:<canal>. Vincule os Items a ele:

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" }

Dois canais compartilham um state topic e extraem campos JSON diferentes: o padrão normal para dispositivos multissensor. O availabilityTopic marca o Thing como OFFLINE quando o Last Will do dispositivo dispara.

Publicando a partir de regras

O Thing broker expõe a ação publishMQTT, útil para notificações ou para falar com dispositivos que não têm 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 listeners genéricos, adicione um canal Publish trigger no próprio Thing broker: seu state topic aceita curingas (testmqtt/openhab/+/event) e as regras recebem topic#payload como evento.

Teste cada salto

Entrada: publique uma leitura de sensor simulada e veja os Items mudarem:

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

O events.log (/var/log/openhab/events.log nos pacotes Linux) deve mostrar Item 'LivingRoom_Temperature' changed from NULL to 21.5 °C.

Saída: assine o command topic e alterne o switch na interface ou pelo console do openHAB:

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

# em outro shell: openhab-cli console, e então
openhab> openhab:send LivingRoom_Lamp ON

Você deve ver testmqtt/openhab/livingroom/lamp/set ON. Se preferir o navegador, o cliente MQTT online funciona igualmente bem nas duas direções.

Veja o tráfego MQTT do openHAB no navegador

Quando nada acontece, aumente o nível de log no console com log:set DEBUG org.openhab.binding.mqtt e log:set DEBUG org.openhab.core.io.transport.mqtt. Achados típicos: o Item está vinculado a outro UID de canal, o JSONPath não casa (o valor fica NULL e um aviso de transformação é registrado) ou o topic difere em um caractere; cole os dois no topic matcher para conferir.

Descoberta automática: Homie e Home Assistant

O binding também entende duas convenções de descoberta. Dispositivos que se anunciam pela convenção Homie ou pelo Home Assistant MQTT discovery (Tasmota, ESPHome, Zigbee2MQTT com discovery ativo) aparecem na Inbox do openHAB com os canais já criados. Isso poupa digitação, mas os Generic Things continuam sendo a opção mais previsível para firmware próprio e para dispositivos como Shelly ou Zigbee2MQTT quando você quer controle total dos nomes de topics. Seja qual for a escolha, um design de topics consistente para casa inteligente mantém a configuração de canais curta.

O binding MQTT do openHAB é simples quando as duas camadas fazem sentido: um Thing broker por conexão, Generic MQTT Things com um canal por valor e Items vinculados aos canais. Comece com um único canal, comprove-o com mosquitto_pub e events.log e depois adicione o resto da casa.

Perguntas frequentes