Omni IoT Integration

Omni IoT devices provide vehicle connectivity through the SCOR TCP protocol. This guide covers device setup, available commands, error code interpretation, and configuration options.

Overview

Omni IoT devices communicate using the SCOR protocol, enabling:

• Lock/Unlock - Remote vehicle control
• Location Tracking - GPS position updates
• Status Monitoring - Battery, speed, odometer data
• Error Reporting - Controller malfunction alerts
• Vehicle Settings - Headlight, throttle, speed mode

Protocol Architecture

Levy Fleets Dashboard
         ↓
    SCOR TCP Protocol
         ↓
    Omni IoT Device
         ↓
    UART Interface
         ↓
  Vehicle Controller

The IoT device translates between SCOR (TCP) and UART (Controller), handling the communication protocol for both directions.

Device Setup

Adding an Omni Device

Device Information

SCOR Protocol Commands

Lock and Unlock

The primary commands for vehicle control:

Unlock Vehicle

*SCOS,OM,<IMEI>,S25,1,1,0#

Initiates the R0 → L0 handshake to unlock the scooter.

Lock Vehicle

*SCOS,OM,<IMEI>,S25,1,1,1#

Initiates the R0 → L1 handshake to lock the scooter.

Operation Key Handshake

For manual lock/unlock operations, the SCOR protocol uses a key exchange:

R0 Command Format:

*SCOS,OM,<IMEI>,R0,<OPERATION>,<KEY_VALIDITY>,<USER_ID>,<TIMESTAMP>#

Status and Location

Request Vehicle Status (S6)

*SCOS,OM,<IMEI>,S6#

Returns battery level, lock state, ignition status, speed, and odometer.

Request Location (D0)

*SCOS,OM,<IMEI>,D0#

Returns GPS coordinates with the latest fix.

Heartbeat Configuration

Set Heartbeat Settings (S5)

*SCOS,OM,<IMEI>,S5,0,<S6_UNLOCKED>,<HEARTBEAT_SECONDS>,<S6_INTERVAL>#

Vehicle Settings

Configure Vehicle Settings (S7)

*SCOS,OM,<IMEI>,S7,<HEADLIGHT>,<SPEED_MODE>,<THROTTLE_MODE>,<TAILLIGHT>#

Warning Tones

Trigger Warning (V0)

*SCOS,OM,<IMEI>,V0,<TONE_CODE>#

Firmware and Diagnostics

Get Firmware Version (G0)

*SCOS,OM,<IMEI>,G0#

Returns controller firmware version details.

Request Error Codes (E0)

*SCOS,OM,<IMEI>,E0#

Returns current controller error codes.

Error Codes

Error Severity Levels

Common Error Codes

Error Code Response

When requesting error codes via E0, the response contains:

{
  "code": "4",
  "hex": "0x04",
  "description": "Motor hall issue",
  "severity": "critical",
  "userFriendlyMessage": "Motor sensor malfunction - do not ride",
  "technicalDetails": "Motor hall effect sensor failure detected"
}

Critical Error Actions

When a critical error is detected:

1. Immediately set to Maintenance - Remove from customer view
2. Log the error - Record for maintenance tracking
3. Alert operations - Notify field staff
4. Schedule inspection - Arrange physical check

Telemetry Data

S6 Status Frame

The S6 frame provides comprehensive vehicle status:

D0 Location Frame

The D0 frame provides GPS data:

Data Update Frequency

Dashboard Operations

Sending Commands

From the vehicle detail page:

Viewing Telemetry

The dashboard displays real-time telemetry:

• Battery Level - Current charge percentage
• Lock Status - Locked/Unlocked indicator
• Last Location - GPS coordinates and timestamp
• Speed - Current or last reported speed
• Odometer - Total distance reading
• Error Status - Any active error codes

Command History

View recent commands sent to the device:

1. Go to Vehicle Details → IoT
2. Click Command History
3. Review sent commands and responses
4. Check for any failed commands

Troubleshooting

Device Not Responding

Connection Issues

1. Verify SIM activation - Ensure cellular plan is active
2. Check signal - Device needs adequate coverage
3. Power cycle - May resolve temporary issues
4. Firmware update - Outdated firmware may have bugs

Command Failures

Error Code Alerts

When error codes are reported:

1. Check severity - Critical errors need immediate attention
2. Review history - Is this a recurring issue?
3. Cross-reference - Check for related telemetry anomalies
4. Schedule service - Dispatch technician if needed

Best Practices

Device Configuration

1. Enable S6 during rides - Set S6_UNLOCKED=2 for odometer tracking
2. Set appropriate heartbeat - Balance battery vs. data freshness
3. Monitor error codes - Set up alerts for critical errors
4. Track firmware versions - Keep devices updated

Operational Guidelines

1. Test after installation - Verify lock/unlock works
2. Monitor new devices - Watch for early issues
3. Regular health checks - Review device connectivity
4. Document issues - Track recurring problems

Security Considerations

1. Secure IMEI handling - Don't expose device identifiers
2. Monitor unusual commands - Watch for unauthorized access
3. Audit command logs - Review who sends what commands
4. Update credentials - Rotate any shared secrets

API Reference

Send Command

POST /api/iot/scor
{
  "imei": "123456789012345",
  "command": "*SCOS,OM,123456789012345,S6#"
}

Command Response

{
  "success": true,
  "command_id": "cmd_abc123",
  "sent_at": "2025-01-15T10:30:00Z",
  "response": {
    "received": true,
    "data": { /* telemetry */ }
  }
}

Telemetry Webhook

Telemetry updates can trigger webhooks:

{
  "event": "vehicle.location_updated",
  "data": {
    "vehicle_id": "uuid",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "battery_percent": 85,
    "lock_status": 1
  }
}