📱 Guia de Desenvolvimento — App VL08

O que você vai aprender

• Conectar ao VL08 via BLE sem pareamento
• Enviar comandos XVM e receber respostas
• Consultar GPS, velocidade, CAN, entradas, acelerômetro e mais
• Parsear as respostas para exibir no app
• Exemplos de código em Flutter/Dart, Kotlin (Android) e Swift (iOS)

Métodos de Conexão

Parâmetros GATT

Nome do Dispositivo BLE

O VL08 anuncia como VIRTEC_VL8_XXXX onde XXXX é o ID do equipamento.

Filtre pelo prefixo VIRTEC_VL8_ no scan para encontrar apenas VL08.

Passo a passo detalhado

1. Conectar ao peripheral pelo endereço MAC (Android) ou UUID (iOS)
2. Descobrir serviços — chamar discoverServices()
3. Encontrar serviço com UUID 0000ffff-0000-1000-8000-00805f9b34fb
4. Encontrar characteristic 0000ff01-0000-1000-8000-00805f9b34fb
5. Habilitar notificações — escrever 0x0100 no descriptor CCCD (0x2902)
6. Pronto — agora pode enviar comandos (Write) e receber respostas (Notify)

Envio (Write)

Escreva o comando XVM como bytes ASCII (7-bit) na characteristic 0xFF01. Como o protocolo XVM usa apenas caracteres ASCII imprimíveis, tanto US-ASCII quanto UTF-8 produzem o mesmo resultado:

// Enviar consulta de status completo
byte[] cmd = ">QTT<".getBytes("US-ASCII");
characteristic.setValue(cmd);
gatt.writeCharacteristic(characteristic);

Recepção (Notify)

A resposta chega como notificação na mesma characteristic. Pode vir fragmentada em múltiplas notificações se for maior que o MTU.

// Callback de notificação
onCharacteristicChanged(gatt, characteristic) {
  String chunk = new String(characteristic.getValue(), "UTF-8");
  buffer.append(chunk);

  // Resposta completa quando encontrar ">"...algo..."<"
  if (buffer.contains("<")) {
    String response = buffer.toString();
    parseXvmResponse(response);
    buffer.clear();
  }
}

Máquina de Estados — Conexão BLE

Implemente uma state machine para gerenciar a conexão de forma robusta:

┌──────────┐     scan()     ┌───────────┐    connect()    ┌────────────┐
│          │ ──────────────→ │           │ ──────────────→ │            │
│ IDLE     │                 │ SCANNING  │                 │ CONNECTING │
│          │ ←────────────── │           │ ←────────────── │            │
└──────────┘   timeout/stop  └───────────┘   error/timeout └──────┬─────┘
     ↑                                                            │
     │ disconnect()                                    onConnected│
     │                                                            ↓
┌──────────┐   onDisconnect  ┌────────────┐  discoverSvcs ┌────────────┐
│          │ ←────────────── │            │ ←──────────── │            │
│DISCONN.  │                 │ CONNECTED  │               │ DISCOVERING│
│          │ ──(retry?)────→ │            │ ─────────────→│            │
└──────────┘                 └────────────┘  enable notify└────────────┘

Estratégia de Reconexão

// Exemplo: reconexão com backoff
int retries = 0;
void onDisconnected() {
  if (retries < 5) {
    int delay = pow(2, retries).toInt();  // 1, 2, 4, 8, 16 segundos
    Future.delayed(Duration(seconds: delay), () => connect(device));
    retries++;
  } else {
    notifyUser("Não foi possível reconectar. Verifique o VL08.");
  }
}

void onConnected() {
  retries = 0;  // Reset contador
}

Intervalo entre Comandos

Conexão SPP

Fluxo de Comunicação

1. Parear com o VL08 (dispositivo aparece como VIRTEC_VL8_XXXX)
2. Abrir socket RFCOMM com UUID SPP
3. Enviar comandos XVM como string ASCII via OutputStream
4. Ler respostas via InputStream (delimitadas por >...<)

// Android - Bluetooth Classic SPP
BluetoothSocket socket = device.createRfcommSocketToServiceRecord(
    UUID.fromString("00001101-0000-1000-8000-00805f9b34fb")
);
socket.connect();

