Exemplos de Hierarquia de Tópicos MQTT para Projetos IoT Reais

Estes exemplos de hierarquia de tópicos MQTT oferecem árvores prontas para quatro tipos comuns de projeto: uma casa inteligente, uma frota de veículos, uma fábrica (pense em uma planta em Campinas) e um sistema de monitoramento de energia. Para cada um você verá a árvore, as assinaturas que ela foi feita para atender e as decisões por trás dela, para que possa adaptá-la em vez de começar do zero.

Princípios por trás de boas hierarquias de topics MQTT

Todas as árvores abaixo seguem o mesmo punhado de regras. Conhecê-las facilita adaptar os exemplos ao seu próprio projeto.

1. Do geral para o específico. Coloque o nível mais geral primeiro (planta, casa, frota) e o mais específico por último (uma única medição ou comando).
2. Profundidade fixa por tipo de dado. Se a telemetria de cada dispositivo fica no mesmo nível, um único padrão + encontra todas.
3. Separe os dados por direção. A telemetria sobe, os comandos descem. Dê a eles ramos diferentes para que os dispositivos se inscrevam apenas no que precisam.
4. Minúsculas, sem espaços, sem barra inicial. home/kitchen/temp e Home/Kitchen/Temp são topics diferentes; uma / inicial cria um primeiro nível vazio.
5. Identificadores que sobrevivem a mudanças. Use etiquetas de ativos ou números de série, não rótulos humanos que acabam sendo renomeados.
6. Projete para as assinaturas, não para o publicador. Anote as consultas curinga que os consumidores vão executar antes de fixar a árvore.

O raciocínio detalhado está em convenções de nomenclatura de topics MQTT. Aqui o foco está em árvores concretas.

Exemplo de hierarquia de topics para casa inteligente

Uma casa tem uma estrutura natural: cômodos contêm dispositivos, e os dispositivos expõem estado e aceitam comandos.

home/<room>/<device>/state         # estado atual, retido
home/<room>/<device>/set           # comando para o dispositivo
home/<room>/<device>/availability  # online/offline (Last Will)
home/<room>/<sensor>/<measurement> # leituras numéricas

home/livingroom/lamp/state          -> {"on": true, "brightness": 70}
home/livingroom/lamp/set            -> {"on": false}
home/kitchen/climate/temperature    -> 21.4
home/kitchen/climate/humidity       -> 48
home/garage/door/state              -> "closed"
home/garage/door/availability       -> "online"

Publique state e availability como retained messages para que um dashboard iniciado depois saiba imediatamente a situação atual. Comandos não devem ser retidos; caso contrário, um dispositivo que reinicia vai repetir o "abra o portão da garagem" de ontem. Para um tratamento mais aprofundado de cômodos, integrações e discovery do Home Assistant, veja o guia de estrutura de topics MQTT para casa inteligente.

Exemplo de hierarquia de topics para frota de veículos

Os dados de frota se organizam em torno dos veículos, e os consumidores geralmente querem o quadro completo de um veículo ou um tipo de dado em toda a frota.

fleet/<region>/<vehicleId>/telemetry/<stream>
fleet/<region>/<vehicleId>/events/<eventType>
fleet/<region>/<vehicleId>/cmd/<command>
fleet/<region>/<vehicleId>/status

fleet/eu-west/van-0142/telemetry/gps      -> {"lat": 51.51, "lon": -0.12, "spd": 34}
fleet/eu-west/van-0142/telemetry/engine   -> {"rpm": 1800, "coolant": 88}
fleet/eu-west/van-0142/events/harsh-brake -> {"ts": 1792130400, "g": 0.52}
fleet/eu-west/van-0142/cmd/locate         -> {}
fleet/eu-west/van-0142/status             -> "online"

Decisões que vale a pena copiar:

• Região antes do veículo. Isso permite dividir o processamento por região mais tarde, por exemplo com assinaturas compartilhadas por grupo de workers regional.
• Streams em vez de um payload gigante. GPS a cada segundo e dados do motor a cada trinta segundos não devem ser forçados na mesma mensagem.
• Comandos por veículo. Cada veículo se inscreve em fleet/<region>/<its id>/cmd/# e em mais nada.

Exemplo de hierarquia de topics para fábrica

Na manufatura, a hierarquia de equipamentos já existe na documentação da planta, então a árvore deve espelhá-la. Uma versão simplificada:

<site>/<area>/<line>/<machine>/<namespace>/<detail>

plant1/assembly/line1/robot2/telemetry/joint-temps
plant1/assembly/line1/robot2/state
plant1/assembly/line1/robot2/alarms/overtemp
plant1/machining/line3/cnc1/telemetry/spindle
plant1/machining/line3/cnc1/cmd/stop

Mantenha o vocabulário de namespaces pequeno e fixo: telemetry, state, alarms, events, cmd. Quando um integrador inventa data, values e measurements para a mesma coisa, cada consumidor precisa aprender três padrões.

Exemplo de hierarquia de topics para monitoramento de energia

Projetos de energia misturam medidores, inversores e baterias em vários prédios. A árvore separa a localização física da grandeza energética medida.

energy/<site>/<building>/<meterId>/<quantity>

energy/campus-a/building-3/main-meter/power       -> 42.7   (kW)
energy/campus-a/building-3/main-meter/energy      -> 18233.4 (kWh)
energy/campus-a/building-3/pv-inverter-1/power    -> 12.1
energy/campus-a/building-3/battery-1/soc          -> 76
energy/campus-a/building-3/battery-1/cmd/mode     -> "discharge"

