Realtime Capabilities

Realtime push can support live fleet screens, alarm panels, and status-driven UI changes without high-frequency polling.

Connection Lifecycle

1. Authenticate through Open API v2 and keep the returned id and access-token.
2. Open the WebSocket channel required by the screen.
3. Send the channel-specific registration message and wait for a success response before using the stream.
4. Decode compressed device status messages when compress is 1.
5. Reconnect with backoff after close/error, then reload REST state to close any message gap.

Device Status WebSocket

The device status WebSocket is the channel used by Monitor live screens to receive current status changes. It is the realtime companion to GET /v2/device-statuses.

wss://openapi.tftiot.com:8443/websocket
ws://<server>:8888/websocket

After the WebSocket opens, send a sign-in frame. In the example below, replace 12345 with the id returned by POST /v2/auth/action:

{
  "event": "signin",
  "token": 12345,
  "md5-password": "MD5_OF_ACCOUNT_PASSWORD",
  "compress": 2,
  "parent_id": 12345,
  "customer_name": ""
}

A successful device status WebSocket sign-in returns:

{
  "event": "signin",
  "error": 0,
  "token": 12345`n}

Snapshot Messages

Device status messages update one device at a time. Use imei as the merge key and compare timestamp fields such as status.date or status.heartbeat_time before overwriting a newer local status.

Expanded snapshot example

{
  "event": "snapshot",
  "data": {
    "id": 301,
    "imei": "860000000000301",
    "model": "TLP2-SFB",
    "valid": 1,
    "device_key": "DEV-301",
    "status": {
      "online": 1,
      "latlng_valid": 1,
      "lat": 22.571,
      "lng": 113.877,
      "speed": 45.6,
      "azimuth": 92,
      "event": 1,
      "date": 1700000000000,
      "acc": 1,
      "mileage": 6200,
      "battery_voltage_percent": 87,
      "network_signal": 4,
      "lock_status": {
        "lock_type": 0,
        "lock_msg_date": 1700000000000,
        "lock_id": "LOCK-001",
        "lat": 22.571,
        "lng": 113.877
      }
    }
  }
}

Sub-lock Realtime Status

When sub-lock accessories are enabled, the device status WebSocket can send subLockInfo. Use this message to refresh sub-lock open/closed/error state without polling. Keep the parent device keyed by imei and merge each sub-lock item by ble_id.

{
  "event": "subLockInfo",
  "data": {
    "id": 301,
    "imei": "860000000000301",
    "model": "TLP2-SFB",
    "sub_lock_list": [
      {
        "ble_id": "A1B2C3D4",
        "date": 1700000000000,
        "latlng_valid": 1,
        "latitude": 22.571,
        "longitude": 113.877,
        "lock_type": 0,
        "rssi": -66,
        "voltage": 4.6,
        "solar_voltage": 4.6,
        "temp": 27,
        "is_low_power": 0,
        "is_open_lock_cover": 0,
        "is_open_back_cover": 0
      }
    ]
  }
}

Compressed subLockInfo

When compress: 1 is returned for subLockInfo, the top-level data string uses comma positions 0=id, 1=imei, 2=model, and 3=sub_lock_list. If a string value needs a literal comma, the comma is escaped as #%@#.

The sub_lock_list value is a nested positional array: multiple sub-lock items are separated by *, and fields inside one item are separated by |.

BLE Sensor Realtime Status

BLE sensor WebSocket messages update child sensor data without polling. Keep the parent tracker keyed by imei. For BLE tire pressure, merge each reading by mac; for BLE temperature/humidity, merge each reading by ble_id. REST status remains the recovery source after reconnect.

bleTire example

{
  "event": "bleTire",
  "data": {
    "id": 301,
    "imei": "860000000000301",
    "model": "TLP2-SFB",
    "ble_tire_pressure_list": [
      {
        "mac": "A1B2C3D4E5F6",
        "date": 1700000000000,
        "voltage": 2.92,
        "airPressure": 245,
        "airTemp": 28,
        "alarm": 0
      }
    ]
  }
}

bleTemp example

{
  "event": "bleTemp",
  "data": {
    "id": 301,
    "imei": "860000000000301",
    "model": "TLP2-SFB",
    "ble_temp_list": [
      {
        "ble_id": "A1B2C3D4",
        "date": 1700000000000,
        "temp": 4.8,
        "humidity": 62,
        "battery_percent": 91,
        "light_intensity": 1,
        "rssi": -63
      }
    ]
  }
}

BLE Sensor Compression

When compress: 1 is returned for bleTire or bleTemp, the top-level data string uses comma positions 0=id, 1=imei, 2=model, and 3=sensor_list. If a string value needs a literal comma, the comma is escaped as #%@#.

The nested sensor list uses the same nested array convention as subLockInfo: multiple sensor items are separated by *, and fields inside one item are separated by |.

Compression Format

compress: 1 is not gzip, deflate, or binary compression. The data value is a comma-delimited positional string. Decode it by index using the snapshot field index table.

function decodeSnapshot(data, fieldIndex, typeMap) {
  const values = String(data).split(",").map(function (value) {
    return value.split("#%@#").join(",");
  });
  const result = {};
  const status = {};

  Object.keys(fieldIndex).forEach(function (indexText) {
    const index = Number(indexText);
    if (index >= values.length || values[index] === "") return;

    const field = fieldIndex[indexText];
    const target = index <= 4 ? result : status;
    let value = values[index];

    if (typeMap.integer[field]) value = parseInt(value, 10);
    else if (typeMap.float[field]) value = parseFloat(value);
    else if (typeMap.boolean[field]) value = value === "true";

    target[field] = value;
  });

  result.status = status;
  return result;
}

Snapshot Field Index

This table is the public positional map for compressed snapshot and onlyUpdateEvent status messages. Fields may be absent, empty, or unchanged depending on device model, firmware, account permissions, and hardware accessories.

Notification Registration

The notification push channel delivers alarm and platform messages. After opening the WebSocket gateway supplied for the enabled account, send this JSON message:

{
  "type": "registUserMessage",
  "access-token": "ACCESS_TOKEN",
  "clientId": "customer-web-operator-01",
  "authSeq": "operator-01:1700000000000"
}

Registration Responses

{
  "type": "wsAuthAck",
  "clientId": "customer-web-operator-01",
  "user_id": 2048
}

{
  "type": "wsAuthReject",
  "msg": "Invalid access-token."
}

Notification Message Types

The customer-facing notification payload is delivered as messagePass. The message can contain an alarm_msg object for alarm events, or a plain message field for system, maintenance, or suggestion messages.

Alarm Message Payload

Alarm push is the most important notification payload for tracking platforms. Use alert_code with the Event / Alarm Code Definitions table in the Core API Reference.

{
  "type": "messagePass",
  "from_id": 1,
  "to_id": 2048,
  "id": 0,
  "date": 1700000009999,
  "alarm_msg": {
    "imei": "860000000000301",
    "device_key": "DEV-301",
    "device_name": "Tracker Alpha",
    "alert_code": 4096,
    "latitude": 22.571,
    "longitude": 113.877,
    "speed": 88,
    "mileage": 6200,
    "extra": "geofence name or event-specific detail"
  }
}

System or Maintenance Message Example

{
  "type": "messagePass",
  "from_id": 0,
  "to_id": -1,
  "id": 301,
  "date": 1700000005678,
  "message": "Scheduled maintenance notice",
  "message_type": 7
}

Implementation Pattern

1. Keep a device map keyed by devices[].imei from GET /v2/devices, then keep current status fresh with GET /v2/device-statuses.
2. Apply snapshot and onlyUpdateEvent messages to the current-status cache only after decoding and timestamp checks.
3. When messagePass.alarm_msg arrives, validate alarm_msg.imei, alert_code, date, and coordinates before updating the UI.
4. Append alarm notifications to the alarm panel and show map markers when coordinates are usable.
5. Use GET /v2/devices or GET /v2/devices/{imei} when the screen needs device metadata, configuration, or a newly assigned device object.
6. Use GET /v2/alarm-points to rebuild the alarm list after reconnect or after the user opens the alarm center.
7. Debounce UI work if many messages arrive in a short period.

Reconnect Recovery

• Reconnect with backoff after a socket close.
• For notification push, refresh the v2 token if registration returns wsAuthReject.
• For device status WebSocket, sign in again after reconnect and wait for event: "signin" with error: 0.
• Use a stable clientId per active notification client to reduce duplicate delivery during reconnects.
• While disconnected, poll GET /v2/device-statuses at a controlled interval for screens that must stay fresh.
• After reconnect, reload current device status with GET /v2/device-statuses and alarm state with GET /v2/alarm-points before trusting the local browser cache.