> For the complete documentation index, see [llms.txt](https://adatrack.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adatrack.gitbook.io/docs/documentation/iot-ingestion/codec8.md).

# Codec8 (Teltonika TCP)

AdaTrack natively ingests telemetry from **Teltonika GPS trackers** (FMB920, FMT100, FMB140, and others) via the built-in **Codec8 plugin**. Devices connect with factory-default TCP server settings — no custom firmware or third-party bridge required.

***

## When to Use Codec8 TCP vs UDP or MQTT

|                           | UDP                           | MQTT                                               | Codec8 TCP                                                |
| ------------------------- | ----------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
| **Device type**           | Custom hardware               | Any MQTT-capable device                            | Teltonika GPS trackers                                    |
| **Authentication**        | HMAC-SHA256 per packet        | Username/password per session                      | IMEI handshake per connection                             |
| **Connection model**      | Stateless, fire-and-forget    | Persistent TCP session                             | Persistent TCP session                                    |
| **Bi-directional**        | No                            | Yes                                                | No                                                        |
| **Multi-record batching** | No                            | No                                                 | Yes — up to 255 AVL records per frame                     |
| **Decoder required**      | Custom JS decoder             | Custom JS decoder                                  | Auto-configured (passthrough)                             |
| **Best for**              | High-frequency custom sensors | Devices needing reliable delivery or two-way comms | Off-the-shelf Teltonika trackers with no firmware changes |

All three transports feed the same decoder, database, geofencing, alerting, and real-time dashboard pipeline. Switching a device between transports does not affect its alert rules, geofences, or dashboard widgets.

***

## Prerequisites

* AdaTrack **Standard tier** license or above (SaaS) — or a self-hosted license with the `plugin:codec8` feature enabled
* The **Codec8** plugin enabled in **Admin > Plugins**

***

## Enabling the Plugin

1. Navigate to **Admin > Plugins**.
2. Find **Codec8** and click **Enable**.
3. Optionally open **Configure** to set a custom TCP listen address (default `0.0.0.0:6868`).
4. The TCP listener starts immediately — no server restart required.

Ensure your firewall allows inbound TCP on port `6868` (or your configured port) from the Teltonika device IP range.

***

## Setting a Device to Codec8 TCP Transport

1. Open the device in **Devices > Edit** (or create a new device).
2. Under **Transport Type**, select **Codec8 TCP**.
3. Enter the **IMEI** of your Teltonika device (15 digits, printed on the device label).
4. Save the device.

When you select Codec8 TCP, AdaTrack automatically:

* Finds or creates a **passthrough decoder profile** for Teltonika devices.
* Pre-selects that profile — no manual decoder setup required.
* Registers the IMEI → device UUID mapping in the plugin's IMEI table.

***

## Connecting a Teltonika Device

Configure your Teltonika device to send data to the AdaTrack TCP server using the standard Teltonika configurator (FOTA Web or Teltonika Configurator desktop app):

| Parameter    | Value                               |
| ------------ | ----------------------------------- |
| **Server**   | Your AdaTrack server hostname or IP |
| **Port**     | `6868` (or your configured port)    |
| **Protocol** | Codec8 TCP (factory default)        |

No credentials are configured on the device side — authentication is based on the IMEI registered in AdaTrack.

### Connection Flow

1. The device opens a TCP connection and sends its IMEI (`[2-byte length][IMEI string]`).
2. AdaTrack looks up the IMEI in the mapping table.
   * If found → replies `0x01` (accepted) and begins receiving data.
   * If not found → replies `0x00` (rejected) and closes the connection.
3. The device sends data packets containing 1–255 AVL records per frame.
4. AdaTrack validates the CRC-16/IBM checksum, parses all AVL records, and replies with a 4-byte ACK containing the count of successfully ingested records.

***

## Telemetry Data

Each AVL record contains a full GPS fix plus IO element values. AdaTrack maps these to standard telemetry columns:

| AVL field     | AdaTrack column                     |
| ------------- | ----------------------------------- |
| `latitude`    | `readings.location` (PostGIS point) |
| `longitude`   | `readings.location` (PostGIS point) |
| `time`        | `readings.time`                     |
| `speed`       | `readings.payload.speed`            |
| `altitude`    | `readings.payload.altitude`         |
| `angle`       | `readings.payload.angle`            |
| `satellites`  | `readings.payload.satellites`       |
| `priority`    | `readings.payload.priority`         |
| `event_io_id` | `readings.payload.event_io_id`      |
| IO elements   | `readings.payload.io.<id>`          |

IO elements (digital inputs, voltage, accelerometer, etc.) are stored in the `payload` JSONB column and are immediately available in the statistics page, dashboard widgets, alert rules, and workflow conditions.

### Example Payload (stored in `readings.payload`)

```json
{
  "speed": 65,
  "altitude": 112,
  "angle": 270,
  "satellites": 12,
  "priority": 0,
  "event_io_id": 239,
  "io": {
    "239": 1,
    "240": 0,
    "21": 3,
    "66": 12450
  }
}
```

Common Teltonika IO IDs: `21` = GSM signal, `66` = external voltage (mV), `239` = ignition, `240` = movement.

***

## Codec8 and Codec8E

The plugin supports both protocol variants automatically — no configuration needed:

| Variant     | Codec ID | IO element ID size    |
| ----------- | -------- | --------------------- |
| **Codec8**  | `0x08`   | 1 byte (IDs 0–255)    |
| **Codec8E** | `0x8E`   | 2 bytes (IDs 0–65535) |

The variant is detected per-frame from the Codec ID byte. A single TCP connection can interleave both variants.

***

## Admin Page

The plugin admin page at **Admin > Plugins > Codec8** provides:

* **Server health panel** — active TCP connections, total packets received, CRC errors, plugin uptime (polled every 10 seconds).
* **IMEI mappings table** — lists all registered IMEI → device UUID mappings across all users, with device name, IMEI, and last-seen timestamp.
* **Bulk management** — admins can add or remove IMEI mappings directly from this page.

Regular users manage their own device's IMEI from the standard **Devices > Edit** form and do not need to visit the admin page.

***

## Monitoring

The IoT Backend Grafana dashboard (provisioned automatically at `make dev`) includes Codec8-specific panels for active TCP connections and per-second AVL record ingestion rate.

***

## Troubleshooting

| Symptom                                      | Likely cause                    | Fix                                                                                              |
| -------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------ |
| Device connects then immediately disconnects | IMEI not registered             | Enter the correct IMEI in **Devices > Edit** and save                                            |
| No telemetry appearing after connection      | Wrong decoder profile           | Re-select **Codec8 TCP** transport in the device form to auto-assign the passthrough profile     |
| CRC errors in admin page                     | Packet corruption or wrong port | Verify the device is configured for Codec8 TCP (not Codec8 UDP) and pointing at the correct port |
| Plugin not available                         | License or tier                 | Ensure your license includes `plugin:codec8` and is Standard or above                            |

***

## License Requirement

The Codec8 plugin requires a **Standard** or **Enterprise** license. It is not available on the Community Edition. See [Licensing](/docs/documentation/administration/licensing.md) for upgrade information.