Integracao IoT Segway

O Levy Fleets fornece integracao nativa com dispositivos IoT Segway usando o Protocolo de Telemetria TCP Segway. Este guia cobre a integracao completa incluindo comandos suportados, processamento de telemetria, tratamento de erros e solucao de problemas.

Visao Geral

Dispositivos IoT Segway se comunicam com o Levy Fleets atraves de um protocolo baseado em TCP que fornece:

• Rastreamento GPS em tempo real com dados de localizacao em formato NMEA
• Monitoramento de bateria incluindo suporte a dupla bateria
• Controle de bloqueio/desbloqueio com reconhecimento
• Monitoramento de heartbeat para status de conectividade
• Status abrangente do veiculo incluindo velocidade, hodometro e temperatura
• Tratamento de erros e alarmes com classificacao de gravidade
• Atualizacoes de firmware OTA via HTTP ou FTP
• Suporte a bloqueio mecanico para travas de cabo/roda

Configuracao do Dispositivo

Configuracoes do Servidor

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

Autenticacao

Dispositivos Segway autenticam via chave de API. Certifique-se de que sua implantacao inclua a chave de API correta no cabecalho x-api-key para todas as comunicacoes.

Identificacao do Dispositivo

Os dispositivos sao identificados por IMEI. O formato da mensagem inclui o IMEI do dispositivo no cabecalho:

*HBCR,NB,{IMEI},{COMANDO},...#

Comandos Suportados

Operacoes Principais

Protocolo de Bloqueio/Desbloqueio

O processo de bloqueio/desbloqueio do Segway envolve uma troca de chaves:

Codigos de Status de Reconhecimento

Status do Veiculo (Serie S)

Localizacao e Rastreamento (Serie D)

Formato GPS D0

O comando D0 usa formato semelhante ao NMEA:

*HBCR,NB,{IMEI},D0,,{HORA},A,{LAT},{DIR_LAT},{LON},{DIR_LON},{VELOCIDADE},{RUMO},{DATA},{ALT},...#

• HORA: HHMMSS.sss
• A/V: Fixacao Valida/Invalida
• LAT: DDMM.MMMM (graus e minutos decimais)
• DIR_LAT: N/S
• LON: DDDMM.MMMM
• DIR_LON: E/O
• VELOCIDADE: Nos (convertido para km/h)
• DATA: DDMMAA

Configuracao de Rede (Serie N)

Recursos do Dispositivo (Diversos)

Bloqueio Mecanico (Serie C)

Tipos de bloqueio suportados:

• Tipo 1: Trava de cabo
• Tipo 6: Trava de roda
• Tipo 8: Trava combo capacete/cabo

Atualizacoes OTA (Serie U)

Codigos de status de atualizacao:

• 0: Iniciado
• 1: Baixando/Conectando
• 2: Download completo
• 3: Instalando
• 4: Sucesso
• 5: Falhou
• 6: Cancelado

Relatorios Estendidos

Processamento de Telemetria

Heartbeat (H0)

O heartbeat H0 e o sinal principal de keep-alive e inclui:

• Status de Bloqueio: 0 (desbloqueado) ou 1 (bloqueado)
• Voltagem IoT: Voltagem bruta em unidades de centivolt
• Forca do Sinal: Nivel de sinal celular
• Porcentagem de Bateria: Bateria do veiculo (0-100%)
• Estado de Carregamento: 0 (nao carregando) ou 1 (carregando)

O sistema calcula a porcentagem de bateria IoT a partir da voltagem:

Bateria IoT % = ((voltagem_mv - 3200) / (4200 - 3200)) * 100

Relatorio de Status (S6)

Fornece status abrangente em tempo real:

Status Estendido (S8)

Diagnosticos detalhados do veiculo:

Status Completo (P2)

O comando P2 retorna mais de 30 campos para diagnostico completo do veiculo:

• Modelo do dispositivo, firmware, versoes de hardware
• Bateria: porcentagem, voltagem, corrente, temperatura
• Temperaturas do motor e controlador
• Velocidade: atual, media, maxima
• Quilometragem: total e da viagem
• GPS: coordenadas, velocidade, sinal
• Forca do sinal GSM
• Dados do acelerometro (X, Y, Z)

Tratamento de Codigos de Erro

Traducao de Codigos de Erro

Codigos de erro Segway E0 sao automaticamente traduzidos para mensagens legiveis. O sistema:

1. Analisa os codigos de erro da mensagem E0
2. Traduz cada codigo usando o mapeamento de codigos de erro Segway
3. Determina o nivel de gravidade (aviso, erro, critico)
4. Formata uma mensagem amigavel ao usuario
5. Atualiza o registro do veiculo com status de erro

Niveis de Gravidade

Referencia Completa de Codigos de Alarme

O Levy Fleets traduz codigos de alarme Segway em alertas acionaveis. Abaixo esta a referencia completa:

Alarmes de Seguranca

Alarmes de Seguranca

Alarmes de Bateria

Alarmes de Comunicacao

Alarmes de Hardware

Categorias de Alarme

O sistema categoriza alarmes nos seguintes grupos:

Notificacoes por Email

Para codigos de erro com gravidade "erro" ou "critico":

1. Sistema gera uma notificacao por email
2. Email e enviado para gerentes de frota configurados
3. Inclui: ID do veiculo, IMEI, codigo de erro, descricao, gravidade
4. Enviado assincronamente para nao bloquear processamento de telemetria

Processamento de Localizacao

Conversao de Dados GPS

Mensagens D0 contem coordenadas em formato NMEA que sao convertidas para graus decimais:

