Integracao IoT Queclink

O Levy Fleets fornece suporte abrangente para dispositivos IoT Queclink serie GL530, implementando 100% do Protocolo @Track Air Interface v80.56. Com mais de 85 comandos suportados, esta e uma das integracoes IoT mais ricas em recursos disponiveis.

Visao Geral

Dispositivos IoT Queclink se comunicam com o Levy Fleets atraves de um endpoint de API seguro que processa dados extensivos de telemetria. A integracao suporta:

• Rastreamento GPS de alta precisao com suporte multi-GNSS
• Monitoramento abrangente de bateria incluindo integracao BMS
• Controle de ECU para bloqueio/desbloqueio e limitacao de velocidade
• Geofencing multi-zonas com deteccao de entrada/saida
• Sistema extensivo de alarmes com gatilhos configuraveis
• Integracao de barramento CAN para diagnostico de veiculos
• Configuracao OTA para gerenciamento remoto de dispositivos
• Suporte NFC para operacoes baseadas em cartao

Configuracao do Dispositivo

Configuracoes do Servidor

Configure seu dispositivo Queclink para se comunicar com o Levy Fleets:

Autenticacao

Dispositivos Queclink autenticam usando a chave de API IoT. Configure o cabecalho x-api-key nas configuracoes do seu dispositivo.

Identificacao do Dispositivo

Os dispositivos sao identificados por IMEI no payload da mensagem. O sistema usa cache inteligente para buscas de veiculos para otimizar o desempenho.

Comandos Suportados (85+)

Relatorios de Localizacao

Status e Informacoes

Bateria e Energia

ECU (Unidade de Controle Eletronico)

Operacoes de Bloqueio

Velocidade e Acelerador

Geofencing

Alarmes e Alertas

Deteccao de Movimento

Tombamento e Recuperacao

Eventos do Sistema

Configuracao e GPS

NFC e Externo

Deteccao de Seguranca Avancada

Dispositivos Queclink suportam recursos de seguranca avancados exclusivos desta integracao:

Deteccao de AI e Auxiliar

Dispositivos com integracao de caixa AI suportam deteccao inteligente:

O sistema de deteccao AI pode identificar:

• Conformidade de uso de capacete
• Padroes de comportamento do piloto
• Deteccao de obstaculos
• Avisos de saida de faixa

Reconhecimentos e Buffer

Formato de Mensagem

Estrutura da Mensagem

Mensagens Queclink seguem este formato:

+RESP:GTXXX,PROTOCOLO,IMEI,...,CHECKSUM$

Componentes:

• +RESP / +ACK / +BUFF - Tipo de mensagem
• GTXXX - Codigo de comando
• PROTOCOLO - Identificador de versao do protocolo
• IMEI - Identificador do dispositivo de 15 digitos
• ... - Campos de dados especificos do comando
• CHECKSUM$ - Checksum da mensagem

Mensagens de Exemplo

Relatorio de Localizacao (GTFRI):

+RESP:GTFRI,380701,867648045123456,,0,0,1,1,0.0,0,35.6,-73.9876,40.7580,20251225120000,0310,0260,00F7,36A3,00,0.0,,,99,20251225120001,0065$

Status da Bateria (GTBAT):

+RESP:GTBAT,380701,867648045123456,,0,85,4200,0,20251225120000,0065$

Bloqueio Bem-Sucedido (GTLOC):

+RESP:GTLOC,380701,867648045123456,,0,1,20251225120000,0065$

Processamento de Telemetria

Processamento de Relatorio de Localizacao

Ao receber mensagens GTFRI ou GTERI:

1. Analisar coordenadas - Extrair latitude, longitude, velocidade, direcao
2. Validar fixacao GPS - Verificar indicador de qualidade da fixacao
3. Atualizar veiculo - Definir posicao atual e last_location_update
4. Armazenar no historico da viagem - Se viagem ativa, adicionar a ride_locations
5. Calcular velocidade - Converter e validar leitura de velocidade
6. Aplicar hodometro - Atualizar distancia cumulativa
7. Acionar verificacao de zona - Avaliar limites de geofence

Campos de Dados de Bateria

Mensagens de bateria incluem dados BMS abrangentes:

Processamento de Relatorio ECU

Mensagens ECU (GTECU, GTECS) fornecem dados do controlador do veiculo:

Resolucao de Identidade do Veiculo

Estrategia de Cache

A integracao usa cache eficiente para buscas de veiculos:

1. Verificar cache de memoria - Procurar IMEI em cache de 1 hora
2. Cache encontrado - Retornar identidade do veiculo em cache imediatamente
3. Cache nao encontrado - Consultar banco de dados para veiculo por iot_imei
4. Popular cache - Armazenar resultado por 1 hora
5. Retornar identidade - Fornecer UUID e numero do veiculo

Beneficios

• Carga de banco de dados reduzida - Consulta unica por hora por dispositivo
• Processamento mais rapido - Buscas em cache em sub-milissegundos
• Identidade consistente - Mesmo ID de veiculo em todas as mensagens

Invalidacao de Cache

O cache e automaticamente limpo quando:

• Dispositivos IoT sao importados em massa
• IMEI do veiculo e alterado
• Limpeza manual de cache e acionada

Integracao de Viagem Ativa

Deteccao de Viagem

Para cada mensagem recebida:

