Instalação e validação — H1TECH Middleware LITE

Guia operacional para instalar o middleware em um cliente e validar tudo antes de o hardware chegar. Ao final, o servidor fica pronto para que os leitores Zebra FX sejam apenas apontados para ele.

Versão de referência deste guia: branch refactor-arq2-eventos (padrão dos dois repositórios), back 0fc4fca + front bef8e66, ambos de 22/07/2026.

Use a build 1.0.1 ou mais nova

A build 1.0.0 do MiddlewareRFID-Setup.exe falha ao registrar o serviço do Windows, terminando com erro -1 — e ainda assim exibe "instalação concluída com sucesso". Corrigido na 1.0.1; detalhes e contorno na seção 12.

---

1. O que é instalado

Um único processo Node empacotado (middleware-api.exe) que sobe duas portas:

Porta	Variável	Padrão	Para que serve
HTTP	PORT	4141	Painel web + API REST + Socket.IO + simulador de APIs
TCP	HIOT_TCP_PORT	5555	Onde o DA-APP embarcado no leitor Zebra FX conecta de volta

O frontend é servido pelo próprio backend na porta HTTP (mesma origem) — não existe servidor web separado. O banco é SQLite local, sem dependência de Postgres, Redis ou serviço externo.

Componentes entregues pelo instalador:

• middleware-api.exe e node_sqlite3.node — backend;
• frontend-dist\ — painel web estático;
• .env — configuração de portas e caminhos;
• H1TECH-Middleware-LITE-Service.exe (WinSW) — wrapper que registra o middleware como serviço do Windows;
• Start-MiddlewareRFID.cmd + atalhos — sobem o serviço, se parado, e abrem o painel no navegador.

---

2. Pré-requisitos no servidor do cliente

• Windows x64 (Server ou Desktop), com permissão de administrador para instalar.
• Portas 4141 e 5555 livres e liberadas no firewall.
• Espaço em disco: ~120 MB de instalação + crescimento do SQLite/CSV em C:\ProgramData.
• Não é necessário instalar Node.js, banco de dados ou IIS.
• Rede: o servidor precisa ser alcançável pelos leitores (TCP 5555) e pelos operadores (HTTP 4141).

Reserve com a equipe de infra do cliente:

• IP fixo ou DNS interno do servidor;
• exceções de firewall/antivírus para o executável e as duas portas;
• se for VM em nuvem, liberação também no security group.

---

3. Instalação no Windows (caminho recomendado)

Artefato: Middleware-RFID-Back/installer/dist-installer/MiddlewareRFID-Setup.exe (versionado no repositório, já contém back + front buildados).

1. Copie o .exe para o servidor e execute como administrador.
2. Confirme a pasta de instalação (padrão C:\Program Files\H1TECH-Middleware-LITE).
3. Na tela "Configuração do Middleware", informe:
   • Porta HTTP do backend/painel — padrão 4141;
   • Porta HIOT TCP do DA APP — padrão 5555;
   • Pasta de logs — padrão C:\ProgramData\H1TECH-Middleware-LITE\logs.
4. Conclua. O instalador, ao final, grava o .env, registra e inicia o serviço automaticamente.

O que o instalador cria:

Caminho	Conteúdo
C:\Program Files\H1TECH-Middleware-LITE	binários, frontend-dist\, .env, wrapper do serviço
C:\ProgramData\H1TECH-Middleware-LITE	banco SQLite middleware-rfid-bridge.db
C:\ProgramData\H1TECH-Middleware-LITE\leituras	CSVs de leitura (quando habilitado)
C:\ProgramData\H1TECH-Middleware-LITE\logs	log operacional da aplicação (JSONL)
C:\ProgramData\H1TECH-Middleware-LITE\service-logs	stdout/stderr do serviço, com rotação

Serviço do Windows

Item	Valor
ID do serviço	H1TECHMiddlewareLITE
Nome exibido	H1TECH - Middleware LITE
Inicialização	Automática (sobe junto com o Windows)
Falha	Reinício automático em 10s e 30s; contador zera após 1h
Logs	rotação diária/10 MB, zip após 7 dias, retenção de 14 arquivos

Comandos úteis (prompt como administrador):

sc query H1TECHMiddlewareLITE
net stop H1TECHMiddlewareLITE
net start H1TECHMiddlewareLITE

Liberação de firewall

netsh advfirewall firewall add rule name="H1TECH Middleware LITE - Painel 4141" dir=in action=allow protocol=TCP localport=4141
netsh advfirewall firewall add rule name="H1TECH Middleware LITE - DA-APP 5555" dir=in action=allow protocol=TCP localport=5555

Ajuste as portas se você as alterou na instalação.

---

4. Configuração (.env)

