Integração MQTT - Neon

Documentação restrita

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

Este documento especifica o protocolo e as mensagens trocadas entre a controladora NEON e o servidor de controle de acesso quando um broker MQTT atua como intermediário da comunicação. Esse protocolo aberto, baseado em conceitos de IoT, é o OpenION — a forma nativa de a Neon se integrar a softwares de mercado.

Fonte: NEON — Manual de Integração v1.5 (jun/2024).

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.
O fluxo de mensagens tem quatro naturezas:
- Mensagens enviadas de forma independente e automática pelo controlador (keepalives, atualizações de status).
- Mensagens enviadas pelo controlador sempre que ocorrem eventos específicos (solicitações de acesso, logs).
- Mensagens enviadas de forma independente e automática pelo servidor (keepalives).
- Mensagens enviadas pelo servidor sempre que ocorrem eventos específicos (abertura remota, envio de listas de acesso).
Muitas mensagens exigem resposta. Por exemplo, uma solicitação de acesso gerada pelo controlador exige que o servidor gere uma nova mensagem que a resolva.

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 deve ser configurado nos controladores e no servidor de acesso com o mesmo valor, e faz parte do nome do tópico na comunicação com o broker MQTT. Para garantir a maior compatibilidade possível, recomenda-se o formato:

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

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 controladores:

cond5991/#

Todos os controladores 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 controlador específico. Cada controlador possui um alias/apelido que faz parte do tópico:

cond5991/controlador88/to     (servidor → controlador específico)
cond5991/controlador88/from   (controlador → servidor)

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

Tópico	Origem	Destino
`facility/broadcast/to`	Servidor	Todos os controladores
`facility/alias/to`	Servidor	Controlador específico
`facility/alias/from/#`	Controlador específico	Servidor
`facility/+/from/#`	Todos os controladores	Servidor

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 solicitação de acesso enviada do controlador ao servidor), a resposta sempre deve referenciar o msgid original. Caso seja gerada uma resposta com msgid diferente do da solicitação original, a mensagem será ignorada pelo controlador.

Valores JSON

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

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. Por exemplo, em uma validação online o servidor pode ou não enviar o uid; ambas as mensagens são válidas. Da mesma forma, se a senha estiver presente o controlador fará o controle de senha; se não estiver, não fará.

Mensagens enviadas pelo servidor

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

Keepalive

O servidor deve publicar periodicamente um keepalive para que os controladores determinem se podem contar com o servidor para decisões de acesso ou se devem entrar em modo de contingência. Caso o controlador não receba keepalive por mais de 2 minutos, entra automaticamente em contingência e só sai ao receber um keepalive com timestamp válido. Sugere-se publicar com a flag retain_message ativa.

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

Chave	Valor/tipo	Observações
`cmd`	`"keepalive"`	Valor fixo
`timestamp`	string(12)	Data/hora formato YYMMDDHHMMSS
`tz`	int(3)	Timezone

{
  "cmd": "keepalive",
  "timestamp": "191231123456",
  "tz": -3
}

Resposta: não há.

Acesso via MQTT (`access_mqtt`)

Solicitação de acesso enviada pelo broker. É tratada normalmente, como se um cartão tivesse sido apresentado em um leitor físico, mas o controlador considera que a origem foi MQTT, o que permite tratamento diferenciado.

Chave	Valor/tipo	Observações
`cmd`	`"access_mqtt"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`card`	string(16)	Número do cartão
`channel`	int(1)	Número do canal da solicitação

{
  "cmd": "access_mqtt",
  "timestamp": "191231123456",
  "msgid": 812,
  "card": "0000001234567890",
  "channel": 2
}

Resposta: não há.

Acesso pré-autorizado via MQTT (`access_auto`)

Acesso pré-autorizado: o controlador não faz verificação/validação (offline ou online), mas gera os logs normalmente, como em um cenário regular.

Chave	Valor/tipo	Observações
`cmd`	`"access_auto"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`card`	string(16)	Número do cartão
`channel`	int(1)	Número do canal da solicitação
`uid`	int(9)	ID do usuário (int32)

{
  "cmd": "access_auto",
  "timestamp": "191231123456",
  "msgid": 812,
  "card": "0000001234567890",
  "channel": 2,
  "uid": 773127
}

Resposta: não há.

Solicitar envio de estado (`get_info`)

Solicita ao controlador que envie uma atualização de status (versão, espaço da lista de cartões etc.).

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

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

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

Liberação de bloqueio / REX (`rex_server`)

Libera um determinado bloqueio (recurso comumente referido como REX — Request to EXit). O bloqueio fica liberado até a próxima passagem ou até um timeout de passagem, e gera um log específico.

Chave	Valor/tipo	Observações
`cmd`	`"rex_server"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`channel`	int(1)	Número do canal da solicitação

{
  "cmd": "rex_server",
  "timestamp": "191231123456",
  "msgid": 8812,
  "channel": 1
}

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

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

{
  "cmd": "rex_server_ack",
  "timestamp": "191231123456",
  "tz": -3,
  "msgid": 8812,
  "status": "done"
}

Capturar dados do próximo cartão (`capture`)

Faz com que o próximo cartão apresentado não seja tratado como solicitação de acesso; apenas o número do cartão é retornado. Útil para cadastro de cartões não-sequenciais em lote ou para certificar-se do número interno de um cartão. É necessário definir o topic onde a resposta deve ser publicada, para evitar conflito no tratamento de mensagens.

Chave	Valor/tipo	Observações
`cmd`	`"capture"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`channel`	int(1)	Número do canal da solicitação
`topic`	string	Tópico onde a resposta deve ser publicada

{
  "cmd": "capture",
  "timestamp": "191231123456",
  "msgid": 8812,
  "channel": 1,
  "topic": "facilityid/mycapturetopic-183"
}

Resposta — tópico definido em topic:

Chave	Valor/tipo	Observações
`cmd`	`"capture_response"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`tz`	int(3)	Timezone
`msgid`	int(5)	ID da mensagem original
`origin`	int(2)	Origem do evento (vide ORIGEM_EVENTOS)
`data`	string	Dados capturados

{
  "cmd": "capture_response",
  "timestamp": "191231123456",
  "tz": -3,
  "msgid": 8812,
  "origin": 1,
  "data": "77912874"
}

Definir estado de operação (`set_mode`)

O controlador possui três estados de operação: normal, emergência e pânico. Esta mensagem alterna entre eles (vide ESTADOS_OPERACAO).

Chave	Valor/tipo	Observações
`cmd`	`"set_mode"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`mode`	int(1)	Modo de operação (vide ESTADOS_OPERACAO)

{
  "cmd": "set_mode",
  "timestamp": "191231123456",
  "msgid": 412,
  "mode": 2
}

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

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

