Estrutura de Topics MQTT para Casa Inteligente: Boas Práticas para Cômodos, Dispositivos e Comandos

Uma boa estrutura de topics MQTT para casa inteligente é a diferença entre automações que você entende num relance e um emaranhado de topics sensor1/temp2 de que ninguém se lembra. Neste guia você vai receber uma organização cômodo/dispositivo/propriedade pronta para usar, entender por que os topics de comando e de estado precisam ser separados e ver como retained messages, disponibilidade e curingas se encaixam em um broker real.

Por que o design de topics importa antes do décimo dispositivo

Com três dispositivos, qualquer nomenclatura funciona. Quando você chega a trinta, os nomes dos topics determinam a facilidade de:

• assinar "tudo na cozinha" ou "todas as temperaturas da casa" com um único curinga,
• adicionar um dispositivo novo sem editar todas as automações,
• saber se uma mensagem é um pedido ou um fato,
• ver em um explorador de topics o que realmente está acontecendo.

O MQTT não impõe nenhuma estrutura. Os topics são apenas strings UTF-8 separadas por /, e o broker compara as assinaturas com elas. Essa liberdade é exatamente o motivo pelo qual você precisa de uma convenção. Se o básico de como o broker roteia essas mensagens for novidade para você, comece por o que um broker MQTT faz.

A organização recomendada: casa, cômodo, dispositivo, propriedade

Uma organização que escala bem para a maioria das casas é:

<home>/<room>/<device>/<property>[/set]

Exemplos:

home1/kitchen/ceiling-light/power            state: "ON" or "OFF" (retained)
home1/kitchen/ceiling-light/power/set        command: "ON", "OFF", "TOGGLE"
home1/kitchen/ceiling-light/brightness       state: 0-100 (retained)
home1/kitchen/ceiling-light/brightness/set   command: 0-100
home1/livingroom/climate/temperature         state: 21.6 (retained)
home1/livingroom/climate/humidity            state: 48 (retained)
home1/garage/door/state                      state: "open", "closed", "opening" (retained)
home1/garage/door/state/set                  command: "OPEN", "CLOSE"
home1/garage/door/availability               "online" or "offline" (retained, last will)

Por que essa ordem funciona:

Mantenha a profundidade em cinco níveis ou menos. Árvores profundas são mais difíceis de digitar, e o broker público de teste limita os topics a oito níveis de qualquer forma, o que é um teto sensato para uma casa.

Topics de comando e de estado em uma estrutura de topics MQTT para casa inteligente

A regra mais importante de todas: nunca use o mesmo topic para comandos e para estado.

Se uma lâmpada escuta e informa no mesmo home1/kitchen/ceiling-light/power, um dashboard que publica ON vai ver a própria mensagem voltar como eco, não consegue saber se a lâmpada realmente acendeu, e um comando ON retido vai acender a lâmpada de novo toda vez que o dispositivo se reconectar, mesmo depois que alguém a tiver desligado no interruptor.

Com topics separados, o fluxo é inequívoco:

1. O dashboard publica ON em .../power/set (sem retain).
2. O dispositivo aciona o relé.
3. O dispositivo publica ON em .../power com a flag de retain.
4. Todos os assinantes, inclusive o dashboard, se atualizam a partir do topic de estado.

O topic de estado passa a ser a única fonte de verdade. Comandos são pedidos que podem falhar; estados são fatos que o dispositivo confirma.

Retenha o estado, nunca retenha comandos

As retained messages permitem que um client recém-conectado veja o estado atual imediatamente. Isso é exatamente o que você quer para estados e disponibilidade, e exatamente o que você não quer para comandos. Um OPEN retido no topic de comando de um portão de garagem é um portão que se abre sozinho depois de cada queda de energia. Nosso tutorial de abridor de portão de garagem MQTT mostra esse padrão em um projeto em que errar tem consequências reais.

Escolha o QoS por tipo de topic

Estados de sensores podem usar QoS 0 ou 1; uma temperatura perdida é substituída pela próxima. Comandos devem usar QoS 1 para serem entregues pelo menos uma vez, e os dispositivos devem tratar comandos repetidos como idempotentes (ON duas vezes continua ligado). Para entender as contrapartidas, veja os níveis de QoS do MQTT explicados.

Disponibilidade e last will

Todo dispositivo deve publicar um topic availability. Defina-o como online (retido) após conectar e configure uma mensagem de last will offline (retida) no mesmo topic. Se o dispositivo perder energia ou Wi-Fi, o broker publica o will em nome dele, e os dashboards podem deixar o dispositivo esmaecido em vez de mostrar um valor antigo como se fosse atual.

// ESP32 com PubSubClient: last will na conexão e depois anuncia online
const char* AVAIL = "home1/garage/door/availability";
if (mqtt.connect(clientId, user, pass, AVAIL, 1, true, "offline")) {
  mqtt.publish(AVAIL, "online", true);
  mqtt.subscribe("home1/garage/door/state/set", 1);
}

Convenções de payload

A estrutura de topics e o formato do payload andam juntos. Escolha uma abordagem e use-a em todo lugar:

• Um valor por topic (.../temperature = 21.6) é simples, funciona com qualquer ferramenta e torna os curingas poderosos.
• JSON por dispositivo (.../climate = {"temperature":21.6,"humidity":48}) reduz o número de mensagens e mantém valores relacionados consistentes.

Muitas casas usam os dois: JSON para dispositivos com vários sensores vindos do Zigbee2MQTT ou do ESPHome e valores únicos para dispositivos caseiros. Se usar JSON, documente as chaves e inclua as unidades no nome da chave (temp_c) ou em uma nota de schema. Evite misturar 21.6, "21.6" e "21.6 C" entre dispositivos.

