Barium — Integração MQTT (OpenBarium)

Documento de uso interno/restrito

Este documento descreve a API de desenvolvedor do protocolo de integração do anunciador de áudio Barium. O conteúdo é de uso interno/restrito e não deve ser publicado no portal público.

Este documento especifica o protocolo OpenBarium e as mensagens trocadas entre o anunciador de áudio BARIUM e um broker MQTT durante a operação do produto. A estrutura de tópicos, o formato das mensagens e o fluxo de informações descritos aqui são tudo o que é necessário para integrar o Barium a qualquer software de gestão.

Fonte: BARIUM — Anunciador de mensagens, Manual de Integração MQTT v1.11 (nov/2021).

Visão geral do protocolo

Todas as mensagens utilizam formato JSON.
Espera-se que o broker MQTT tenha suporte ao padrão MQTT V3.1.
Algumas mensagens são enviadas de forma independente e automática pelo equipamento (ex.: keepalive, status, info).
As demais mensagens são comandos enviados pelo servidor (reproduzir áudio, ajustar relógio, ler/ajustar configuração) — boa parte exige resposta (ack).

Configuração do MQTT no equipamento

A conexão MQTT do Barium é configurada na tela de configuração MQTT do equipamento (página de configuração WiFi servida pelo próprio dispositivo). Os campos seguem o objeto de configuração /config_mqtt.json descrito mais adiante.

config mqtt

Campo da tela	Parâmetro (`/config_mqtt.json`)	Descrição
Connection	`brokerconnectiontype`	Tipo de conexão: sem broker, Accelero Cloud ou broker customizado
Facility ID	`brokerfacilityid`	Facility ID da instalação (ver Facility ID)
TLS	`brokerusetls`	Habilita conexão TLS com o broker
Broker	`brokermqtt`	URL/endereço do broker
Port	`brokerport`	Porta do broker (ex.: `1883`)
User name	`brokerusername`	Usuário do broker
Password	`brokerpass`	Senha do usuário
Device Id	`brokerboardid`	Identificador do Barium usado no tópico (Device ID)

Conceitos básicos

Facility ID

Toda instalação deve possuir um Facility ID, identificador único da instalação. Por exemplo, em um condomínio fictício o Facility ID poderia ser cond5991.

O Facility ID faz parte do nome do tópico na comunicação com o broker MQTT, tanto nas mensagens publicadas (publish) quanto nas recebidas (subscribe). Para garantir a maior compatibilidade possível, recomenda-se o formato:

Máximo de 16 caracteres.
Caracteres utilizados — regexp [a-zA-Z0-9].

Device ID

Com exceção do tópico broadcast, todas as mensagens têm como origem ou destino um Barium específico. Cada equipamento possui um Device ID configurável que faz parte do tópico (ex.: barium07A6175A). O Device ID é configurado no campo Device Id da tela MQTT e corresponde ao parâmetro brokerboardid.

Estrutura de tópicos MQTT

A comunicação segue regras básicas na estrutura de tópicos para garantir que as mensagens sejam capturadas de forma eficiente.

O Facility ID sempre é o primeiro nível na estrutura. Por exemplo, um client que faça subscribe no tópico abaixo receberá todas as mensagens enviadas, tanto pelo servidor quanto pelos equipamentos:

cond5991/#

Todos os equipamentos Barium fazem subscribe automático no tópico broadcast abaixo, usado pelo servidor para enviar mensagens de controle, como keepalives:

cond5991/broadcast/to

Com exceção desse tópico broadcast, o restante das mensagens sempre tem como origem ou destino um Barium específico, identificado pelo Device ID no tópico:

cond5991/barium07A6175A/to     (servidor → Barium específico)
cond5991/barium88/from         (Barium → servidor)

A tabela a seguir resume a forma mais simples de realizar uma integração (facility = Facility ID; deviceid = Device ID do Barium):

Tópico	Origem	Destino
`facility/broadcast/to`	Servidor	Todos os dispositivos
`facility/deviceid/to`	Servidor	Equipamento específico
`facility/deviceid/from/#`	Equipamento específico	Servidor
`facility/+/from/#`	Todos os equipamentos	Servidor

Sobre ${alias} nos tópicos de resposta

No manual, os tópicos de resposta (ack) aparecem como ${facilityid}/${alias}/from/ack. O ${alias} corresponde ao mesmo Device ID (${deviceid}) do equipamento — o manual usa os dois termos de forma intercambiável.

