Documentação Técnica

Eduardo Martini

Visão geral

Esta solução de leitura de cartão Hikvision é composta por dois artefatos:

Frontend: aplicação visual usada para configurar o leitor, acompanhar status, visualizar logs e iniciar ou parar a leitura.
Backend: serviço em C# responsável pela comunicação com o leitor, validação operacional da leitura e envio do código lido para o buffer do teclado.

Estrutura da aplicação

Os dois componentes fazem parte da mesma solução operacional:

O frontend roda como aplicação com interface e pode permanecer minimizado no tray.
O backend roda em segundo plano e é o componente que efetivamente mantém a leitura funcionando.

Importante:

Depois que o leitor estiver configurado e a leitura for iniciada com sucesso, a operação normal do leitor pode continuar somente com o backend em execução.
Em outras palavras, o frontend é usado principalmente para configuração, monitoramento e suporte.
O backend é o componente essencial para a leitura contínua no ambiente do cliente.

Local obrigatório do serviço

A pasta do serviço deve estar sempre presente no caminho:

C:\Insoft4\insoft-reader-card-hikvision

Esse diretório é obrigatório para a operação correta da solução. Arquivos, configurações, logs, licença e executáveis esperados pelo sistema devem permanecer nesse local.

O que é o serviço C#

O serviço C# é o processo de retaguarda da solução. Ele é responsável por:

Comunicar com o equipamento leitor Hikvision.
Aplicar as configurações operacionais do leitor.
Manter a leitura ativa em segundo plano.
Registrar logs para diagnóstico e suporte.
Validar a licença necessária para permitir a conexão do equipamento com o serviço.
Receber o cartão lido e enviar o código para o buffer do teclado.

Sem o backend em execução, o leitor não consegue manter a leitura operacional.

Licença obrigatória

Para que o serviço aceite a conexão com o equipamento, é necessário adicionar uma licença válida.

Essa licença:

É gerada por outro serviço da empresa.
É usada para validar se o equipamento está autorizado a se conectar com o serviço.
Deve estar presente no ambiente antes da operação normal do leitor.

Se a licença estiver ausente, inválida ou não reconhecida:

O equipamento pode não conectar corretamente.
A leitura pode não iniciar.
O suporte deve verificar a presença e a validade do arquivo licenciador.

Como funciona a digitação do cartão

Quando um cartão é lido com sucesso, o código retornado é enviado para um campo fixo da aplicação e também para o cursor do teclado.

O comportamento correto é:

O código do cartão é digitado no buffer do teclado.
Isso significa que o valor será escrito exatamente no local em que o cursor estiver posicionado no momento da leitura.
Se o cursor estiver em um campo de texto, sistema, navegador ou outro aplicativo, o número do cartão será digitado nesse ponto.

Orientação de uso:

Antes de aproximar o cartão, posicione o cursor no campo em que o código deve ser recebido.
Evite deixar o foco em campos indevidos para não digitar o código em local incorreto.

Como iniciar o tray e o serviço

Passo 1. Validar a estrutura da pasta

Confirme que a pasta abaixo existe:

C:\Insoft4\insoft-reader-card-hikvision

Se essa pasta não existir, a solução não deve ser considerada pronta para uso.

Você irá encontrar essa pasta no tópico "Versões" deste serviço.

Passo 2. Validar a licença

Antes de iniciar a operação:

Confirme que a licença gerada pelo serviço externo foi adicionada no local esperado.
Confirme que o ambiente reconhece a licença como válida.

Sem isso, a conexão com o leitor pode falhar.

Licença gerada por app externo, evitando uso da aplicação com outros equipamentos, não sendo vendidos por nós.

Passo 3. Iniciar o frontend

Abra a aplicação frontend.

O frontend será usado para:

Verificar status do tray.
Configurar o leitor.
Selecionar tecnologia do cartão.
Ajustar intervalo entre leituras.
Iniciar a leitura.
Consultar logs e status para suporte.

Passo 4. Iniciar o backend

Inicie o processo de backend através da aba "Gerenciamento do Tray" -> "Iniciar Tray".

Objetivo desta etapa:

