Esempi Pratici: Comunicazione Device ↔ Server

Questa guida mostra il flusso di comunicazione reale tra un dispositivo GPS e il server Visla, con esempi in formato esadecimale annotati byte-per-byte.

🔌 Scenario Completo: Accensione Dispositivo

Simuliamo cosa succede quando un tracker viene acceso e inizia a comunicare.

┌─────────┐                              ┌─────────┐
│ DEVICE  │                              │ SERVER  │
└────┬────┘                              └────┬────┘
     │                                        │
     │ 1. TCP Connect (Porta 5021/5006/5059)  │
     ├───────────────────────────────────────►│
     │                                        │
     │ 2. Login/Register Packet               │
     ├───────────────────────────────────────►│
     │                                        │
     │ 3. Login Response (OK)                 │
     │◄───────────────────────────────────────┤
     │                                        │
     │ 4. Location Report                     │
     ├───────────────────────────────────────►│
     │                                        │
     │ 5. ACK Response                        │
     │◄───────────────────────────────────────┤
     │                                        │
     │ 6. Heartbeat (ogni 60s)                │
     ├───────────────────────────────────────►│
     │                                        │

📡 Protocollo S21L (Porta 5021)

Il dispositivo si presenta con il suo IMEI.

Device → Server:

7E                      // Delimitatore start
01 00                   // Tipo: MSG_REGISTER (0x0100)
00 2C                   // Lunghezza attributi
01 35 86 84 03 39 40    // IMEI in BCD: 135868403940 (12 cifre)
00 01                   // Sequence number
                        // [Body: Provincia, Città, Produttore, Modello...]
67                      // Checksum XOR
7E                      // Delimitatore end

Server → Device:

7E
81 00                   // Tipo: MSG_REGISTER_RESPONSE
00 03                   // Lunghezza
01 35 86 84 03 39 40    // IMEI echo
00 01                   // Sequence
00                      // Result: 0 = SUCCESS
XX                      // Auth token (opzionale)
7E

2. Location Report (0x0200)

Il pacchetto principale che trasporta tutto.

Device → Server:

7E
02 00                   // Tipo: MSG_LOCATION_REPORT
00 28                   // Lunghezza: 40 bytes
01 35 86 84 03 39 40    // Device ID (BCD)
00 15                   // Sequence: 21

// ------ ALARM FLAGS (4 bytes) ------
00 00 00 00             // Nessun allarme attivo
                        // Bit 0: SOS, Bit 1: Overspeed, Bit 7: LowBattery

// ------ STATUS FLAGS (4 bytes) ------
00 00 00 03             // Bit 0: ACC ON, Bit 1: GPS Valid
                        // = Quadro acceso, GPS valido

// ------ COORDINATE ------
02 6B 3E 88             // Latitude: 45.123456° (x 10^-6)
00 8F 5C 28             // Longitude: 9.456789° (x 10^-6)

// ------ ALTITUDE, SPEED, COURSE ------
00 C8                   // Altitude: 200m
00 3C                   // Speed: 60 km/h (0.1 units)
01 2C                   // Course: 300°

// ------ TIMESTAMP (BCD) ------
24 12 28                // Data: 2024-12-28
10 30 00                // Ora: 10:30:00

// ------ ESTENSIONI TLV ------
01 04 00 01 D4 C0       // Tag 0x01: Odometer = 120.000 km
69 02 04 B0             // Tag 0x69: Battery = 12.00 V
30 01 1F                // Tag 0x30: RSSI = 31
31 01 0C                // Tag 0x31: Satellites = 12

XX                      // Checksum
7E

Parsing del Decoder (Java):

// S21lFrameDecoder.decodeLocation()
long alarm = buf.readUnsignedInt();  // 0x00000000
int status = buf.readInt();          // 0x00000003

position.setIgnition((status & 0x01) != 0);  // true
position.setValid((status & 0x02) != 0);     // true

double lat = buf.readUnsignedInt() * 0.000001;  // 45.123456
double lon = buf.readUnsignedInt() * 0.000001;  // 9.456789

