Glossario: Termini e Concetti
Questa guida spiega tutti i termini tecnici utilizzati nella documentazione dei protocolli GPS.
📦 Struttura Dati
Frame
Un frame è l'unità completa di comunicazione tra device e server. Contiene tutto il necessario per trasmettere un messaggio: header, dati, checksum e trailer.
┌─────────┬─────────┬───────────┬──────────┬─────────┐
│ Header │ Type │ Payload │ Checksum │ Trailer │
└─────────┴─────────┴───────────┴──────────┴─────────┘
↑ ↑
Frame Start Frame End
Packet (Pacchetto)
Sinonimo di frame. Indica l'insieme di byte che costituisce un singolo messaggio.
Payload
Il contenuto utile del frame, esclusi header, checksum e trailer. Contiene i dati veri e propri (coordinate, allarmi, stato, etc.).
Frame totale: 7E 02 00 [............PAYLOAD............] XX 7E
↑__________________________↑
Payload
Header
I primi byte del frame che identificano l'inizio e spesso contengono metadati come tipo e lunghezza.
| Protocollo | Header |
|---|---|
| S21L | 7E |
| G11LSE | 78 78 (corto) o 79 79 (lungo) |
| C059 | 7E o E7 |
Trailer
I byte finali del frame che segnalano la fine del messaggio.
| Protocollo | Trailer |
|---|---|
| S21L | 7E |
| G11LSE | 0D 0A (CR LF) |
| C059 | 7E o E7 |
🔢 Sistemi Numerici
Esadecimale (Hex)
Sistema numerico in base 16. Usa cifre 0-9 e lettere A-F. Ogni byte (8 bit) si rappresenta con 2 caratteri hex.
Decimale: 255 → Hex: FF
Decimale: 126 → Hex: 7E
Decimale: 1234 → Hex: 04D2
Perché si usa? È compatto e si allinea perfettamente con i byte (2 cifre hex = 1 byte).
Binario
Sistema numerico in base 2. Ogni cifra è un bit (0 o 1). 8 bit = 1 byte.
Hex: 7E → Binario: 0111 1110
Hex: FF → Binario: 1111 1111
Uso pratico: Per analizzare singoli flag (bit di stato/allarme).
BCD (Binary-Coded Decimal)
Formato che codifica ogni cifra decimale in 4 bit. Usato per timestamp e IMEI.
Orario 10:30:45 in BCD:
10 → 0x10 (non 0x0A!)
30 → 0x30
45 → 0x45
Risultato: 10 30 45 (6 bytes)
✅ Controllo Errori
Checksum
Un valore calcolato sui dati del frame per rilevare errori di trasmissione. Se il checksum ricevuto non corrisponde a quello calcolato, il frame è corrotto.
Tipi comuni:
| Tipo | Calcolo | Usato da |
|---|---|---|
| XOR | XOR di tutti i byte | S21L, C059 |
| CRC16 X.25 | Polinomiale ITU-T | G11LSE |
Esempio XOR:
Bytes: 02 00 28 01 35 ...
XOR: 02 ^ 00 ^ 28 ^ 01 ^ 35 = 1E
CRC (Cyclic Redundancy Check)
Checksum più robusto basato su divisione polinomiale. Rileva più tipi di errori rispetto a XOR.
🔀 Caratteri Speciali
Delimitatore
Byte speciale che marca inizio e fine del frame. Il problema: cosa succede se il payload contiene lo stesso byte del delimitatore?
Delimitatore: 7E
Payload: ... 45 7E AA ... ← Problema! Sembra fine frame!
Escape Sequence
Meccanismo per evitare ambiguità quando il delimitatore appare nel payload. Si sostituisce il byte problematico con una sequenza speciale.
S21L/C059:
7E nel payload → 7D 02 (escape)
7D nel payload → 7D 01 (escape dell'escape)
Esempio:
Dati originali: AA 7E BB
Dopo escaping: AA 7D 02 BB ← Ora 7E non confonde il parser
Unescaping
Processo inverso: il decoder riconverte le escape sequence nei byte originali.
📍 Dati di Posizione
Coordinate
Latitudine e longitudine. Diversi protocolli usano formati diversi:
| Formato | Esempio | Conversione |
|---|---|---|
| Microgradi | 45123456 | ÷ 1.000.000 = 45.123456° |
| Minuti/30000 | 81234000 | ÷ 60 ÷ 30000 = 45.13° |
Velocità
Tipicamente in km/h nel protocollo, convertita in nodi (knots) internamente.
double knots = kmh / 1.852;
Course (Direzione)
Angolo di direzione in gradi (0-360°). 0° = Nord, 90° = Est, 180° = Sud, 270° = Ovest.
Satellites
Numero di satelliti GPS visibili. Più satelliti = posizione più precisa.
RSSI
Received Signal Strength Indicator: potenza del segnale cellulare (0-31 tipicamente).
🚗 Stato Veicolo
Ignition (ACC)
Stato del quadro acceso/spento. Indica se il veicolo è in funzione.
Charging
Indica se il dispositivo è in carica (collegato all'alimentazione esterna).
Valid
Indica se il fix GPS è valido. Se false, le coordinate potrebbero essere imprecise o vecchie.
Blocked
Stato del relè di blocco motore. Se true, il comando di blocco è attivo.
⚠️ Allarmi
Bitmask (Maschera di Bit)
Un intero dove ogni singolo bit rappresenta uno stato o allarme diverso.
Alarm flags: 0x00010001 (32 bit)
│ │
│ └── Bit 0: SOS (1 = attivo)
└────────── Bit 16: Tampering (1 = attivo)
Lettura in Java:
if ((alarm & 0x01) != 0) { // Bit 0
position.addAlarm("sos");
}
if ((alarm & 0x10000) != 0) { // Bit 16
position.addAlarm("tampering");
}
Flag
Singolo bit che indica uno stato binario (on/off, vero/falso).
🔄 Comunicazione
TCP
Transmission Control Protocol: protocollo di trasmissione affidabile. Garantisce che i dati arrivino in ordine e senza perdite.
Sessione
Associazione tra un device ID e una connessione TCP. Creata al login, mantenuta finché il device è connesso.
Handshake
Scambio iniziale di messaggi per stabilire la connessione (Login → Response).
ACK (Acknowledgement)
Messaggio di conferma dal server al device che indica "ho ricevuto il tuo messaggio".
Heartbeat
Messaggio "keep-alive" inviato periodicamente per mantenere la connessione attiva anche senza dati nuovi.
📐 Formati Dati
TLV (Tag-Length-Value)
Formato flessibile per dati opzionali. Ogni blocco contiene:
- Tag: Tipo di dato (1 byte)
- Length: Lunghezza del valore (1 byte)
- Value: Il dato vero e proprio (N byte)
01 04 00 01 D4 C0
│ │ └─────────┴── Value: Odometer = 120.000
│ └───────────── Length: 4 bytes
└──────────────── Tag: 0x01 = Odometer
Big Endian vs Little Endian
Ordine dei byte per numeri multi-byte.
Numero: 0x1234
Big Endian: 12 34 (byte più significativo prima)
Little Endian: 34 12 (byte meno significativo prima)
I protocolli GPS tipicamente usano Big Endian.
🛠️ Debug
Wireshark
Software per catturare e analizzare traffico di rete. Permette di vedere i byte grezzi scambiati tra device e server.
tcpdump
Tool da linea di comando per catturare traffico:
sudo tcpdump -i eth0 port 5021 -w capture.pcap
Hex Dump
Rappresentazione di dati binari in formato esadecimale leggibile:
7E 02 00 00 28 01 35 86 84 03 39 40 00 15 ...