OutputStream out = socket.getOutputStream();
out.write(">QTT<\r\n".getBytes());

InputStream in = socket.getInputStream();
// Ler até encontrar '<'

Configuração no VL08

// 1. Cadastrar rede Wi-Fi
>VSWI20,"MinhaRede""MinhaSenha"<

// 2. Configurar IP do seu servidor
>VSIP8,192.168.1.100.05000.05000,UDP,AUX0<

// 3. Criar evento para enviar via Wi-Fi
>SED001 TD01++ +- WF8 TT<

App como Servidor

// Servidor UDP simples (Python)
import socket

sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.bind(("0.0.0.0", 5000))

while True:
    data, addr = sock.recvfrom(1024)
    print(f"VL08: {data.decode('ascii')}")

    # Enviar comando de volta
    sock.sendto(b">QTT<", addr)

Triggers Wi-Fi úteis

Formato Simplificado (BLE/Serial)

Via BLE ou serial, o formato mínimo é:

>COMANDO<

// Exemplos:
>QTT<           // Consultar status completo
>QGP<           // Consultar posição GPS
>QSN<           // Consultar serial
>QVR<           // Consultar versão firmware

Formato Completo (TCP/UDP)

Para comunicação via rede (TCP/UDP), o formato completo com checksum é recomendado:

>COMANDO;ID=XXXX;#NNNN;*CC<[CR][LF]

│         │       │      │
│         │       │      └─ Checksum (XOR de todos bytes de '>' até último ';')
│         │       └─ Número da mensagem (hex)
│         └─ ID do equipamento
└─ Delimitador de início

// Numeração:
// 8000–FFFF = mensagens originadas pelo app
// 0001–7FFF = mensagens originadas pelo dispositivo

Múltiplos Comandos

Envie vários comandos separados por <> em uma única mensagem (máx. 180 chars):

>QSN<>QVR<       // Serial + Versão
>QGP<>QIN<>QAD<  // GPS + Entradas + Analógicas

Padrão de Resposta

Toda resposta XVM é delimitada por > e <. O tipo de resposta é identificado pelo prefixo:

Estratégia de Parsing

// Pseudocódigo
function parseResponse(raw: String) {
  // Extrair conteúdo entre > e <
  content = raw.substringBetween('>', '<')

  // Identificar tipo pela primeiras 3 letras
  type = content.substring(0, 3)

  switch (type) {
    case "RTT": return parseQTT(content)
    case "RGP": return parseQGP(content)
    case "RSN": return parseQSN(content)
    case "RSD": return parseQSD(content)
    case "RUV": return parseRUV(content)
    // ...
  }
}

Enviar

>QTT<

Resposta — RTT (formato contíguo)

A resposta RTT é composta por 4 blocos separados por espaços. O primeiro bloco é contíguo (sem espaços internos).

>RTT140521125208-2352502-046678930012673005F0002 04050711 010 00020422042203951454<
     │      │      │        │        │  │  ││ │  │  ││ │    │  │ │  │  │    │    │    │    │
     │      │      │        │        │  │  ││ │  │  ││ │    │  │ │  │  │    │    │    │    └ Alim. principal (×0.01V)
     │      │      │        │        │  │  ││ │  │  ││ │    │  │ │  │  │    │    │    └ Bateria interna (×0.01V)
     │      │      │        │        │  │  ││ │  │  ││ │    │  │ │  │  │    │    └ Analógica 2 (×0.01V)
     │      │      │        │        │  │  ││ │  │  ││ │    │  │ │  │  │    └ Analógica 1 (×0.01V)
     │      │      │        │        │  │  ││ │  │  ││ │    │  │ │  │  └ Analógica 0 (×0.01V)
     │      │      │        │        │  │  ││ │  │  ││ │    │  │ │  └ Saídas (OUT0 OUT1 OUT2)
     │      │      │        │        │  │  ││ │  │  ││ │    │  │ └ Sats céu
     │      │      │        │        │  │  ││ │  │  ││ │    │  └ Sats vistos
     │      │      │        │        │  │  ││ │  │  ││ │    └ Sats usados
     │      │      │        │        │  │  ││ │  │  ││ └ Estado posicionamento GPS (0-7)
     │      │      │        │        │  │  ││ │  │  │└ Antena GPS (0=ok 1=curto 2=desc)
     │      │      │        │        │  │  ││ │  │  └─ [espaço]
     │      │      │        │        │  │  ││ │  └ HDOP (0-50)
     │      │      │        │        │  │  ││ └ Nº evento (decimal)
     │      │      │        │        │  │  │└ Entradas digitais (hex, bit7=IGN)
     │      │      │        │        │  │  └ Idade posição (hex, segundos)
     │      │      │        │        │  └ Estado GPS (0-9)
     │      │      │        │        └ Heading (0-359°)
     │      │      │        └ Velocidade (km/h)
     │      │      └ Longitude (sinal + 3 graus + 5 decimais) ex: -046.67893°
     │      └ Latitude (sinal + 2 graus + 5 decimais) ex: -23.52502°
     └ Data/Hora UTC (DDMMAAhhmmss)