{
  "cmd": "set_mode_ack",
  "timestamp": "191231123456",
  "msgid": 412,
  "status": "error"
}

Buscar versão (`get_version`)

Obtém a versão do controlador com resposta específica. Útil para testes de comunicação.

Chave	Valor/tipo	Observações
`cmd`	`"get_version"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000

{
  "cmd": "get_version",
  "timestamp": "191231123456",
  "msgid": 5399
}

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

Chave	Valor/tipo	Observações
`cmd`	`"version"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`tz`	int(3)	Timezone
`msgid`	int(5)	ID da mensagem original
`version`	string	Versão de firmware em uso
`date`	string(6)	Data de publicação da versão (YYMMDD)

{
  "cmd": "version",
  "timestamp": "191231123456",
  "tz": -3,
  "msgid": 5399,
  "version": "4.1.0",
  "date": "191231"
}

Upgrade de firmware (`upgrade`)

Instrui o controlador a realizar upgrade de firmware. A mensagem deve conter um endereço HTTP(S) de onde obter o firmware; o controlador faz um GET no endereço, baixa, valida e inicia automaticamente a atualização.

Chave	Valor/tipo	Observações
`cmd`	`"upgrade"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`protocol`	string(5)	`"http"` ou `"https"`
`host`	string	Endereço base do host
`port`	int	Porta de conexão (geralmente 80 ou 443)
`path`	string	URI do arquivo

{
  "cmd": "upgrade",
  "timestamp": "191231123456",
  "msgid": 9483,
  "protocol": "https",
  "host": "www.iongrade.com.br",
  "port": 443,
  "path": "/firmware/v1.17.3.bin"
}

Resposta (gerada após o upgrade) — tópico ${facilityid}/${alias}/from/ack:

Chave	Valor/tipo	Observações
`cmd`	`"upgrade_result"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`tz`	int(3)	Timezone
`msgid`	int(5)	ID da mensagem original
`status`	string	`"done"` ou `"error"`
`version`	string	Versão de firmware em uso
`date`	string(6)	Data de publicação da versão (YYMMDD)

{
  "cmd": "upgrade_result",
  "timestamp": "191231123456",
  "tz": -3,
  "msgid": 9483,
  "status": "done",
  "version": "v1.17.2",
  "date": "191231"
}

Envio de lista de cartões (`load_cards`)

Instrui o controlador a buscar um novo arquivo de lista de cartões. Em caso de sucesso, a lista atual é inteiramente substituída pela nova.

Chave	Valor/tipo	Observações
`cmd`	`"load_cards"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`protocol`	string(5)	`"http"` ou `"https"`
`host`	string	Endereço base do host
`port`	int	Porta de conexão (geralmente 80 ou 443)
`path`	string	URI do arquivo
`isordered`	int(1)	Informa se o arquivo está ordenado
`orderedcount`	int(6)	Quantidade de cartões ordenados no arquivo

{
  "cmd": "load_cards",
  "timestamp": "191231123456",
  "msgid": 49111,
  "protocol": "http",
  "host": "192.168.1.88",
  "port": 80,
  "path": "/listascartao/lista_controlador_01.data",
  "isordered": 1,
  "orderedcount": 15052
}

Resposta (após a atualização) — tópico ${facilityid}/${alias}/from/ack:

Chave	Valor/tipo	Observações
`cmd`	`"load_cards_result"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`tz`	int(3)	Timezone
`timestampserver`	string(12)	Eco do timestamp da mensagem original
`msgid`	int(5)	ID da mensagem original
`status`	string	`"done"` ou `"error"`

{
  "cmd": "load_cards_result",
  "timestamp": "191231123458",
  "tz": -3,
  "timestampserver": "191231123456",
  "msgid": 49111,
  "status": "error"
}

Excluir todos os cartões (`wipe_cards`)

Exclui todos os cartões em memória.

Chave	Valor/tipo	Observações
`cmd`	`"wipe_cards"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000

{
  "cmd": "wipe_cards",
  "timestamp": "191231123456",
  "msgid": 4
}

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

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

{
  "cmd": "wipe_cards_ack",
  "timestamp": "191231123456",
  "msgid": 4,
  "status": "done"
}

Excluir cartão específico (`del`)

Exclui um cartão específico da lista local.

Chave	Valor/tipo	Observações
`cmd`	`"del"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`card`	string(16)	Número do cartão

{
  "cmd": "del",
  "timestamp": "191231123456",
  "msgid": 8431,
  "card": "A843BJ8418"
}

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

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

{
  "cmd": "del_ack",
  "timestamp": "191231123456",
  "tz": -3,
  "msgid": 8431,
  "status": "done"
}

Inserir ou alterar cartão (`ins`)

Inclui ou atualiza um cartão específico sem necessidade de enviar a lista completa. Se o cartão não existir, é inserido (campos opcionais ausentes recebem valor padrão). Se já existir, os valores presentes na mensagem são atualizados (campos opcionais ausentes não são alterados). Os campos marcados com (*) são obrigatórios.

Chave	Valor/tipo	Observações
`cmd`	`"ins"`	(*) Valor fixo
`timestamp`	string(12)	(*) YYMMDDHHMMSS
`msgid`	int(5)	(*) 0 a 60000
`card`	string(16)	(*) Número do cartão
`uid`	int(9)	(*) ID da pessoa
`tp`	int(1)	Tipo do cartão (vide TIPOS_CARTAO). Default: 0
`sts`	int(1)	Status do cartão. 0 = Desabilitado (default); 1 = Habilitado
`ch1`	int(1)	Status no canal 1. 0 = Desabilitado; 1 = Habilitado (default)
`ch2`	int(1)	Status no canal 2. 0 = Desabilitado; 1 = Habilitado (default)
`ch3`	int(1)	Status no canal 3. 0 = Desabilitado; 1 = Habilitado (default)
`uart`	int(1)	Passagem habilitada em leitores UART. 0 = Desabilitado; 1 = Habilitado (default)
`web`	int(1)	Passagem habilitada em leitores WEB. 0 = Desabilitado; 1 = Habilitado (default)
`mqtt`	int(1)	Passagem habilitada via MQTT. 0 = Desabilitado; 1 = Habilitado (default)
`vsv`	int(1)	Consultar servidor se estiver online. 0 = Desabilitado (default); 1 = Habilitado
`erq`	int(1)	Acesso condicionado à presença de Escort. 0 = Não (default); 1 = Sim
`esc`	int(1)	Pode ser Escort de outras pessoas. 0 = Não (default); 1 = Sim
`bio`	int(1)	Acesso condicionado a uso de biometria. 0 = Não (default); 1 = Sim
`totp`	int(1)	Validar TOTP. 0 = Não (default); 1 = Sim
`ups`	string(5)	Hash da senha de acesso. Se igual a `"0"`, a senha é desabilitada. Default: `"0"`
`vde`	string(6)	Validade inicial do cartão (YYMMDD). Default: `"000101"`
`vat`	string(6)	Validade final do cartão (YYMMDD). Default: `991231`
`h1ini`	string(4)	Faixa horária 01 — horário inicial (HHMM). Default: `"0000"`
`h1fim`	string(4)	Faixa horária 01 — horário final (HHMM). Default: `"2359"`
`h1dia`	string(7)	Faixa horária 01 — dias válidos. Sequência de 7 caracteres `"0"`/`"1"`, um por dia da semana iniciando no domingo (`"1"` = válida). Ex.: domingos e sextas = `"1000010"`. Default: `"1111111"`
`h2ini`	string(4)	Faixa horária 02 — horário inicial (HHMM). Default: `"0000"`
`h2fim`	string(4)	Faixa horária 02 — horário final (HHMM). Default: `"2359"`
`h2dia`	string(7)	Faixa horária 02 — dias válidos. Ex.: seg a sex = `"0111110"`. Default: `"0000000"`
`dur`	int(1)	0 = Cartão normal; 1 = Cartão de coação

