Teltonika Codec 8 (TCP) — implementation notes

Disclaimer: This document describes behaviour implemented in services/telematics-gateway/src/codec8.ts. Always validate against the official Teltonika protocol PDF for your firmware.

Session flow

1. Device sends IMEI preamble: uint16 big-endian length L, then L bytes ASCII IMEI (typically 15 digits).
2. Server responds with one byte: 0x01 = accept, 0x00 = reject (this gateway rejects unknown IMEIs if TELEM_GATEWAY_ALLOW_UNKNOWN_IMEI is not true).
3. Device sends Codec 8 AVL packets (may repeat on the same TCP connection).

Codec 8 packet layout (parsed subset)

Field	Size	Notes
Preamble	4	Must be 00 00 00 00
Data field length	4	Big-endian; length of data starting at Codec ID through second “Number of Data”
Codec ID	1	0x08 for Codec 8
Number of Data 1	1	Record count
Records	variable	Each record: Timestamp, Priority, GPS element (15 bytes), IO element (variable)
Number of Data 2	1	Must match Number of Data 1
CRC	4	CRC-16-IBM of preceding bytes per Teltonika spec — optional validation in gateway

GPS element (15 bytes)

All multi-byte integers big-endian.

Field	Bytes
Longitude	4 signed
Latitude	4 signed
Altitude	2 unsigned
Angle	2 unsigned
Satellites	1
Speed	2 unsigned

IO element (Codec 8)

After GPS: Event IO ID (1) + N total IO (1), then counts for 1/2/4/8-byte IO sections with id+value pairs. The gateway parses all sections and stores a JSON snapshot in device_positions.raw_io:

• eventIoId, nTotalIo — as sent by the device
• io — map of IO element ID (string) → value (number or string for 64-bit values that do not fit in JS safe integer)
• hints — optional best-effort labels for common Teltonika IDs (ignition, HDOP, GSM signal, …); not a substitute for the numeric io map, which is firmware-specific

Which physical signals appear on which IO IDs is device- and configuration-dependent (FMC920 manual / Configurator). HDOP/PDOP, ignition, DIN, AIN, voltages, etc. are typically carried here when enabled in the device profile.

Codec 8 Extended (0x8E)

Implemented in the gateway alongside Codec 0x08. FMBxxx devices often use Codec 8 Extended in Configurator (“Codec 8 Extended”); the IO block uses 2-byte counts and AVL IDs (and optional NX variable-length values). GPS element is the same 15 bytes as Codec 8.

If the device is set to Extended but the server only accepted 0x08, IMEI handshakes would succeed while no AVL was stored — always match server capability to the device Data protocol setting.

What this codebase does not decode yet

• Codec 16 (0x10), Codec 14 (0x0E) — different layouts; add when required.
• BLE beacon payload — often embedded in IO or extended records depending on firmware.
• Automatic unit conversion — speed is stored as reported (Teltonika Codec 8 commonly uses km/h for speed); analog values are raw as sent.

Acknowledgment (mandatory)

After successfully parsing a Codec 8 packet, the server must send:

4 bytes big-endian unsigned integer = number of AVL records accepted in that packet.

Wrong acknowledgment causes devices to retransmit or stall — treat as protocol-critical.

Test vectors

Hex fixtures live in services/telematics-gateway/src/codec8.test.ts. Extend these with captures from your devices in staging.

Codec 16 (0x10)

Not implemented; add a parser path when devices require it and validate against hardware.