O binding MQTT do openHAB transforma qualquer tópico MQTT em canais que você pode vincular a items, exibir em dashboards e usar em regras. Neste tutorial você vai conectar o openHAB a um broker externo, definir generic MQTT things para um sensor e um interruptor de estufa (pense em uma estufa de hortaliças no interior de São Paulo), interpretar payloads JSON, publicar comandos a partir de regras e reforçar a configuração com TLS e credenciais.
Como o Binding MQTT do openHAB É Organizado
O openHAB modela o MQTT em duas camadas. A broker bridge (mqtt:broker) é a conexão: host, porta, TLS, client ID e credenciais. Abaixo dela ficam as things, cada uma descrevendo um dispositivo pelos seus tópicos. O tipo de thing mais flexível é a generic MQTT thing (mqtt:topic), na qual você declara cada canal e os tópicos de estado e de comando que ele usa. Os items então se vinculam a esses canais exatamente como fariam com qualquer outro binding.
| Camada | Tipo de thing | Contém |
|---|---|---|
| Conexão | mqtt:broker (bridge) |
Host, porta, TLS, client ID, usuário, senha, last will |
| Dispositivo | mqtt:topic (generic thing) |
Canais com tópicos de estado e de comando |
| Dispositivo (automático) | Things Home Assistant ou Homie | Criadas a partir de mensagens de discovery |
| Modelo | Items | Vinculados a canais, usados na UI e em regras |
Uma única broker bridge pode atender centenas de things e usa apenas uma conexão MQTT. Isso importa em planos com cotas de conexão: o openHAB conta como um único cliente, não importa quantos dispositivos ele modele.
Instale o binding em Settings > Add-on Store > Bindings > MQTT Binding. Se seus dispositivos enviam JSON, instale também a JSONPath Transformation na seção de transformações.
Conectando o openHAB a um Broker MQTT
Você pode criar a bridge pela UI (Things > + > MQTT Binding > MQTT Broker) ou em um arquivo .things. A configuração em texto é mais fácil de compartilhar e de fazer backup, por isso este tutorial a utiliza. Crie 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"
]
}
}
Isso se conecta ao servidor MQTT público (gratuito) de forma anônima. Substitua r4t8w1 por uma string aleatória sua, porque o servidor MQTT público é compartilhado, pode ser lido por todos e serve apenas para testes e protótipos. O client ID não pode ser vazio e deve ser único; reutilizar um que outro cliente já esteja usando fará as duas conexões caírem repetidamente.
Verifique Settings > Things: a bridge deve ficar ONLINE em poucos segundos, seguida pela thing greenhouse.
Vinculando items
Crie 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" }
Observe o padrão do UID do canal: mqtt:topic:<bridge id>:<thing id>:<channel id>. Um erro de digitação ali é o motivo mais comum de um item continuar NULL.
Testando os Canais MQTT do openHAB
Simule o dispositivo a partir de um terminal:
# leitura do sensor (JSON interpretado pelo JSONPath)
mosquitto_pub -h broker.connectmq.com -p 1883 -i sim-r4t8w1 \
-t 'connectmq/demo/r4t8w1/greenhouse/telemetry' -m '{"temp":24.6,"hum":71}'
# contato da porta
mosquitto_pub -h broker.connectmq.com -p 1883 -i sim-r4t8w1 \
-t 'connectmq/demo/r4t8w1/greenhouse/door' -m 'OPEN'
# acompanhe os comandos que o openHAB envia
mosquitto_sub -h broker.connectmq.com -p 1883 -i mon-r4t8w1 \
-t 'connectmq/demo/r4t8w1/greenhouse/fan/set' -v
Alterne o ventilador na UI do openHAB e o comando ON ou OFF aparece na janela do assinante. Um dispositivo real executaria o comando e publicaria seu novo estado em fan/state, que o openHAB usa para atualizar o item. Manter os tópicos de comando e de estado separados faz a UI mostrar o estado confirmado, e não apenas o último clique.
Interpretando JSON e Formatando Comandos
A maioria dos dispositivos modernos publica JSON. Além de transformationPattern para valores de entrada, a generic thing suporta formatBeforePublish para os de saída. Por exemplo, um dimmer 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
]
As transformações podem ser encadeadas com o caractere ∩ no padrão se você precisar de várias etapas, por exemplo JSONPath seguido de uma consulta MAP. Mantenha as cadeias curtas; quando a lógica cresce, uma regra é mais fácil de depurar.
Publicando Mensagens MQTT a partir de Regras do openHAB
Comandos vinculados a canais cobrem a maioria das necessidades, mas às vezes você quer publicar em um tópico arbitrário, por exemplo para enviar uma programação a um controlador. A broker bridge expõe a ação publishMQTT para isso. Em um arquivo de regras 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
A mesma ação está disponível em regras JavaScript por meio de actions.get("mqtt", "mqtt:broker:connectmq"). Evite publicar no mesmo tópico que um canal assina, a menos que você queira criar um loop.
Disparando regras a partir de tópicos brutos
Se você só quer reagir a uma mensagem sem modelar um item, adicione um canal de gatilho à bridge:
Bridge mqtt:broker:connectmq "ConnectMQ Broker" [ ... ] {
Channels:
Type publishTrigger : alarms "Alarms" [
stateTopic="connectmq/demo/r4t8w1/+/alarm",
separator="#"
]
}
Uma regra disparada por Channel "mqtt:broker:connectmq:alarms" triggered recebe o tópico e o payload unidos pelo separador, de modo que uma única regra pode tratar os alarmes de todos os dispositivos.
Configuração de Produção com TLS e Credenciais
Antes de conectar dispositivos reais, saia do servidor MQTT público. Crie um broker privado e atualize a 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
]
O certificado da ConnectMQ é emitido pela Let's Encrypt, na qual o Java confia por padrão, então não é preciso importar nenhum certificado extra. O certificate pinning é desativado explicitamente porque os certificados Let's Encrypt são renovados a cada poucos meses; um certificado fixado faria a bridge rejeitar o broker após a próxima renovação. Use o client ID exatamente como foi emitido, já que ele está vinculado às credenciais. Para saber mais sobre como proteger o sistema inteiro, leia as boas práticas de segurança MQTT.
Se preferir rodar o broker localmente dentro da rede do openHAB, você ainda pode fazer bridge com a nuvem depois, mas um broker MQTT gerenciado elimina a necessidade de manter um host separado para o broker e permite que locais remotos e celulares alcancem os mesmos tópicos.
Exibindo a Disponibilidade dos Dispositivos
Uma generic thing continua ONLINE enquanto a bridge estiver conectada, mesmo que o dispositivo por trás dela tenha perdido energia há horas. Para tornar isso visível, faça cada dispositivo publicar uma mensagem online retida ao se conectar e defina um last will offline retido. Depois adicione as configurações de disponibilidade à thing:
Thing topic greenhouse "Greenhouse Sensor" [
availabilityTopic="connectmq/demo/r4t8w1/greenhouse/status",
payloadAvailable="online",
payloadNotAvailable="offline"
] {
// canais como antes
}
Quando o dispositivo cai, o broker publica o will dele, o openHAB marca a thing como OFFLINE e os items vinculados ficam UNDEF. Regras e dashboards conseguem então distinguir "o sensor está lendo 0" de "o sensor sumiu", o que faz toda a diferença para qualquer coisa que controle aquecimento, irrigação ou alarmes.
Checklist de Solução de Problemas
- A bridge continua OFFLINE. Verifique host e porta, e se
secure=trueestá definido apenas com a porta 8883. Procure o reason code emopenhab.log. - A bridge oscila entre ONLINE e OFFLINE. Client ID duplicado; outra instância do openHAB ou ferramenta de teste usa o mesmo.
- Thing ONLINE, mas item NULL. UID de canal errado no item, erro de digitação no tópico ou o add-on JSONPath está faltando. Use
log:set DEBUG org.openhab.binding.mqttno console para ver cada mensagem recebida. - O interruptor mostra UNDEF. O payload não corresponde exatamente a
onouoff; os valores diferenciam maiúsculas de minúsculas. - Os comandos não fazem nada. Garanta que o dispositivo escute no tópico de comando e que você não esteja publicando no tópico de estado dele.
Onde o openHAB se Encaixa em um Sistema Maior
O openHAB é um consumidor no broker, não o dono dos dados. Nós ESPHome, tomadas Tasmota e o Zigbee2MQTT podem todos publicar no mesmo broker, e outras ferramentas podem ler os mesmos tópicos. O tutorial de ESPHome MQTT mostra como publicar a partir de dispositivos configurados em YAML, e o Tasmota MQTT aborda tomadas inteligentes com firmware gravado. Para o panorama arquitetural mais amplo, veja o guia de automação com IoT. E se você ainda está comparando brokers, a visão geral sobre broker MQTT na nuvem explica os prós e contras.
Rode o openHAB em um Broker ConnectMQ
A ConnectMQ oferece um broker MQTT gerenciado e privado, com MQTT 3.1.1 e 5.0, TLS, credenciais geradas e um explorador de tópicos ao vivo que torna simples depurar os canais do openHAB. Crie um broker no plano Serverless (Free) em app.connectmq.com, sem cartão de crédito, cole as credenciais na sua bridge e suas things do openHAB estarão online.
Perguntas frequentes
O openHAB inclui um broker MQTT próprio?
Não. As versões atuais do openHAB fornecem apenas o binding cliente, então você precisa de um broker externo, como uma instância local do Mosquitto ou um broker na nuvem como a ConnectMQ.
O openHAB pode usar MQTT 5?
A broker bridge tem um parâmetro mqttVersion que pode ser definido como V5. A versão 3.1.1 continua sendo o padrão e funciona com quase todos os dispositivos.
Quantas conexões MQTT o openHAB usa?
Uma por broker bridge, independentemente de quantas generic things estejam sob ela. Isso o torna eficiente em planos com limite de conexões.
Por que meus items atualizam, mas os comandos não são enviados?
Provavelmente o canal não tem commandTopic, ou o item está vinculado como somente leitura. Adicione um tópico de comando e confirme com um assinante que a mensagem está sendo publicada.
