Skip to main content

Palladium — Integrações (MQTT e Webservice Cloud)

Documentação restrita

Este documento descreve as APIs de integração do monitor de ruídos Palladium. O conteúdo é de uso interno/restrito e não deve ser publicado no portal público.

O monitor de ruídos Palladium expõe uma única integração com duas faces, cobrindo sempre o mesmo conjunto de eventos — alarme, reconhecimento de alarme, alteração de configuração, dados atuais de configuração, telemetria (dados aferidos), keepalive/informações, status do Access Point e alteração de responsável — por transportes diferentes:

  • MQTT (OpenPalladium) — comunicação direta entre o equipamento e um broker MQTT. O Palladium publica seus eventos e assina comandos do servidor por tópicos JSON. É o transporte de baixo nível.
  • Webservice (Palladium Cloud) — o Palladium Cloud (nuvem da Iongrade) recebe as mensagens dos equipamentos e repassa os eventos selecionados a um endpoint HTTP do cliente, via POST application/x-www-form-urlencoded. É o mesmo evento, entregue pela nuvem em vez de exigir um broker próprio.

Em resumo: o MQTT é o protocolo direto do equipamento; o webservice é o mesmo evento repassado pela nuvem. Quem precisa de controle total (incluindo comandos do servidor → equipamento) integra via MQTT; quem só precisa receber eventos sem manter um broker integra via webservice do Cloud.

Fontes: Palladium — Manual de Integração (MQTT) v1.02 (dez/2021) e Palladium Cloud — Webservices v1.00 (abr/2020). Os exemplos JSON das mensagens MQTT do equipamento foram conferidos com os arquivos de referência mqtt/from_palladium.txt e mqtt/to_palladium.txt do repositório.

Normalização da fonte

O arquivo mqtt/from_palladium.txt traz o cabeçalho "MENSAGENS ENVIADAS PELA CONTROLADORA AURUM" — resíduo de copy-paste de outro produto. O conteúdo é, de fato, do Palladium (eventos de ruído, telemetria de dB, temperatura). Neste documento o conteúdo foi normalizado para Palladium e cruzado com o .docx autoritativo do manual MQTT.


Integração MQTT (OpenPalladium)

Todas as mensagens utilizam formato JSON. Espera-se que o broker MQTT tenha suporte ao padrão MQTT V3.1. O fluxo tem mensagens enviadas automaticamente pelo equipamento (keepalive, telemetria), mensagens enviadas pelo equipamento em eventos (alarme, reconhecimento) e mensagens enviadas pelo servidor (atualização de configuração, solicitação de status, reconhecimento remoto).

Configuração MQTT no equipamento

A interface de comunicação é definida na configuração local do Palladium. Em modo Nuvem, o equipamento conversa com o Palladium Cloud; em modo servidor especial, conecta-se a um broker MQTT informado manualmente. A tela CLOUD (acessível via Access Point WiFi do próprio equipamento, menu COMUNIC. > CLOUD) oferece duas opções de envio:

  • Automático — envia as informações para o Palladium Cloud; nenhuma informação adicional é necessária.
  • Servidor especial — envia para um broker MQTT informado pelo integrador. Exige os campos abaixo (obtidos com o fornecedor):
CampoDescrição
Facility IDIdentificador único da instalação (ver abaixo)
BrokerEndereço do servidor MQTT
PortPorta de comunicação do servidor MQTT
UsernameNome do usuário para acesso ao broker
PasswordSenha de acesso ao broker
Device idIdentificação única do Palladium

Facility ID e Device ID

Toda instalação possui um Facility ID, identificador único da instalação (ex.: em um condomínio fictício, cond5991). O Facility ID faz parte do nome do tópico, tanto nas mensagens publicadas (publish) quanto nas recebidas (subscribe). Recomenda-se o formato:

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

Cada equipamento possui ainda um Device ID configurável (ex.: palladium04c1), que também faz parte do tópico.

Estrutura de tópicos MQTT

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

cond5991/#

Todos os equipamentos 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 Palladium específico, identificado pelo Device ID:

cond5991/palladium04c1/to (servidor → equipamento específico)
cond5991/palladium04c1/from (equipamento → servidor)

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

TópicoOrigemDestino
facility/broadcast/toServidorTodos os equipamentos
facility/deviceid/toServidorEquipamento específico
facility/deviceid/from/#Equipamento específicoServidor
facility/+/from/#Todos os equipamentosServidor

