OKAI IoT Integration

Levy Fleets provides comprehensive support for OKAI ZK Series IoT devices, implementing 100% of the @Track Air Interface Protocol v80.56. This guide covers the complete integration, including supported commands, telemetry processing, and troubleshooting.

Overview

OKAI IoT devices communicate with Levy Fleets through a secure API endpoint that processes telemetry data, location reports, and vehicle control commands. The integration supports:

• Real-time GPS tracking with location history
• Battery monitoring including charging status
• Lock/unlock control with status confirmation
• Speed limiting for zone enforcement
• Alarm and alert handling for security events
• Diagnostic data for maintenance and troubleshooting

Device Configuration

Server Settings

Configure your OKAI device to communicate with Levy Fleets using these settings:

Authentication

OKAI devices authenticate via API key. Ensure your IoT devices are configured with the correct API key in the x-api-key header.

Device Identification

Devices are identified by their IMEI number. When a device connects:

1. The IMEI is extracted from the message
2. The system looks up the vehicle linked to that IMEI
3. Telemetry is associated with the correct vehicle
4. If no vehicle is found, the message is logged as "unmatched"

Supported Commands

Levy Fleets implements complete coverage of the OKAI protocol. Commands are organized into functional categories:

Location & Telemetry

Status & Information

Battery Management

ECU (Electronic Control Unit)

Lock Operations

Motion & Alarms

Speed & Geofencing

System & Network

Power Events

Configuration

NFC & Service

Binding & Bluetooth

Data Collection

Telemetry Processing

Location Reports

When the device sends a location report (GTFRI, GTERI, or GTRTO), Levy Fleets:

1. Parses GPS coordinates (latitude, longitude)
2. Extracts speed, heading, and altitude
3. Updates the vehicle's current position
4. If an active ride exists, stores the location in ride history
5. Triggers zone enforcement if coordinates have changed

Battery Updates

Battery status messages include:

• Battery Level - Percentage (0-100%)
• Battery Voltage - Actual voltage reading
• Charging Status - Whether the vehicle is charging
• IoT Battery - Backup/IoT module battery (if separate)

The system uses battery level to:

• Update vehicle availability (low battery = unavailable)
• Filter vehicles in the dashboard by battery status
• Trigger low battery alerts

Lock Status

Lock state changes update the vehicle record:

Zone Enforcement

After processing location updates during an active ride:

1. The vehicle's coordinates are checked against all zones
2. If the vehicle enters a speed limit zone, a throttle command is sent
3. If the vehicle enters a no-go zone, the throttle is disabled
4. If the vehicle exits the service area, an alert is triggered
5. Ride statistics are recalculated

Vehicle Identity Resolution

OKAI integration uses intelligent caching for vehicle lookups:

Lookup Process

1. Check cache - First, look for IMEI in the vehicle identity cache
2. Cache hit - Return cached vehicle UUID and number
3. Cache miss - Query database for vehicle with matching iot_imei
4. Store in cache - Cache the result for 1 hour
5. Return identity - Provide vehicle UUID for telemetry association

Unmatched Devices

If no vehicle is found for an IMEI:

1. The message is still processed for logging
2. The device is recorded in the "unmatched devices" table
3. Operators can view unmatched devices in the dashboard
4. Once the device is registered, future messages are properly associated

Active Ride Detection

For each incoming message, the system checks for active rides:

1. Query rides with status active or paused
2. Filter by vehicle_uuid matching the identified vehicle
3. If found, associate telemetry with the ride
4. Location data is added to ride history
5. Ride statistics (distance, duration) are updated

Legacy Ride Support

For backwards compatibility with older ride records:

1. If no ride is found by UUID, search by vehicle_number
2. If a legacy ride is found, normalize the identifiers
3. Backfill the vehicle_uuid field for future queries

Sending Commands to Devices

IoT Password

Commands to OKAI devices require the correct password. Set this in:

Settings > Vehicles > IoT Passwords > Okai

Default password: zk200

Available Commands

From the vehicle detail page, you can send:

Command Flow

1. Operator clicks command button in dashboard
2. Command is queued for the device
3. Device receives command on next heartbeat (or immediately if online)
4. Device executes command and sends confirmation
5. Dashboard updates with new status

Troubleshooting

Device Not Reporting Location

Symptoms: Vehicle shows no location or stale location data

Solutions:

1. Check device power - ensure battery is charged
2. Verify GPS antenna - must have clear sky view
3. Check cellular connectivity - device needs network access
4. Review device configuration - verify server settings
5. Check for GPS fix - new installations may need 5-10 minutes

Lock/Unlock Commands Not Working

Symptoms: Commands sent but vehicle doesn't respond

Solutions:

1. Verify IoT password is correct in Settings
2. Confirm device is online (check last seen timestamp)
3. Check for ECU errors in telemetry
4. Verify vehicle has sufficient battery
5. Try power cycling the vehicle

Battery Not Updating

Symptoms: Battery level stays at same value

Solutions:

1. Check reporting interval configuration
2. Verify device is actually reporting (check last seen)
3. Some devices only report battery on specific events
4. Review telemetry logs for GTBAT messages

Geofence Not Triggering

Symptoms: Vehicle enters zone but no enforcement happens

Solutions:

1. Verify zone is properly configured and active
2. Check that zone type supports enforcement
3. Confirm ride is active (zone enforcement only applies during rides)
4. Review location accuracy - GPS may be imprecise
5. Check zone boundaries for gaps

Device Shows as Unmatched

Symptoms: Device reporting but appears in unmatched list

Solutions:

1. Register the device in IoT Devices section
2. Verify IMEI matches exactly (no spaces/dashes)
3. Link device to a vehicle
4. Clear cache if recently added (cache updates hourly)

Data Storage

Telemetry Table

All OKAI messages are stored in the vehicle_telemetry table with:

• vehicle_uuid - Associated vehicle
• imei - Device identifier
• raw_payload - Complete message data as JSON
• message_type - Command type (e.g., "GTFRI")
• timestamp - Message timestamp
• battery_level, speed, latitude, longitude - Extracted values

Retention

Telemetry data is retained according to your plan's data retention policy. Contact support for information about extended retention options.

API Reference

Endpoint

POST /api/iot/okai

Headers

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

Request Body

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

Response

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

Health Check

GET /api/iot/okai

Returns service status and list of supported commands.

---