Inclua as unidades na documentação ou no payload, nunca no próprio topic. Um topic como .../power_kw fica errado no dia em que alguém publica em watts. Um payload JSON como {"v": 42.7, "unit": "kW", "ts": 1792130400} mantém o topic estável e a leitura autodescritiva.

Terminando com uma árvore no estilo ISA-95

Quando um projeto cresce além de uma planta ou começa a alimentar um Unified Namespace, ele normalmente converge para uma árvore no estilo ISA-95: empresa, planta, área, linha, célula ou máquina e, por fim, um namespace de dados. Esse também é o formato que o ConnectMQ usa ao republicar dados Sparkplug B em topics legíveis. Uma mensagem Sparkplug em

spBv1.0/factory1/DDATA/line1/cnc1

é decodificada e republicada em

connectmq/factory1/production/line1/cnc1/telemetry

Isso dá um exemplo completo da estrutura de destino:

<enterprise>/<site>/<area>/<line>/<machine>/<namespace>

connectmq/factory1/production/line1/cnc1/telemetry
connectmq/factory1/production/line1/cnc1/state
connectmq/factory1/production/line2/press4/telemetry
connectmq/factory1/quality/lab/cmm1/events

O portal do ConnectMQ reconhece topics ISA-95 e Unified Namespace e mostra os dispositivos agrupados por esses níveis, então uma árvore disciplinada compensa diretamente na visão de dispositivos. O artigo sobre topics MQTT ISA-95 explica cada nível e suas armadilhas, e o guia de Sparkplug B e Unified Namespace mostra como os dois se encaixam.

Comparando as quatro árvores

A profundidade importa em brokers reais. Alguns brokers limitam os níveis de topic, e cada nível extra custa bytes em cada mensagem. O servidor MQTT público (gratuito) em broker.connectmq.com, por exemplo, permite até 8 níveis de topic, então um prefixo de demonstração como connectmq/demo/<id> deixa cinco níveis para a sua própria árvore.

Teste uma árvore no broker público

Você pode prototipar qualquer uma dessas hierarquias no servidor MQTT público antes de se comprometer com ela. Use um prefixo único, porque ele pode ser lido por todos, e mantenha ali apenas dados de teste, nunca dados de produção.

# Assinante: todos os estados de dispositivos da sua casa de demonstração
mosquitto_sub -h broker.connectmq.com -p 1883 -i tree-sub-a91c \
  -t 'connectmq/demo/a91c/home/+/+/state' -v

# Publicador: um estado de lâmpada retido
mosquitto_pub -h broker.connectmq.com -p 1883 -i tree-pub-a91c -r \
  -t 'connectmq/demo/a91c/home/livingroom/lamp/state' \
  -m '{"on": true, "brightness": 70}'

Esse exemplo usa sete níveis, o que cabe no limite do servidor MQTT público. Se o assinante vê o estado da lâmpada, o seu plano de curingas funciona. Depois, experimente connectmq/demo/a91c/home/livingroom/# e confirme que ele retorna apenas a sala de estar. Se a árvore for novidade para você, o guia de curingas MQTT explica exatamente como + e # correspondem a cada nível, e o tutorial de MQTT cobre o básico de publish e subscribe.

Erros comuns em hierarquias de topics

• Colocar o tipo de dado primeiro. temperature/kitchen espalha cada dispositivo por muitos ramos e torna desajeitadas as assinaturas por dispositivo.
• Codificar valores nos topics. Ter home/lamp/on e home/lamp/off como topics significa que os consumidores precisam se inscrever nos dois; publique o valor como payload.
• Um topic por ID de mensagem ou timestamp. Topics são endereços, não registros. Topics únicos por mensagem incham o armazenamento retido e as listas de topics.
• Separadores misturados. line-1, line_1 e Line1 na mesma árvore vão acabar quebrando o curinga de alguém. Escolha um estilo.
• Sem ramo de comandos. Se os comandos compartilham um topic com a telemetria, os dispositivos recebem os próprios dados de volta e precisam de filtragem extra.

Comece a usar o ConnectMQ

Quando a sua árvore estiver pronta para dispositivos reais, execute-a em um broker MQTT na nuvem com TLS e credenciais privadas, como o broker MQTT gerenciado do ConnectMQ. Crie um broker Serverless gratuito em app.connectmq.com, sem cartão de crédito, e veja a sua hierarquia se preencher com o explorador de topics ao vivo e a visão de dispositivos ISA-95.

Perguntas frequentes

Qual deve ser a profundidade de uma hierarquia de topics MQTT?

Profunda o suficiente para identificar a origem e o tipo de dado, geralmente de quatro a seis níveis. Mais níveis adicionam bytes a cada mensagem e podem esbarrar em limites do broker sem acrescentar estrutura útil.

O ID do dispositivo ou o tipo de dado deve vir primeiro?

Coloque primeiro a localização e a identidade do dispositivo e depois o tipo de dado. Assim todos os dados de um dispositivo ficam sob um único ramo, e curingas + ainda conseguem selecionar um tipo de dado em vários dispositivos.

Posso mudar minha hierarquia de topics depois?

Sim, mas todo publicador e todo assinante precisa mudar junto. Um caminho de migração comum é publicar nas árvores antiga e nova durante um período de transição e aposentar a antiga quando os consumidores tiverem migrado.

Preciso de ISA-95 em um projeto pequeno?

Não. Uma árvore simples como a do exemplo de casa inteligente funciona bem em projetos pequenos. Árvores no estilo ISA-95 compensam quando várias plantas, equipes ou sistemas compartilham um único namespace.