Queclink IoT Integration

Levy Fleets supports Queclink KS/EB TCP devices using the Queclink Air Interface Protocol v91.28 command set and a TCP ingress proxy on port 9003.

Overview

Queclink IoT devices communicate with Levy Fleets through a raw TCP connection to the Queclink proxy, which forwards telemetry to the application API. The integration supports:

• High-precision GPS tracking with multi-GNSS support
• Comprehensive battery monitoring including BMS integration
• ECU control for lock/unlock and speed limiting
• Multi-zone geofencing with entry/exit detection
• Extensive alarm system with customizable triggers
• CAN bus integration for vehicle diagnostics
• OTA configuration for remote device management
• NFC support for card-based operations

Device Configuration

Server Settings

Configure your Queclink device to communicate with Levy Fleets:

Authentication

Queclink devices do not send HTTP headers to Levy Fleets. The device authenticates operationally by connecting to the correct TCP host and port and sending its IMEI in the Queclink payload. The x-api-key header is used only internally by the proxy when forwarding the message to /api/iot/queclink.

Device Identification

Devices are identified by IMEI in the message payload. The system uses intelligent caching for vehicle lookups to optimize performance.

Supported Commands

Location Reports

Status & Information

Battery & Power

ECU (Electronic Control Unit)

Lock Operations

Speed & Throttle

Geofencing

Alarms & Alerts

Motion Detection

Overturn & Recovery

System Events

Configuration & GPS

NFC & External

Advanced Safety Detection

Queclink devices support advanced safety features unique to this integration:

AI Detection & Auxiliary

Devices with AI box integration support intelligent detection:

The AI detection system can identify:

• Helmet usage compliance
• Rider behavior patterns
• Obstacle detection
• Lane departure warnings

Acknowledgments & Buffered

Message Format

Message Structure

Queclink messages follow this format:

+RESP:GTXXX,PROTOCOL,IMEI,...,CHECKSUM$

Components:

• +RESP / +ACK / +BUFF - Message type
• GTXXX - Command code
• PROTOCOL - Protocol version identifier
• IMEI - 15-digit device identifier
• ... - Command-specific data fields
• CHECKSUM$ - Message checksum

Example Messages

Location Report (GTFRI):

+RESP:GTFRI,380701,867648045123456,,0,0,1,1,0.0,0,35.6,-73.9876,40.7580,20251225120000,0310,0260,00F7,36A3,00,0.0,,,99,20251225120001,0065$

Battery Status (GTBAT):

+RESP:GTBAT,380701,867648045123456,,0,85,4200,0,20251225120000,0065$

Lock Success (GTLOC):

+RESP:GTLOC,380701,867648045123456,,0,1,20251225120000,0065$

Telemetry Processing

Location Report Processing

When receiving GTFRI or GTERI messages:

1. Parse coordinates - Extract latitude, longitude, speed, heading
2. Validate GPS fix - Check fix quality indicator
3. Update vehicle - Set current position and last_location_update
4. Store in ride history - If active ride, add to ride_locations
5. Calculate speed - Convert and validate speed reading
6. Apply odometer - Update cumulative distance
7. Trigger zone check - Evaluate geofence boundaries

Battery Data Fields

Battery messages include comprehensive BMS data:

ECU Report Processing

ECU messages (GTECU, GTECS) provide vehicle controller data:

Vehicle Identity Resolution

Caching Strategy

The integration uses efficient caching for vehicle lookups:

1. Check memory cache - Look for IMEI in 1-hour cache
2. Cache hit - Return cached vehicle identity immediately
3. Cache miss - Query database for vehicle by iot_imei
4. Populate cache - Store result for 1 hour
5. Return identity - Provide vehicle UUID and number

Benefits

• Reduced database load - Single query per hour per device
• Faster processing - Sub-millisecond cache lookups
• Consistent identity - Same vehicle ID across all messages

Cache Invalidation

Cache is automatically cleared when:

• IoT devices are bulk imported
• Vehicle IMEI is changed
• Manual cache clear is triggered

Active Ride Integration

Ride Detection

For each incoming message:

1. Query for active/paused rides by vehicle_uuid
2. If not found, check by vehicle_number (legacy support)
3. Backfill legacy rides with proper UUIDs
4. Associate telemetry with ride