Identificação das mensagens

Todas as mensagens são formatadas em JSON. A maior parte possui a chave msgid, número identificador da mensagem.

O valor de msgid deve estar entre 0 e 60000.
Nas mensagens que exigem resposta (ex.: confirmação de alteração de configuração), a resposta sempre deve referenciar o msgid original. Caso a resposta use um msgid diferente, a mensagem é ignorada.

Valores JSON

É importante respeitar o tipo de dado (string/int) na formatação JSON. Mensagens que não respeitem o tipo esperado são ignoradas e não tratadas pelo equipamento.

Dada a especificação:

{
  "msgID": "integer(5)",
  "timestamp": "string(12)"
}

Mensagens inválidas (tipo incorreto):

{
  "msgID": "123",
  "timestamp": "190101121314"
}

{
  "msgID": 123,
  "timestamp": 190101121314
}

Mensagem válida:

{
  "msgID": 123,
  "timestamp": "190101121314"
}

Alguns valores possuem tamanho máximo, indicado entre parênteses (ex.: string(12)). Esse limite deve ser respeitado para que a mensagem seja válida — "msgID": 123456 é inválido para um campo integer(5).

Há campos obrigatórios e opcionais. Caso falte um valor obrigatório, a mensagem é ignorada. No caso de valores opcionais, a ausência implica o uso de um valor default pré-determinado.

Mensagens enviadas pelo servidor

Salvo indicação contrária, o tópico de envio dessas mensagens é ${facilityid}/${deviceid}/to e o tópico de resposta (quando há) é ${facilityid}/${deviceid}/from/ack.

Solicitar envio de status (`get_info`)

O servidor pode solicitar ao equipamento que envie uma mensagem informando sua configuração atual.

Chave	Valor/tipo	Observações
`cmd`	`"get_info"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS

{
  "cmd": "get_info",
  "timestamp": "210702123456"
}

Resposta: não há resposta direta. O equipamento enviará imediatamente uma mensagem de atualização de status (ver Info).

Reproduzir áudio (`play`)

O servidor pode solicitar ao equipamento que reproduza um arquivo de áudio localizado em sua memória ou em uma URL.

Chave	Valor/tipo	Observações
`cmd`	`"play"`	Valor fixo
`msgid`	int(5)	0 a 60000
`mode`	string(16)	Origem do arquivo: `"file"` = arquivo no Barium; `"http"` = arquivo em uma URL
`file`	string(128)	Nome/URL do arquivo mp3
`volume`	int(3)	Nível de volume a utilizar (0 a 100)

{
  "cmd": "play",
  "msgid": 1674,
  "mode": "file",
  "file": "bom_dia.mp3"
}

Resposta — tópico ${facilityid}/${deviceid}/from/ack:

Chave	Valor/tipo	Observações
`cmd`	`"play_ack"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	ID da mensagem original
`status`	string	`"done"` ou `"error"`

{
  "cmd": "play_ack",
  "timestamp": "210702123456",
  "msgid": 1674,
  "status": "done"
}

Interromper reprodução (`stop`)

Finaliza a reprodução de um arquivo de áudio comandada anteriormente.

Chave	Valor/tipo	Observações
`cmd`	`"stop"`	Valor fixo
`msgid`	int(5)	ID da mensagem — 0 a 60000

{
  "cmd": "stop",
  "msgid": 1675
}

Resposta — tópico ${facilityid}/${deviceid}/from/ack:

Chave	Valor/tipo	Observações
`cmd`	`"stop_ack"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	ID da mensagem original
`status`	string	`"done"` ou `"error"`

{
  "cmd": "stop_ack",
  "timestamp": "210702123456",
  "msgid": 1675,
  "status": "done"
}

Pausar reprodução (`pause`)

Suspende a reprodução de um arquivo de áudio comandada anteriormente.

Chave	Valor/tipo	Observações
`cmd`	`"pause"`	Valor fixo
`msgid`	int(5)	ID da mensagem — 0 a 60000

{
  "cmd": "pause",
  "msgid": 1676
}

Resposta — tópico ${facilityid}/${deviceid}/from/ack:

Chave	Valor/tipo	Observações
`cmd`	`"pause_ack"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	ID da mensagem original
`status`	string	`"done"` ou `"error"`