Mapa de Campos (posições fixas)

Estado GPS (campo posição 38)

Entradas Digitais (campo hex posição 41–42)

Exemplo: 5F = 01011111 → IGN=off, ALIM=on, IN05=off, IN04=on, IN03..IN00=on

Coordenadas — Formato Graus Decimais

Parser RTT — Dart (posicional)

class RTTData {
  final String date, time;
  final double lat, lon;
  final int speed, heading, gpsState, ageSeconds;
  final int inputs, eventNum, hdop;
  final int antennaState, gpsFix, satsUsed, satsSeen, satsSky;
  final int out0, out1, out2;
  final int ad0, ad1, ad2, batteryMv, mainMv;

  RTTData._({required this.date, required this.time, required this.lat,
    required this.lon, required this.speed, required this.heading,
    required this.gpsState, required this.ageSeconds, required this.inputs,
    required this.eventNum, required this.hdop, required this.antennaState,
    required this.gpsFix, required this.satsUsed, required this.satsSeen,
    required this.satsSky, required this.out0, required this.out1,
    required this.out2, required this.ad0, required this.ad1,
    required this.ad2, required this.batteryMv, required this.mainMv});

  /// Tensões em Volts
  double get batteryVolts => batteryMv / 100.0;
  double get mainVolts    => mainMv / 100.0;
  bool   get ignition     => (inputs & 0x80) != 0;
  bool   get powered      => (inputs & 0x40) != 0;
  bool   get hasGpsFix    => gpsState >= 2 && gpsState <= 5;

  static RTTData parse(String raw) {
    String s = raw.replaceAll(RegExp(r'[><]'), '');
    // s = "RTT140521125208-2352502-046678930012673005F0002 04050711 010 0002..."

    return RTTData._(
      date:         s.substring(3, 9),               // "140521" → 14/05/21
      time:         s.substring(9, 15),               // "125208" → 12:52:08
      lat:          _parseCoord(s.substring(15, 23), 2), // "-2352502" → -23.52502
      lon:          _parseCoord(s.substring(23, 32), 3), // "-04667893" → -46.67893
      speed:        int.parse(s.substring(32, 35)),   // "001"
      heading:      int.parse(s.substring(35, 38)),   // "267"
      gpsState:     int.parse(s.substring(38, 39)),   // "3"
      ageSeconds:   int.parse(s.substring(39, 41), radix: 16), // "00" hex
      inputs:       int.parse(s.substring(41, 43), radix: 16), // "5F" hex
      eventNum:     int.parse(s.substring(43, 45)),   // "00"
      hdop:         int.parse(s.substring(45, 47)),   // "02"
      // [espaço pos 47]
      antennaState: int.parse(s.substring(48, 49)),   // "0"
      gpsFix:       int.parse(s.substring(49, 50)),   // "4"
      satsUsed:     int.parse(s.substring(50, 52)),   // "05"
      satsSeen:     int.parse(s.substring(52, 54)),   // "07"
      satsSky:      int.parse(s.substring(54, 56)),   // "11"
      // [espaço pos 56]
      out0:         int.parse(s.substring(57, 58)),   // "0"
      out1:         int.parse(s.substring(58, 59)),   // "1"
      out2:         int.parse(s.substring(59, 60)),   // "0"
      // [espaço pos 60]
      ad0:          int.parse(s.substring(61, 65)),   // "0002"
      ad1:          int.parse(s.substring(65, 69)),   // "0422"
      ad2:          int.parse(s.substring(69, 73)),   // "0422"
      batteryMv:    int.parse(s.substring(73, 77)),   // "0395" → 3.95V
      mainMv:       int.parse(s.substring(77, 81)),   // "1454" → 14.54V
    );
  }