As mensagens do equipamento são publicadas em subtópicos específicos sob from/ (ex.: from/alarm, from/data, from/info), detalhados em cada seção abaixo.

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.: uma atualização de configuração enviada pelo servidor), a resposta sempre deve referenciar o msgid original. Caso seja gerada uma resposta com msgid diferente, a mensagem é ignorada.

É importante respeitar o tipo de dado (string/int) na formatação JSON; mensagens com tipo incorreto são ignoradas. Alguns valores possuem tamanho máximo, indicado entre parênteses (ex.: string(12)), que deve ser respeitado. Há campos obrigatórios e opcionais; a ausência de um obrigatório invalida a mensagem, enquanto a ausência de um opcional implica o uso de um valor default.


Mensagens enviadas pelo servidor

Atualização de configuração (cfg_update)

O servidor envia dados de configuração para o Palladium. As novas configurações têm efeito imediato. A configuração cobre 4 faixas horárias (índices 0 a 3) para um dia da semana (weekday).

Tópico: ${facilityid}/${deviceid}/to

ChaveValor/tipoObservações
cmd"cfg_update"Valor fixo
timestampstring(12)YYMMDDHHMMSS
tzint(5)Timezone
msgidint(5)0 a 60000
weekdayint(1)0 (domingo) a 6 (sábado)
enabledNint(1)Faixa horária N — 0 (desabilitada) ou 1 (habilitada)
alarmlevelNstring(5)Faixa horária N — nível de ruído para alarmes
sampletimeNstring(2)Faixa horária N — janela de tempo, em segundos
timeiniNstring(5)Faixa horária N — horário de início (HH:MM)
timeendNstring(5)Faixa horária N — horário final (HH:MM)
playbuzzerNint(1)Faixa horária N — acionar buzzer em alarmes

N vai de 0 a 3 (faixas horárias 01 a 04). Todas as quatro faixas são enviadas em uma única mensagem.

{
"cmd": "cfg_update",
"timestamp": "201231235959",
"tz": -3,
"msgid": 41122,
"weekday": 1,
"enabled0": 1,
"alarmlevel0": "40",
"sampletime0": "30",
"timeini0": "00:00",
"timeend0": "07:59",
"playbuzzer0": 1,
"enabled1": 1,
"alarmlevel1": "75.5",
"sampletime1": "30",
"timeini1": "08:00",
"timeend1": "17:59",
"playbuzzer1": 0,
"enabled2": 0,
"alarmlevel2": "0",
"sampletime2": "60",
"timeini2": "18:00",
"timeend2": "21:59",
"playbuzzer2": 1,
"enabled3": 1,
"alarmlevel3": "60",
"sampletime3": "30",
"timeini3": "22:00",
"timeend3": "23:59",
"playbuzzer3": 1
}

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

ChaveValor/tipoObservações
cmd"cfg_update_ack"Valor fixo
timestampstring(12)YYMMDDHHMMSS
tzint(5)Timezone
msgidint(5)ID da mensagem original
statusstring"DONE" ou "ERROR"
{
"cmd": "cfg_update_ack",
"timestamp": "201231235959",
"tz": -3,
"msgid": 41122,
"status": "DONE"
}

Solicitar envio de status (get_cfg)

Solicita ao equipamento que envie sua configuração atual para um dia da semana específico.

Tópico: ${facilityid}/${deviceid}/to

ChaveValor/tipoObservações
cmd"get_cfg"Valor fixo
timestampstring(12)YYMMDDHHMMSS
tzint(5)Timezone
weekdayint(1)0 (domingo) a 6 (sábado)
{
"cmd": "get_cfg",
"timestamp": "191231123456",
"tz": -3,
"weekday": 4
}

Resposta: não há resposta direta. O equipamento enviará imediatamente uma mensagem de dados atuais de configuração (cfg).

Reconhecimento remoto de alarme (ack_alarm)

O servidor envia ao equipamento uma mensagem para reconhecer remotamente um estado de alarme. O efeito prático equivale ao usuário pressionar o botão frontal do Palladium.

Tópico: ${facilityid}/${deviceid}/to

