Integracao IoT OKAI

O Levy Fleets fornece suporte abrangente para dispositivos IoT OKAI Serie ZK, implementando 100% do Protocolo @Track Air Interface v80.56. Este guia cobre a integracao completa, incluindo comandos suportados, processamento de telemetria e solucao de problemas.

Visao Geral

Dispositivos IoT OKAI se comunicam com o Levy Fleets atraves de um endpoint de API seguro que processa dados de telemetria, relatorios de localizacao e comandos de controle de veiculos. A integracao suporta:

• Rastreamento GPS em tempo real com historico de localizacao
• Monitoramento de bateria incluindo status de carregamento
• Controle de bloqueio/desbloqueio com confirmacao de status
• Limitacao de velocidade para aplicacao de zonas
• Tratamento de alarmes e alertas para eventos de seguranca
• Dados de diagnostico para manutencao e solucao de problemas

Configuracao do Dispositivo

Configuracoes do Servidor

Configure seu dispositivo OKAI para se comunicar com o Levy Fleets usando estas configuracoes:

Autenticacao

Dispositivos OKAI autenticam via chave de API. Certifique-se de que seus dispositivos IoT estejam configurados com a chave de API correta no cabecalho x-api-key.

Identificacao do Dispositivo

Os dispositivos sao identificados pelo numero IMEI. Quando um dispositivo conecta:

1. O IMEI e extraido da mensagem
2. O sistema procura o veiculo vinculado a esse IMEI
3. A telemetria e associada ao veiculo correto
4. Se nenhum veiculo for encontrado, a mensagem e registrada como "nao correspondida"

Comandos Suportados

O Levy Fleets implementa cobertura completa do protocolo OKAI. Os comandos sao organizados em categorias funcionais:

Localizacao e Telemetria

Status e Informacoes

Gerenciamento de Bateria

ECU (Unidade de Controle Eletronico)

Operacoes de Bloqueio

Movimento e Alarmes

Velocidade e Geofencing

Sistema e Rede

Eventos de Energia

Configuracao

NFC e Servico

Vinculacao e Bluetooth

Coleta de Dados

Processamento de Telemetria

Relatorios de Localizacao

Quando o dispositivo envia um relatorio de localizacao (GTFRI, GTERI ou GTRTO), o Levy Fleets:

1. Analisa coordenadas GPS (latitude, longitude)
2. Extrai velocidade, direcao e altitude
3. Atualiza a posicao atual do veiculo
4. Se existir uma viagem ativa, armazena a localizacao no historico da viagem
5. Aciona a aplicacao de zonas se as coordenadas mudaram

Atualizacoes de Bateria

Mensagens de status de bateria incluem:

• Nivel de Bateria - Porcentagem (0-100%)
• Voltagem da Bateria - Leitura de voltagem real
• Status de Carregamento - Se o veiculo esta carregando
• Bateria IoT - Bateria de backup/modulo IoT (se separada)

O sistema usa o nivel de bateria para:

• Atualizar a disponibilidade do veiculo (bateria baixa = indisponivel)
• Filtrar veiculos no painel por status de bateria
• Acionar alertas de bateria baixa

Status de Bloqueio

Mudancas de estado de bloqueio atualizam o registro do veiculo:

Aplicacao de Zonas

Apos processar atualizacoes de localizacao durante uma viagem ativa:

1. As coordenadas do veiculo sao verificadas contra todas as zonas
2. Se o veiculo entrar em uma zona de limite de velocidade, um comando de acelerador e enviado
3. Se o veiculo entrar em uma zona proibida, o acelerador e desabilitado
4. Se o veiculo sair da area de servico, um alerta e acionado
5. As estatisticas da viagem sao recalculadas

Resolucao de Identidade do Veiculo

A integracao OKAI usa cache inteligente para buscas de veiculos:

Processo de Busca

1. Verificar cache - Primeiro, procurar IMEI no cache de identidade de veiculos
2. Cache encontrado - Retornar UUID e numero do veiculo em cache
3. Cache nao encontrado - Consultar banco de dados para veiculo com iot_imei correspondente
4. Armazenar em cache - Armazenar o resultado por 1 hora
5. Retornar identidade - Fornecer UUID do veiculo para associacao de telemetria

Dispositivos Nao Correspondidos

Se nenhum veiculo for encontrado para um IMEI:

1. A mensagem ainda e processada para registro
2. O dispositivo e registrado na tabela "dispositivos nao correspondidos"
3. Operadores podem visualizar dispositivos nao correspondidos no painel
4. Uma vez que o dispositivo e registrado, mensagens futuras sao devidamente associadas

Deteccao de Viagem Ativa

Para cada mensagem recebida, o sistema verifica viagens ativas:

