docs/wiki/entities/teltonika.md

title, type, created, updated, sources, tags

title	type	created	updated	sources	tags
Teltonika	entity	2026-04-30	2026-04-30	teltonika-ingestion-architecture teltonika-data-sending-protocols	vendor gps-hardware protocol

Teltonika

Lithuanian GPS hardware vendor. First (and currently only) device family supported by tcp-ingestion. Device families seen include FMB / FMC / FMM / FMU.

Protocol overview

Binary frames, self-describing via codec ID byte. Both TCP and UDP transports are supported by the protocol; our tcp-ingestion implementation is TCP-only by deliberate choice (connection-oriented reliability + persistent session for phase-2-commands).

Codec inventory (canonical, from the official Teltonika wiki):

Codec	Hex ID	Direction	Purpose
8	0x08	device → server	AVL telemetry; 1-byte IO IDs
8 Extended	0x8E	device → server	AVL telemetry; 2-byte IO IDs + variable-length IO (NX section)
16	0x10	device → server	AVL telemetry; 2-byte IO IDs + Generation Type; AVL IDs > 255
12	0x0C	bidirectional	Server commands + device responses (ASCII text)
13	0x0D	device → server	One-way command upload with timestamp
14	0x0E	bidirectional	Like 12, IMEI-addressed; ACK 0x06 / nACK 0x11
15	0x0F	device → server	One-way; FMX6 professional devices via RS232 — out of scope
4	0x04	SMS	24-position daily SMS, bit-field compressed — out of scope

See avl-data-format for the byte-level packet structure across the three telemetry codecs.

Notes on individual codecs

• Codec 8 — baseline AVL format. 8-bit IO element IDs. Older firmware.
• Codec 8 Extended — 16-bit IO IDs and a variable-length IO section (NX) carrying length-prefixed values. Default on modern FMB/FMC/FMM/FMU devices.
• Codec 16 — adds a 1-byte Generation Type field per record (values 0–7: On Exit, On Entrance, On Both, Reserved, Hysteresis, On Change, Eventual, Periodical). Required for AVL IDs > 255 on FMB630/FM63XY firmware ≥ 00.03.xx.
• Codec 13 — Device→Server only. Used only when "Message Timestamp" is enabled in RS232 settings.
• Codec 14 — Device returns nACK (Type 0x11) when the command's IMEI doesn't match. Available from FMB.Ver.03.25.04.Rev.00.
• Codec 15 — FMX6 professional devices only, via RS232 modes (TCP/UDP Ascii/Binary, ±Buffered). Includes both timestamp (4B, seconds) and IMEI (8B HEX). Not applicable to the deployed FMB/FMC/FMM/FMU fleet.

Frame envelope (data codecs)

┌──────────────┬──────────────┬───────────┬─────────────┬─────┐
│ Preamble     │ Data length  │ Codec ID  │ AVL data    │ CRC │
│ 4 bytes (0)  │ 4 bytes      │ 1 byte    │ N bytes     │ 4 B │
└──────────────┴──────────────┴───────────┴─────────────┴─────┘

CRC is CRC-16/IBM (lower 2 bytes carry the value; upper 2 are zero).

Self-describing → model-agnostic parser

The codec ID announces framing; fixed AVL fields (timestamp, lat/lon/alt, angle, satellites, speed) are codec-defined and identical across models for a given codec; only the IO element bag varies between models. The bag is { id → value } pairs the parser reads byte-correctly without knowing what each id means.

A brand-new Teltonika model will:

• Parse correctly at frame and codec layers (envelope, CRC, codec dispatch unchanged).
• Produce a correct position-record (codec-defined fields).
• Carry IO elements through as raw integer keys until a model-aware mapping is added in the processor.

This is the load-bearing property of the protocol-adapter design.

IMEI handshake

Device connects → sends 2-byte length + ASCII IMEI → server responds 0x01 to accept (or 0x00 to reject). Phase 1 always accepts.

ACK protocol

After parsing a data frame, server sends 4-byte big-endian record count. Devices retransmit unacknowledged frames on the next session — this is the protocol-correct way to handle CRC failures (just don't ACK).

Packet size limits

• Minimum AVL record: 45 bytes (all IO elements disabled).
• Maximum AVL record: 255 bytes.
• Maximum AVL packet: 512 bytes for FMB640/FMB641/FMC640/FMM640; 1280 bytes for other devices.

Phase 1 vs Phase 2

Phase	Codecs	Purpose	Status
Phase 1 (now)	8, 8E, 16	Device → server telemetry	In scope
Phase 2 (later)	12, 13, 14	Server → device commands	Reserved

Phase 1 covers essentially the entire deployed Teltonika telemetry fleet. Codec 15 and SMS-based protocols (Codec 4, binary SMS) are out of scope for now. See phase-2-commands for the deferred command-codec design.