Bootstrap LLM-maintained wiki with TRM architecture knowledge
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.
This commit is contained in:
@@ -0,0 +1,86 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user