{
  "cmd": "pause_ack",
  "timestamp": "210702123456",
  "msgid": 1676,
  "status": "done"
}

Continuar reprodução (`resume`)

Retoma a reprodução de um arquivo de áudio suspensa anteriormente.

Chave	Valor/tipo	Observações
`cmd`	`"resume"`	Valor fixo
`msgid`	int(5)	ID da mensagem — 0 a 60000

{
  "cmd": "resume",
  "msgid": 1677
}

Resposta — tópico ${facilityid}/${deviceid}/from/ack:

Chave	Valor/tipo	Observações
`cmd`	`"resume_ack"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	ID da mensagem original
`status`	string	`"done"` ou `"error"`

{
  "cmd": "resume_ack",
  "timestamp": "210702123456",
  "msgid": 1677,
  "status": "done"
}

Ajustar relógio/calendário (`set_date`)

Embora o Barium ajuste o calendário via NTP e mantenha relógio interno com bateria, em alguns casos é necessário ajustar o relógio manualmente.

Chave	Valor/tipo	Observações
`cmd`	`"set_date"`	Valor fixo
`timestamp`	string(12)	Nova data/hora no formato YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000

{
  "cmd": "set_date",
  "timestamp": "210702120132",
  "msgid": 8431
}

Resposta:

{
  "cmd": "datetime_adj",
  "timestamp": "210702120132"
}

Arquivos de configuração

A leitura e o ajuste de parâmetros usam um par de comandos genéricos: getconfig / getconfig_ack (leitura) e setconfig / setconfig_ack (ajuste). O campo file identifica o arquivo de configuração; o objeto data contém os parâmetros, que variam por arquivo.

Ler arquivos de configuração (`getconfig`)

Lê os parâmetros de configuração do Barium. A mensagem contém o nome do arquivo; a resposta contém os dados.

Mensagem — tópico ${facilityid}/${deviceid}/to:

Chave	Valor/tipo	Observações
`cmd`	`"getconfig"`	Valor fixo
`msgid`	int(5)	0 a 60000
`file`	string(32)	Nome do arquivo a ler

{
  "cmd": "getconfig",
  "msgid": 16049,
  "file": "/config_time.json"
}

Resposta — tópico ${facilityid}/${deviceid}/from/ack. O cabeçalho (cmd: "getconfig_ack", timestamp, msgid, file) é comum; o objeto data traz os campos específicos do arquivo lido (ver tabelas a seguir).

{
  "cmd": "getconfig_ack",
  "timestamp": "210702120132",
  "msgid": 16049,
  "file": "/config_time.json",
  "data": {
    "ntpon": 1,
    "ntphost": "ntp.iongrade.com.br",
    "ntpzone": "-3",
    "ntpdaylightsaving": 0
  }
}

Ajustar arquivos de configuração (`setconfig`)

Envia parâmetros de configuração do Barium. A mensagem tem um cabeçalho com o nome do arquivo e o objeto data com os campos a alterar. Os dados são armazenados em memória não-volátil.

info

Nas mensagens setconfig os parâmetros não são obrigatórios — podem ser enviados apenas os que se deseja alterar; os demais são mantidos intactos. Algumas mudanças têm efeito imediato; outras exigem reboot (indicado em cada arquivo abaixo).

Mensagem — tópico ${facilityid}/${deviceid}/to:

Chave	Valor/tipo	Observações
`cmd`	`"setconfig"`	Valor fixo
`msgid`	int(5)	0 a 60000
`file`	string(32)	Nome do arquivo a ajustar
`data`	object	Parâmetros do comando (depende do arquivo)

{
  "cmd": "setconfig",
  "msgid": 8431,
  "file": "/config_volume.json",
  "data": {
    "volume": "60"
  }
}

Resposta (comum a todos os setconfig) — tópico ${facilityid}/${deviceid}/from/ack:

Chave	Valor/tipo	Observações
`cmd`	`"setconfig_ack"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	ID da mensagem original
`status`	string	`"done"` ou `"error"`

{
  "cmd": "setconfig_ack",
  "timestamp": "210702120132",
  "msgid": 8431,
  "status": "done"
}

Campos do objeto `data` por arquivo

As tabelas abaixo listam os campos do objeto data de cada arquivo de configuração. Os mesmos campos valem para a leitura (getconfig_ack) e para o ajuste (setconfig).

`/config_wifi.json` — WIFI