1. Consultar viagens com status active ou paused
2. Filtrar por vehicle_uuid correspondente ao veiculo identificado
3. Se encontrada, associar telemetria a viagem
4. Dados de localizacao sao adicionados ao historico da viagem
5. Estatisticas da viagem (distancia, duracao) sao atualizadas

Suporte a Viagens Legadas

Para compatibilidade retroativa com registros de viagens antigos:

1. Se nenhuma viagem for encontrada por UUID, pesquisar por vehicle_number
2. Se uma viagem legada for encontrada, normalizar os identificadores
3. Preencher o campo vehicle_uuid para consultas futuras

Enviando Comandos para Dispositivos

Senha IoT

Comandos para dispositivos OKAI requerem a senha correta. Configure isso em:

Configuracoes > Veiculos > Senhas IoT > Okai

Senha padrao: zk200

Comandos Disponiveis

Na pagina de detalhes do veiculo, voce pode enviar:

Fluxo de Comandos

1. Operador clica no botao de comando no painel
2. Comando e enfileirado para o dispositivo
3. Dispositivo recebe comando no proximo heartbeat (ou imediatamente se online)
4. Dispositivo executa comando e envia confirmacao
5. Painel atualiza com novo status

Solucao de Problemas

Dispositivo Nao Reportando Localizacao

Sintomas: Veiculo nao mostra localizacao ou dados de localizacao desatualizados

Solucoes:

1. Verificar energia do dispositivo - garantir que a bateria esta carregada
2. Verificar antena GPS - deve ter visao clara do ceu
3. Verificar conectividade celular - dispositivo precisa de acesso a rede
4. Revisar configuracao do dispositivo - verificar configuracoes do servidor
5. Verificar fixacao GPS - novas instalacoes podem precisar de 5-10 minutos

Comandos de Bloqueio/Desbloqueio Nao Funcionando

Sintomas: Comandos enviados mas veiculo nao responde

Solucoes:

1. Verificar se a senha IoT esta correta em Configuracoes
2. Confirmar que o dispositivo esta online (verificar carimbo de ultima visualizacao)
3. Verificar erros da ECU na telemetria
4. Verificar se o veiculo tem bateria suficiente
5. Tentar reiniciar o veiculo

Bateria Nao Atualizando

Sintomas: Nivel de bateria permanece no mesmo valor

Solucoes:

1. Verificar configuracao de intervalo de relatorio
2. Verificar se o dispositivo esta realmente reportando (verificar ultima visualizacao)
3. Alguns dispositivos so reportam bateria em eventos especificos
4. Revisar logs de telemetria para mensagens GTBAT

Geofence Nao Acionando

Sintomas: Veiculo entra na zona mas nenhuma aplicacao acontece

Solucoes:

1. Verificar se a zona esta devidamente configurada e ativa
2. Verificar se o tipo de zona suporta aplicacao
3. Confirmar que a viagem esta ativa (aplicacao de zona so se aplica durante viagens)
4. Revisar precisao da localizacao - GPS pode ser impreciso
5. Verificar limites da zona para lacunas

Dispositivo Aparece como Nao Correspondido

Sintomas: Dispositivo reportando mas aparece na lista de nao correspondidos

Solucoes:

1. Registrar o dispositivo na secao Dispositivos IoT
2. Verificar se o IMEI corresponde exatamente (sem espacos/tracos)
3. Vincular dispositivo a um veiculo
4. Limpar cache se adicionado recentemente (cache atualiza de hora em hora)

Armazenamento de Dados

Tabela de Telemetria

Todas as mensagens OKAI sao armazenadas na tabela vehicle_telemetry com:

• vehicle_uuid - Veiculo associado
• imei - Identificador do dispositivo
• raw_payload - Dados completos da mensagem como JSON
• message_type - Tipo de comando (ex.: "GTFRI")
• timestamp - Carimbo de data/hora da mensagem
• battery_level, speed, latitude, longitude - Valores extraidos

Retencao

Dados de telemetria sao retidos de acordo com a politica de retencao de dados do seu plano. Entre em contato com o suporte para informacoes sobre opcoes de retencao estendida.

Referencia da API

Endpoint

POST /api/iot/okai

Cabecalhos

x-api-key: sua-chave-api-iot
Content-Type: application/json

Corpo da Requisicao

{
  "imei": "867648045123456",
  "message": "+RESP:GTFRI,...",
  "timestamp": "2025-12-25T12:00:00Z"
}

Resposta

{
  "success": true,
  "imei": "867648045123456",
  "messageType": "+RESP",
  "command": "GTFRI",
  "processed": true
}

Verificacao de Saude

GET /api/iot/okai

Retorna status do servico e lista de comandos suportados.

---