> 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/queclink.md).

# Queclink (@Track TCP)

AdaTrack natively ingests telemetry from **Queclink GPS trackers** (GV58CEU(CG) and other `@Track Air Interface Protocol`-compatible models) via the built-in **Queclink** plugin. Devices connect over a dedicated TCP port using Queclink's own ASCII `+RESP:GTxxx` protocol — no custom firmware or third-party bridge required.

Queclink devices do **not** speak AdaTrack's core HMAC-signed UDP protocol. Pointing a Queclink tracker at the core ingestion port (`9000`) will not work — it must be configured for the dedicated Queclink TCP port described below.

***

## When to Use Queclink TCP vs UDP, MQTT, or Codec8

|                      | UDP                           | MQTT                                               | Codec8 TCP                       | Queclink TCP                    |
| -------------------- | ----------------------------- | -------------------------------------------------- | -------------------------------- | ------------------------------- |
| **Device type**      | Custom hardware               | Any MQTT-capable device                            | Teltonika GPS trackers           | Queclink GPS trackers           |
| **Authentication**   | HMAC-SHA256 per packet        | Username/password per session                      | IMEI handshake per connection    | IMEI embedded in every message  |
| **Connection model** | Stateless, fire-and-forget    | Persistent TCP session                             | Persistent TCP session           | Persistent TCP session          |
| **Decoder required** | Custom JS decoder             | Custom JS decoder                                  | Auto-configured (passthrough)    | Auto-configured (passthrough)   |
| **Best for**         | High-frequency custom sensors | Devices needing reliable delivery or two-way comms | Off-the-shelf Teltonika trackers | Off-the-shelf Queclink trackers |

All transports feed the same decoder, database, geofencing, alerting, and real-time dashboard pipeline.

***

## Prerequisites

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

***

## Enabling the Plugin

1. Navigate to **Admin > Plugins**.
2. Find **Queclink @Track TCP** and click **Enable**.
3. Optionally open **Configure** to set a custom TCP listen address (default `0.0.0.0:9101`), max concurrent connections, or idle timeout.
4. The TCP listener starts immediately — no server restart required.

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

***

## One-Time Setup: Device Profile and Decoder

Like Codec8, Queclink is configured directly from the **Devices > Add/Edit** form's Transport Type selector — select **Queclink TCP**, enter the device's **IMEI** (15 digits, printed on the device label), and the form auto-assigns (or creates) the passthrough decoder profile for you. The plugin's own admin page (**Admin > Plugins > Queclink**) remains available for bulk management of IMEI mappings and status, but is no longer the only way to register a device.

1. In **Devices > Add**, set **Transport Type** to **Queclink TCP** (disabled until the plugin is enabled under **Admin > Plugins**).
2. Enter the device's **IMEI** in the field that appears — the form fetches the passthrough decoder template (also available at `GET /api/v1/plugins/queclink/decoder-template`) and auto-selects or creates a matching [device profile](/docs/documentation/core-concepts/device-profiles.md).
3. Save the device. The IMEI → device mapping is created automatically; editing a Queclink device later lets you change the IMEI the same way.

The IMEI → device mapping is itself the authorization boundary — there's no device secret involved. A message from an unregistered IMEI is silently dropped and counted as a parse/unmapped event, not rejected with an error (the protocol has no reject frame).

***

## Connecting a Queclink Device

Configure your Queclink device (via SMS, USB, or the manufacturer's config tool) to report to the AdaTrack TCP server in a **TCP** report mode — not UDP:

| Parameter       | Value                                                                           |
| --------------- | ------------------------------------------------------------------------------- |
| **Server**      | Your AdaTrack server hostname or IP                                             |
| **Port**        | `9101` (or your configured port)                                                |
| **Report Mode** | TCP (`AT+GTSRI`/`AT+GTMSI` mode `1`, `2`, `3`, or `7`) — **not** mode `4` (UDP) |

Example configuration command:

```
AT+GTSRI=gv58ceu,,1,,,,adatrack.example.com,9101,,,,,,,0$
```

No credentials are configured on the device side — authentication is based on the IMEI embedded in every message.

***

## Telemetry Data

The plugin supports the three report types Queclink customers most commonly need. Each is mapped to the standard telemetry pipeline via a JSON passthrough payload:

### GTFRI (periodic fix report)

| Field                            | AdaTrack payload key                                              |
| -------------------------------- | ----------------------------------------------------------------- |
| Latitude / Longitude             | `latitude` / `longitude` (→ `readings.location`)                  |
| GPS fix time                     | `time` (→ `readings.time`)                                        |
| Speed                            | `payload.speed`                                                   |
| Azimuth (heading)                | `payload.azimuth`                                                 |
| Altitude                         | `payload.altitude`                                                |
| Mileage                          | `payload.mileage`                                                 |
| Cell tower (MCC/MNC/LAC/Cell ID) | `payload.mcc` / `payload.mnc` / `payload.lac` / `payload.cell_id` |

### GTBAT (battery report)

| Field                | AdaTrack payload key      |
| -------------------- | ------------------------- |
| Battery percent      | `payload.battery_percent` |
| Battery voltage (mV) | `payload.voltage_mv`      |
| Charging flag        | `payload.charging`        |

### GTLOC (lock status report)

| Field       | AdaTrack payload key |
| ----------- | -------------------- |
| Lock status | `payload.locked`     |

GTBAT and GTLOC carry no GPS fix of their own — they use the message's send time for ordering and update the device's last-seen status without moving the map marker.

***

## Admin Page

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

* **Status cards** — active TCP connections, total messages received, records ingested, and parse errors (polled every 10 seconds).
* **Uptime and listen address**, plus a breakdown of messages received by report type (GTFRI / GTBAT / GTLOC).
* **IMEI mappings table** — lists all registered IMEI → device UUID mappings, with add/delete controls.

***

## Troubleshooting

| Symptom                                        | Likely cause                                                                                      | Fix                                                                                                                                            |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Device connects but no telemetry appears       | IMEI not yet mapped                                                                               | Add the IMEI → device UUID mapping via **Devices > Edit** (Transport Type: Queclink TCP) or **Admin > Plugins > Queclink**                     |
| No data at all, device "times out"             | Device still pointed at the core UDP port                                                         | Reconfigure `AT+GTSRI`/`AT+GTMSI` to the Queclink TCP port (`9101`) in a TCP report mode (1/2/3/7), not UDP mode (4)                           |
| Parse errors counter increasing                | Unsupported report type, or a field-layout mismatch for a device variant not yet validated        | Only GTFRI/GTBAT/GTLOC are supported in v1; other report types are logged and dropped, connection stays open                                   |
| Mileage looks wrong or missing on some devices | Firmware variant that sends extra GTFRI fields (e.g. motion status) between mileage and send time | Handled automatically — the extra fields are logged once per connection and don't shift mileage or other fields out of place; no action needed |
| Plugin not available                           | License or tier                                                                                   | Ensure your license includes `plugin:queclink` and is Standard or above                                                                        |

Queued/store-and-forward reports resent by the device after a reconnect (`+BUFF:` frames) and device heartbeat acknowledgments (`+ACK:` frames) are both expected traffic — they're handled automatically and don't count toward parse errors.

***

## License Requirement

The Queclink 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.