{
  "cmd": "ins",
  "msgid": 8411,
  "timestamp": "191231123456",
  "card": "84818283",
  "uid": "991",
  "tp": 1,
  "sts": 1,
  "ch1": 1,
  "ch2": 0,
  "ch3": 0,
  "uart": 0,
  "web": 0,
  "mqtt": 1,
  "vsv": 1,
  "erq": 0,
  "esc": 0,
  "bio": 0,
  "totp": 0,
  "ups": "0",
  "vde": "190101",
  "vat": "191231",
  "h1ini": "0800",
  "h1fim": "1800",
  "h1dia": "0111110",
  "h2ini": "0900",
  "h2fim": "1400",
  "h2dia": "1000001",
  "dur": 0
}

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

Chave	Valor/tipo	Observações
`cmd`	`"ins_ack"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`tz`	int(3)	Timezone
`msgid`	int(5)	ID da mensagem original
`status`	string	`"done"` ou `"NO ROOM"`

{
  "cmd": "ins_ack",
  "timestamp": "191231123456",
  "tz": -3,
  "msgid": 8431,
  "status": "done"
}

Mensagens de biometria (servidor → controlador)

Capturar template biométrico (`bioget_template`)

Inicia a captura de um template biométrico no controlador. O template é retornado em base64.

Chave	Valor/tipo	Observações
`cmd`	`"bioget_template"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`channel`	int(1)	Canal onde será feita a captura
`topic`	string	Tópico onde a resposta deve ser enviada

{
  "cmd": "bioget_template",
  "timestamp": "191231123456",
  "msgid": 8431,
  "channel": 1
}

Resposta — tópico informado em topic:

Chave	Valor/tipo	Observações
`cmd`	`"bioget_template_ack"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`tz`	int(3)	Timezone
`msgid`	int(5)	ID da mensagem original
`status`	string	`"done"` ou `"error"` ou `"timeout"`
`quality`	int(5)	Qualidade da captura (0-100)
`templatesize`	int(5)	Tamanho em bytes do template capturado
`template`	string	Template em base64

{
  "cmd": "bioget_template_ack",
  "timestamp": "191231123456",
  "tz": -3,
  "msgid": 8431,
  "status": "done",
  "quality": 78,
  "templatesize": 12,
  "template": "ababab121212cfcfcfbbaa88"
}

Obter dados sobre módulo biométrico (`bioget_info`)

Retorna informações sobre os módulos biométricos em uso no controlador.

Chave	Valor/tipo	Observações
`cmd`	`"bioget_info"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`channel`	int(1)	Canal a consultar

{
  "cmd": "bioget_info",
  "timestamp": "191231123456",
  "msgid": 8431,
  "channel": 1
}

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

Chave	Valor/tipo	Observações
`cmd`	`"bioget_info_ack"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`tz`	int(3)	Timezone
`msgid`	int(5)	ID da mensagem original
`channel`	int(1)	Número do canal
`status`	string	`"done"` ou `"error"`
`description`	string(16)	Descrição do modelo do módulo
`maxtemplates`	int(5)	Capacidade máxima de templates
`usedtemplates`	int(5)	Templates em uso
`freetemplates`	int(5)	Templates livres

{
  "cmd": "bioget_info_ack",
  "timestamp": "191231123456",
  "tz": -3,
  "msgid": 8431,
  "channel": 1,
  "status": "done",
  "description": "SFM5020",
  "maxtemplates": 900,
  "usedtemplates": 180,
  "freetemplates": 720
}

Adicionar template biométrico (`bioenroll`)

Inclui um template biométrico no controlador.

Chave	Valor/tipo	Observações
`cmd`	`"bioenroll"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`channel`	int(1)	Canal
`uid`	int	ID do usuário (int32)
`templatesize`	int(5)	Tamanho do template
`template`	string	Template em base64

{
  "cmd": "bioenroll",
  "timestamp": "191231123456",
  "msgid": 8431,
  "channel": 1,
  "uid": 88841,
  "templatesize": 12,
  "template": "ababab121212cfcfcfbbaa88"
}

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

Chave	Valor/tipo	Observações
`cmd`	`"bioenroll_ack"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`tz`	int(3)	Timezone
`msgid`	int(5)	ID da mensagem original
`channel`	int(1)	Número do canal
`status`	string	`"done"` ou `"error"` ou `"timeout"`

{
  "cmd": "bioenroll_ack",
  "timestamp": "191231123456",
  "tz": -3,
  "msgid": 8431,
  "channel": 1,
  "status": "done"
}

Excluir template biométrico (`biodel`)

Exclui um template biométrico do controlador.

Chave	Valor/tipo	Observações
`cmd`	`"biodel"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`channel`	int(1)	Canal
`uid`	int	ID do usuário (int32)

{
  "cmd": "biodel",
  "timestamp": "191231123456",
  "msgid": 8431,
  "channel": 1,
  "uid": 4817721
}

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

Chave	Valor/tipo	Observações
`cmd`	`"biodel_ack"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`tz`	int(3)	Timezone
`msgid`	int(5)	ID da mensagem original
`channel`	int(1)	Número do canal
`status`	string	`"done"` ou `"error"` ou `"timeout"` ou `"nouserid"`

{
  "cmd": "biodel_ack",
  "timestamp": "191231123456",
  "tz": -3,
  "msgid": 8431,
  "channel": 1,
  "status": "done"
}

Comandos de operação e manutenção (servidor → controlador)

Forçar modo offline (`force_offline`)

Força o controlador a entrar em modo offline imediatamente. Útil para manutenções programadas, evitando que a entrada em offline ocorra por timeout de comunicação.

Chave	Valor/tipo	Observações
`cmd`	`"force_offline"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000