Location History

During active rides, location reports:

1. Insert into ride_locations table
2. Include: coordinates, speed, altitude, heading
3. Calculate if vehicle is moving
4. Store raw data for debugging
5. Update ride distance/duration

Zone Enforcement

After location processing:

await enforceZoneActions(admin, {
  vehicleId: vehicleUuid,
  rideId: rideId,
  latitude: location.latitude,
  longitude: location.longitude,
  context: 'iot_queclink'
})

Zone actions include:

• Speed limit application in slow zones
• Throttle disable in no-go zones
• Alert generation for boundary violations

Sending Commands

IoT Password

Configure the Queclink password:

Settings > Vehicles > IoT Passwords > Queclink

Default password: zk600

Dashboard Commands

Command Response Handling

Lock/unlock commands include result processing:

Alarm Handling

Alarm Types

The system processes multiple alarm categories:

Alarm Processing

1. Parse alarm message and extract type
2. Look up associated customer (if ride active)
3. Create alarm record in database
4. Generate notification if warranted
5. Update vehicle status if needed

Customer Notifications

For certain alarms during active rides:

• SOS alerts notify fleet operators immediately
• Crash detection may trigger emergency protocols
• Tamper alerts flag for investigation

Data Storage

Telemetry Table

All messages stored with:

Ride Locations

For active rides, GPS data stored in ride_locations:

Unmatched Devices

Recording Unmatched

When a message arrives from an unknown IMEI:

1. Process message for logging purposes
2. Record in iot_unmatched_devices table
3. Store: IMEI, protocol, source, payload, timestamps
4. Make visible in dashboard "Unmatched Devices"

Resolving Unmatched

To register an unmatched device:

1. Navigate to IoT Devices > Unmatched Devices
2. Click on the unmatched entry
3. Click "Register Device"
4. Fill required fields (subaccount, IoT type)
5. Save - device is now tracked normally

Configuration Options

Report Intervals

Configure how often the device reports:

Power Modes

Geofence Configuration

Configure up to 100 geofence zones per device:

Troubleshooting

No Location Updates

Symptoms: Vehicle position not updating

Solutions:

1. Check device power and battery level
2. Verify GPS antenna has sky view
3. Review FRI interval configuration
4. Check cellular connectivity
5. Examine recent GTHBD, GTFRI, or GTNCN messages for connectivity and fix status

Commands Not Working

Symptoms: Lock/unlock commands not executed

Solutions:

1. Verify IoT password in Settings
2. Check device is online (last seen < 5 min)
3. Review command response (GTLOF/GTULF = failure)
4. Check ECU status for errors
5. Power cycle vehicle if needed

Heartbeat Missing

Symptoms: Device shows offline, no GTHBD

Solutions:

1. Verify server configuration on device
2. Check cellular signal strength
3. Ensure SIM card is active
4. Review for watchdog reboots (GTDOG)
5. Check device isn't in deep sleep

Zone Enforcement Not Working

Symptoms: Speed not limited in slow zones

Solutions:

1. Verify zone is properly configured
2. Check zone type supports enforcement
3. Confirm ride is active
4. Review location accuracy
5. Check ECU can receive speed commands

Buffered Messages

Symptoms: Delayed telemetry arrival

Explanation: When offline, device buffers messages and sends when reconnected. These arrive with +BUFF prefix.

Handling:

• Messages are processed with original timestamps
• Ride statistics are retroactively updated
• Zone enforcement not applied to historical data

API Reference

Endpoint

POST /api/iot/queclink

Headers

These headers apply to the proxy-to-API request, not the raw TCP session from the device.

x-api-key: your-iot-api-key
Content-Type: application/json

Request Body

{
  "imei": "867648045123456",
  "message": "+RESP:GTFRI,380701,867648045123456,...",
  "timestamp": "2025-12-25T12:00:00Z"
}

Response

{
  "success": true,
  "imei": "867648045123456",
  "messageType": "+RESP",
  "command": "GTFRI",
  "processed": true
}

Health Check

GET /api/iot/queclink

Returns service status including:

• Service name and version
• Protocol version
• Route-level handled command counts
• List of all supported commands

---