Manual SDK Facial

1. Introdução

O Leitor Facial Topdata é uma solução avançada de identificação utilizando inteligência artificial. Ele pode ser integrado a dispositivos como catracas, portas e cancelas, permitindo identificação rápida e segura.
Este manual destina-se a orientar desenvolvedores e integradores na utilização do SDK para a comunicação da sua aplicação com o leitor facial. Ele abrange desde a configuração inicial até comandos específicos.

2. Aplicação

O leitor facial pode ser utilizado como um coletor de marcações para registro de ponto, identificando o usuário e enviando o registro realizado para o software de tratamento de ponto. Além disso, também atua como controlador de acesso em aplicações como: academias, escolas, condomínios, clubes, empresas, hospitais, etc. Pode ser utilizando tanto em modo offline, com verificação dos usuários e das regras de acesso no próprio leitor, quanto em modo online, quando a identificação é enviada para que a aplicação defina se o acesso deve ser liberado ou bloqueado.

3. Controle de Acesso

O leitor facial oferece dois modos de operação principais quando está atuando como controle de acesso: offline e online .

Em ambos os casos, é necessário enviar o cadastro dos usuários para o leitor, para que o reconhecimento facial possa ser executado. No modo offline, o leitor utiliza esses dados localmente para validar o acesso. No modo online, o leitor identifica o usuário e envia as informações ao aplicativo, que decide se o acesso será liberado ou negado.

3.1 Modo Offline

Nesse modo, o leitor realiza o reconhecimento facial e decide se o acesso será liberado ou negado, com base nos cadastrados do próprio leitor. Após identificar o usuário, o dispositivo envia um evento sendlog ao aplicativo, informando o resultado da tentativa de acesso.

Fluxo de comunicação:

1. Ao identificar um usuário, libera ou nega o acesso localmente.
2. Envia evento sendlog ao aplicativo com detalhes da identificação e resultado do acesso.

No modo offline, é possível enviar tabelas de horários ao leitor para que ele valide o acesso com base em regras de tempo.

3.2 Modo Online

No modo online, quando um usuário é identificado, essa informação é enviada para a aplicação através de um evento sendlog. A aplicação valida os cadastros do usuário e as regras de negócio do seu sistema, e envia uma resposta para o leitor informando se o acesso deve ser liberado ou bloqueado.

Fluxo de comunicação:

1. Ao identificar um usuário, envia evento sendlog ao aplicativo.
2. O aplicativo processa as informações e responde com access:true ou access:false.

3.3 Configuração do Modo de Operação

A mudança entre os modos é realizada através do comando setdevinfo, especificando o valor do campo server_verify:

• 0: Modo Offline apenas
• 1: Modo Online apenas
• 2: Modo Automático (fallback entre online e offline)

4. Comunicação

O leitor utiliza o protocolo WebSocket , ideal para comunicação bidirecional em tempo real entre o leitor (cliente) e o aplicativo (servidor).

4.1 Estabelecimento da Conexão

1. Configure o IP do servidor no leitor.
2. O leitor tentará conectar ao servidor periodicamente
3. Quando o servidor WebSocket estiver ativo, aceita a conexão do leitor.
4. O leitor envia o comando reg para registro inicial.
5. Somente após a resposta do reg pelo servidor, a comunicação completa é iniciada.

Caso o leitor tenha eventos armazenados enquanto estava desconectado, eles são enviados imediatamente após a resposta do reg.

4.2 Envio de Evento Assíncrono (sendlog)

Quando um usuário é identificado, o leitor envia o evento sendlog ao aplicativo de forma assíncrona. Esse evento pode ser recebido mesmo enquanto o aplicativo está enviando outros comandos ao leitor.

É importante que o sistema trate corretamente a ordem e origem das mensagens recebidas, distinguindo entre comandos e eventos assíncronos.

4.3 Estrutura de Comunicação no Aplicativo

Método para Enviar Comandos

Os comandos são enviados via método de escrita no WebSocket. Cada mensagem deve conter o campo "cmd" indicando qual ação está sendo executada.

Exemplo:

{ 
  "cmd": "getuserinfo", 
  "enrollid": 12345, 
  "backupnum": 0 
}

Método para Receber Respostas

Para receber as respostas do leitor, o aplicativo deve possuir um listener ativo que processe todas as mensagens recebidas. As respostas contêm o campo "ret" associado ao comando enviado.

Exemplo:

{ 
  "ret": "getuserinfo", 
  "result": true, 
  "name": "João" 
}

Importante

• O envio e o recebimento de mensagens são processos independentes .
• O método de envio não retorna a resposta diretamente.
• A resposta ou evento é tratado quando chega no listener , devendo ser correlacionado com o comando original ou interpretado como evento assíncrono (sendlog).

5. Estrutura das Mensagens

Todas as mensagens trocadas entre o leitor e o aplicativo devem estar no formato JSON .

Campos Principais:

Campo	Descrição
cmd	Comando enviado pelo aplicativo
ret	Resposta retornada pelo leitor

Exemplos

Envio (comando):

{ 
  "cmd": "getuserinfo", 
  "enrollid": 12345 
}

Resposta:

{ 
  "ret": "getuserinfo", 
  "result": true, 
  "name": "João" 
}

6. Comandos do Leitor

Os comandos do leitor facial são divididos em categorias, cada um com descrição, formato de requisição e resposta, campos obrigatórios e observações.

6.1 Eventos do Leitor

• reg: Registro inicial do leitor
• sendlog: Evento assíncrono de identificação de usuário

6.2 Comandos Gerais

• enabledevice / disabledevice: Habilitar / Desabilitar Comunicação
• getuserlist: Obter a Lista de Usuários
• getuserinfo: Obter Informações de Usuário
• setuserinfo: Enviar Dados de Usuário
• setuserlock: Configurar Bloqueios de Acesso Por Usuário
• deleteuser: Remover Usuário
• setdevinfo: Configurar Parâmetros
• setdevlock: Configurar Bloqueios e Horários
• cleanuser: Apagar Todos Usuários
• getalllog: Obter Todos os Logs
• cleanlog: Limpar Todos os Logs

7. Coletor de marcações para Ponto

Uma das formas de utilizar o leitor facial é como coletor de marcações para registro de ponto. Quando um usuário é identificado, o leitor faz o registro na sua memória e envia o registro para o software de tratamento do ponto.

Para a aplicação de registro de ponto é recomendável realizar uma configuração no leitor facial para evitar que a marcação seja feita de forma involuntária.

• definir o método de ativação da tela como “Touch” (Sistema → Ativar tela → Touch).
• configurar o equipamento com um tempo reduzido de ativação da tela, em torno de 3 segundos (Sistema → Tela de repouso)

O tempo reduzido de ativação da tela fará com que o leitor entre rapidamente no modo de repouso. Com a configuração “Touch” será necessário que o usuário toque a tela para que o leitor saia do modo de repouso e fique disponível para identificação facial. Isso evitará que um usuário que passe pela frente do leitor e execute um registro de ponto involuntário apenas por olhar para a tela.

8. Downloads

Utilize o link abaixo para fazer o download do SDK Facial.

Download do SDK Facial.

9. FAQ – Dúvidas Frequentes

• Como mudar do modo offline para online?
  Use o comando setdevinfo com server_verify = 1.
• Qual o tamanho ideal da foto para cadastro facial?
  O tamanho ideal para foto é 480×640 pixel.
• É possível usar o leitor sem servidor?
  Sim, é possível, através do modo offline. A identificação do usuário será feita localmente pelo leitor, com base nas regras de acesso e horário.