Garantir que o serviço em C# esteja ativo.
Garantir que o processo esteja disponível em segundo plano.
Garantir que a leitura possa ser mantida mesmo sem o frontend aberto depois da configuração.

Passo a passo para iniciar a leitura

Verifique o status do tray

Na tela de gerenciamento:

Confirme que o tray está em execução.
Se necessário, use a opção de iniciar tray.

Verifique a licença

Antes de continuar:

Confirme que não há alerta de licença ausente ou inválida.
Se houver erro de licença, corrija antes de tentar iniciar a leitura.
Adicione a licença na pasta "license".

5. Configure usuário e senha

Na tela de conexão:

Preencha o usuário.
Preencha a senha.

Essas credenciais são usadas para a comunicação com o dispositivo.

6. Escolha o dispositivo

Clique em iniciar leitura para carregar os dispositivos disponíveis.

Depois:

Selecione o leitor desejado.
Confirme o dispositivo correto antes de conectar.

7. Ajuste as configurações do leitor

Antes ou depois da conexão, conforme o fluxo operacional:

Defina o tipo de cartão.
Defina o intervalo entre leituras.
Salve as configurações.

Observação:

Após salvar as configurações, reinicie o serviço quando a aplicação orientar isso.

8. Inicie a leitura

Com o dispositivo selecionado:

Clique para iniciar a leitura.
Aguarde a confirmação de que o leitor entrou em modo de leitura.

9. Posicione o cursor no campo correto

Antes de aproximar o cartão:

Clique no campo em que o código deve ser digitado.

10. Aproxime o cartão

Quando a leitura ocorrer:

O código será digitado automaticamente no local em que o cursor estiver ativo.

Configurações do leitor

Tipo de cartão

O sistema permite configurar a tecnologia do cartão.

Opções:

Mifare: mantém a leitura no formato esperado para operação Mifare.
Wiegand: usa a leitura com tratamento de backend para conversão automática do cartão retornado.

Finalidade:

Essa configuração define como o backend interpreta e processa o cartão lido.
Deve ser ajustada conforme a tecnologia usada no ambiente do cliente.

Intervalo entre leituras

Essa configuração define o tempo entre uma leitura e outra.

Finalidade:

Evitar leituras repetidas em sequência imediata.
Controlar o tempo mínimo para nova captura do mesmo cartão ou de outro cartão.
Reduzir duplicidade de digitação em cenários de aproximação contínua.

Exemplo prático:

Se o intervalo estiver configurado em 5 segundos, o sistema aguardará esse período antes de aceitar uma nova leitura conforme a regra aplicada no backend.

Operação sem frontend

Depois que:

o backend estiver em execução,
a licença estiver válida,
o leitor estiver configurado,
e a leitura tiver sido iniciada com sucesso,

o funcionamento normal pode continuar apenas com o backend rodando.

Isso significa:

O frontend não precisa permanecer aberto para a leitura continuar em operação normal, desde que o backend continue ativo e configurado corretamente.

Quando usar o frontend novamente

O frontend deve ser aberto novamente quando for necessário:

Alterar usuário e senha.
Selecionar outro dispositivo.
Mudar tipo de cartão.
Alterar intervalo entre leituras.
Reiniciar ou parar a leitura.
Consultar status do tray.
Verificar mensagens e logs.
Apoiar diagnóstico de suporte.

Checklist rápido de suporte

Em caso de falha, validar nesta ordem:

A pasta C:\Insoft4\insoft-reader-card-hikvision existe.
O backend em C# está em execução.
A licença foi adicionada e está válida.
O tray está ativo.
O leitor correto foi selecionado.
Usuário e senha do equipamento estão corretos.
O tipo de cartão está configurado corretamente.
O intervalo entre leituras está adequado para o ambiente.
O cursor está posicionado no campo correto para receber o código.
Os logs não apresentam erro de conexão, licença ou leitura.

Resumo operacional

O frontend serve para configurar, iniciar, monitorar e dar suporte.
O backend em C# é quem mantém a leitura funcionando.
A pasta C:\Insoft4\insoft-reader-card-hikvision deve existir sempre.
A licença é obrigatória para validar a conexão do equipamento com o serviço.
O código do cartão é digitado no buffer do teclado, no campo em que o cursor estiver posicionado.