{
  "cmd": "force_offline",
  "timestamp": "191231123456",
  "msgid": 8431
}

Resposta: não há. Para voltar ao modo online é necessário enviar um keepalive.

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

Embora o NEON 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": "210311120132",
  "msgid": 8431
}

Resposta:

{
  "cmd": "datetime_adj",
  "timestamp": "210311120132",
  "tz": -3
}

Forçar relé (`force_relay`)

Os relés de saída podem ser forçados para os estados ligado ou desligado.

O forçamento se sobrepõe ao controle do controlador (ex.: se um acesso for autorizado e o relé LOCK estiver forçado para desligado, ele não será ligado).
O forçamento considera o estado default configurado para o relé. Se o default é ligado, forçar para ligar irá desenergizar o relé.
timer define o tempo (s) do forçamento. Se timer = 0, o relé fica forçado indefinidamente. Se timer > 0, ao final do período o controlador envia force_relay_ack com status igual a "end".

Chave	Valor/tipo	Observações
`cmd`	`"force_relay"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`relay`	int(1)	Número do relé — 1 a 4
`value`	int(1)	Valor do forçamento — 0 ou 1
`timer`	int(5)	Temporização — 0 a 99999 s. Se `timer = 0`, não temporiza

{
  "cmd": "force_relay",
  "msgid": 1604,
  "relay": 4,
  "value": 1,
  "timer": 10
}

Respostas — tópico ${facilityid}/${alias}/from/ack:

{
  "cmd": "force_relay_ack",
  "timestamp": "211015071904",
  "tz": -3,
  "msgid": 1604,
  "relay": 4,
  "status": "done"
}

{
  "cmd": "force_relay_ack",
  "timestamp": "211015071904",
  "tz": -3,
  "msgid": 1604,
  "relay": 5,
  "status": "error"
}

Mensagem de ack ao final do período do forçamento:

{
  "cmd": "force_relay_ack",
  "timestamp": "211015071904",
  "tz": -3,
  "msgid": 1604,
  "relay": 4,
  "status": "end"
}

Remover forçamento de relé (`unforce_relay`)

Remove um forçamento aplicado a um relé.

Chave	Valor/tipo	Observações
`cmd`	`"unforce_relay"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`relay`	int(1)	Número do relé — 1 a 4

{
  "cmd": "unforce_relay",
  "timestamp": "210311120132",
  "msgid": 8431,
  "relay": 2
}

Respostas — tópico ${facilityid}/${alias}/from/ack:

{
  "cmd": "unforce_relay_ack",
  "timestamp": "210311120132",
  "tz": -3,
  "relay": 2,
  "status": "done"
}

{
  "cmd": "unforce_relay_ack",
  "timestamp": "210311120132",
  "tz": -3,
  "relay": 0,
  "status": "error"
}

Imprimir ticket QR Code (`print`)

Envia dados para impressão de um ticket em impressora conectada a uma das UARTs do controlador. A diretiva ${qrcode} no campo data determina onde o QR Code é impresso dentro do texto.

Chave	Valor/tipo	Observações
`cmd`	`"print"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	0 a 60000
`data`	string(512)	Texto a imprimir; usar `${qrcode}` para posicionar o QR Code
`qrcode`	string(99)	QR Code a ser impresso
`port`	int(1)	UART a ser utilizada (1 ou 2)
`topic`	string(64)	Tópico onde a resposta deve ser publicada

{
  "cmd": "print",
  "msgid": 22995,
  "timestamp": "210626094902",
  "data": "Seja benvindo${qrcode}Valido ate 31/12/2024",
  "qrcode": "Conteudo do QRCode",
  "port": 1,
  "topic": "HOMOLOG/aurum15BF9CE8/from/ack"
}

Resposta — tópico definido em topic:

Chave	Valor/tipo	Observações
`cmd`	`"printer_status"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`tz`	int(3)	Timezone
`msgid`	int(5)	ID da mensagem original
`port`	int(1)	UART utilizada (1 ou 2)
`status`	string	`"ok"` ou `"ok low paper"` ou `"no paper"` ou `"print timeout"`

{
  "cmd": "print_status",
  "timestamp": "210626094901",
  "tz": -3,
  "msgid": 22995,
  "port": 1,
  "status": "done"
}

note

No manual, a tabela de resposta documenta cmd como "printer_status", mas o exemplo JSON usa "print_status". Essa divergência vem da própria fonte (firmware/manual); confirmar o valor correto com o firmware antes de usar.

Forçar modo configuração (`enablecfg`)

Força um reset do NEON, que entra em modo configuração após o reset.

caution

Em modo configuração apenas o ponto de acesso WiFi do próprio controlador fica ativo. Será necessária intervenção no local para resetar novamente o controlador e retornar ao modo de operação normal.

Chave	Valor/tipo	Observações
`cmd`	`"enablecfg"`	Valor fixo

{
  "cmd": "enablecfg"
}

Resposta: não há.

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 da NEON. A mensagem contém o nome do arquivo; a resposta contém os dados.

Mensagem — tópico ${facilityid}/${alias}/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": 16041,
  "file": "/config_network.json"
}

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

{
  "cmd": "getconfig_ack",
  "timestamp": "210401154917",
  "tz": -3,
  "msgid": 16049,
  "file": "/config_network.json",
  "data": {
    "networkmode": "1"
  }
}

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

Envia parâmetros de configuração da NEON. 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}/${alias}/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": 16041,
  "file": "/config_accmode.json",
  "data": {
    "accmode": "0"
  }
}

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

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

{
  "cmd": "setconfig_ack",
  "timestamp": "191231123456",
  "tz": -3,
  "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_network.json` — NETWORK

Tipo de rede usado na comunicação. Exige reboot para ter efeito.

Chave	Valor/tipo	Observações
`networkmode`	string(1)	`"0"` = Sem rede; `"1"` = Ethernet RJ45; `"2"` = WiFi

`/config_ethernet.json` — ETHERNET

Parâmetros da conexão Ethernet RJ45. 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

`/config_wifi.json` — WIFI

Parâmetros da conexão 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

`/config_mqtt.json` — MQTT

Parâmetros da conexão com o broker MQTT. 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)	Neon ID

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

`/config_time.json` — TIME

Parâmetros da conexão com o servidor NTP. Exige reboot para ter efeito.

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

`/config_accmode.json` — ACCMODE

Tipo de bloqueio a ser controlado. Efeito imediato.