1. Consultar viagens ativas/pausadas por vehicle_uuid
2. Se nao encontrada, verificar por vehicle_number (suporte legado)
3. Preencher viagens legadas com UUIDs adequados
4. Associar telemetria a viagem

Historico de Localizacao

Durante viagens ativas, relatorios de localizacao:

1. Inserem na tabela ride_locations
2. Incluem: coordenadas, velocidade, altitude, direcao
3. Calculam se veiculo esta em movimento
4. Armazenam dados brutos para depuracao
5. Atualizam distancia/duracao da viagem

Aplicacao de Zonas

Apos processamento de localizacao:

await enforceZoneActions(admin, {
  vehicleId: vehicleUuid,
  rideId: rideId,
  latitude: location.latitude,
  longitude: location.longitude,
  context: 'iot_queclink'
})

Acoes de zona incluem:

• Aplicacao de limite de velocidade em zonas lentas
• Desabilitar acelerador em zonas proibidas
• Geracao de alerta para violacoes de limite

Enviando Comandos

Senha IoT

Configure a senha Queclink:

Configuracoes > Veiculos > Senhas IoT > Queclink

Senha padrao: ks600

Comandos do Painel

Tratamento de Resposta de Comando

Comandos de bloqueio/desbloqueio incluem processamento de resultado:

Tratamento de Alarmes

Tipos de Alarme

O sistema processa multiplas categorias de alarme:

Processamento de Alarme

1. Analisar mensagem de alarme e extrair tipo
2. Buscar cliente associado (se viagem ativa)
3. Criar registro de alarme no banco de dados
4. Gerar notificacao se garantido
5. Atualizar status do veiculo se necessario

Notificacoes ao Cliente

Para certos alarmes durante viagens ativas:

• Alertas SOS notificam operadores de frota imediatamente
• Deteccao de colisao pode acionar protocolos de emergencia
• Alertas de adulteracao sao sinalizados para investigacao

Armazenamento de Dados

Tabela de Telemetria

Todas as mensagens armazenadas com:

Localizacoes de Viagem

Para viagens ativas, dados GPS armazenados em ride_locations:

Dispositivos Nao Correspondidos

Registrando Nao Correspondidos

Quando uma mensagem chega de um IMEI desconhecido:

1. Processar mensagem para fins de registro
2. Registrar na tabela iot_unmatched_devices
3. Armazenar: IMEI, protocolo, origem, payload, carimbos de data/hora
4. Tornar visivel no painel "Dispositivos Nao Correspondidos"

Resolvendo Nao Correspondidos

Para registrar um dispositivo nao correspondido:

1. Navegar para Dispositivos IoT > Dispositivos Nao Correspondidos
2. Clicar na entrada nao correspondida
3. Clicar "Registrar Dispositivo"
4. Preencher campos obrigatorios (subconta, tipo IoT)
5. Salvar - dispositivo agora e rastreado normalmente

Opcoes de Configuracao

Intervalos de Relatorio

Configure com que frequencia o dispositivo reporta:

Modos de Energia

Configuracao de Geofence

Configure ate 100 zonas de geofence por dispositivo:

Solucao de Problemas

Sem Atualizacoes de Localizacao

Sintomas: Posicao do veiculo nao atualizando

Solucoes:

1. Verificar energia e nivel de bateria do dispositivo
2. Verificar se antena GPS tem visao do ceu
3. Revisar configuracao de intervalo FRI
4. Verificar conectividade celular
5. Examinar mensagens GTGPS para status de fixacao

Comandos Nao Funcionando

Sintomas: Comandos de bloqueio/desbloqueio nao executados

Solucoes:

1. Verificar senha IoT em Configuracoes
2. Verificar se dispositivo esta online (ultima visualizacao < 5 min)
3. Revisar resposta de comando (GTLOF/GTULF = falha)
4. Verificar status da ECU para erros
5. Reiniciar veiculo se necessario

Heartbeat Ausente

Sintomas: Dispositivo mostra offline, sem GTHBD

Solucoes:

1. Verificar configuracao do servidor no dispositivo
2. Verificar forca do sinal celular
3. Garantir que cartao SIM esta ativo
4. Revisar reinicializacoes por watchdog (GTDOG)
5. Verificar se dispositivo nao esta em sleep profundo

Aplicacao de Zona Nao Funcionando

Sintomas: Velocidade nao limitada em zonas lentas

Solucoes:

1. Verificar se zona esta devidamente configurada
2. Verificar se tipo de zona suporta aplicacao
3. Confirmar que viagem esta ativa
4. Revisar precisao de localizacao
5. Verificar se ECU pode receber comandos de velocidade

Mensagens em Buffer

Sintomas: Telemetria chegando com atraso

Explicacao: Quando offline, dispositivo armazena mensagens em buffer e envia quando reconecta. Estas chegam com prefixo +BUFF.

Tratamento:

• Mensagens sao processadas com carimbos de data/hora originais
• Estatisticas de viagem sao atualizadas retroativamente
• Aplicacao de zona nao aplicada a dados historicos

Referencia da API

Endpoint

POST /api/iot/queclink

Cabecalhos

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

Corpo da Requisicao

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

Resposta

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

Verificacao de Saude

GET /api/iot/queclink

Retorna status do servico incluindo:

• Nome e versao do servico
• Versao do protocolo
• Estatisticas de cobertura (85 comandos, 100%)
• Lista de todos os comandos suportados

---