  /// Graus decimais: ±DD(D)XXXXX → grau + XXXXX/100000
  static double _parseCoord(String s, int degDigits) {
    int sign = s.startsWith('-') ? -1 : 1;
    String num = s.replaceAll(RegExp(r'[+-]'), '');
    double deg = double.parse(num.substring(0, degDigits));
    double dec = double.parse(num.substring(degDigits)) / 100000;
    return (deg + dec) * sign;
  }
}

Comandos Disponíveis

Resposta RGP — Formato Documentado

A resposta QGP é mais compacta que QTT — ideal para consultas rápidas de posição.

>RGP140521125234-2352502-046678970012673005F0015<
     │      │      │        │        │  │  ││ │  ││
     │      │      │        │        │  │  ││ │  │└ HDOP (0-50)
     │      │      │        │        │  │  ││ │  └ Nº evento (decimal)
     │      │      │        │        │  │  ││ └ Entradas digitais (hex)
     │      │      │        │        │  │  │└ Idade posição (hex, segundos)
     │      │      │        │        │  │  └ Estado GPS (0-9)
     │      │      │        │        │  └ Heading (0-359°)
     │      │      │        │        └ Velocidade (km/h)
     │      │      │        └ Longitude (±DDD + 5 decimais)
     │      │      └ Latitude (±DD + 5 decimais)
     └──────┴── Data/Hora (DDMMAAhhmmss)

Parser RGP — Dart (posicional)

class RGPData {
  final String dateTime;
  final double lat, lon;
  final int speed, heading, gpsState;

  static RGPData parse(String raw) {
    String s = raw.replaceAll(RegExp(r'[><]'), '');
    return RGPData(
      dateTime: s.substring(3, 15),
      lat:     _coord(s.substring(15, 23), 2),
      lon:     _coord(s.substring(23, 32), 3),
      speed:   int.parse(s.substring(32, 35)),
      heading: int.parse(s.substring(35, 38)),
      gpsState: int.parse(s.substring(38, 39)),
    );
  }

  static double _coord(String s, int dg) {
    int sign = s.startsWith('-') ? -1 : 1;
    String n = s.replaceAll(RegExp(r'[+-]'), '');
    return (double.parse(n.substring(0, dg))
          + double.parse(n.substring(dg)) / 100000) * sign;
  }
}

Consulta rápida de velocidade

// Enviar
>QSD<

// Resposta
>RSD0035<    // 35 km/h
// Parser: int.parse(response.substring(5))  → 35

CTs Padrão — Script Newtec

Com o script padrão vl08_conf_newtec + biblioteca CAN, os dados ficam nos CTs:

Consultar faixa de CTs

// Consultar CT01 a CT10 de uma vez
>QCT001010<

// Resposta:
>RCT01 01500 02 085 03 078 04 032 05 128 06 045 07 088 08 125340 09 4520 10 065<

// Cada par é: índice + valor

OBD2 — VIN do Veículo

// Solicitar VIN
>VOBD_ASK_VIN<

// Aguardar ~2s, depois consultar
>VOBD_VIN<

// Resposta contém o VIN de 17 chars

Entradas Digitais

// Consultar
>QIN<

// Resposta
>RIN0000000001000000<
// 8 dígitos: IN00 a IN07 (0=aberto, 1=fechado)
// IN07 = Ignição (mais comum)

Entradas Analógicas — QAD (formato RAD)