Parâmetros da conexão de rede WiFi. Exige reboot para ter efeito.

Chave	Valor/tipo	Observações
`fixip`	int(1)	0 = IP fixo; 1 = Usar DHCP
`ip`	string(15)	Endereço IP a utilizar
`dns`	string(15)	Endereço IP do servidor DNS
`gateway`	string(15)	Endereço IP do gateway
`subnet`	string(15)	Máscara da rede
`ssid`	string(32)	Nome da rede WiFi a conectar
`pass`	string(16)	Password
`authmode`	string(1)	`"0"` = OPEN; `"1"` = WEP; `"2"` = WPA_PSK; `"3"` = WPA2_PSK; `"4"` = WPA_WPA2_PSK; `"5"` = WPA2_ENTERPRISE; `"6"` = WPA3_PSK; `"7"` = WPA2_WPA3_PSK

{
  "fixip": 1,
  "ip": "192.168.17.176",
  "gateway": "192.168.17.1",
  "dns": "192.168.17.1",
  "subnet": "255.255.0.0",
  "ssid": "minharedewifi",
  "pass": "senhasecreta",
  "authmode": "2"
}

`/config_mqtt.json` — MQTT

Parâmetros da conexão com o broker MQTT (correspondem à tela MQTT CONFIG). Exige reboot para ter efeito.

Chave	Valor/tipo	Observações
`brokerconnectiontype`	string(1)	`"0"` = Sem conexão com broker; `"1"` = Accelero Cloud; `"2"` = Custom broker
`brokermqtt`	string(64)	URL do broker
`brokerport`	string(5)	Porta do broker
`brokerusername`	string(16)	Usuário do broker
`brokerpass`	string(16)	Senha do usuário
`brokerusetls`	int(1)	0 = Conexão normal; 1 = Usar TLS
`brokerfacilityid`	string(32)	Facility ID
`brokerboardid`	string(32)	Device ID do Barium

{
  "brokerconnectiontype": "1",
  "brokermqtt": "meumosquitto.com.br",
  "brokerport": "1883",
  "brokerusername": "admin",
  "brokerpass": "senhasecreta",
  "brokerusetls": 0,
  "brokerfacilityid": "TESTE",
  "brokerboardid": "barium07A6175A"
}

Resíduo de copy-paste na fonte

No manual, a observação do campo brokerboardid aparece como "Aurum Id" (e o exemplo usa "catraca1"), resquício de copy-paste do manual da controladora Aurum. Normalizado aqui para Device ID do Barium — semanticamente é o identificador do próprio anunciador no tópico MQTT.

`/config_time.json` — TIME

Parâmetros da conexão com o servidor NTP. Efeito imediato.

Chave	Valor/tipo	Observações
`ntpon`	int(1)	0 = Não usa servidor NTP; 1 = Usa servidor NTP
`ntphost`	string(64)	URL do servidor NTP
`ntpzone`	int(3)	Timezone
`ntpregion`	string(16)	Região
`ntpdaylightsaving`	int(1)	0 = Não ajusta horário de verão; 1 = Ajusta horário de verão

{
  "ntpon": 1,
  "ntphost": "ntp.iongrade.com.br",
  "ntpzone": "-3",
  "ntpregion": "20",
  "ntpdaylightsaving": 0
}

note

Na tabela da fonte o campo de horário de verão aparece como int(1) sem nome; o exemplo JSON usa ntpdaylightsaving. Adotado ntpdaylightsaving (provável erro de digitação na fonte).

`/config_volume.json` — VOLUME

Volume de reprodução de áudio. Efeito imediato.

Chave	Valor/tipo	Observações
`volume`	string(3)	Volume do áudio (`"0"` a `"100"`)

{
  "volume": "60"
}

`/config_filecmd.json` — INPUT CMD

Arquivo de áudio reproduzido quando comandado pela entrada digital de comando. Efeito imediato.

Chave	Valor/tipo	Observações
`filename`	string(32)	Nome do arquivo a ser reproduzido

{
  "filename": "bom_dia.mp3"
}

note

A tabela de setconfig da fonte indica filename como string(3), enquanto a leitura (getconfig_ack) indica string(32). Adotado string(32), coerente com os nomes de arquivo dos exemplos (provável erro de digitação na fonte).

Mensagens enviadas pelo Barium

Status

