Palladium — Integrações (MQTT e Webservice Cloud)
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
POSTapplication/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.txtemqtt/to_palladium.txtdo repositório.
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):
| Campo | Descrição |
|---|---|
| Facility ID | Identificador único da instalação (ver abaixo) |
| Broker | Endereço do servidor MQTT |
| Port | Porta de comunicação do servidor MQTT |
| Username | Nome do usuário para acesso ao broker |
| Password | Senha de acesso ao broker |
| Device id | Identificaçã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ópico | Origem | Destino |
|---|---|---|
facility/broadcast/to | Servidor | Todos os equipamentos |
facility/deviceid/to | Servidor | Equipamento específico |
facility/deviceid/from/# | Equipamento específico | Servidor |
facility/+/from/# | Todos os equipamentos | Servidor |
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
msgiddeve 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
msgidoriginal. Caso seja gerada uma resposta commsgiddiferente, 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
| Chave | Valor/tipo | Observações |
|---|---|---|
cmd | "cfg_update" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
tz | int(5) | Timezone |
msgid | int(5) | 0 a 60000 |
weekday | int(1) | 0 (domingo) a 6 (sábado) |
enabledN | int(1) | Faixa horária N — 0 (desabilitada) ou 1 (habilitada) |
alarmlevelN | string(5) | Faixa horária N — nível de ruído para alarmes |
sampletimeN | string(2) | Faixa horária N — janela de tempo, em segundos |
timeiniN | string(5) | Faixa horária N — horário de início (HH:MM) |
timeendN | string(5) | Faixa horária N — horário final (HH:MM) |
playbuzzerN | int(1) | Faixa horária N — acionar buzzer em alarmes |
Nvai de0a3(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:
| Chave | Valor/tipo | Observações |
|---|---|---|
cmd | "cfg_update_ack" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
tz | int(5) | Timezone |
msgid | int(5) | ID da mensagem original |
status | string | "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
| Chave | Valor/tipo | Observações |
|---|---|---|
cmd | "get_cfg" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
tz | int(5) | Timezone |
weekday | int(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
| Chave | Valor/tipo | Observações |
|---|---|---|
cmd | "ack_alarm" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
tz | int(5) | Timezone |
msgid | int(5) | 0 a 60000 |
{
"cmd": "ack_alarm",
"timestamp": "191231123456",
"tz": -3,
"msgid": 871
}
Resposta — tópico ${facilityid}/${deviceid}/from/ack:
| Chave | Valor/tipo | Observações |
|---|---|---|
cmd | "ack_alarm_ack" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
tz | int(5) | Timezone |
msgid | int(5) | ID da mensagem original |
status | string | "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
| Chave | Valor/tipo | Observações |
|---|---|---|
cmd | "alarm" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
tz | int(5) | Timezone |
value | float | Nível medido em dB |
limit | float | Ní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
| Chave | Valor/tipo | Observações |
|---|---|---|
cmd | "ack" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
tz | int(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
| Chave | Valor/tipo | Observações |
|---|---|---|
cmd | "cfg_write" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
tz | int(5) | Timezone |
origin | int(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
| Chave | Valor/tipo | Observações |
|---|---|---|
cmd | "cfg" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
tz | int(5) | Timezone |
weekday | int(1) | 0 (domingo) a 6 (sábado) |
enabledN | int(1) | Faixa horária N — 0 (desabilitada) ou 1 (habilitada) |
alarmlevelN | string(5) | Faixa horária N — nível de ruído para alarmes |
sampletimeN | string(2) | Faixa horária N — janela de tempo, em segundos |
timeiniN | string(5) | Faixa horária N — horário de início (HH:MM) |
timeendN | string(5) | Faixa horária N — horário final (HH:MM) |
playbuzzerN | int(1) | Faixa horária N — acionar buzzer em alarmes |
Nvai de0a3(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
| Chave | Valor/tipo | Observações |
|---|---|---|
cmd | "info" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
tz | int(5) | Timezone |
boardid | string | ID único Palladium |
version | string | Versão de firmware atual |
ipaddress | string(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
| Chave | Valor/tipo | Observações |
|---|---|---|
cmd | "data" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
tz | int(5) | Timezone |
msgid | int(5) | 0 a 60000 |
value | float | Nível de ruído instantâneo |
med | float | Nível de ruído médio na última janela de tempo |
max | float | Nível de ruído máximo na última janela de tempo |
min | float | Nível de ruído mínimo na última janela de tempo |
limit | float | Nível máximo de ruído aceito na faixa horária ativa |
temp | float | Temperatura 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
| Chave | Valor/tipo | Observações |
|---|---|---|
cmd | "change_ap" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
tz | int(5) | Timezone |
status | int(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
| Chave | Valor/tipo | Observações |
|---|---|---|
cmd | "register" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
msgid | int(5) | 0 a 60000 |
deviceid | string | Device ID |
newowner | string | E-mail do novo responsável |
{
"cmd": "register",
"timestamp": "201231123456",
"msgid": 884,
"deviceid": "palladiumA8B1",
"newowner": "contato@iongrade.com.br"
}
Resposta — tópico ${facilityid}/${deviceid}/to:
| Chave | Valor/tipo | Observações |
|---|---|---|
cmd | "register_ack" | Valor fixo |
msgid | int(5) | 0 a 60000 |
timestamp | string(12) | YYMMDDHHMMSS |
status | int(1) | 0 (erro) ou 1 (sucesso) |
txtmsg | string | Mensagem a ser apresentada ao usuário |
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:
- URL (endpoint HTTP) — para onde os eventos serão enviados.
- 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.
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.
| Chave | Valor/tipo | Descrição |
|---|---|---|
cmd | "alarm" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
value | float | Nível medido em dB |
limit | float | Nível máximo de ruído aceito na faixa horária |
palladium | string | Alias 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.
| Chave | Valor/tipo | Descrição |
|---|---|---|
cmd | "ack" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
palladium | string | Alias 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.
| Chave | Valor/tipo | Descrição |
|---|---|---|
cmd | "cfg_write" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
origin | int(1) | 0 (alteração local) ou 1 (alteração remota) |
palladium | string | Alias 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).
| Chave | Valor/tipo | Descrição |
|---|---|---|
cmd | "data" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
msgid | int(5) | ID da mensagem (0-60000) |
value | float | Nível de ruído instantâneo |
med | float | Nível de ruído médio na última janela de tempo |
max | float | Nível de ruído máximo na última janela de tempo |
min | float | Nível de ruído mínimo na última janela de tempo |
limit | float | Nível máximo de ruído aceito na faixa horária ativa |
temp | float | Temperatura interna do equipamento |
palladium | string | Alias 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.
| Chave | Valor/tipo | Descrição |
|---|---|---|
cmd | "register" | Valor fixo |
timestamp | string(12) | YYMMDDHHMMSS |
msgid | int(5) | ID da mensagem (0-60000) |
deviceid | string | Identificador único do equipamento |
newowner | string | E-mail do novo responsável |
palladium | string | Alias do equipamento no Palladium Cloud |
{
"cmd": "register",
"timestamp": "201231123456",
"msgid": 884,
"deviceid": "palladiumA8B1",
"newowner": "contato@iongrade.com.br",
"palladium": "Condomínio ABC"
}
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.