Chave	Valor/tipo	Observações
`accmode`	string(1)	`"0"` = Catraca completa; `"1"` = Porta completa; `"2"` = Duas portas; `"3"` = Catraca um leitor bidir + urna; `"4"` = Duas portas intertravadas; `"5"` = Registro (logger); `"6"` = Porta com retardo de abertura; `"7"` = Porta intertravada combo; `"8"` = Duas cancelas passagem automática; `"9"` = Catraca telecomando; `"10"` = Catraca leitores unidir controle giro; `"11"` = Catraca telecomando controle giro; `"12"` = Catraca com leitor bidirecional 3 Lock

`/config_listmodecard.json` — LISTMODECARD

Tratamento da lista de cartões local e tratamento de coação. Efeito imediato.

Chave	Valor/tipo	Observações
`alwaysaskserver`	string(1)	`"0"` = Lista local + servidor; `"1"` = Sempre consulta servidor; `"2"` = Nunca consulta servidor
`duressaction`	string(1)	`"1"` = Autoriza passagem em coação; `"2"` = Aplica política normal

`/config_msgs.json` — MSGS

Texto das mensagens apresentadas no display LCD. Efeito imediato. Cada chave é um código de 2 dígitos (string), com valor string(16).

Chave	Significado
`"00"`	Acesso solicitado
`"01"`	Acesso autorizado
`"02"`	Identificador inválido
`"03"`	Identificador inativo
`"04"`	Leitor desabilitado
`"05"`	Acesso negado pelo servidor
`"06"`	Password inválida
`"07"`	Identificador data validade vencida
`"08"`	Negado faixa horária
`"09"`	Acesso negado escort não autorizou
`"10"`	Digite a password
`"11"`	Aguarde autorização do servidor
`"12"`	Aguarde autorização pelo escort
`"13"`	Leitor bloqueado (intertravamento)
`"14"`	Rex bloqueado (intertravamento)
`"15"`	Solicita id biometria (toque o sensor)
`"16"`	Aguarde temporizador (retardo)
`"17"`	Apresente identificação (pós retardo)
`"19"`	Identificador inválido (pós retardo)
`"30"`	Apresente identificação

{
  "00": "ACCESS REQUESTED",
  "01": "ACCESS GRANTED  ",
  "02": "INVALID IDENTITY",
  "30": " SHOW YOUR CARD "
}

`/config_readers.json` — READERS

Configuração dos leitores de cartão (Wiegand/Abatrack). Efeito imediato.

Chave	Valor/tipo	Observações
`reader1active`	int(1)	0 = Inativo; 1 = Ativo
`reader1type`	string(3)	`"0"` = Nenhum; `"1"` = Wiegand 26 bits standard; `"2"` = Wiegand 34 bits HID N1002; `"3"` = Wiegand 34 bits HID H10306; `"4"` = Wiegand 66 TOTP; `"5"` = Wiegand 66 LN (Linear); `"6"` = Wiegand 34 Antena TAG Hex (Acura); `"7"` = Wiegand 26 Citrox KB; `"8"` = Wiegand 32 Mifare; `"9"` = Wiegand 34 Mifare; `"10"` = Wiegand 32 Mifare HID RK40; `"11"` = Wiegand 34 HIK DS-K1100; `"101"` = Abatrack standard
`reader2active`	int(1)	Idem `reader1active`
`reader2type`	string(1)	Idem `reader1type`

note

Na leitura (getconfig do arquivo READERS) a lista de reader1type apresentada no manual é reduzida ("0", "1", "2", "3", "101"). A relação completa acima é a do ajuste (setconfig).

`/config_uarts.json` — UARTS

Parâmetros das UARTs (portas seriais). Efeito imediato.

Chave	Valor/tipo	Observações
`uart1active`	int(1)	0 = Inativa; 1 = Ativa
`uart1type`	string(1)	`"0"` = Nenhum; `"1"` = Data + `<CR>`; `"2"` = QR Code Accelero (crypto); `"3"` = Bluetooth; `"4"` = Suprema modo 1:1; `"5"` = Suprema modo 1:N; `"6"` = QR Code Livo; `"7"` = Autodetect QRCode Livo/QRCode Accelero/Data`<CR>`
`uart1baud`	string(6)	`"1200"`, `"2400"`, `"4800"`, `"9600"`, `"19200"`, `"38400"`, `"57600"` ou `"115200"`
`uart2active`	int(1)	Idem `uart1active`
`uart2type`	string(1)	Idem `uart1type`
`uart2baud`	string(6)	Idem `uart1baud`

`/config_relays.json` — RELAYS

Parâmetros dos relés. Efeito imediato. Numeração: Relé 1 = LOCK1; Relé 2 = ALARM1; Relé 3 = LOCK2; Relé 4 = ALARM2.

Chave	Valor/tipo	Observações
`relay1_default_state`	string(1)	`"0"` = Desligado; `"1"` = Ligado
`relay1_preset_timer`	string(3)	Tempo de energização em segundos
`relay2_default_state`	string(1)	Idem `relay1_default_state`
`relay2_preset_timer`	string(3)	Idem `relay1_preset_timer`
`relay3_default_state`	string(1)	Idem `relay1_default_state`
`relay3_preset_timer`	string(3)	Idem `relay1_preset_timer`
`relay4_default_state`	string(1)	Idem `relay1_default_state`
`relay4_preset_timer`	string(3)	Idem `relay1_preset_timer`

`/config_channels.json` — CHANNELS

Parâmetros dos canais. Efeito imediato.

Chave	Valor/tipo	Observações
`channel1checkescort`	int(1)	0 = Não solicita escort; 1 = Exige escort
`channel1checkpasswd`	int(1)	0 = Não solicita password; 1 = Exige password
`channel1checkbio`	int(1)	0 = Não solicita biometria; 1 = Exige biometria
`channel1ignorevsv`	int(1)	0 = Verifica na lista local sem consultar servidor; 1 = Consulta servidor sem verificar lista local
`channel1searchuid`	int(1)	0 = Identifica pelo cartão; 1 = Identifica pelo ID do usuário
`channel1dontuserelayalarm`	int(1)	0 = Relé Alarme normal; 1 = Relé Alarme desabilitado
`channel2checkescort`	int(1)	Idem `channel1checkescort`
`channel2checkpasswd`	int(1)	Idem `channel1checkpasswd`
`channel2checkbio`	int(1)	Idem `channel1checkbio`
`channel2ignorevsv`	int(1)	Idem `channel1ignorevsv`
`channel2searchuid`	int(1)	Idem `channel1searchuid` (vale p/ canal 3)
`channel2dontuserelayalarm`	int(1)	Idem `channel1dontuserelayalarm`
`channel3checkescort`	int(1)	Idem `channel1checkescort`
`channel3checkpasswd`	int(1)	Idem `channel1checkpasswd`