// Converter DDMM.MMMM para graus decimais
graus = floor(coordenada / 100)
minutos = coordenada - (graus * 100)
decimal = graus + (minutos / 60)
// Aplicar direcao (negativo para S/O)

Historico de Localizacao da Viagem

Durante viagens ativas, mensagens D0:

1. Extraem coordenadas GPS e velocidade
2. Inserem na tabela ride_locations
3. Incluem altitude e status de movimento
4. Acionam verificacao de aplicacao de zonas
5. Atualizam estatisticas da viagem

Aplicacao de Zonas

Apos processar localizacao D0 durante uma viagem ativa:

1. Verificar se coordenadas caem dentro de quaisquer zonas definidas
2. Aplicar limites de velocidade para zonas lentas
3. Desabilitar acelerador para zonas proibidas
4. Atualizar RPC de estatisticas da viagem

Atualizacoes de Veiculos

Campos Atualizados por Telemetria

Carimbos de Data/Hora

Cada atualizacao de telemetria define:

• updated_at - Carimbo de data/hora de atualizacao geral
• iot_last_update - Ultima comunicacao IoT
• last_signal_at - Ultimo sinal recebido

Atualizacoes de localizacao tambem definem:

• last_location_update - Ultima fixacao GPS

Enviando Comandos

Senha IoT

Configure a senha Segway em Configuracoes:

Configuracoes > Veiculos > Senhas IoT > Segway

Senha padrao: 0000

Comandos Disponiveis no Painel

Sequencia de Comandos

Para bloqueio/desbloqueio:

1. Painel envia R0 (solicitar chave)
2. Dispositivo responde com chave de operacao
3. Painel envia L0/L1 com chave
4. Dispositivo executa e envia reconhecimento
5. Painel atualiza status do veiculo

Referencia de Configuracao

Configuracoes do Dispositivo (S5)

Configuracoes de Rastreamento (D1/D2)

Configuracoes de Velocidade (S1/S4)

Solucao de Problemas

Dispositivo Nao Conectando

Sintomas: Nenhum heartbeat recebido, dispositivo offline

Solucoes:

1. Verificar configuracao de IP e porta do servidor
2. Verificar conectividade celular e ativacao do SIM
3. Confirmar que configuracoes APN correspondem aos requisitos da operadora
4. Reiniciar o veiculo
5. Verificar se firewall esta bloqueando conexoes TCP

Comandos de Bloqueio Falhando

Sintomas: Bloqueio/desbloqueio retorna status de erro

Verificar codigo de status:

• Codigo 2 (Chave Invalida): Senha nao corresponde - verificar senha IoT em Configuracoes
• Codigo 3 (Viagem em Andamento): Encerrar a viagem atual primeiro
• Codigo 4 (ECU Falhou): Problema no controlador do veiculo - verificar erros E0
• Codigo 5 (Estrategia Recusou): Bloqueio de logica de negocios - verificar status do veiculo

GPS Nao Atualizando

Sintomas: Localizacao permanece no mesmo ponto ou mostra (0,0)

Solucoes:

1. Verificar indicador de fixacao "V" (invalido) em mensagens D0
2. Garantir que veiculo tem visao clara do ceu
3. Aguardar GPS adquirir satelites (ate 5 min cold start)
4. Verificar se intervalos de rastreamento D1 nao estao muito longos
5. Verificar se dispositivo esta em modo de baixa energia

Leitura de Bateria Incorreta

Sintomas: Bateria mostra 0%, valor errado, ou nao muda

Solucoes:

1. Para veiculos com dupla bateria, verificar ambos valores SOC em S8
2. Verificar comunicacao BMS (verificar contagens de ciclo de bateria)
3. Algumas leituras requerem veiculo ligado (nao apenas IoT)
4. Verificar se a bateria esta devidamente conectada

Codigos de Erro Aparecendo

Sintomas: Mensagens E0 mostrando codigos de erro

Acoes:

1. Anotar o numero do codigo de erro
2. Verificar notificacoes por email para traducao
3. Revisar registro do veiculo para campo error_message
4. Erros criticos requerem inspecao fisica
5. Limpar erros reiniciando se apropriado

Armazenamento de Dados

Registros de Telemetria

Todas as mensagens Segway sao armazenadas com:

• vehicle_uuid - Veiculo associado
• vehicle_number - ID legivel por humanos
• imei - Identificador do dispositivo
• raw_payload - Mensagem completa como JSON
• message_type - Tipo de comando (ex.: "H0_HEARTBEAT")
• timestamp - Carimbo de data/hora da mensagem
• idempotency_key - Chave de deduplicacao

Idempotencia

Cada registro de telemetria inclui uma chave de idempotencia gerada:

{vehicleId}-{imei}-{timestamp}-{messageType}

Isso previne entradas duplicadas de mensagens reenviadas.

Referencia da API

Endpoint

POST /api/iot/segway

Cabecalhos

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

Corpo da Requisicao

{
  "imei": "867648045123456",
  "cmd": "H0",
  "raw": "*HBCR,NB,867648045123456,H0,1,420,25,85,0#",
  "timestamp": "2025-12-25T12:00:00Z",
  "parsed": {}
}

Resposta

{
  "success": true,
  "vehicle_number": "LV-001",
  "ride_number": null,
  "command": "H0",
  "cmd": "H0"
}

Verificacao de Saude

GET /api/iot/segway

Retorna:

{
  "service": "Segway TCP Telemetry Ingestion",
  "status": "healthy",
  "timestamp": "2025-12-25T12:00:00Z",
  "supported_commands": ["R0", "L0", "L1", "H0", ...]
}

---