position.setAltitude(buf.readShort());          // 200
position.setSpeed(buf.readUnsignedShort() * 0.1 / 1.852);  // ~32 knots
position.setCourse(buf.readUnsignedShort());    // 300

3. Allarme SOS

Stesso pacchetto Location, ma con bit allarme acceso.

// Solo la parte Alarm Flags cambia:
00 00 00 01             // Bit 0 = 1 → SOS attivo!

if ((alarm & 0x01) != 0) {
    position.addAlarm("sos");
    logger.warn("ALARM",
        kv("alarmType", "SOS"),
        kv("latitude", position.getLatitude()),
        kv("longitude", position.getLongitude()));
}

📡 Protocollo G11LSE (Porta 5006)

Device → Server:

78 78                   // Header (frame corto)
0D                      // Lunghezza: 13 bytes
01                      // Tipo: MSG_LOGIN (0x01)

// ------ IMEI (8 bytes BCD) ------
08 68 12 02 00 15 35 71 // IMEI: 868120200153571
                        // (primo nibble 0 viene scartato)

// ------ Model Code ------
00 36                   // Modello dispositivo

00 01                   // Sequence
XX XX                   // CRC16 X.25
0D 0A                   // Trailer

Server → Device:

78 78
05                      // Lunghezza
01                      // Tipo: LOGIN response
00 01                   // Sequence echo
XX XX                   // CRC16
0D 0A

2. Heartbeat

G11LSE ha un pacchetto heartbeat dedicato (S21L no).

Device → Server:

78 78
0B                      // Lunghezza: 11 bytes
23                      // Tipo: MSG_HEARTBEAT (0x23)

// ------ STATUS BYTE ------
42                      // 0b01000010
                        // Bit 1: ACC = ON
                        // Bit 6: Charging = YES

// ------ VOLTAGE & SIGNAL ------
06                      // Battery level: 6 (100%)
1F                      // RSSI: 31

// ------ Lingua/Timezone ------
01                      
00 01                   // Sequence
XX XX                   // CRC16
0D 0A

// G11lseFrameDecoder.java
case MSG_HEARTBEAT:
    int status = buf.readUnsignedByte();  // 0x42
    position.setIgnition((status & 0x02) != 0);   // true
    position.setCharging((status & 0x04) != 0);   // false (bit 2, not 6)
    // Nota: Il mapping esatto dei bit varia per variante

3. GPS + LBS + Status (Pacchetto Completo)

Device → Server:

78 78
1F                      // Lunghezza: 31 bytes
16                      // Tipo: MSG_GPS_LBS_STATUS_1

// ------ TIMESTAMP ------
18 0C 1C 0A 1E 00       // 2024-12-28 10:30:00

// ------ GPS INFO ------
CC                      // GPS Info: 0xCC
                        // Nibble basso (0x0C=12): Satelliti
                        // Nibble alto: Lunghezza dati GPS

// ------ COORDINATE (minuti/30000) ------
02 78 7D 00             // Lat raw → 45.123° 
05 A0 8C 00             // Lon raw → 9.456°

// ------ SPEED & FLAGS ------
3C                      // Speed: 60 km/h
13 2C                   // Flags + Course: 300°, GPS valid, Nord-Est

// ------ LBS (Cell Tower) ------
00 F1                   // MCC: 241 (Italia)
01                      // MNC: 01 (TIM)
12 34                   // LAC
00 AB CD                // Cell ID

// ------ STATUS ------
CC                      // Status byte (ACC ON, allarme vibrazione)
05                      // Battery: 5 (83%)
1A                      // RSSI: 26

00 17                   // Sequence
XX XX                   // CRC16
0D 0A

4. Pacchetto Allarme Dedicato (0x95)

A differenza di S21L, G11LSE ha un tipo messaggio specifico per allarmi.

78 78
0A                      // Lunghezza
95                      // Tipo: MSG_ALARM

// ------ ALARM CODE ------
01                      // Codice: 0x01 = SOS