// Consultar todas
>QAD<

// Resposta com estrutura posicional:
>RAD00 010100001829 1248329725662566000003632709<
     ││ │            │   │   │   │   │   │   │
     ││ │            │   │   │   │   │   │   └ Alimentação principal (×0.01V)
     ││ │            │   │   │   │   │   └ Bateria interna (×0.01V)
     ││ │            │   │   │   │   └ Reservado (0000)
     ││ │            │   │   │   └ Analógica IN2 (×0.01V)
     ││ │            │   │   └ Analógica IN2 (×0.01V)
     ││ │            │   └ Analógica IN1 (×0.01V)
     ││ │            └ Analógica AD0 (×0.01V)
     ││ └ Data/Hora (DDMMAAhhmmss)
     │└ Nº evento
     └ RAD

// Valores de tensão: 4 dígitos, 2 inteiros + 2 decimais
// Ex: 0363 = 3.63V | 1248 = 12.48V | 2709 = 27.09V

// Consultar analógica específica:
>QAD00<   // AD0 (fio marrom)
>QAD05<   // Bateria interna
>QAD06<   // Alimentação principal

Uso típico no App

Leitura 3 eixos

// Consultar
>GMV<

// Resposta
>GMV V±xxxx X±xxxx Y±xxxx Z±xxxx S H<
//     │       │       │       │    │ └ Heading
//     │       │       │       │    └ Speed
//     │       │       │       └ Eixo Z (G×100)
//     │       │       └ Eixo Y (G×100)
//     │       └ Eixo X (G×100)
//     └ Módulo (G×100)

// Exemplo: GMV V+0098 X+0011 Y-0003 Z+0097 035 270
// → 0.98G módulo, eixo Z ~1G (parado na horizontal)

Tensões via QTT (posições fixas na RTT)

Os campos finais da resposta RTT contêm as tensões (posições 73–80):

• Pos. 73–76: Bateria interna (×0.01V) → 0395 = 3.95V
• Pos. 77–80: Alimentação principal (×0.01V) → 1454 = 14.54V

Valores de 0000 a 3000 (0.00V a 30.00V). Bateria de lítio normal: 3.50–4.20V. Bateria veículo: 12.00–14.50V.

Formatos de Report Definidos

Reports pré-configurados com estrutura fixa. Usados em eventos com destino TT, GP, AD, etc.

Formatos de Report Configuráveis (RUV)

Reports configuráveis com SUCxx. O conteúdo depende da programação.

x = 0–15 (slot do report). Exemplo: V1 envia RUV01, U3 envia RUS03.

RUV01: Dados Básicos de Tracking — Campo a Campo

O formato mais usado para tracking periódico. Vem como resposta de V1 nos eventos.

>RUV01100,NT003,240622184546-1926542-046895630000009FFDE0000,04221376,00000,00000,00000,
  1111111111,2222222222,03333,00444,55555,00100,0,0,4G:1,1644991399;ID=0081;#8012;*18<

Eventos do RUV01

Outros Formatos RUV

Configurar Report via BLE

// Evento: enviar RUV01 a cada 10 segundos via BLE
>STD01999999990010<             // TD01 = cada 10s
>SED001 TD01++ +- BTT V1<      // Report V1 via Bluetooth

// No app, o report RUV01 chegará como notificação BLE a cada 10s
// A prioridade de envio BT pode ser:
//   BTT     → Normal (5 tentativas)
//   BTT_LO  → Baixa prioridade (1 tentativa)
//   BTT_HI  → Alta prioridade (retenta até ACK)

Exemplos de Configurações

// Configurar APN
>SCF0000,MX2,APN zap.vivo.com.br,SUP2 vivo vivo<

// Configurar IP do servidor
>VSIP0,200.100.50.25.05000.05000,UDP,AUX0<

// Configurar Wi-Fi
>VSWI20,"MinhaRede""MinhaSenha"<

// Programar evento
>SED001 TD01++ +- GF0 V0<

// Limpar configuração
>CLN0000<

// Resetar
>RST<

Boas Práticas

Problemas Comuns

Referência Rápida — Todos os Comandos úteis para App