`/config_timeouts.json` — TIMEOUTS

Parâmetros de timeout e timers. Efeito imediato.

Chave	Valor/tipo	Observações
`timeout_password`	string(2)	Tempo máx (s) para entrada de password
`timeout_bio`	string(2)	Tempo máx (s) para entrada de biometria
`timeout_escort`	string(2)	Tempo máx (s) para identificação de escort
`timeout_capture`	string(2)	Tempo máx (s) para captura de cartão
`timeout_consulta_server`	string(2)	Tempo máx (s) para resposta do servidor
`timeout_user_delayed_door`	string(2)	Tempo máx (s) para identificação de usuário em porta com retardo
`timeout_open_door`	string(2)	Tempo máx (s) para detecção de porta aberta por tempo excessivo
`timer_delayed_door`	string(3)	Tempo default (off-line) para reidentificação em porta com retardo

`/config_totp.json` — TOTP

Parâmetros de validação TOTP. Efeito imediato.

Chave	Valor/tipo	Observações
`totp_enable`	int(1)	0 = TOTP habilitado; 1 = TOTP desabilitado
`totp_key`	string(20)	Secret TOTP Key
`totp_duration`	string(3)	Janela de tempo para validação (s)
`totp_tolerance`	string(3)	Quantidade de janelas de tolerância

caution

No manual, o campo totp_enable está documentado como 0 = TOTP habilitado / 1 = TOTP desabilitado (lógica invertida em relação ao esperado). Mantido conforme a fonte; confirmar com firmware antes de usar.

`/config_counter.json` — COUNTER

Contadores de passagem. Disponível apenas para bloqueios telecomando com controle de giro. Efeito imediato.

Chave	Valor/tipo	Observações
`counterA`	int(5)	Valor do contador anti-horário
`counterH`	int(5)	Valor do contador horário

Mensagens enviadas pelo controlador

Validação online de acesso (`acc_req`)

Enviada quando o controlador está configurado para consultar o servidor e o cartão também está configurado para essa checagem.

Tópico: ${facilityid}/${alias}/from/access

Chave	Valor/tipo	Observações
`cmd`	`"acc_req"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`tz`	int(3)	Timezone
`msgid`	int(5)	0 a 60000
`card`	string(16)	Número do cartão
`channel`	int(1)	Canal onde a requisição ocorreu
`search`	string(3)	Modo de busca: `"ref"` (por cartão) ou `"uid"` (por ID)
`origin`	int(2)	Origem do evento (vide ORIGEM_EVENTOS)
`channelaux`	array[int]	Canais associados à requisição (em bloqueios bidirecionais, dois canais podem estar presentes)
`tp`	int(1)	Tipo do cartão (vide TIPOS_CARTAO)
`uid`	int(9)	ID do usuário (int32)

{
  "cmd": "acc_req",
  "timestamp": "191231123456",
  "tz": -3,
  "msgid": 18651,
  "card": "123456",
  "channel": 1,
  "origin": 2,
  "channelaux": [1],
  "search": "ref",
  "tp": 1,
  "uid": 48982
}

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

Chave	Valor/tipo	Observações
`cmd`	`"acc_req_auth"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	ID da mensagem original
`channel`	int(1)	Canal que deve tratar a resposta
`sts`	int(1)	Código de retorno (vide STATUS_ACC_REQUEST)
`uid`	int(9)	Opcional. ID do usuário (int32)
`password`	string(5)	Opcional. Hash da senha do usuário, caso o controlador deva exigir senha antes de liberar
`delay1`	int(3)	Tempo de retardo para reidentificação (s). Apenas modo 6 (porta com retardo)
`delay2`	int(2)	Limite de tempo para reidentificação (s). Apenas modo 6
`channelaux`	string(1)	Sentido da liberação: `"1"` = canal 01; `"2"` = canal 02; `"0"` = ambos
`templatesize`	int(5)	Opcional. Tamanho do template biométrico para validação
`template`	string	Opcional. Template biométrico em base64
`disp1`	string(16)	Opcional. Mensagem na linha 1 do display (válido só com display configurado p/ mensagens do servidor e modo Catraca Telecomando)
`disp2`	string(16)	Opcional. Mensagem na linha 2 do display (válido só com display configurado p/ mensagens do servidor)

{
  "cmd": "acc_req_auth",
  "timestamp": "191231123456",
  "msgid": 18651,
  "channel": 1,
  "sts": 1,
  "uid": 7718,
  "password": "88147",
  "channelaux": "1"
}

Validação online de escort (`acc_req_escort`)

Enviada quando um cartão apresentado como escort exige validação online.

Tópico: ${facilityid}/${alias}/from/access

Chave	Valor/tipo	Observações
`cmd`	`"acc_req_escort"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`tz`	int(3)	Timezone
`msgid`	int(5)	0 a 60000
`channel`	int(1)	Canal onde a requisição ocorreu
`origin`	int(2)	Origem do evento (vide ORIGEM_EVENTOS)
`channelaux`	array[int]	Canais associados à requisição
`search`	string(3)	`"ref"` (por cartão) ou `"uid"` (por ID)
`card`	string(16)	Número do cartão da pessoa escortada
`tp`	int(1)	Tipo do cartão (vide TIPOS_CARTAO)
`uid`	int(9)	ID do usuário (int32)
`card_escort`	string(16)	Número do cartão do escort
`uid_escort`	int(9)	ID do escort (int32)

{
  "cmd": "acc_req_escort",
  "timestamp": "220118124609",
  "tz": -3,
  "msgid": 28235,
  "channel": 1,
  "origin": 1,
  "channelaux": [1],
  "search": "ref",
  "card": "         1794077",
  "tp": 0,
  "uid": 0,
  "card_escort": "          473040",
  "uid_escort": 0
}

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

Chave	Valor/tipo	Observações
`cmd`	`"acc_req_escort_auth"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`msgid`	int(5)	ID da mensagem original
`channel`	int(1)	Canal que deve tratar a resposta
`sts`	int(1)	Código de retorno (vide STATUS_ACC_REQUEST)

{
  "cmd": "acc_req_escort_auth",
  "timestamp": "191231123456",
  "msgid": 4124,
  "channel": 1,
  "sts": 1
}

Envio de log (`log`)

O controlador envia logs operacionais sempre que a conexão com o broker estiver online (logs de acesso, de sistema e outros). As mensagens são publicadas em sub-tópicos específicos por tipo de evento (origin) e por pessoa (uid), o que permite monitoramento granular. Para tratar todos os logs, basta fazer subscribe no tópico base .../from/log/#.

Tópico: ${facilityid}/${alias}/from/log/${origin}/${uid}