// ------ LBS Info (per localizzazione approssimativa) ------
00 F1 01 12 34 00 AB CD

00 05                   // Sequence
XX XX                   // CRC16
0D 0A

// G11lseFrameDecoder.decodeAlarmCode()
String alarm = switch (code) {
    case 0x01 -> "sos";
    case 0x02 -> "powerCut";
    case 0x03 -> "vibration";
    case 0x06 -> "overspeed";
    // ...
};

📡 Protocollo C059 (Porta 5059)

1. Time Sync Request

Prima di inviare posizioni, il device chiede l'ora esatta.

Device → Server:

7E
01 09                   // Tipo: MSG_TIME_SYNC_REQUEST
00 00                   // Attributi
01 35 86 84 03 39 40    // Device ID
00 01                   // Sequence
                        // (nessun body)
XX                      // Checksum XOR
7E

Server → Device:

7E
81 09                   // Tipo: MSG_TIME_SYNC_RESPONSE
00 07                   // Lunghezza: 7 bytes
01 35 86 84 03 39 40    // Device ID
00 00                   // Sequence

// ------ TIMESTAMP UTC ------
07 E8                   // Anno: 2024
0C                      // Mese: 12
1C                      // Giorno: 28
0A                      // Ora: 10
1E                      // Minuto: 30
00                      // Secondo: 00

XX
7E

2. Batch Location (Dati Accumulati)

Quando il device era offline, accumula posizioni e le invia tutte insieme.

7E
07 04                   // Tipo: MSG_LOCATION_BATCH
00 96                   // Lunghezza: 150 bytes (3 posizioni x 50)
01 35 86 84 03 39 40
00 22

00 03                   // Count: 3 posizioni
00                      // Location type: 0 = normal

// ------ POSIZIONE 1 ------
00 32                   // Lunghezza singola: 50 bytes
[...dati posizione 1...]

// ------ POSIZIONE 2 ------
00 32
[...dati posizione 2...]

// ------ POSIZIONE 3 ------
00 32
[...dati posizione 3...]

XX
7E

🔧 Debug con Wireshark

Per analizzare i pacchetti reali:

Cattura traffico:

sudo tcpdump -i eth0 port 5021 -w capture.pcap

Filtra in Wireshark:

tcp.port == 5021 && tcp.len > 0

Cerca pattern:
- S21L/C059: Cerca 7e come delimitatore
- G11LSE: Cerca 78 78 o 79 79 come header

📊 Cheat Sheet Rapido

Cosa Cercare	S21L	G11LSE	C059
Start	`7E`	`78 78`	`7E`
Login	`01 00`	`01`	`01 00`
Location	`02 00`	`16` / `12`	`02 00`
Heartbeat	(nel Location)	`23`	`00 02`
Alarm	(bit in Location)	`95`	(bit in Location)
End	`7E`	`0D 0A`	`7E`

🔌 Scenario Completo: Accensione Dispositivo​

📡 Protocollo S21L (Porta 5021)​

1. Login (Register)​

2. Location Report (0x0200)​

3. Allarme SOS​

📡 Protocollo G11LSE (Porta 5006)​

1. Login​

2. Heartbeat​

3. GPS + LBS + Status (Pacchetto Completo)​

4. Pacchetto Allarme Dedicato (0x95)​

📡 Protocollo C059 (Porta 5059)​

1. Time Sync Request​

2. Batch Location (Dati Accumulati)​

🔧 Debug con Wireshark​

📊 Cheat Sheet Rapido​

🔌 Scenario Completo: Accensione Dispositivo

📡 Protocollo S21L (Porta 5021)

1. Login (Register)

2. Location Report (0x0200)

3. Allarme SOS

📡 Protocollo G11LSE (Porta 5006)

1. Login

2. Heartbeat

3. GPS + LBS + Status (Pacchetto Completo)

4. Pacchetto Allarme Dedicato (0x95)

📡 Protocollo C059 (Porta 5059)

1. Time Sync Request

2. Batch Location (Dati Accumulati)

🔧 Debug con Wireshark

📊 Cheat Sheet Rapido