H1 Tech - Middleware LITE: Guia de Implantacao e Uso

Este documento orienta a instalacao, validacao e operacao do H1 Tech - Middleware LITE em ambiente on-premise ou servidor local/nuvem. O foco e apoiar engenheiros de implantacao na configuracao do leitor Zebra FX, instalacao do middleware, simulacao de leitores/tags e homologacao de integracoes REST/actions.

1. Visao geral da solucao

O H1 Tech - Middleware LITE faz a ponte entre leitores Zebra FX com DA-APP embarcado e sistemas externos via REST, CSV ou cadeias de actions configuraveis.

Fluxo principal:

Arraste para mover · zoom nos botões (ou Ctrl + scroll) · “Tela cheia” para ampliar

Componentes:

• DA-APP embarcado no leitor FX: agente instalado no leitor Zebra FX que conecta automaticamente ao middleware.
• Middleware backend: recebe o socket do leitor, aplica comandos, acumula leituras e envia lotes.
• Painel web: interface para configurar leitores, actions, modo de leitura, GPI/GPO e leitores simuladores.
• Simulador de APIs: endpoint visual para validar bodies REST antes de apontar para APIs reais.

Para visualizar as telas e o fluxo web com imagens, consulte a página do fluxo:

Fluxo web (baseado no front)

Credenciais padrao do painel:

Usuario: admin
Senha: h1techspencer

2. Instalacao do DA-APP no leitor Zebra FX

O DA-APP sera fornecido junto ao pacote de implantacao. Ele deve ser embarcado no leitor Zebra FX para que o leitor se conecte automaticamente ao middleware.

Ao gerar/configurar o DA-APP, informe:

• IP ou DNS do servidor do middleware: endereco alcancavel a partir da rede do leitor.
• Porta TCP do HIOT/DA-APP: porta usada para socket entre leitor e middleware.
• Usuario e senha do leitor: credenciais usadas pelo DA-APP para autenticar e chamar as APIs locais do FX.

Portas padrao:

Uso	Variavel	Padrao	Observacao
Painel web/API HTTP	PORT	4141	Pode ser alterada no .env; em testes locais pode ser 3131.
Socket DA-APP/Leitor	HIOT_TCP_PORT	5555	Deve estar liberada no firewall entre leitor e servidor.

Regras de rede:

• O leitor FX precisa conseguir abrir conexao TCP ate IP_DO_SERVIDOR:HIOT_TCP_PORT.
• O operador precisa acessar o painel web em http://IP_DO_SERVIDOR:PORT.
• Em servidor Windows, liberar entrada no firewall para as portas PORT e HIOT_TCP_PORT.
• Se o servidor estiver em nuvem, liberar as portas tambem no security group/firewall da VPS.

Exemplo:

Servidor middleware: 192.168.0.50
Painel web: http://192.168.0.50:4141
Socket DA-APP: 192.168.0.50:5555

Depois que o DA-APP estiver instalado e iniciado no FX, o leitor deve aparecer automaticamente no menu lateral do painel.

3. Instalacao Windows via .exe

Use o instalador fornecido (MiddlewareRFID-Setup.exe). Ele instala o middleware como servico do Windows (H1TECHMiddlewareLITE, inicializacao automatica), pergunta as portas HTTP/TCP e a pasta de logs, grava o .env e ja inicia o servico ao final.

O passo a passo completo — pre-requisitos, firewall, caminhos de dados e logs, comandos do servico, atualizacao e desinstalacao — esta na pagina dedicada:

Instalacao e validacao (Windows / Docker)

Endereco padrao do painel:

http://localhost:4141

4. Configuracao via .env

No diretorio de instalacao existe um arquivo .env. Ele permite alterar portas e caminhos sem recompilar a aplicacao.

Exemplo:

PORT=4141
HIOT_TCP_PORT=5555
DB_PATH=middleware-rfid-bridge.db
H1TECH_DATA_DIR=C:\ProgramData\H1TECH-Middleware-LITE
LOG_DIR=C:\ProgramData\H1TECH-Middleware-LITE\logs
FRONTEND_DIST_PATH=frontend-dist

Campos principais:

Variavel	Funcao
PORT	Porta HTTP do painel e APIs do middleware.
HIOT_TCP_PORT	Porta TCP onde o DA-APP do leitor conecta.
H1TECH_DATA_DIR	Pasta base para dados persistentes.
DB_PATH	Caminho do SQLite. Pode ser relativo ao H1TECH_DATA_DIR.
LOG_DIR	Pasta onde os logs da aplicacao sao gravados.
FRONTEND_DIST_PATH	Pasta do frontend servido pelo backend.

A informacao detalhada sobre telas, modais e o fluxo do Painel Web (Adicionar leitor, simulador, cadastro de actions, cards de status e visualizacoes) foi movida para a pagina de fluxo web.

Consulte: Fluxo web (baseado no front)

12. Casos de uso comuns

Cancela ou catraca

Fluxo:

1. Sensor/GPI inicia leitura.
2. Middleware identifica veiculo e pessoas por prefixo EPC.
3. Action envia body para API de autorizacao.
4. Em sucesso, GPO abre cancela por tempo configurado.
5. Em erro, GPO de sinalizacao pode acionar luz ou buzzer.

Doca de recebimento

Fluxo:

1. Operador inicia leitura manual.
2. Leitor coleta tags por tempo definido.
3. Middleware envia lote em batch.
4. CSV local e gerado como contingencia.

Portal continuo

Fluxo:

1. Leitor fica em modo continuo.
2. Middleware acumula tags por intervalo de batch.
3. Lotes sao enviados periodicamente para API externa.

Homologacao sem hardware

Fluxo:

1. Criar leitor simulador.
2. Importar CSV de tags conhecidas.
3. Configurar modo de leitura.
4. Criar action e apontar para /simulador-apis.
5. Startar o leitor simulador e validar body recebido.

13. Checklist de validacao em campo

Antes de finalizar a implantacao, validar:

• Painel abre em http://IP_DO_SERVIDOR:PORT.
• Login funciona com usuario e senha padrao ou credenciais definidas.
• DA-APP conecta ao middleware pela porta HIOT_TCP_PORT.
• Leitor real aparece automaticamente no menu lateral.
• Status de antenas, GPI e GPO e exibido.
• Modo de leitura pode ser aplicado.
• Start/Stop manual funciona.
• Modo temporizado encerra sozinho.
• GPI inicia/encerra leitura conforme configuracao.
• Action recebe body no /simulador-apis.
• Endpoint real recebe o lote esperado.
• CSV e gerado quando habilitado.
• Leitor simulador consegue emitir tags de teste.

14. Observacoes operacionais

• O middleware salva configuracoes no SQLite local.
• Actions cadastradas podem ser reaproveitadas por varios leitores.
• Leitores simuladores sao persistidos e podem ser removidos pelo menu.
• Em producao, revise firewall, antivirus e permissoes de escrita no diretorio de dados.
• Para CSV local, prefira pasta fora de Program Files, como C:\ProgramData\H1TECH-Middleware-LITE\leituras.
• O login do painel e validado no frontend e as rotas /api/* nao exigem token: mantenha as portas 4141 e 5555 restritas a rede interna do cliente, nunca expostas na internet.