Fica na pasta de instalação. Alterar exige reiniciar o serviço.

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

Variável	Função
PORT	Porta HTTP do painel e da API.
HIOT_TCP_PORT	Porta TCP onde o DA-APP do leitor conecta.
DB_PATH	Arquivo SQLite. Caminho relativo é resolvido dentro de H1TECH_DATA_DIR.
H1TECH_DATA_DIR	Pasta base de dados persistentes (banco, CSVs).
LOG_DIR	Pasta dos logs da aplicação.
FRONTEND_DIST_PATH	Pasta do painel estático servido pelo backend.
HIOT_COMMAND_TIMEOUT_MS	Opcional. Timeout de comando ao leitor; padrão 15000.

Reinstalação sobrescreve o .env

O instalador reescreve o .env inteiro com os valores das três perguntas do assistente. Chaves adicionadas manualmente (por exemplo HIOT_COMMAND_TIMEOUT_MS) precisam ser recolocadas depois de cada atualização. Guarde uma cópia do arquivo antes de reinstalar.

---

5. Acesso ao painel

http://localhost:4141          (no próprio servidor)
http://IP_DO_SERVIDOR:4141     (na rede do cliente)

Credenciais padrão:

Usuário: admin
Senha:   h1techspencer

O painel não tem autenticação real

