Pular para o conteúdo principal

Documentação técnica

Manual técnico do Middleware Mobile RFID para configuração de leitor, integração HTTP, coleta de leituras e envio de dados.

Visão geral​

O app Middleware Mobile permite configurar um leitor RFID/2D, coletar leituras de tags ou códigos de barras e enviar essas leituras para uma integração HTTP configurável.

Fluxo principal:

  1. Configurar o leitor RFID.
  2. Criar uma integração.
  3. Selecionar a integração.
  4. Realizar as leituras.
  5. Enviar os dados para o endpoint configurado.

1. Configuração do RFID​

Dispositivo RFID​

  1. Toque em Atualizar para buscar leitores disponíveis.
  2. Aguarde a lista de dispositivos aparecer.
  3. Toque no leitor desejado.
  4. O dispositivo selecionado aparecerá como selecionado.

Se nenhum dispositivo aparecer, verifique:

  • Leitor ligado
  • Bluetooth ativo
  • Distância entre leitor e celular/coletor
  • Permissões concedidas ao app

Potência de leitura​

A potência define a intensidade com que o leitor RFID busca as tags.

  1. Use o controle deslizante em potência de leitura.
  2. Escolha o valor desejado.
  3. Quanto maior a potência, maior tende a ser o alcance da leitura.

Recomendação:

  • Potência baixa: leitura próxima e mais controlada
  • Potência alta: maior alcance, podendo capturar tags indesejadas

A alteração é aplicada na próxima conexão ou leitura do leitor.

Volume do beep​

Opções disponíveis:

  • Desligado
  • Baixo
  • Médio
  • Alto

Prefixo EPC nativo​

O prefixo EPC limita a leitura nativa do leitor para tags que começam com determinado valor.

Exemplo: 4F400251

Com esse prefixo configurado, o leitor prioriza tags cujo EPC começa com 4F400251.

Session RFID​

A session define o comportamento de repetição das leituras RFID.

  • S0: reseta rápido, ideal para leitura contínua
  • S1: curto prazo, ideal para inventário rápido
  • S2: médio prazo, ajuda a evitar releituras
  • S3: longo prazo, controle mais rígido de releitura

Dev mode​

Permite usar o app sem conectar um leitor físico.

Use apenas para testes e simulações.

2. Filtros de leitura​

Os filtros de leitura são aplicados no app, após a leitura chegar do leitor.

Tipo de filtro​

  • Prefixo
  • Sufixo
  • Regex

Modo​

  • Incluir
  • Excluir

Valor​

Define o texto ou expressão do filtro.

Exemplo com prefixo: 4F400251

RSSI mínimo​

Define a força mínima do sinal para aceitar uma leitura.

Referência prática:

  • 40: sinal forte
  • 70: sinal médio/fraco
  • 90: sinal fraco

3. Criação de integração​

Na tela de integrações:

  1. Toque para criar uma nova integração.
  2. Informe os dados da integração.

Campos principais:

  • Nome: identificador da integração
  • Endpoint URL: URL que receberá as leituras
  • Tipo de leitura:
    • RFID + 2D
    • Somente 2D
  • Método HTTP:
    • POST
    • PUT

4. Autenticação​

Tipos suportados:

Nenhuma​

Usar quando o endpoint não exige autenticação.

API Key​

Configurações:

  • Nome do parâmetro
  • Valor
  • Enviar em:
    • Query string
    • Header

Bearer Token​

Informe apenas o token. O app monta o header automaticamente.

Basic Auth​

Informe usuário e senha. O app monta o header Authorization automaticamente.

5. Campos extras do corpo​

Além das leituras, a integração pode enviar campos extras no corpo da requisição.

Tipos disponíveis:

  • Texto
  • Número
  • Booleano

Esses campos aparecem na tela de leitura para preenchimento antes do envio.

6. Tela de leituras​

Status do leitor​

Exibe estados como:

  • Leitor conectado
  • Conectando leitor
  • Modo 2D ativo
  • Dev mode

Alternar entre RFID e 2D​

Quando a integração for RFID + 2D, é possível alternar entre os modos.

Lista de leituras​

Cada leitura exibe:

  • EPC ou código lido
  • RSSI
  • Opção para localizar item

Ordenação das leituras​

Opções:

  • Última leitura
  • Primeira leitura
  • RSSI

7. Localizar item​

Na lista de leituras, toque em Localizar item.

O app mostra:

  • EPC da tag
  • Percentual de proximidade
  • Barra visual de aproximação

