Homebridge MQTT: Levando Dispositivos MQTT para o Apple Home

A integração Homebridge MQTT permite controlar sensores, relés e luzes DIY pelo app Casa (Apple Home) e pela Siri, mesmo que o próprio HomeKit não saiba nada de MQTT. Neste tutorial você vai instalar o plugin mqttthing, mapear tópicos para características do HomeKit para um sensor de temperatura, um interruptor, uma luz dimerizável e um sensor de contato, lidar com payloads JSON e migrar a configuração para um broker privado com TLS.

Como o Homebridge Conversa com o MQTT

O Homebridge é um servidor Node.js que emula acessórios HomeKit. Os plugins fornecem a lógica real dos dispositivos. O plugin MQTT mais usado, homebridge-mqttthing, permite declarar um acessório em JSON e mapear cada característica do HomeKit para um tópico MQTT: um tópico get que o Homebridge assina para obter o valor atual e um tópico set no qual ele publica quando você toca em um bloco ou pede algo à Siri.

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

Como os dispositivos só conversam com o broker, eles podem estar em outra rede ou em outro local. O Homebridge só precisa de acesso de saída ao broker. Se quiser primeiro o contexto desse padrão, o artigo sobre o que um broker MQTT faz explica publish e subscribe em termos simples.

Instalando o Plugin mqttthing

Se você usa a Homebridge UI (o padrão nas imagens oficiais), abra Plugins, pesquise mqttthing e instale o Homebridge Mqttthing. Pela linha de comando em um host Homebridge:

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

Os acessórios são definidos no array accessories do config.json. A UI inclui um editor baseado em formulário para o plugin, mas o JSON bruto é mais claro para aprender, por isso os exemplos abaixo o utilizam. Você pode colá-los em Config > JSON Config.

Um Primeiro Acessório Homebridge MQTT: Sensor de Temperatura

Comece com o servidor MQTT público (gratuito), feito para testes e protótipos, para poder acompanhar tudo acontecendo. Escolha uma string aleatória (aqui h3m8x2) para manter seus tópicos separados na área pública compartilhada.

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

Salve, reinicie o Homebridge e publique uma leitura:

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

O bloco no Apple Home atualiza em menos de um segundo. A flag -r torna a mensagem retida, de modo que, após uma reinicialização do Homebridge, o último valor é entregue imediatamente, em vez de o bloco exibir "Sem Resposta" até a próxima leitura.

Interruptores e Luzes com Comandos

Acessórios controláveis precisam de um tópico get e de um tópico set. Usar tópicos separados para comandos e para o estado confirmado é uma boa prática: o Homebridge publica a solicitação, o dispositivo executa e publica de volta o seu 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"
}

Uma luz dimerizável acrescenta uma característica de brilho:

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

Acompanhe o que o Homebridge envia enquanto você toca nos blocos:

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

Lidando com Payloads JSON

Muitos dispositivos publicam um único documento JSON com vários valores em vez de um tópico por valor. O mqttthing aceita um objeto de tópico com uma função apply, um pequeno corpo JavaScript que recebe message e retorna o valor a ser usado.

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

O sensor de contato do HomeKit usa 0 para detectado (fechado) e 1 para não detectado (aberto), e por isso a função mapeia open para 1. A mesma técnica funciona em tópicos set para encapsular um comando em JSON, por exemplo "apply": "return JSON.stringify({state: message});".

Mapeando Tipos de Dispositivos Comuns

O plugin suporta muitos outros tipos, incluindo portões de garagem, termostatos, ventiladores e persianas. Cada um tem seus próprios nomes de características; o README do plugin lista todos.

Número de Conexões e Client IDs

Cada acessório mqttthing abre sua própria conexão MQTT. Dez acessórios significam, portanto, dez clientes no broker, cada um precisando de um client ID único. Isso tem duas consequências:

1. Dê a cada acessório seu próprio clientId em mqttOptions. IDs duplicados fazem o broker desconectar a sessão anterior, e os acessórios ficam alternando entre responder e não responder.
2. Conte as conexões em relação ao seu plano. O plano Serverless (Free) da ConnectMQ permite até 25 conexões simultâneas, o que cobre o Homebridge mais um número modesto de dispositivos. Configurações maiores cabem no plano Serverless (Paid), com até 1.000.

Se você precisar de muitos acessórios em uma única conexão, considere deixar o Home Assistant ou o Node-RED donos da conexão com o broker e expor o HomeKit pelas bridges HomeKit deles.