ChaveValor/tipoObservações
cmd"ack_alarm"Valor fixo
timestampstring(12)YYMMDDHHMMSS
tzint(5)Timezone
msgidint(5)0 a 60000
{
"cmd": "ack_alarm",
"timestamp": "191231123456",
"tz": -3,
"msgid": 871
}

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

ChaveValor/tipoObservações
cmd"ack_alarm_ack"Valor fixo
timestampstring(12)YYMMDDHHMMSS
tzint(5)Timezone
msgidint(5)ID da mensagem original
statusstring"DONE" ou "ERROR"
{
"cmd": "ack_alarm_ack",
"timestamp": "191231123456",
"tz": -3,
"msgid": 871,
"status": "DONE"
}

Mensagens enviadas pelo Palladium

Estas mensagens são publicadas pelo equipamento em subtópicos sob ${facilityid}/${deviceid}/from/. Salvo indicação, não exigem resposta.

Alarme (alarm)

Gerada automaticamente quando o Palladium entra em estado de alarme (ruído acima do limite da faixa horária).

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

ChaveValor/tipoObservações
cmd"alarm"Valor fixo
timestampstring(12)YYMMDDHHMMSS
tzint(5)Timezone
valuefloatNível medido em dB
limitfloatNível máximo de ruído aceito na faixa horária
{
"cmd": "alarm",
"timestamp": "191231123456",
"tz": -3,
"value": 75.8,
"limit": 70
}

Resposta: não há.

Reconhecimento de alarme (ack)

Gerada quando um estado de alarme é reconhecido, seja pelo botão frontal do equipamento, seja de modo remoto (via ack_alarm).

Tópico: ${facilityid}/${deviceid}/from/alarm-ack

ChaveValor/tipoObservações
cmd"ack"Valor fixo
timestampstring(12)YYMMDDHHMMSS
tzint(5)Timezone
{
"cmd": "ack",
"timestamp": "191231123456",
"tz": -3
}

Resposta: não há.

Alteração de configuração (cfg_write)

Gerada sempre que uma alteração de configuração do Palladium é concluída com sucesso, informando se a origem foi local ou remota.

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

ChaveValor/tipoObservações
cmd"cfg_write"Valor fixo
timestampstring(12)YYMMDDHHMMSS
tzint(5)Timezone
originint(1)0 (alteração local) ou 1 (alteração remota)
{
"cmd": "cfg_write",
"timestamp": "191231123456",
"tz": -3,
"origin": 0
}

Resposta: não há.

Dados atuais de configuração (cfg)

O Palladium reporta seus dados de configuração atuais para um dia da semana específico — tipicamente em resposta a um get_cfg. A estrutura das faixas horárias é a mesma do cfg_update.

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

ChaveValor/tipoObservações
cmd"cfg"Valor fixo
timestampstring(12)YYMMDDHHMMSS
tzint(5)Timezone
weekdayint(1)0 (domingo) a 6 (sábado)
enabledNint(1)Faixa horária N — 0 (desabilitada) ou 1 (habilitada)
alarmlevelNstring(5)Faixa horária N — nível de ruído para alarmes
sampletimeNstring(2)Faixa horária N — janela de tempo, em segundos
timeiniNstring(5)Faixa horária N — horário de início (HH:MM)
timeendNstring(5)Faixa horária N — horário final (HH:MM)
playbuzzerNint(1)Faixa horária N — acionar buzzer em alarmes

N vai de 0 a 3 (faixas horárias 01 a 04).

{
"cmd": "cfg",
"timestamp": "201231235959",
"tz": -3,
"weekday": 1,
"enabled0": 1,
"alarmlevel0": "40",
"sampletime0": "30",
"timeini0": "00:00",
"timeend0": "07:59",
"playbuzzer0": 1,
"enabled1": 1,
"alarmlevel1": "75.5",
"sampletime1": "30",
"timeini1": "08:00",
"timeend1": "17:59",
"playbuzzer1": 0,
"enabled2": 0,
"alarmlevel2": "0",
"sampletime2": "60",
"timeini2": "18:00",
"timeend2": "21:59",
"playbuzzer2": 1,
"enabled3": 1,
"alarmlevel3": "60",
"sampletime3": "30",
"timeini3": "22:00",
"timeend3": "23:59",
"playbuzzer3": 1
}

Resposta: não há.

Keepalive / Informações gerais (info)

Mensagem periódica de keepalive, com dados básicos e status do equipamento.

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