Chave	Valor/tipo	Observações
`cmd`	`"log"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`tz`	int(3)	Timezone
`origin`	int(2)	Origem do evento (vide ORIGEM_EVENTOS)
`search`	string(3)	`"ref"` (por cartão) ou `"uid"` (por ID)
`uid`	int(9)	ID do usuário do evento (int32) (vide IDENTIFICADOR_EVENTOS)
`ref`	string(16)	Número do cartão associado ao evento; string vazia se não houver
`event`	int(2)	Identificador do evento (vide TIPOS_EVENTOS)
`accmode`	int(2)	Modo de funcionamento do controlador (vide MODOS_CONTROLE)

{
  "cmd": "log",
  "timestamp": "191231123456",
  "tz": -3,
  "origin": 2,
  "search": "ref",
  "uid": 739812,
  "ref": "84019809321",
  "event": 2,
  "accmode": 1
}

Resposta: não há.

Keepalive (`keepalive`)

Enviado periodicamente para que o servidor monitore o status. Publicado com flag retain_message ativa.

Tópico: ${facilityid}/${alias}/from/keepalive

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

{
  "cmd": "keepalive",
  "timestamp": "191231123456",
  "tz": -3,
  "uptime": 15398,
  "nrestart": 23,
  "ncmqtt": 1
}

Resposta: não há.

Info (`info`)

Enviada periodicamente com o estado atual do controlador. Publicada com flag retain_message ativa. Também é enviada imediatamente após o comando get_info.

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

Chave	Valor/tipo	Observações
`cmd`	`"info"`	Valor fixo
`timestamp`	string(12)	YYMMDDHHMMSS
`tz`	int(3)	Timezone
`boardid`	string	Identificador único do controlador
`serialid`	string	Número de série de fabricação
`version`	string	Versão de firmware em uso
`capcards`	int	Capacidade máxima de cartões em memória
`freecards`	int	Quantidade de cartões livres em memória
`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
`opmode`	int	Vide MODOS_OPERACAO
`accmode`	int	Vide MODOS_CONTROLE
`reader1active`	int(1)	0 (inativo) ou 1 (ativo)
`reader1desc`	string	Descrição do tipo de leitor
`reader2active`	int(1)	0 (inativo) ou 1 (ativo)
`reader2desc`	string	Descrição do tipo de leitor
`uart1active`	int(1)	0 (inativo) ou 1 (ativo)
`uart1desc`	string	Descrição do dispositivo conectado
`uart2active`	int(1)	0 (inativo) ou 1 (ativo)
`uart2desc`	string	Descrição do dispositivo conectado
`bio1desc`	string	Descrição do módulo biométrico do canal 1
`bio1used`	int(5)	Templates utilizados no canal 1
`bio1free`	int(5)	Templates livres no canal 1
`bio2desc`	string	Descrição do módulo biométrico do canal 2
`bio2used`	int(5)	Templates utilizados no canal 2
`bio2free`	int(5)	Templates livres no canal 2

{
  "cmd": "info",
  "timestamp": "191231123456",
  "tz": -3,
  "boardid": "aurum-4824",
  "version": "v1.013.911",
  "accmode": 1,
  "capcards": 5000,
  "freecards": 1917,
  "media": "wireless",
  "iplocal": "192.168.0.77",
  "ipdns": "8.8.8.8",
  "ipgateway": "192.168.0.1",
  "subnetmask": "255.255.255.0",
  "reader1active": 1,
  "reader1desc": "Wiegand26",
  "reader2active": 0,
  "reader2desc": "",
  "uart1active": 1,
  "uart1desc": "Serial CRLF",
  "uart2active": 1,
  "uart2desc": "Serial CRLF",
  "bio1desc": "SFM5020",
  "bio1used": 900,
  "bio1free": 100,
  "bio2desc": "",
  "bio2used": -1,
  "bio2free": -1
}

Resposta: não há.

Status (`status`)

A NEON envia periodicamente seu status de comunicação. Publicada com flag retain_message ativa.

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

Chave	Valor/tipo	Observações
`cmd`	`"status"`	Valor fixo
`status`	string(12)	`"connected"` ou `"disconnected"`
`timestamp`	string(12)	YYMMDDHHMMSS (apenas em `"connected"`)
`tz`	int(3)	Timezone (apenas em `"connected"`)

A mensagem "disconnected" é enviada pelo broker via LWT (Last Will Testament), ou seja, quando o broker detecta a falha de comunicação com a NEON.
Apenas a mensagem com status "connected" possui os parâmetros timestamp e tz.

{
  "cmd": "status",
  "status": "connected",
  "timestamp": "191231123456",
  "tz": -3
}

{
  "cmd": "status",
  "status": "disconnected"
}

Resposta: não há.

Tabelas de referência

ORIGEM_EVENTOS

Código	Descrição
0	Eventos de sistema
1	Leitor ABA/WIE — canal 1 ou REX01
2	Leitor ABA/WIE — canal 2 ou REX02
3	Leitor ABA/WIE — canal 3 (não usado)
4	UART — canal 1
5	UART — canal 2
6	NÃO UTILIZADO
7	WEB — canal 1
8	WEB — canal 2
9	WEB — canal 3
10	MQTT — canal 1
11	MQTT — canal 2
12	MQTT — canal 3
13	QRCODE — canal 1
14	QRCODE — canal 2
15	NÃO UTILIZADO

ESTADOS_OPERACAO

Código	Descrição
0	Normal
2	Emergência
3	Pânico

TIPOS_CARTAO

Código	Descrição
0	Normal / visitante
1	Temporário
2	Emergência
3	Pânico
4	QRCode dinâmico

IDENTIFICADOR_EVENTOS

Valor	Descrição
`"NEON"`	Evento interno do controlador
`"MQTT_cmd"`	Evento associado diretamente a uma mensagem recebida via MQTT
`"REX_SWITCH"`	Evento disparado por acionamento de botão de abertura
`"DOOR_SWITCH"`	Evento disparado por timeout de porta aberta
`"?"`	Evento envolve um cartão mas não foi possível identificar o usuário associado
`${ID do usuário}`	String com o ID do usuário, quando o evento de acesso teve o usuário devidamente identificado

TIPOS_EVENTOS

