Antenas
Antenas são os receptores de sinal BLE instalados nas zonas do site. Cada antena capta os advertisements BLE emitidos pelos beacons e os envia ao servidor via MQTT para o cálculo de localização — a própria antena atua como gateway (BLE → MQTT), sem necessidade de um dispositivo intermediário.
A antena de campo da Iongrade é o Gateway Radium — hardware proprietário. O ION Guard também é compatível com gateways BLE de terceiros — atualmente o Minew MG4C —, que atuam como antena da mesma forma.
Nesta página, antena é o termo genérico para o dispositivo de campo do módulo Synapsys. A antena da Iongrade é o Gateway Radium; o Minew MG4C é um gateway de terceiros compatível. As instruções valem para ambos, salvo onde indicado (ex.: os parâmetros de scan específicos de gateways Minew).
| Antena | Origem | Configuração do MQTT | Documentação |
|---|---|---|---|
| Gateway Radium | Hardware proprietário Iongrade | Pelo portal do próprio gateway (Comunicação ▸ MQTT) — ver Configuração manual | Documentação do Radium |
| Minew MG4C | Gateway de terceiros | Provisionamento automático pela API HTTP local do gateway | — |
Status da antena
| Status | Indicador | Significado |
|---|---|---|
| Pendente | Cinza | Cadastrada mas ainda não conectou |
| Online | Verde (pulsante) | Recebendo e transmitindo sinais |
| Offline | Vermelho | Parou de transmitir sinais |
| Manutenção | Azul | Temporariamente offline para manutenção programada |
Lista de antenas
A página de Antenas (/antennas) exibe todas as antenas do site selecionado:
- Hardware ID — Identificador único do dispositivo (MAC address)
- Label — Nome amigável
- Status — Com indicador visual (dot pulsante quando online)
- Zona — Zona atribuída (ou "Não atribuída")
- Último sinal — Quando a antena foi vista pela última vez
Filtros disponíveis
- Busca por hardware ID ou label
- Status: Pendente, Online, Offline, Manutenção
- Ordenação por hardware ID, label ou último sinal
Cadastrar uma antena
- Na lista de antenas, clique em "Adicionar Antena"
- Preencha o formulário:
| Campo | Obrigatório | Descrição |
|---|---|---|
| Hardware ID | Sim | MAC address do gateway (ex: AC233FC22C94). Único por site |
| Driver | Sim | Driver de hardware compatível (ex: Minew MG4C Gateway) |
| Label | Sim | Nome amigável (ex: "Antena - Recepção Norte"). Máx. 255 caracteres |
| IP do Gateway | Não | Endereço IP do gateway na rede local (ex: 192.168.1.100). Necessário para provisionamento automático |
| Zona | Não | Zona à qual a antena está associada. Pode ser atribuída depois |
- Clique em "Salvar"
Consulte a tabela ARP do servidor (arp -a) ou o painel do roteador para encontrar o IP do gateway pelo MAC address. Gateways Minew aparecem com hostname no formato MG4C-xxxxxx.
Configuração do gateway
Após cadastrar a antena, ela precisa ser configurada para enviar dados ao servidor ION Guard via MQTT. Existem duas formas:
Provisionamento automático (recomendado)
O ION Guard pode configurar o gateway automaticamente via sua API HTTP local. Este método está disponível quando o servidor e o gateway estão na mesma rede (instalações on-premises).
O provisionamento automático depende da API HTTP local do gateway e hoje está disponível para os gateways Minew MG4C. No Radium, por decisão de projeto, a configuração de rede e do broker é feita somente pelo portal da própria placa — nunca remotamente —, justamente para o gateway não se trancar fora da rede por um comando remoto. Use a configuração manual.
- Na página de detalhes da antena, verifique que o campo IP do Gateway está preenchido
- Clique no botão "Provisionar Gateway"
- O sistema verifica se o gateway está acessível e exibe suas informações (modelo, versão, bateria)
- Confirme clicando em "Provisionar"
O provisionamento executa automaticamente:
- Geração de credenciais MQTT únicas (username + password)
- Envio da configuração completa ao gateway (broker MQTT, tópicos, parâmetros de scan)
- Reboot do gateway para aplicar as configurações
Após ~10 segundos, o gateway reconecta ao broker MQTT e começa a enviar dados. O status muda de Pendente para Online.
Ao provisionar novamente uma antena que já foi configurada, as credenciais anteriores são invalidadas. O gateway receberá novas credenciais automaticamente.
Configuração manual
Para gateways que não são acessíveis via rede (ex: instalações SaaS onde o servidor está na nuvem), a configuração deve ser feita manualmente:
- Clique em "Gerar Credenciais MQTT" para obter username e password
- Clique no botão de informações MQTT para ver os parâmetros de conexão
- Acesse a interface web do gateway (ex:
http://192.168.1.100) e configure:
| Parâmetro | Valor |
|---|---|
| MQTT URL | mqtt://{ip-do-servidor}:{porta} |
| Client ID | Hardware ID da antena (ex: AC233FC22C94) |
| Username | Valor gerado pelo sistema |
| Password | Valor gerado pelo sistema |
| Publish Topic | ionguard/{hardware_id}/signals |
| Subscribe Topic | ionguard/{hardware_id}/to |
| Response Topic | ionguard/{hardware_id}/from |
| QoS | 1 |
| Keep Alive | 30 segundos |
A senha MQTT é exibida apenas uma vez no momento da geração. Se perdê-la, gere novas credenciais.
No Gateway Radium
No Radium, o portal é servido pela própria placa: entre no modo de configuração aproximando o ímã do sensor magnético, conecte-se à rede WiFi do gateway e abra http://192.168.4.1 — o procedimento completo está no Manual de Instalação do Radium.
Os parâmetros gerados acima são preenchidos em Comunicação ▸ MQTT (referência dos campos):
| Parâmetro do ION Guard | Onde informar no Radium |
|---|---|
| MQTT URL (host e porta) | Tipo de conexão = Manual, campos Broker e Porta |
| Username / Password | Usuário e Senha |
| MQTT sobre TLS (porta 8883) | Segurança = TLS (ou mTLS), com a Versão TLS e a verificação de CN/SAN |
| Keep Alive | Comunicação ▸ MQTT — Telemetria, campo Keep-alive |
A página MQTT do Radium não expõe campos de tópico (publish/subscribe/response) — eles são definidos pelo firmware. Use o botão Testar da página MQTT para confirmar a conexão antes de sair do portal.
Parâmetros de scan (gateways Minew)
O provisionamento automático configura os seguintes parâmetros padrão de scan BLE:
| Parâmetro | Valor | Descrição |
|---|---|---|
| Upload Interval | 5s | Intervalo de envio de dados ao servidor |
| Scan Interval | 100ms | Intervalo entre scans BLE |
| Scan Window | 100ms | Janela de scan (100% = scan contínuo) |
| Active Scan | Sim | Captura advertising + scan response packets |
| RSSI Filter | -90 dBm | Ignora sinais mais fracos que -90 dBm (ruído) |
| MAC Filter | ^AC233F.*|^C30000.* | Filtra apenas beacons Minew |
| NTP Server | br.pool.ntp.org | Servidor de tempo brasileiro |
| Timezone | UTC+3 | Horário de Brasília |
Equivalentes no Gateway Radium
No Radium os mesmos parâmetros existem, mas são ajustados no portal da placa — e nenhum deles é enviado pelo ION Guard:
| Parâmetro | Onde fica no Radium | Padrão de fábrica |
|---|---|---|
| Upload Interval | Comunicação ▸ MQTT — Telemetria, Intervalo de envio | 1 s |
| Scan Interval / Scan Window | Hardware ▸ Bluetooth | 100 ms / 80 ms |
| Active Scan | Hardware ▸ Bluetooth, Modo ativo | — |
| RSSI Filter | Hardware ▸ Filtros, RSSI mínimo | -90 dBm |
| MAC Filter | Hardware ▸ Filtros, Filtro por MAC (prefixos) | Vazio (passa tudo) |
| NTP Server / Timezone | Hardware ▸ Horário | ntp.iongrade.com.br · UTC-3 |
No Radium, informe apenas o início do MAC, separando várias famílias por | — ex.: AC233F|C30000. A forma ^AC233F.*|^C30000.* usada nos gateways Minew também é aceita, por compatibilidade: o ^ e o .* são simplesmente ignorados.
Atribuição de zona
A zona atribuída a uma antena determina qual zona o Location Engine considera quando essa antena recebe um sinal de beacon. Por isso:
- Cada antena deve ser atribuída a exatamente uma zona
- Uma zona pode ter múltiplas antenas (melhora a precisão)
- Antenas sem zona atribuída não contribuem para o cálculo de localização
Para atribuir ou alterar a zona, edite a antena e selecione a zona no dropdown.
Detalhes da antena
Ao clicar em uma antena, a página de detalhes exibe:
- Informações gerais — Label, hardware ID, driver, status, zona atribuída
- IP do Gateway — Endereço IP na rede local
- Status do Gateway —
Configurado em {data}quando provisionado - Configuração MQTT — Dados de conexão para referência
Ações disponíveis
| Botão | Função |
|---|---|
| Provisionar Gateway | Configura o gateway automaticamente (gera credenciais + envia config + reboot) |
| Guia MQTT | Exibe os parâmetros de conexão MQTT para configuração manual |
| Gerar Credenciais | Gera ou regenera credenciais MQTT (sem configurar o gateway) |
| Editar | Altera label, zona e IP do gateway |
| Excluir | Remove a antena e suas credenciais MQTT |
Editar uma antena
Na página de detalhes, clique em "Editar". É possível alterar:
- Label — Nome amigável
- IP do Gateway — Endereço IP na rede local
- Zona — Atribuir, trocar ou remover a zona
Excluir uma antena
Na lista ou nos detalhes, clique em "Excluir". Um diálogo de confirmação é exibido. A exclusão desassocia a antena da zona e remove o registro.
Resolução de problemas
Gateway não conecta após provisionamento
- Verifique se o gateway reiniciou (LED pisca durante o boot)
- Aguarde ~15 segundos para a conexão MQTT ser estabelecida
- Verifique os logs do MQTT:
docker logs ionguard_mosquitto_{deploy} | tail -20 - Confirme que o firewall permite a porta MQTT (1883)
Botão "Provisionar" desabilitado
O botão fica desabilitado quando o campo IP do Gateway não está preenchido. Edite a antena e adicione o IP.
Diagnóstico pelo próprio Radium
O Radium sinaliza o problema no LED de status antes mesmo de olhar o servidor: vermelho com 1 piscada = nenhuma interface de rede no ar; 2 piscadas = MQTT fora do ar (broker inacessível); 5 piscadas = relógio sem sincronização. A tabela completa está no Manual de Instalação.
No portal da placa, a página Info ▸ Diagnóstico lista os erros de conexão (MQTT, NTP e quedas de internet) e a página Ferramentas de rede faz ping, DNS e traceroute a partir do próprio gateway.
O Radium continua varrendo e guardando os sinais enquanto o broker está fora do ar, e os republica com o horário original quando a conexão volta — os pânicos primeiro. Ver buffer offline.
Gateway responde mas não envia dados
- Verifique se as credenciais MQTT estão corretas:
docker logs ionguard_mosquitto_{deploy} | grep {hardware_id} - Se aparecer "not authorised", gere novas credenciais via provisionamento
- Verifique o filtro de MAC (
regex_mac) — apenas beacons Minew (AC233F*) são capturados por padrão