O namespace de topics do Sparkplug é a estrutura fixa que toda mensagem Sparkplug B usa: spBv1.0/group_id/message_type/edge_node_id/device_id. Neste guia você vai aprender o que cada elemento significa, como nomear groups, nodes e devices para mantê-los gerenciáveis e quais assinaturas com wildcard você precisa para monitoramento, comandos e depuração.
Por que o Sparkplug fixa a estrutura de topics
O MQTT puro permite inventar qualquer hierarquia de topics. Essa liberdade é ótima em um projeto isolado e dolorosa em uma planta inteira, como uma fábrica em Manaus ou uma mineradora com vários sites, onde cada integrador escolhe um esquema diferente. O Sparkplug elimina essa escolha. Os topics seguem um único padrão, então qualquer aplicação host compatível com Sparkplug consegue descobrir todos os edge nodes e devices sem configuração específica por site.
A contrapartida é que o topic não descreve a hierarquia da sua planta além de group, node e device. Site, área e linha ficam nos IDs de group e node ou dentro dos nomes das métricas. Essa distinção importa quando você projeta um Unified Namespace, e voltamos a ela mais adiante.
O namespace de topics do Sparkplug elemento por elemento
spBv1.0/{group_id}/{message_type}/{edge_node_id}/{device_id}
| Elemento | Exemplo | Significado | Obrigatório |
|---|---|---|---|
| Namespace | spBv1.0 |
Identifica a versão do payload Sparkplug B | Sempre |
| group_id | factory1 |
Agrupamento lógico de edge nodes | Sempre |
| message_type | DDATA |
Que tipo de mensagem é esta | Sempre |
| edge_node_id | line1 |
O gateway ou edge node | Sempre |
| device_id | cnc1 |
Um device atrás do edge node | Apenas em mensagens D |
Namespace: spBv1.0
O primeiro nível é sempre a string literal spBv1.0. Ela informa aos consumidores que o payload é Sparkplug B em Protobuf. O antigo Sparkplug A usava spAv1.0 e está descontinuado. Se você vir um topic que começa com qualquer outra coisa, ele não é Sparkplug B, mesmo que o payload por acaso seja Protobuf.
group_id
O group ID agrupa edge nodes de forma lógica. Muitas equipes usam um site ou uma área, por exemplo plant-izmir ou packaging. Uma aplicação host costuma assinar por group, então escolha groups que correspondam à forma como você quer dividir o monitoramento e as permissões.
message_type
Este é o coração do namespace. Ele diz ao consumidor como tratar o payload:
| Tipo | Remetente | Finalidade |
|---|---|---|
| NBIRTH | Edge node | O node ficou online e anuncia todas as métricas do node |
| NDEATH | Broker (will) ou node | O node ficou offline |
| DBIRTH | Edge node | O device ficou online e anuncia as métricas do device |
| DDEATH | Edge node | O device ficou offline |
| NDATA | Edge node | Valores alterados de métricas do node |
| DDATA | Edge node | Valores alterados de métricas do device |
| NCMD | Aplicação host | Comando para o edge node, por exemplo rebirth |
| DCMD | Aplicação host | Comando para um device, por exemplo escrita de setpoint |
| STATE | Aplicação host | Status online/offline do host |
Os tipos de birth e death carregam o modelo de estado que torna o Sparkplug confiável. Nosso guia sobre certificados de birth e death do Sparkplug explica o ciclo de vida completo.
edge_node_id
O edge node ID identifica o gateway, CLP ou software que mantém a conexão MQTT. Ele precisa ser único dentro do seu group. Dois nodes com o mesmo ID vão sobrescrever os births um do outro e corromper os números de sequência, o que é um dos bugs de comissionamento mais comuns.
device_id
Os devices ficam atrás de um edge node: uma CNC, um inversor, um medidor Modbus. Mensagens em nível de device (DBIRTH, DDEATH, DDATA, DCMD) acrescentam o device ID como quinto nível. Mensagens em nível de node terminam no edge node ID.
O topic STATE
A mensagem STATE é a exceção ao padrão. No Sparkplug 3.0 ela é spBv1.0/STATE/{host_id}, com um pequeno payload JSON, publicada como retained pela Primary Host Application do Sparkplug. Implementações 2.2 mais antigas usavam STATE/{host_id} sem o prefixo do namespace. Se você roda versões mistas, verifique qual formato o seu host e os seus nodes esperam.
Regras de nomenclatura que poupam trabalho depois
A especificação proíbe os caracteres especiais do MQTT +, # e / dentro dos IDs de group, node e device, porque eles quebrariam os níveis do topic. Além disso, algumas convenções ajudam:
- Use apenas letras minúsculas, dígitos e hifens. Misturar maiúsculas e minúsculas convida a divergências entre sistemas.
- Mantenha os IDs estáveis. Renomear um edge node cria um novo node do ponto de vista do host, e o histórico pode ficar dividido.
- Não codifique em um ID valores que mudam, como versão de firmware ou endereço IP.
- Coloque a hierarquia mais profunda nos nomes das métricas, por exemplo
Spindle/Speed, em vez de tentar adicionar níveis ao topic. - Documente o significado de cada group para que novos integradores posicionem os nodes corretamente.
- Mantenha os IDs curtos. Eles se repetem em todos os topics e aparecem em todos os logs.
Assinaturas úteis
A estrutura fixa torna as assinaturas com wildcard previsíveis. Estes são os padrões que você mais vai usar:
spBv1.0/# everything Sparkplug on the broker
spBv1.0/factory1/# everything in one group
spBv1.0/+/NBIRTH/# every node birth, all groups
spBv1.0/+/DDATA/+/+ every device data message
spBv1.0/factory1/+/line1/# everything from one edge node
spBv1.0/factory1/DDATA/line1/cnc1 one device's data
spBv1.0/STATE/+ host application status
Você pode testá-los no servidor MQTT público (gratuito), que serve apenas para testes e protótipos. Ele pode ser lido por qualquer pessoa, então use um group ID aleatório e nunca publique dados reais da planta lá:
mosquitto_sub -h broker.connectmq.com -p 1883 -i ns-explorer-5c21 -t "spBv1.0/demo-5c21/#" -v
Em um segundo terminal, publique uma mensagem de teste em um topic de dados de device. O payload aqui é texto simples só para verificar o roteamento; um node real envia Protobuf:
mosquitto_pub -h broker.connectmq.com -p 1883 -i ns-pub-5c21 -t "spBv1.0/demo-5c21/DDATA/line1/cnc1" -m "routing test"
Observe que os topics Sparkplug no servidor MQTT público usam cinco níveis, bem dentro do limite de oito níveis, então um simulador Sparkplug funciona lá sem alterações.
Navegando pelo namespace em um topic explorer
Um namespace fica muito mais fácil de entender quando você o vê como uma árvore. No ConnectMQ, o topic explorer do portal mostra os topics spBv1.0 à medida que chegam e, como o broker decodifica Sparkplug B, você pode clicar em um topic DDATA e ler suas métricas em vez de bytes brutos. Isso agiliza responder a perguntas de comissionamento, como se um novo edge node já publicou o seu birth ou quais devices ficam sob determinado node.
O ConnectMQ também pode republicar dados Sparkplug em topics ISA-95. Uma mensagem em spBv1.0/factory1/DDATA/line1/cnc1 fica disponível em connectmq/factory1/production/line1/cnc1/telemetry, o que é mais amigável para dashboards e ferramentas que esperam uma hierarquia de planta.
Topics Sparkplug e o Unified Namespace
O namespace de topics do Sparkplug é plano por design: group, node, device. Um Unified Namespace normalmente segue o ISA-95: empresa, site, área, linha, célula. Essas duas visões coexistem em muitas arquiteturas. O Sparkplug cuida do transporte confiável e consciente de estado a partir da borda, e uma árvore ISA-95 oferece a pessoas e aplicações um modelo navegável, que também serve de base para um gêmeo digital da planta. Para o raciocínio de design, leia MQTT, Sparkplug B e o Unified Namespace e, para o contexto mais amplo, veja o guia de IoT Industrial com MQTT.
Solução de problemas com topics
| Sintoma | Causa provável | O que verificar |
|---|---|---|
| O host nunca vê um node | Erro de digitação ou maiúsculas/minúsculas erradas em spBv1.0 |
A string exata do namespace, que diferencia maiúsculas de minúsculas |
| Dois nodes fazem rebirth sem parar | Edge node ID duplicado em um group | IDs únicos por group |
| Comandos não são recebidos | O node não assinou seus topics NCMD/DCMD | O node assina spBv1.0/group/NCMD/node e DCMD |
| Dados do device ignorados | DDATA enviado antes do DBIRTH | O device precisa publicar o DBIRTH primeiro |
| Status do host ausente | Host e nodes discordam sobre o formato do topic STATE | Topic STATE da 2.2 versus 3.0 |
Quando suspeitar de um problema de topic, assine spBv1.0/your-group/# com saída detalhada e observe a ordem das mensagens durante a inicialização. Os births devem chegar primeiro, depois os dados.
Escolhendo onde rodar
O tráfego Sparkplug funciona em qualquer broker MQTT compatível, mas plantas em produção precisam de credenciais, TLS e alguém responsável pela disponibilidade. Um broker MQTT gerenciado cuida da infraestrutura para que a sua equipe possa se concentrar em nomenclatura, modelagem e integração. Quando births e dados estiverem fluindo, o próximo passo é ler os próprios payloads, assunto do nosso guia de payload Sparkplug B.
Comece com o ConnectMQ
Crie um broker no plano Serverless (Free) em app.connectmq.com, sem cartão de crédito. Conecte o seu edge node com as credenciais geradas via TLS na porta 8883 e navegue pelo namespace de topics do Sparkplug, decodificado e organizado, no topic explorer do ConnectMQ.
Perguntas frequentes
Posso adicionar mais níveis a um topic Sparkplug?
Não. O namespace de topics do Sparkplug é fixo em quatro níveis para mensagens de node e cinco para mensagens de device. Coloque hierarquia adicional nos nomes das métricas ou mapeie os dados para uma árvore ISA-95.
O group ID é o mesmo que um site?
Pode ser, mas a especificação o define apenas como um agrupamento lógico de edge nodes. Muitas equipes usam um group por site ou por área, dependendo de como as aplicações host são delimitadas.
Por que o topic STATE tem um formato diferente?
As mensagens STATE vêm de aplicações host, não de edge nodes, então não seguem o padrão de node e device. No Sparkplug 3.0 o topic é spBv1.0/STATE/{host_id}.
Os topics Sparkplug diferenciam maiúsculas de minúsculas?
Sim. Topics MQTT diferenciam maiúsculas de minúsculas, então spBv1.0 e SPBV1.0 são topics diferentes, assim como Line1 e line1.
