Se hai lavorato con un Teltonika in produzione, prima o poi ti sei imbattuto nella domanda: quale codec uso, 8, 8E o 16? La risposta breve è che quasi sempre Codec 8E. Quella lunga implica capire come Teltonika impacchetta i dati AVL, perché ci sono tre formati, e quando conviene ognuno. Questo post è il riferimento che ci sarebbe piaciuto avere quando abbiamo integrato il primo FMC920.
Cos'è un codec in Teltonika
Un codec nel mondo Teltonika non è audio né video. È il formato binario con cui il dispositivo serializza i record di telemetria (posizione, velocità, IO, eventi) per inviarli al server via TCP. È l'equivalente dello "schema" del protocollo: definisce quali campi vanno, in che ordine, con che tipo e dimensione.
Quando configuri un Teltonika puntando al tuo server (Traccar, Wialon, Fletaro o uno proprio), il codec è il contratto tra i due. Se il server non implementa il codec che il dispositivo invia, non può decodificare la trama.
I tre codec più usati oggi sono:
- Codec 8 — il classico, originale. AVL ID di 1 byte. Limitato ma compatto.
- Codec 8 Extended (8E) — estende AVL ID a 2 byte. È il codec di default in tutti i Teltonika moderni (FMB, FMC, FMM e successivi).
- Codec 16 — aggiuntivo, incorpora un generation type esplicito per record. Utile per differenziare eventi dai record periodici.
Struttura generale di un pacchetto AVL
Prima di entrare in ciascun codec, questa è l'envelope TCP comune di qualsiasi pacchetto Teltonika:
Preamble (4 bytes) → 0x00000000 Data Field Length (4) → numero di byte del data field Codec ID (1) → 0x08, 0x8E, 0x10 (16 decimale) Number of Data 1 (1) → quanti record AVL arrivano [AVL Data ...] → record AVL in formato codec Number of Data 2 (1) → stesso numero del primo CRC-16 (4) → CRC di Data Field Length+Data
Il codec ID identifica il formato del blocco AVL. Quello che cambia tra codec 8, 8E e 16 è come si serializza ciascun record AVL all'interno di quel blocco.
Codec 8 (Codec ID = 0x08)
Il codec originale. Ogni record AVL include:
Timestamp (8 bytes) → ms dall'epoca (UTC) Priority (1 byte) → 0=low, 1=high, 2=panic GPS Element (15 bytes): Longitude (4) → intero con segno, moltiplica per 10⁻⁷ gradi Latitude (4) → stesso formato Altitude (2) → metri Angle (2) → 0-359° Satellites (1) → numero di satelliti in uso Speed (2) → km/h IO Element: Event IO ID (1) → AVL ID che ha scatenato questo record (0 = periodico) Total IO (1) → numero totale di IO nel record N1 (1) + [IO ID (1) + Value (1 byte)] × N1 N2 (1) + [IO ID (1) + Value (2 bytes)] × N2 N4 (1) + [IO ID (1) + Value (4 bytes)] × N4 N8 (1) + [IO ID (1) + Value (8 bytes)] × N8
Limitazione chiave: l'AVL ID è codificato in 1 byte (0-255). Sufficiente per gli IO di base (accensione, velocità, voltaggio, GSM signal) ma non per tutti gli AVL ID esistenti nel Teltonika moderno. L'FMC920 da sola ha ~190 AVL ID dichiarati. Il totale dell'intera gamma (con bus CAN, sensori esterni, moduli LV-CAN) supera i 1.500. Non entrano in 1 byte.
Codec 8 funziona ancora per casi base (tracking + una manciata di IO), ma è deprecato. Se inizi un progetto nuovo, non usarlo.
Codec 8 Extended / 8E (Codec ID = 0x8E)
L'estensione naturale dell'8: AVL ID passa da 1 byte a 2 byte (65.535 valori possibili), e si aggiunge un campo Variable Length IO per dati di lunghezza arbitraria (necessario per sensori che restituiscono stringhe, blob binari o dati lunghi come mappe di eventi CAN).
Timestamp (8 bytes) → identico al Codec 8 Priority (1) → identico GPS Element (15 bytes) → identico IO Element: Event IO ID (2 bytes) → ← cambio: ora 2 byte Total IO (2) → ← cambio: ora 2 byte N1 (2) + [IO ID (2) + Value (1)] × N1 N2 (2) + [IO ID (2) + Value (2)] × N2 N4 (2) + [IO ID (2) + Value (4)] × N4 N8 (2) + [IO ID (2) + Value (8)] × N8 NX (2) + [IO ID (2) + Length (2) + Value (Length)] × NX ← variable length
Codec 8E è la scelta predefinita consigliata per qualsiasi dispositivo Teltonika moderno. Supporta tutta la gamma di AVL ID attuali e futuri, supporta payload variabili (necessari per CAN-CONTROL, lettori 1-Wire, sensori BLE), e tutte le piattaforme serie lo implementano.
Esempio: decodificare un AVL Element 8E reale
Trama esempio (in hex), presa da un FMC920 che invia posizione + 5 IO:
00000000 00000089 8E 01 00 0001 87B2 33BE 00 00 01D6CC9F 4F35EAD2 0064 0000 0F 09 00 0005 0000 ← Event IO ID (=0, periodico) e Total IO (=5) 0005 ← N1 (5 IO da 1 byte) 0015 03 → IO 21 (GSM signal) = 3 0001 01 → IO 1 (Digital Input 1) = 1 0042 5C → IO 66 (Battery voltage centiV) = 92 → 9.2V 00B5 0F → IO 181 (GNSS HDOP) = 15 00B6 0B → IO 182 (GNSS PDOP) = 11 0000 ← N2 (0 IO da 2 byte) 0000 ← N4 0000 ← N8 0000 ← NX 01 00007D8B ← CRC
Quella stessa trama in Codec 8 sarebbe ~10 byte più corta (perché gli AVL ID sarebbero 1 byte), ma IO 181 e IO 182 non entrerebbero nemmeno (i loro ID sono > 255).
Codec 16 (Codec ID = 0x10)
Codec 16 introduce un campo Generation Type per ogni record AVL. È simile al Codec 8 (AVL ID di 1 byte), ma aggiunge informazione sulla causa del record:
Timestamp (8 bytes)
Timestamp Extension (1 byte) ← microsecondi / generazione
Priority (1)
GPS Element (15)
Event IO ID (2 bytes) ← stessa estensione di 8E
Generation Type (1 byte) ← causa del record: 0=on exit, 1=on entrance,
2=on both, 3=reserved, 4=hysteresis,
5=on change, 6=eventual, 7=periodical
N1 ... NX (identico a 8E)
Codec 16 serve per casi in cui devi sapere esattamente perché si è generato il record senza doverlo dedurre dall'Event IO ID. Utile in flotte grandi dove vuoi post-processare eventi discriminando tra "record periodico ogni 30s" e "record scatenato da evento" senza guardare l'AVL ID.
In pratica quasi nessuno usa Codec 16. Se ti serve, già sai perché; se non ti serve, continua con 8E.
Quando usare ciascun codec
| Scenario | Codec consigliato |
|---|---|
| Nuovo progetto, dispositivo moderno (FMB, FMC, FMM, MTB) | Codec 8E |
| Devi leggere bus CAN o collegare sensori BLE/RS485 | Codec 8E (ti servono ID >255 e variable length) |
| Integrazione con server antico che supporta solo 8 | Codec 8 (breve termine, migrare a 8E prima possibile) |
| Audit regolatorio che richiede generation type esplicito per record | Codec 16 |
| Dispositivi FM legacy (FM1100, FM2200, FM3622) in produzione ereditata | Codec 8 (non supportano 8E su hardware antico) |
Regola pratica: se il tuo dispositivo è della famiglia FMB / FMC / FMM e la tua piattaforma è moderna (Wialon, Traccar >= 5.0, Fletaro, GpsGate, Flespi), scegli Codec 8E e dimenticatene.
Codec aggiuntivi che esistono ma si vedono poco
- Codec 12 — comandi GPRS: il server manda comandi al dispositivo (riavvio, cambio di configurazione, query di stato). Lo usa lo strumento di configurazione remota e piattaforme che mandano comandi a distanza.
- Codec 13 — risposta al Codec 12. Il dispositivo risponde.
- Codec 14 — comandi per IMEI / indirizzo diretto, simile al 12 ma con indirizzamento per IMEI esplicito.
- Codec 7 / 7E — per scarico di file (tipicamente tachigrafo digitale). L'FMC650 scarica DDD usando Codec 7E.
Questi non competono con Codec 8/8E/16: sono canali paralleli per task specifici (comandi, scarico di file). Il tuo server probabilmente li implementa in modo trasparente.
Come configurare il codec in un Teltonika
Tramite lo strumento di configurazione ufficiale (FM Configurator connesso via cavo USB) o via FOTA con la piattaforma FOTA Web:
- System → Codec: dropdown con le opzioni disponibili del firmware attuale.
- Impostare GPRS Server, porta, APN.
- Applicare configurazione.
Sotto-dettaglio: in alcuni firmware il dispositivo sceglie automaticamente tra 8 e 8E in base al numero di IO attivi. Se hai solo IO da 1 byte ID, manda 8; nel momento in cui attivi uno >255, salta a 8E. Verificalo nel log della prima trama ricevuta nel tuo server — il Codec ID è nel byte 9 del pacchetto.
Errori tipici nell'integrazione
1. Il server decodifica AVL ID in 1 byte e ricevi ID giganti. La tua trama è 8E ma il tuo decodificatore tratta il primo byte dell'AVL ID come l'ID completo. Risultato: AVL ID 0x01B5 viene decodificato come 0x01 + 0xB5 separati. Verifica che il tuo decodificatore rispetti il Codec ID e applichi il formato corretto.
2. Il CRC fallisce e scarti la trama. Il CRC-16 di Teltonika usa polinomio 0xA001 (CRC-16/IBM, "IBM Bisync"), non il CRC-16/CCITT standard. Se la tua libreria CRC non è quella corretta, tutti i CRC falliranno anche se la trama è corretta.
3. Il dispositivo "manda 8E" ma mancano IO. Se hai attivato un IO nella configurazione ma non compare, di solito è perché l'IO richiede un altro IO precedente attivato, o richiede connettività CAN/BLE non fisicamente collegata. Guarda la documentazione del modello per vedere le dipendenze tra IO.
4. Latenza alta e pensi sia la rete, ma è il codec. Codec 8E genera trame più grandi del Codec 8. Con un piano dati molto lento (2G in zone rurali) puoi notare la differenza. In 4G è irrilevante.
Riepilogo
Se ti resti con due idee:
- Codec 8E è la scelta moderna di default: 2 byte per AVL ID, variable length per sensori, compatibile con tutta la gamma attuale di Teltonika.
- Il tuo CRC è CRC-16/IBM, non CCITT. Se il tuo server scarta trame con CRC non valido e niente quadra, parti da lì.
Per una guida ufficiale con il dettaglio byte per byte e gli AVL ID per dispositivo, la wiki di Teltonika ha il riferimento completo (in inglese). Se ti monti un decoder proprio, quella wiki + questa nota dovrebbero bastare per un'integrazione pulita.
Se hai già hardware Teltonika e vuoi una piattaforma di gestione che già implementa tutti i codec e processa le trame correttamente, Fletaro è la nostra azienda sorella SaaS che lo fa nativamente. O se ti serve hardware con codec correttamente configurati di fabbrica, nel nostro negozio li spediamo pre-configurati per integrazione standard.