Quando o Barium se conecta ao broker, envia uma mensagem com seu status "connected" para que o servidor monitore o estado da comunicação. A mensagem é publicada com a flag retain_message ativa.

Tópico: ${facilityid}/${deviceid}/from/status

Chave	Valor/tipo	Observações
`cmd`	`"status"`	Valor fixo
`status`	string(12)	`"connected"` (*) ou `"disconnected"`

(*) A mensagem "disconnected" é enviada pelo broker via LWT (Last Will and Testament) — ou seja, publicada caso o broker detecte falha de comunicação com o Barium.

{
  "cmd": "status",
  "status": "connected"
}

Resposta: não há.

Info

Ao ser ligado, e a cada 60 minutos, o Barium envia uma mensagem com seu estado atual para que o servidor monitore dados relevantes. A mensagem é publicada com a flag retain_message ativa.

Tópico: ${facilityid}/${deviceid}/from/info

Chave	Valor/tipo	Observações
`cmd`	`"info"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`boardid`	string	Identificador único do equipamento
`serialid`	string	Número de série de fabricação
`version`	string	Versão de firmware em uso
`media`	string	Mídia de comunicação: `"wired"` ou `"wireless"`
`iplocal`	string	Configuração IP — endereço local
`ipdns`	string	Configuração IP — servidor DNS
`ipgateway`	string	Configuração IP — gateway
`subnetmask`	string	Configuração IP — máscara de rede

{
  "cmd": "info",
  "timestamp": "210703123456",
  "boardid": "barium75123456",
  "serialid": "9991",
  "version": "1.0.1",
  "media": "wireless",
  "iplocal": "192.168.0.77",
  "ipdns": "8.8.8.8",
  "ipgateway": "192.168.0.1",
  "subnetmask": "255.255.255.0"
}

Resposta: não há.

Keepalive

A cada 30 segundos o Barium envia uma mensagem informando que está ativo.

Tópico: ${facilityid}/${deviceid}/from/change-ap

Chave	Valor/tipo	Observações
`cmd`	`"keepalive"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`uptime`	int(9)	Tempo de operação após o último reset
`nrestart`	int(9)	Quantidade de resets desde a fabricação
`ncmqtt`	int(9)	Quantidade de reconexões ao broker após o reset

{
  "cmd": "keepalive",
  "timestamp": "210703123456",
  "uptime": 15398,
  "nrestart": 23,
  "ncmqtt": 1
}

Resposta: não há.

Documentos relacionados

Barium — Fabricação — montagem de fábrica, placa ESP32 e pinagem interna.

Visão geral do protocolo​

Configuração do MQTT no equipamento​

Conceitos básicos​

Facility ID​

Device ID​

Estrutura de tópicos MQTT​

Identificação das mensagens​

Valores JSON​

Mensagens enviadas pelo servidor​

Solicitar envio de status (get_info)​

Reproduzir áudio (play)​

Interromper reprodução (stop)​

Pausar reprodução (pause)​

Continuar reprodução (resume)​

Ajustar relógio/calendário (set_date)​

Arquivos de configuração​

Ler arquivos de configuração (getconfig)​

Ajustar arquivos de configuração (setconfig)​

Campos do objeto data por arquivo​

/config_wifi.json — WIFI​

/config_mqtt.json — MQTT​

/config_time.json — TIME​

/config_volume.json — VOLUME​

/config_filecmd.json — INPUT CMD​

Mensagens enviadas pelo Barium​

Status​

Info​

Keepalive​

Documentos relacionados​

Visão geral do protocolo

Configuração do MQTT no equipamento

Conceitos básicos

Facility ID

Device ID

Estrutura de tópicos MQTT

Identificação das mensagens

Valores JSON

Mensagens enviadas pelo servidor

Solicitar envio de status (`get_info`)

Reproduzir áudio (`play`)

Interromper reprodução (`stop`)

Pausar reprodução (`pause`)

Continuar reprodução (`resume`)

Ajustar relógio/calendário (`set_date`)

Arquivos de configuração

Ler arquivos de configuração (`getconfig`)

Ajustar arquivos de configuração (`setconfig`)

Campos do objeto `data` por arquivo

`/config_wifi.json` — WIFI

`/config_mqtt.json` — MQTT

`/config_time.json` — TIME

`/config_volume.json` — VOLUME

`/config_filecmd.json` — INPUT CMD

Mensagens enviadas pelo Barium

Status

Info

Keepalive

Documentos relacionados