julian
22b1b069df
Initialize CLAUDE.md schema, index, and log; ingest three architecture sources (system overview, Teltonika ingestion design, official Teltonika data-sending protocols) into 7 entity pages, 8 concept pages, and 3 source pages with wikilink cross-references.
87 lines
4.9 KiB
Markdown
87 lines
4.9 KiB
Markdown
---
|
||
title: Teltonika
|
||
type: entity
|
||
created: 2026-04-30
|
||
updated: 2026-04-30
|
||
sources: [teltonika-ingestion-architecture, teltonika-data-sending-protocols]
|
||
tags: [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|outbound 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.
|