ChaveValor/tipoObservações
cmd"info"Valor fixo
timestampstring(12)YYMMDDHHMMSS
tzint(5)Timezone
boardidstringID único Palladium
versionstringVersão de firmware atual
ipaddressstring(15)Endereço IPv4 atual
{
"cmd": "info",
"timestamp": "201231123456",
"tz": -3,
"boardid": "palladium04cf",
"version": "1.18",
"ipaddress": "192.168.0.66"
}

Resposta: não há.

Dados aferidos / Telemetria (data)

Mensagem periódica com os valores de ruído medidos na última janela de tempo, além da temperatura interna.

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

ChaveValor/tipoObservações
cmd"data"Valor fixo
timestampstring(12)YYMMDDHHMMSS
tzint(5)Timezone
msgidint(5)0 a 60000
valuefloatNível de ruído instantâneo
medfloatNível de ruído médio na última janela de tempo
maxfloatNível de ruído máximo na última janela de tempo
minfloatNível de ruído mínimo na última janela de tempo
limitfloatNível máximo de ruído aceito na faixa horária ativa
tempfloatTemperatura interna do equipamento
{
"cmd": "data",
"timestamp": "201231123456",
"tz": -3,
"msgid": 4388,
"value": 56.8,
"med": 52.0,
"max": 58.3,
"min": 43.1,
"limit": 70,
"temp": 23.9
}

Resposta: não há.

Alteração do status do Access Point (change_ap)

Gerada quando o Access Point (AP) WiFi do Palladium é ativado ou desativado, para fins de controle.

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

ChaveValor/tipoObservações
cmd"change_ap"Valor fixo
timestampstring(12)YYMMDDHHMMSS
tzint(5)Timezone
statusint(1)0 (AP desligado) ou 1 (AP ligado)
{
"cmd": "change_ap",
"timestamp": "201231123456",
"tz": -3,
"status": 1
}

Resposta: não há.

Alteração de responsável (register)

Cada equipamento possui um usuário responsável (usuário Master). Quando o responsável é alterado, o equipamento gera esta mensagem. O servidor confirma com register_ack, cuja txtmsg é apresentada ao usuário.

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

ChaveValor/tipoObservações
cmd"register"Valor fixo
timestampstring(12)YYMMDDHHMMSS
msgidint(5)0 a 60000
deviceidstringDevice ID
newownerstringE-mail do novo responsável
{
"cmd": "register",
"timestamp": "201231123456",
"msgid": 884,
"deviceid": "palladiumA8B1",
"newowner": "contato@iongrade.com.br"
}

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

ChaveValor/tipoObservações
cmd"register_ack"Valor fixo
msgidint(5)0 a 60000
timestampstring(12)YYMMDDHHMMSS
statusint(1)0 (erro) ou 1 (sucesso)
txtmsgstringMensagem a ser apresentada ao usuário
Fontes do evento de responsável

O evento de alteração de responsável (register / register_ack) está descrito no arquivo mqtt/from_palladium.txt, mas não consta do .docx do manual MQTT v1.02 (que vai do alarme ao change-ap). Confirmar tópico e payload com o firmware antes de tratar a mensagem.


Integração Webservice (Palladium Cloud)

O Palladium Cloud é o sistema em nuvem da Iongrade que recebe as mensagens dos equipamentos físicos (via MQTT) e permite que determinados eventos sejam repassados a um endpoint HTTP de escolha do cliente. É a forma de integração para quem deseja receber os eventos do Palladium sem manter um broker MQTT próprio — os mesmos eventos do protocolo MQTT, entregues pela nuvem.

Funcionamento

Dentro do Palladium Cloud configuram-se, para cada equipamento individualmente, duas coisas:

  1. URL (endpoint HTTP) — para onde os eventos serão enviados.
  2. Eventos a notificar — quais tipos de evento (Alarme, Reconhecimento, etc.) disparam uma notificação.

Sempre que o Palladium Cloud recebe um evento de um tipo selecionado, ele faz um request HTTP POST para a URL configurada, em formato application/x-www-form-urlencoded, repassando os dados do evento. Cada tipo de evento possui sua própria relação de parâmetros.

A URL deve ser um endereço HTTP válido e acessível pela internet. São permitidos endpoints HTTP ou HTTPS, com portas e paths conforme a necessidade. Exemplos válidos:

http://meuservidor.com.br/api/palladium
https://meuservidor.com.br:880/api/palladium.cgi
http://usuario@170.31.81.99:8080/notificacoes.py
https://meuservidor.com.br/notificacoes.php?key=a87cf814a3ce

Como o transporte é HTTP POST form-urlencoded, qualquer linguagem e qualquer webserver podem receber e tratar os eventos.

Webservice é repasse, não controle

O webservice do Cloud é unidirecional (Cloud → endpoint do cliente): ele apenas notifica eventos. Comandos do servidor para o equipamento (atualização de configuração, reconhecimento remoto, solicitação de status) só existem no transporte MQTT.

Todas as notificações incluem o parâmetro palladium — o alias definido para o equipamento dentro do Palladium Cloud — além dos campos próprios de cada evento.

Parâmetros POST por evento

Alarme

Disparada toda vez que o Palladium entra em estado de alarme.

ChaveValor/tipoDescrição
cmd"alarm"Valor fixo
timestampstring(12)YYMMDDHHMMSS
valuefloatNível medido em dB
limitfloatNível máximo de ruído aceito na faixa horária
palladiumstringAlias do equipamento no Palladium Cloud
{
"cmd": "alarm",
"timestamp": "191231123456",
"value": 75.8,
"limit": 70,
"palladium": "ChurrasqueiraCondominio"
}

Reconhecimento de alarme

Disparada quando um estado de alarme é reconhecido, pelo botão frontal do equipamento ou de modo remoto.

ChaveValor/tipoDescrição
cmd"ack"Valor fixo
timestampstring(12)YYMMDDHHMMSS
palladiumstringAlias do equipamento no Palladium Cloud
{
"cmd": "ack",
"timestamp": "191231123456",
"palladium": "Salao de festas"
}

Alteração de configuração

Disparada sempre que uma alteração de configuração do Palladium é concluída com sucesso.

ChaveValor/tipoDescrição
cmd"cfg_write"Valor fixo
timestampstring(12)YYMMDDHHMMSS
originint(1)0 (alteração local) ou 1 (alteração remota)
palladiumstringAlias do equipamento no Palladium Cloud
{
"cmd": "cfg_write",
"timestamp": "191231123456",
"origin": 0,
"palladium": "881237 - Zona 04"
}

Dados aferidos

Repasse da telemetria periódica (valores da última janela de tempo + temperatura).

ChaveValor/tipoDescrição
cmd"data"Valor fixo
timestampstring(12)YYMMDDHHMMSS
msgidint(5)ID da mensagem (0-60000)
valuefloatNível de ruído instantâneo
medfloatNível de ruído médio na última janela de tempo
maxfloatNível de ruído máximo na última janela de tempo
minfloatNível de ruído mínimo na última janela de tempo
limitfloatNível máximo de ruído aceito na faixa horária ativa
tempfloatTemperatura interna do equipamento
palladiumstringAlias do equipamento no Palladium Cloud
{
"cmd": "data",
"timestamp": "201231123456",
"msgid": 4388,
"value": 56.8,
"med": 52.0,
"max": 58.3,
"min": 43.1,
"limit": 70,
"temp": 23.9,
"palladium": "Salão 03"
}

Alteração de responsável

Todo equipamento possui um usuário responsável (usuário Master) cadastrado no Palladium Cloud. Quando o responsável é alterado, esta notificação é gerada.

ChaveValor/tipoDescrição
cmd"register"Valor fixo
timestampstring(12)YYMMDDHHMMSS
msgidint(5)ID da mensagem (0-60000)
deviceidstringIdentificador único do equipamento
newownerstringE-mail do novo responsável
palladiumstringAlias do equipamento no Palladium Cloud
{
"cmd": "register",
"timestamp": "201231123456",
"msgid": 884,
"deviceid": "palladiumA8B1",
"newowner": "contato@iongrade.com.br",
"palladium": "Condomínio ABC"
}
Cobertura do webservice

O webservice do Cloud (v1.00) notifica cinco dos eventos do equipamento: Alarme, Reconhecimento, Alteração de configuração, Dados aferidos e Alteração de responsável. Eventos puramente operacionais do MQTT — keepalive (info), dados atuais de configuração (cfg) e status do Access Point (change_ap) — não têm notificação correspondente no webservice e só estão disponíveis via MQTT direto.