Produção: TLS e Credenciais

Qualquer coisa na área pública de teste pode ser lida por quem adivinhar o tópico, e alguém também poderia publicar nos seus tópicos set. Antes de controlar equipamentos reais, crie um broker privado e mude todos os acessórios para 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"
}

O Node.js confia de fábrica na cadeia Let's Encrypt usada pela ConnectMQ, então nenhum arquivo de CA é necessário. Na ConnectMQ, os client IDs ficam vinculados às credenciais emitidas no portal; por isso, quando precisar de várias conexões, emita um conjunto de credenciais por grupo de acessórios e registre qual ID pertence a qual.

Rodando o mqttthing como Child Bridge

O Homebridge pode rodar um plugin como child bridge: um processo separado com seu próprio pareamento HomeKit. Ativá-lo para o mqttthing (nas configurações do plugin, Bridge Settings) traz dois benefícios práticos. Uma falha ou uma definição de acessório com defeito deixa de derrubar todos os outros plugins, e reiniciar a child bridge depois de editar tópicos é mais rápido do que reiniciar o Homebridge inteiro. Você pareia a child bridge uma vez no app Casa, e os acessórios adicionados a ela depois aparecem automaticamente.

Também vale a pena publicar um tópico de disponibilidade retido em cada dispositivo, com um last will offline. O mqttthing pode usá-lo por meio do tópico getOnline junto com onlineValue e offlineValue, de modo que o Apple Home mostre o dispositivo como sem resposta quando ele está realmente offline, em vez de exibir um valor desatualizado.

Solução de Problemas no Homebridge MQTT

• O acessório mostra Sem Resposta. Nenhum valor chegou ao tópico get desde que o Homebridge iniciou. Publique o estado retido a partir dos dispositivos, ou verifique erros de digitação no tópico com logMqtt: true.
• O bloco volta sozinho. O dispositivo não está publicando seu novo estado no tópico get, ou publica um valor que não corresponde a onValue.
• Mensagens constantes de reconexão no log. Client IDs duplicados ou credenciais erradas. Procure Connection refused e o motivo no log do Homebridge.
• A Siri diz que o dispositivo não responde, mas o app funciona. Normalmente é um problema da central HomeKit (Apple TV ou HomePod), e não do MQTT; verifique se a central alcança o Homebridge na LAN.

Próximos Passos

O Homebridge cuida do lado da Apple; os dispositivos ainda precisam publicar tópicos sensatos. O guia de ESPHome MQTT mostra como construir sensores que publicam estado e aceitam comandos, e o artigo sobre estrutura de tópicos MQTT para casa inteligente ajuda você a projetar tópicos que continuem gerenciáveis. Se o Home Assistant roda junto com o Homebridge, veja Home Assistant com um broker MQTT externo. Para o contexto mais amplo de combinar dispositivos e lógica, leia o guia de automação com IoT e, para entender por que um broker MQTT gerenciado supera um broker no Raspberry Pi do Homebridge para acesso remoto, compare as opções ali.

Conecte o Homebridge à ConnectMQ

A ConnectMQ dá ao Homebridge um broker privado, protegido por TLS e acessível de qualquer rede, com um explorador de tópicos ao vivo para depurar seus acessórios enquanto você os configura. Crie um broker no plano Serverless (Free) em app.connectmq.com, sem cartão de crédito, e cole as credenciais geradas nos seus acessórios mqttthing.

Perguntas frequentes

O HomeKit suporta MQTT nativamente?

Não. O HomeKit usa seu próprio protocolo de acessórios, então você precisa de uma bridge como o Homebridge com um plugin MQTT para traduzir entre os dois.

Posso controlar dispositivos Homebridge MQTT quando estou fora de casa?

Sim, por meio de uma central da casa HomeKit, como de costume. Como os dispositivos conversam com um broker na nuvem, eles podem até estar em um local diferente do Homebridge.

Por que meus sensores mostram Sem Resposta após uma reinicialização?

O Homebridge ainda não recebeu nenhum valor. Publique as mensagens de estado com a flag retain para que o broker entregue o último valor assim que o Homebridge assinar.

O mqttthing é o único plugin MQTT para o Homebridge?

Não, mas é o mais genérico. Outros plugins são voltados a ecossistemas específicos, como Zigbee2MQTT ou Tasmota, e podem ser mais simples se você usar apenas esses dispositivos.