Código	Descrição
0	Acesso solicitado
1	Acesso autorizado
2	Acesso negado (cartão não encontrado)
3	Acesso negado (cartão não habilitado)
4	Acesso negado (usuário não habilitado no leitor)
5	Acesso negado (autorização negada pelo servidor)
6	Acesso negado (senha inválida)
7	Acesso negado (cartão fora da data de validade)
8	Acesso negado (acesso fora da faixa horária permitida)
9	Acesso negado (Escort inválido)
13	Acesso negado (intertravamento leitor)
14	Acesso negado (intertravamento REX)
20	Acesso autorizado não realizado
21	Acesso autorizado pelo servidor
22	Acesso autorizado por um Escort
33	Abertura de bloqueio via botão
34	Passagem efetivamente realizada
35	Modo de emergência ligado
36	Modo de emergência desligado
37	Timeout de porta aberta
39	Porta forçada
40	Acesso solicitado bidirecional
41	Acesso autorizado bidirecional
42	Identificador lido no modo LOGGER
44	Porta normalizada

MODOS_OPERACAO

Código	Descrição
0	Se a comunicação com o servidor está OK, consulta o servidor (exceto identificadores marcados para não consultar). Em modo contingência, usa a lista local
1	Consulta o servidor por identificadores detectados; não usa lista local (exceto cartões de coação existentes na lista local quando em contingência)
2	Busca identificadores apenas na lista local; não consulta o servidor

MODOS_CONTROLE

Código	Descrição
0	Catraca completo, com leitores unidirecionais
1	Porta completa, com leitores unidirecionais
2	Duas portas, cada uma com leitor para entrada e botão para saída
3	Catraca bidirecional com urna opcional
4	Duas portas intertravadas
5	Modo logger
6	Porta com retardo de abertura

STATUS_ACC_REQUEST

Código	Descrição
0	Acesso negado
1	Acesso autorizado
2	Acesso condicionado à presença de Escort
3	Acesso condicionado à autorização por senha
4	Acesso condicionado a biometria
5	Acesso pré-autorizado com retardo (parâmetros `delay1` e `delay2`)

Visão geral do protocolo​

Conceitos básicos​

Facility ID​

Estrutura de tópicos MQTT​

Identificação das mensagens​

Valores JSON​

Mensagens enviadas pelo servidor​

Keepalive​

Acesso via MQTT (access_mqtt)​

Acesso pré-autorizado via MQTT (access_auto)​

Solicitar envio de estado (get_info)​

Liberação de bloqueio / REX (rex_server)​

Capturar dados do próximo cartão (capture)​

Definir estado de operação (set_mode)​

Buscar versão (get_version)​

Upgrade de firmware (upgrade)​

Envio de lista de cartões (load_cards)​

Excluir todos os cartões (wipe_cards)​

Excluir cartão específico (del)​

Inserir ou alterar cartão (ins)​

Mensagens de biometria (servidor → controlador)​

Capturar template biométrico (bioget_template)​

Obter dados sobre módulo biométrico (bioget_info)​

Adicionar template biométrico (bioenroll)​

Excluir template biométrico (biodel)​

Comandos de operação e manutenção (servidor → controlador)​

Forçar modo offline (force_offline)​

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

Forçar relé (force_relay)​

Remover forçamento de relé (unforce_relay)​

Imprimir ticket QR Code (print)​

Forçar modo configuração (enablecfg)​

Arquivos de configuração​

Ler arquivos de configuração (getconfig)​

Ajustar arquivos de configuração (setconfig)​

Campos do objeto data por arquivo​

/config_network.json — NETWORK​

/config_ethernet.json — ETHERNET​

/config_wifi.json — WIFI​

/config_mqtt.json — MQTT​

/config_time.json — TIME​

/config_accmode.json — ACCMODE​

/config_listmodecard.json — LISTMODECARD​

/config_msgs.json — MSGS​

/config_readers.json — READERS​

/config_uarts.json — UARTS​

/config_relays.json — RELAYS​

/config_channels.json — CHANNELS​

/config_timeouts.json — TIMEOUTS​

/config_totp.json — TOTP​

/config_counter.json — COUNTER​

Mensagens enviadas pelo controlador​

Validação online de acesso (acc_req)​

Validação online de escort (acc_req_escort)​

Envio de log (log)​

Keepalive (keepalive)​

Info (info)​

Status (status)​

Tabelas de referência​

ORIGEM_EVENTOS​

ESTADOS_OPERACAO​

TIPOS_CARTAO​

IDENTIFICADOR_EVENTOS​

TIPOS_EVENTOS​

MODOS_OPERACAO​

MODOS_CONTROLE​

STATUS_ACC_REQUEST​

Visão geral do protocolo

Conceitos básicos

Facility ID

Estrutura de tópicos MQTT

Identificação das mensagens

Valores JSON

Mensagens enviadas pelo servidor

Keepalive

Acesso via MQTT (`access_mqtt`)

Acesso pré-autorizado via MQTT (`access_auto`)

Solicitar envio de estado (`get_info`)

Liberação de bloqueio / REX (`rex_server`)

Capturar dados do próximo cartão (`capture`)

Definir estado de operação (`set_mode`)

Buscar versão (`get_version`)

Upgrade de firmware (`upgrade`)

Envio de lista de cartões (`load_cards`)

Excluir todos os cartões (`wipe_cards`)

Excluir cartão específico (`del`)

Inserir ou alterar cartão (`ins`)

Mensagens de biometria (servidor → controlador)

Capturar template biométrico (`bioget_template`)

Obter dados sobre módulo biométrico (`bioget_info`)

Adicionar template biométrico (`bioenroll`)

Excluir template biométrico (`biodel`)

Comandos de operação e manutenção (servidor → controlador)

Forçar modo offline (`force_offline`)

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

Forçar relé (`force_relay`)

Remover forçamento de relé (`unforce_relay`)

Imprimir ticket QR Code (`print`)

Forçar modo configuração (`enablecfg`)

Arquivos de configuração

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

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

Campos do objeto `data` por arquivo

`/config_network.json` — NETWORK

`/config_ethernet.json` — ETHERNET

`/config_wifi.json` — WIFI

`/config_mqtt.json` — MQTT

`/config_time.json` — TIME

`/config_accmode.json` — ACCMODE

`/config_listmodecard.json` — LISTMODECARD

`/config_msgs.json` — MSGS

`/config_readers.json` — READERS

`/config_uarts.json` — UARTS

`/config_relays.json` — RELAYS

`/config_channels.json` — CHANNELS

`/config_timeouts.json` — TIMEOUTS

`/config_totp.json` — TOTP

`/config_counter.json` — COUNTER

Mensagens enviadas pelo controlador

Validação online de acesso (`acc_req`)

Validação online de escort (`acc_req_escort`)

Envio de log (`log`)

Keepalive (`keepalive`)

Info (`info`)

Status (`status`)

Tabelas de referência

ORIGEM_EVENTOS

ESTADOS_OPERACAO

TIPOS_CARTAO

IDENTIFICADOR_EVENTOS

TIPOS_EVENTOS

MODOS_OPERACAO

MODOS_CONTROLE

STATUS_ACC_REQUEST