Use o gatilho do leitor para iniciar a localização.

8. Envio das leituras​

  1. Confira campos extras.
  2. Confira a lista de leituras.
  3. Toque em Enviar leituras.

Resultados:

  • Sucesso: mensagem de sucesso e limpeza das leituras
  • Falha: mensagem com retorno da API ou erro de conexão

9. Formato do payload enviado​

Exemplo:

{
	"user": "gui",
	"completo": true,
	"leituras": [
		{
			"epc": "4F4002511030700338000456",
			"rssi": -47,
			"firstseen": 1776952386455,
			"lastseen": 1776952392382
		}
	]
}

Campos da leitura:

  • epc: EPC ou código lido
  • rssi: força do sinal RFID
  • firstseen: timestamp da primeira leitura
  • lastseen: timestamp da última leitura

Os timestamps são enviados em milissegundos.

10. Boas práticas​

Antes da leitura:

  • Confirmar integração selecionada
  • Confirmar leitor conectado
  • Ajustar potência para o ambiente
  • Usar prefixo EPC para reduzir leituras indesejadas
  • Usar filtro por RSSI quando houver muitas tags próximas

Durante a leitura:

  • Evitar apontar o leitor para áreas com tags indesejadas
  • Usar RSSI para priorizar leituras mais próximas
  • Usar localizar item para encontrar tag específica

Antes do envio:

  • Conferir campos extras
  • Conferir total de leituras
  • Validar endpoint da integração

11. Resolução de problemas​

Nenhum dispositivo RFID aparece​

Verificar:

  • Bluetooth ligado
  • Leitor ligado
  • Permissões concedidas
  • Leitor próximo ao dispositivo

O leitor conecta, mas não lê tags​

Verificar:

  • Potência de leitura
  • Prefixo EPC nativo
  • Filtros ativos
  • Session RFID
  • Modo RFID ativo

Leituras aparecem, mas não enviam​

Verificar:

  • Endpoint URL
  • Método HTTP
  • Autenticação
  • Campos obrigatórios da API
  • Conexão com internet
  • Mensagem de erro exibida no app

RSSI muito baixo​

Possíveis causas:

  • Tag distante
  • Potência baixa
  • Interferência no ambiente
  • Tag mal posicionada
  • Direção incorreta do leitor

Muitas leituras indesejadas​

Possíveis soluções:

  • Reduzir potência
  • Usar prefixo EPC
  • Ativar filtro por prefixo, sufixo ou regex
  • Configurar RSSI mínimo
  • Usar session S2 ou S3

12. Mapeamento de telas do app​

Estrutura atual observada no front:

  • Integrations: lista e seleção de integrações
  • IntegrationForm: cadastro/edição de integração
  • RfidSettings: parâmetros RFID e filtros
  • Reads: operação de leitura e envio
  • ExportImport: backup/restauração de integrações
  • Logs: área reservada para histórico operacional

13. Arquitetura da solução​

A arquitetura do Middleware Mobile RFID foi projetada para operação em campo com baixa fricção de integração.

Componentes:

  • Dispositivo handheld para coleta
  • Camada de telas dinâmicas para operação
  • Motor de processamento e fila de envio
  • API externa para consumo dos eventos

Conectividade:

  • Modo online para envio imediato
  • Modo offline para armazenamento local e sincronização posterior

14. Persistência local​

O app salva localmente:

  • Integrações cadastradas
  • Configurações RFID
  • Filtros de leitura

Isso permite manter o ambiente configurado entre sessões no dispositivo.

15. Exportação e importação de integrações​

  • Exportação gera JSON com as integrações atuais
  • Importação valida a estrutura antes de aplicar
  • Em caso de erro, a importação é rejeitada com mensagem descritiva

Validações observadas:

  • id e name obrigatórios
  • method aceitando apenas POST ou PUT
  • readMode aceitando BARCODE ou HYBRID
  • Estrutura mínima de autenticação
  • Estrutura de campos extras (fieldDefs) quando presente

16. Checklist inicial​

  1. Definir integrações e contratos de payload por operação.
  2. Configurar autenticação correta para cada endpoint.
  3. Selecionar modo de leitura adequado (híbrido ou 2D).
  4. Ajustar parâmetros RFID conforme ambiente físico.
  5. Definir filtros para reduzir leituras indesejadas.
  6. Validar envio, retorno de erro e limpeza de leituras após sucesso.
  7. Exportar JSON de configurações como backup operacional.