A tela de login é validada no navegador, com usuário e senha fixos no código do frontend. As rotas /api/* respondem sem token. Portanto:

• nunca exponha as portas 4141/5555 diretamente na internet;
• restrinja o acesso por firewall/VLAN à rede interna do cliente;
• se o cliente exigir exposição externa, coloque um proxy reverso com autenticação na frente.

---

6. Validação sem hardware

Esta é a sequência para homologar a instalação antes de os leitores chegarem. Ela usa o leitor simulador (leitor virtual, com tags fictícias) e o simulador de APIs embutido, exercitando exatamente o mesmo caminho de código do leitor real: leitura → agregação → POST → resposta.

Fluxo validado nesta versão:

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

6.1 Serviço no ar

curl -s -o nul -w "%{http_code}" http://localhost:4141/
curl -s http://localhost:4141/api/readers
curl -s http://localhost:4141/simulador-apis/health

Esperado: 200, uma lista JSON ([] numa instalação nova) e {"ok":true,...}.

6.2 Criar um leitor simulador

Pelo painel: Adicionar leitor simulador → defina nome, nº de antenas e cole o CSV de tags (antena,epc por linha). Ou via API:

curl -X POST http://localhost:4141/api/virtual-readers ^
  -H "Content-Type: application/json" ^
  -d "{\"hostName\":\"FX Teste\",\"antennaCount\":2,\"tagsCsv\":\"antena,epc\n1,E2000017221101441890B1C2\n1,E2000017221101441890B1C3\n2,E2000017221101441890B1C4\"}"

A resposta traz o macAddress gerado (VIRTUAL-FX-XXXXXX). O leitor aparece no menu lateral marcado como simulador.

6.3 Apontar a entrega para o simulador de APIs

No painel, na configuração do leitor, aponte a URL de destino para o simulador embutido; ou via API:

curl -X PUT http://localhost:4141/api/readers/<MAC>/endpoint ^
  -H "Content-Type: application/json" ^
  -d "{\"deliveryMode\":\"simple\",\"url\":\"http://localhost:4141/simulador-apis/api/entrada\",\"headers\":\"{}\"}"

6.4 Escolher o modo de leitura

Modos aceitos em Configuração de leitura → Modo:

Valor	Comportamento
manual	Start e stop manuais
timed	Start manual, stop automático após durationSeconds
gpi-timed	Start por GPI, stop por tempo
gpi-window	Start e stop por GPI
continuous	Contínuo, com envio em lotes por intervalo

Para o teste, timed com 5 segundos é o mais rápido de conferir:

curl -X PUT http://localhost:4141/api/readers/<MAC>/mode ^
  -H "Content-Type: application/json" ^
  -d "{\"mode\":\"timed\",\"durationSeconds\":5,\"antennas\":[{\"port\":1,\"enabled\":true,\"power\":27,\"session\":\"S1\"},{\"port\":2,\"enabled\":true,\"power\":27,\"session\":\"S1\"}]}"

6.5 Disparar e conferir a entrega

curl -X PUT http://localhost:4141/api/readers/<MAC>/start -H "Content-Type: application/json" -d "{}"

Após a duração configurada, confira:

curl -s http://localhost:4141/api/readers/<MAC>/reads
curl -s http://localhost:4141/api/readers/<MAC>/delivery-diagnostics
curl -s http://localhost:4141/simulador-apis/requests

Resultado esperado:

• /reads lista os EPCs do CSV, com antena, seenCount e timestamps;
• delivery-diagnostics mostra read-queued → simple-request → simple-response com status: 200;
• /simulador-apis/requests mostra o POST recebido, com reason: "timed-duration-elapsed" (ou "stop-command", se você parou manualmente) e o array reads agregado.

O dashboard visual do simulador fica em http://localhost:4141/simulador-apis — use-o para mostrar o corpo da requisição ao cliente. Ele também simula cenários de erro da API real:

Recurso	Como usar
Forçar status HTTP	?status=500
Atraso na resposta	?delay=3000
Forçar falha	?fail=true
Exigir autenticação	?requireAuth=bearer / basic / apikey
Limpar histórico	DELETE /simulador-apis/requests

6.6 Validar a porta do DA-APP

Mesmo sem leitor, confirme que a porta TCP está escutando e acessível:

netstat -ano | findstr :5555

De outra máquina na rede do cliente:

Test-NetConnection -ComputerName IP_DO_SERVIDOR -Port 5555
Test-NetConnection -ComputerName IP_DO_SERVIDOR -Port 4141

6.7 Validar persistência e reinício

1. Pare e inicie o serviço (net stop / net start).
2. Reabra o painel: o leitor simulador, as actions e a configuração devem continuar lá (ficam no SQLite em C:\ProgramData).
3. Reinicie o servidor e confirme que o serviço sobe sozinho (inicialização automática).

Checklist de aceite (sem hardware)

• Serviço H1TECHMiddlewareLITE em execução e com inicialização automática
• Painel abre em http://IP_DO_SERVIDOR:PORT a partir de outra máquina
• Login com as credenciais padrão
• GET /api/readers responde
• Leitor simulador criado e visível no menu
• Modo de leitura salvo e aplicado
• Start/Stop manual funciona
• Modo timed encerra sozinho e envia o lote
• Simulador de APIs recebe o body esperado, com status 200
• delivery-diagnostics sem estágios de erro
• CSV gerado em ...\leituras, se habilitado
• Portas 4141 e 5555 alcançáveis da rede do cliente
• Configuração sobrevive a reinício do serviço e do servidor
• Regras de firewall documentadas com a equipe do cliente

---

7. Quando o hardware chegar

1. Gerar o DA-APP para o leitor Zebra FX apontando para o servidor instalado. O pacote .deb (hiot-bridge-agent) é gerado pelo DA APP Builder Service (installer/da-app-builder-service), que roda em Linux e recebe:
   • middlewareHost — IP/DNS do servidor do middleware;
   • backendHttpPort — porta HTTP (4141);
   • backendTcpPort — porta TCP (5555);
   • usuário e senha do leitor, usados pelo agente nas APIs locais do FX.
2. Embarcar o .deb no leitor e iniciá-lo.
3. O leitor conecta sozinho na porta TCP e aparece no menu lateral do painel, com IP, status das antenas, GPI e GPO.
4. Repetir os testes da seção 6 apontando para o leitor real, e só então trocar a URL de destino do simulador para a API definitiva do cliente.

---

8. Alternativa: Docker (Linux/VPS)

Mesma aplicação, imagem única publicada no GHCR (ghcr.io/hasarbrasildesenvolvimento/middleware-rfid). O docker-compose.yml do repositório do backend já traz portas e volume:

TAG=v1.0.0 docker compose up -d

• 4141 HTTP e 5555 TCP publicados;
• volume middleware-data montado em /data (SQLite + CSVs);
• healthcheck nativo, sem curl/wget;
• restart: unless-stopped.

Requer login no GHCR se o pacote for privado. Detalhes de build e publicação em DOCKER.md, no repositório do backend.

---

9. Atualização e desinstalação

Atualizar: execute a versão nova do MiddlewareRFID-Setup.exe. Ele para e desregistra o serviço antigo, substitui os binários e registra/inicia o serviço de novo. Os dados em C:\ProgramData\H1TECH-Middleware-LITE são preservados; o .env é reescrito (ver seção 4).

Desinstalar: Configurações → Aplicativos → H1TECH - Middleware LITE → Desinstalar; ou rode unins000.exe na pasta de instalação (/VERYSILENT para desassistido). O desinstalador para e remove o serviço, apaga binários, frontend-dist, atalhos e o XML do serviço.

O que permanece de propósito:

• C:\ProgramData\H1TECH-Middleware-LITE inteiro — banco SQLite, CSVs, logs e service-logs. Apague à mão para uma limpeza completa (ou entre testes de instalação, para começar do zero).
• o .env, se já existia antes da instalação.

Conferir depois:

sc query H1TECHMiddlewareLITE

O esperado é o erro 1060 (serviço não existe). Se o serviço ficar órfão — por exemplo se a pasta de instalação foi apagada na mão antes de desinstalar — force a remoção:

sc stop H1TECHMiddlewareLITE
sc delete H1TECHMiddlewareLITE

---

10. Troubleshooting

Sintoma	O que verificar
Serviço não inicia	C:\ProgramData\H1TECH-Middleware-LITE\service-logs — quase sempre porta ocupada ou permissão de escrita
"Porta em uso"	netstat -ano | findstr :4141 e mate/realoque o processo, ou mude PORT no .env
Painel abre em branco	Confirme que a pasta frontend-dist\ existe na instalação e que FRONTEND_DIST_PATH aponta para ela
Painel só abre localmente	Regra de firewall inbound ausente para a porta HTTP
Leitor não aparece	O DA-APP precisa alcançar IP:5555; teste com Test-NetConnection a partir da rede do leitor
Lote não chega na API	delivery-diagnostics mostra o estágio que falhou; teste a URL de destino pelo simulador antes
Erro de escrita no banco	Antivírus ou permissão em C:\ProgramData\H1TECH-Middleware-LITE
Nada nos logs	LOG_DIR foi apontado para uma pasta sem permissão; corrija no .env e reinicie o serviço

Logs para coletar em um chamado:

• C:\ProgramData\H1TECH-Middleware-LITE\logs\*.log (JSONL da aplicação);
• C:\ProgramData\H1TECH-Middleware-LITE\service-logs\* (saída do serviço);
• resposta de GET /api/readers/<MAC>/delivery-diagnostics.

---

11. Gerar o instalador do zero (equipe H1)

Só é necessário quando houver mudança de código depois da última build versionada.

Requisitos: Node.js 18 (o sqlite3 não compila com Node 22 sem build tools) e Inno Setup 6.

cd Middleware-RFID-Front
npm ci
npm run build

cd ..\Middleware-RFID-Back
Copy-Item ..\Middleware-RFID-Front\dist frontend-dist -Recurse -Force
npm ci
npm run build:win     # gera dist\middleware-api.exe + node_sqlite3.node

Depois compile installer\MiddlewareRFID.iss no Inno Setup. A saída vai para installer\dist-installer\MiddlewareRFID-Setup.exe.

Lembre-se de atualizar MyAppVersion no .iss quando a versão do produto mudar.

Artefatos antigos na mesma pasta

installer\dist-installer\ também contém MiddlewareRFID-Setup-v2.exe e -v3.exe. Apesar do nome, os dois são mais antigos que o MiddlewareRFID-Setup.exe e não instalam o serviço do Windows. Não distribua esses arquivos.

---

12. Problema conhecido na build 1.0.0

Sintoma: ao final da instalação aparece "Nao foi possivel instalar o servico do H1TECH Middleware LITE. Codigo: -1" e, logo depois, a tela de conclusão normal do assistente. O serviço H1TECHMiddlewareLITE não existe em services.msc e o painel não sobe sozinho.

Causa: o instalador grava o arquivo de configuração do WinSW como H1TECH-Middleware-LITE-Service.exe.xml, mas o WinSW 2.12 procura H1TECH-Middleware-LITE-Service.xml — o nome do executável sem a extensão. Sem encontrar o config, ele aborta antes de registrar o serviço:

FATAL - Unhandled exception
System.IO.FileNotFoundException: Unable to locate H1TECH-Middleware-LITE-Service.[xml|yml] file
within executable directory

O código -1 é o próprio exit code do WinSW nessa falha.

Agravante: o instalador não interrompia o fluxo. Exibia o erro e seguia para a tela de sucesso, com a saída do WinSW descartada (executado oculto, sem log) — por isso a causa não aparecia em lugar nenhum.

Correção: aplicada em installer/MiddlewareRFID.iss e publicada na build 1.0.1:

• o config passa a ser gravado como <nome-base>.xml, e o .exe.xml de instalações anteriores é removido;
• as chamadas do WinSW rodam via cmd com redirecionamento, gerando ...\service-logs\install-service.log;
• o retorno do Exec passa a ser verificado, e não só o exit code;
• em caso de falha, a tela final avisa ("Instalacao concluida com pendencias") e aponta o log, em vez de declarar sucesso;
• a opção de abrir o painel ao final só aparece se o serviço realmente subiu.

Contorno na build 1.0.0, num prompt como administrador:

cd "C:\Program Files\H1TECH-Middleware-LITE"
ren "H1TECH-Middleware-LITE-Service.exe.xml" "H1TECH-Middleware-LITE-Service.xml"
"H1TECH-Middleware-LITE-Service.exe" install
"H1TECH-Middleware-LITE-Service.exe" start
sc query H1TECHMiddlewareLITE

São os mesmos comandos que o instalador tenta executar. Depois disso, siga a validação da seção 6 normalmente.