Regras de nomenclatura que evitam dor de cabeça

1. Use nomes em minúsculas separados por hífen: ceiling-light, e não Ceiling Light.
2. Sem espaços, sem # ou + nos nomes, sem / no início (isso cria um primeiro nível vazio).
3. Nomeie os cômodos como as pessoas fazem, mas evite nomes que mudam (quarto-do-tom fica estranho quando o Tom se muda; quarto-2 dura).
4. Nomeie os dispositivos pela função, não pela marca ou modelo, para poder trocar o hardware sem renomear.
5. Reserve um prefixo de nível superior para topics do sistema, como home1/system/backup-status.
6. Nunca coloque segredos, códigos de portas ou dados pessoais nos nomes dos topics; os topics ficam visíveis para qualquer assinante com curingas correspondentes.

Integrando topics de ecossistemas

Você não vai controlar o nome de todos os topics. O Zigbee2MQTT publica em zigbee2mqtt/<friendly_name>, o Tasmota usa os prefixos stat/, tele/ e cmnd/, e o discovery do Home Assistant usa homeassistant/<component>/<id>/config. Não brigue com essas convenções. Em vez disso:

• Dê aos dispositivos friendly names que sigam o seu padrão cômodo/dispositivo, por exemplo kitchen/ceiling-light no Zigbee2MQTT, para que os topics virem zigbee2mqtt/kitchen/ceiling-light.
• Mantenha seus próprios dispositivos caseiros sob a sua raiz home1/.
• Deixe o Home Assistant mapear tudo em entidades por meio do MQTT discovery.

Nosso guia de configuração do Zigbee2MQTT mostra como os friendly names se transformam em topics.

Teste a organização em um broker público

Você pode testar a estrutura sem hardware no broker.connectmq.com, o servidor MQTT público (gratuito) do ConnectMQ. Use um prefixo aleatório para que seus topics não colidam com os de outras pessoas:

# Terminal 1: observar a casa inteira
mosquitto_sub -h broker.connectmq.com -p 1883 -i watch-h7q2 -t "connectmq/demo/h7q2/home1/#" -v

# Terminal 2: uma lâmpada informa o estado retido e depois um dashboard envia um comando
mosquitto_pub -h broker.connectmq.com -p 1883 -i light-h7q2 -r -q 1 \
  -t connectmq/demo/h7q2/home1/kitchen/ceiling-light/power -m ON
mosquitto_pub -h broker.connectmq.com -p 1883 -i dash-h7q2 -q 1 \
  -t connectmq/demo/h7q2/home1/kitchen/ceiling-light/power/set -m OFF

# Todas as temperaturas da casa, de qualquer cômodo e qualquer dispositivo
mosquitto_sub -h broker.connectmq.com -p 1883 -i temps-h7q2 -t "connectmq/demo/h7q2/home1/+/+/temperature" -v

O prefixo de demonstração acrescenta três níveis, mais um motivo para manter a sua própria árvore rasa. O servidor MQTT público pode ser lido por qualquer pessoa, então use-o apenas para testes e protótipos de estrutura, não para a sua casa real. Ao migrar para um broker privado, você pode descartar o prefixo de demonstração e começar em home1/.

Checklist da estrutura de topics da casa inteligente

1. Todo dispositivo segue <home>/<room>/<device>/<property>.
2. Os comandos usam o sufixo /set e nunca são retidos.
3. Os estados são retidos e publicados pelo dispositivo depois que ele age.
4. Todo dispositivo tem um topic availability com last will.
5. Os nomes são em minúsculas, com hífens e baseados na função.
6. O formato do payload é documentado e consistente.
7. A profundidade dos topics fica em cinco níveis ou menos.

Rodando sua casa em um broker privado

Uma estrutura de topics só continua limpa se o broker em que ela vive for seguro e confiável. O ConnectMQ oferece um broker MQTT gerenciado com TLS na porta 8883, credenciais geradas e um explorador de topics ao vivo em que a sua árvore de cômodos e dispositivos é fácil de navegar. Se estiver decidindo entre hospedar por conta própria e usar um broker MQTT na nuvem, pense em acesso remoto, certificados e atualizações. Para mais projetos residenciais e prediais, veja o guia de automação IoT.

Comece com o ConnectMQ

Crie um broker Serverless gratuito em app.connectmq.com, sem cartão de crédito, copie as credenciais geradas e publique seus primeiros topics home1/. O explorador de topics ao vivo do ConnectMQ mostra a sua casa inteira como uma árvore em segundos.

Perguntas frequentes

Os topics devem começar com barra?

Não. Uma barra no início cria um primeiro nível vazio, o que é permitido, mas confuso e fácil de digitar errado. Comece pelo nome da sua casa ou do seu local.

É melhor usar um topic JSON por dispositivo ou um topic por valor?

Os dois funcionam. Um valor por topic é o mais simples para curingas e dispositivos caseiros; JSON por dispositivo combina com dispositivos com vários sensores. Escolha um por tipo de dispositivo e documente.

Por que minha luz acende sozinha depois de reiniciar?

Provavelmente você reteve uma mensagem de comando. Limpe-a publicando uma retained message vazia no topic de comando e, daqui em diante, retenha apenas os topics de estado.

Quantos níveis de topic uma casa inteligente deve usar?

Quatro ou cinco são suficientes: casa, cômodo, dispositivo, propriedade e um sufixo set opcional. Árvores mais profundas aumentam a digitação e acrescentam pouco valor.