IoT Device Troubleshooting
This guide provides comprehensive troubleshooting procedures for IoT device issues in Levy Fleets. Whether you're dealing with connectivity problems, command failures, or telemetry errors, follow these systematic approaches to diagnose and resolve issues.
Important
Before troubleshooting IoT devices, ensure you have physical access to the vehicle if needed, and that you have the appropriate permissions (Admin, Fleet Manager, or Service Technician role).
Quick Diagnostic Checklist
Before diving into specific issues, run through this quick checklist:
| Check | How to Verify | Action if Failed |
|---|---|---|
| Device Online | IoT page shows green indicator | See "Device Shows Offline" section |
| Recent Signal | Last seen within 5 minutes | Check cellular/power |
| Correct IMEI | Vehicle IMEI matches IoT device | Re-link if mismatched |
| Correct Password | Settings > Vehicles shows password | Update to correct password |
| Battery Level | Both vehicle and IoT battery | Charge if low |
Device Shows Offline
Symptoms
- Device status indicator is gray/red
- "Last Seen" timestamp is hours or days old
- Vehicle not responding to any commands
- No telemetry data being received
Possible Causes
| Cause | Likelihood | Description |
|---|---|---|
| Dead IoT Battery | High | The IoT module's internal battery is depleted |
| Dead Vehicle Battery | High | Main vehicle battery too low to power IoT |
| No Cellular Coverage | Medium | Device in area with poor/no signal |
| SIM Card Issue | Medium | SIM deactivated, expired, or damaged |
| Hardware Failure | Low | IoT module physically damaged |
| Incorrect Server Config | Low | Device pointing to wrong server |
Solutions
Check Last Known Location
On the IoT device detail page, note the last GPS coordinates. Determine if the vehicle is in an area with known poor coverage (basement, underground parking, rural area).
Check Vehicle Battery
If you can access the vehicle, check the main battery level. If under 10%, the IoT module may have shut down to preserve power. Charge the vehicle.
Power Cycle the Vehicle
Turn the vehicle completely off, wait 30 seconds, then turn it back on. This restarts the IoT module.
Check IoT Module Power
Verify the IoT module is receiving power. Look for indicator LEDs on the device. No lights = no power.
Check SIM Card
Contact your IoT provider to verify the SIM card is active and has data. SIMs can be deactivated for non-payment or inactivity.
Move Vehicle to Better Coverage
If in a low-signal area, move the vehicle outside or to an area with known good coverage and wait 5 minutes.
When to Escalate
If the device remains offline after verifying power and coverage, the IoT module may need replacement. Contact support with:
- Device IMEI
- Last known good communication date
- Physical inspection results
- Steps already attempted
Commands Not Being Received
Symptoms
- Lock/Unlock commands fail silently
- "Command sent" appears but nothing happens
- Vehicle doesn't respond to sound/beep commands
- Commands timeout after 30 seconds
Possible Causes
| Cause | Likelihood | Description |
|---|---|---|
| Incorrect Password | High | IoT password in settings doesn't match device |
| Device Offline | High | Can't receive commands when offline |
| Command Queue Backup | Medium | Too many pending commands |
| Protocol Mismatch | Low | Wrong IoT type selected for device |
Solutions
Verify Device is Online
Check the IoT device page to confirm the device shows online status. Commands cannot be sent to offline devices.
Verify IoT Password
Go to Settings > Vehicles and verify the password for your device type:
| Device Type | Default Password |
|---|---|
| Okai | zk200 |
| Queclink | ks600 |
| Segway | 0000 |
| Omni | 0000 |
| ZIMO | (varies) |
Send Test Command
Try sending a STATUS or HEARTBEAT command first. These don't change vehicle state and help test communication.
Check Telemetry Feed
On the vehicle detail page, expand IoT Commands and watch the telemetry feed. Look for ACK (acknowledgment) or error responses.
Wait for Response
Some devices, especially SMS-based ones (Okai, Queclink), can take 30-60 seconds to respond. Don't send multiple commands in quick succession.
Verify IoT Type
Confirm the device's IoT Type matches the actual hardware. A Queclink device configured as "Okai" won't receive commands correctly.
Device-Specific Command Issues
Segway TCP Devices
- Commands sent via direct TCP connection
- Response typically within 5 seconds
- If failing, check that device IP/port is reachable
Okai/Queclink (SMS-based)
- Commands sent via SMS to device SIM
- Response can take 30-60 seconds
- Verify SIM has SMS capability enabled
- Check if SMS quota is exceeded
ZIMO MQTT Devices
- Commands sent via MQTT broker
- Near real-time response expected
- Verify MQTT broker connectivity
- Check device subscription to command topic
Omni SCOR Devices
- Real-time bidirectional protocol
- Immediate response expected
- No password required for most commands
- Check WebSocket connection status
Telemetry Data Not Updating
Symptoms
- Battery level hasn't changed in hours
- Location showing old coordinates
- Odometer reading is stale
- "Last Updated" timestamp not recent
Possible Causes
| Cause | Likelihood | Description |
|---|---|---|
| Reporting Interval | High | Device configured for infrequent updates |
| Device Sleeping | High | Device in low-power mode |
| GPS Signal Loss | Medium | Can't acquire satellite fix |
| Partial Connectivity | Medium | Heartbeat works but data packets fail |
| Server Processing Delay | Low | Data received but not yet processed |
Solutions
Check Heartbeat Status
Even if data isn't updating, the device should send heartbeats. Check if heartbeats are being received (visible in telemetry feed).
Request Status Update
Send a STATUS command to force the device to report current values.
Check GPS Quality
Review recent telemetry for GPS accuracy values. Indoor/underground vehicles may have poor GPS.
Review Reporting Configuration
Some devices are configured to report less frequently when stationary. This is normal behavior to conserve power.
Check Data Pipeline
If many devices are affected, there may be a system-wide processing delay. Check system status or contact support.
Understanding Reporting Intervals
| Device State | Typical Interval | Notes |
|---|---|---|
| In Ride | 10-30 seconds | Frequent updates for tracking |
| Idle (Available) | 5-15 minutes | Conserves battery |
| Sleeping | 1-4 hours | Minimal power consumption |
| Charging | 1-5 minutes | More frequent during charge |
Incorrect Location Data
Symptoms
- Vehicle shows in wrong location on map
- Location jumps erratically
- GPS coordinates don't match actual position
- Vehicle appears in impossible locations (ocean, other city)
Possible Causes
| Cause | Likelihood | Description |
|---|---|---|
| Poor GPS Signal | High | Indoor, underground, or urban canyon |
| GPS Warm-up | High | Device just powered on needs satellite fix |
| Cached Location | Medium | Device reporting last known good location |
| Hardware Issue | Low | GPS antenna damaged or disconnected |
Solutions
Check Location Timestamp
On the vehicle detail page, check when the location was last updated. Old timestamps indicate stale data.
Review Location History
Look at the GPS trail. Scattered points indicate poor signal; smooth trails indicate good tracking.
Move Vehicle Outside
If the vehicle is indoors or underground, GPS will be unreliable. Move to open sky area.
Wait for GPS Fix
After power cycling, devices need 2-5 minutes to acquire a good GPS fix. Wait before trusting location.
Check GPS Accuracy Value
Some devices report GPS accuracy/HDOP. Values over 10 indicate poor accuracy.
Inspect GPS Antenna
If consistently inaccurate, the GPS antenna may be damaged or obstructed. Check physical installation.
GPS Accuracy by Environment
| Environment | Expected Accuracy | Notes |
|---|---|---|
| Open sky | 2-5 meters | Best case |
| Urban area | 5-15 meters | Building reflections |
| Under tree cover | 10-30 meters | Signal attenuation |
| Near buildings | 15-50 meters | Multipath errors |
| Underground/Indoor | 50+ meters or none | GPS typically unusable |
Battery Readings Incorrect
Symptoms
- Battery shows 100% but vehicle doesn't run
- Battery jumps from high to low suddenly
- Battery reading stuck at one value
- Vehicle Battery vs IoT Battery mismatch
Possible Causes
| Cause | Likelihood | Description |
|---|---|---|
| Calibration Issue | High | Battery gauge needs recalibration |
| Different Batteries | High | Vehicle and IoT have separate batteries |
| Communication Delay | Medium | Reading is cached/old |
| BMS Issue | Medium | Battery Management System reporting incorrectly |
| Damaged Battery | Low | Battery cells damaged |
Solutions
Understand the Two Batteries
Most vehicles have TWO batteries:
- Vehicle Battery: Powers the motor (what riders care about)
- IoT Battery: Powers the tracking module (what keeps device online)
These are reported separately and drain independently.
Request Fresh Reading
Send a STATUS command to get current battery values.
Compare to Actual State
If possible, check the vehicle's physical battery indicator or dashboard display.
Full Charge Cycle
Charge the battery to 100%, then run until empty. This recalibrates the gauge.
Check Charging Status
Verify the "Charging" indicator matches whether the vehicle is actually plugged in.
Battery Reporting by Device Type
| Device Type | Reports Vehicle Battery | Reports IoT Battery | Notes |
|---|---|---|---|
| Segway | Yes | Yes | Both values reliable |
| Okai | Yes | Sometimes | IoT battery may not be reported |
| Queclink | Yes | Yes | IoT shown as "internal" |
| ZIMO | Yes | Yes | Both typically accurate |
| Omni | Yes | No | Only vehicle battery shown |
Lock/Unlock State Mismatch
Symptoms
- Dashboard shows locked but vehicle is unlocked
- Sent unlock command but still shows locked
- State toggles unexpectedly
- Customer reports vehicle locked during ride
Possible Causes
| Cause | Likelihood | Description |
|---|---|---|
| Status Sync Delay | High | Command worked but status not updated |
| Command Failed Silently | Medium | Command didn't reach device |
| Physical Override | Low | Mechanical lock was manually engaged |
| Hardware Failure | Low | Lock mechanism damaged |
Solutions
Wait for Status Update
After sending lock/unlock, wait 30-60 seconds for status to update. Force refresh the page.
Request Status
Send a STATUS command to get the current actual lock state from the device.
Check Telemetry Feed
Look for the command acknowledgment in the telemetry feed. Check for error codes.
Try Command Again
If status didn't update, send the command again. Some commands require multiple attempts in poor coverage.
Physical Inspection
If commands consistently fail, physically inspect the lock mechanism for damage or obstruction.
Device Not Linking to Vehicle
Symptoms
- Created IoT device but can't link to vehicle
- Vehicle shows "No IoT Device"
- IMEI mismatch errors
- Telemetry coming in but not associated with vehicle
Possible Causes
| Cause | Likelihood | Description |
|---|---|---|
| IMEI Mismatch | High | IMEI entered incorrectly |
| Device in Wrong Subaccount | Medium | Device and vehicle in different subaccounts |
| IMEI Already Linked | Medium | Another vehicle using the same IMEI |
| Device Not Created | Medium | Device not in IoT registry |
Solutions
Verify IMEI Format
IMEI should be exactly 15 digits. No spaces, dashes, or letters. Check for typos.
Check Both Records
Verify the IMEI on both the IoT device record AND the vehicle's iot_imei field match exactly.
Check Subaccounts
Ensure the IoT device and vehicle are in the same subaccount.
Check for Duplicate Links
Search for the IMEI across all vehicles. Another vehicle may already be linked.
Check Unmatched Devices
If device is communicating but not linked, it may appear in the "Unmatched Devices" list.
Unmatched Devices Appearing
Symptoms
- Devices in "Unmatched" list
- Unknown IMEIs communicating with server
- Device count higher than expected
Possible Causes
| Cause | Likelihood | Description |
|---|---|---|
| New Devices | High | Devices installed but not registered |
| IMEI Typo | Medium | Registered with wrong IMEI |
| Old Devices | Low | Devices from decommissioned vehicles |
| Wrong Server | Low | Devices from another fleet pointing here |
Solutions
Identify the Device
Check the IMEI against your device inventory. Match to a known physical device.
Register New Devices
If it's a legitimate new device, click "Register" to add it to your fleet.
Correct IMEI Errors
If an existing device was registered with wrong IMEI, update the IoT device record.
Ignore/Delete Old Devices
Unmatched devices from old equipment can be ignored. They'll stop appearing if the device is decommissioned.
Protocol-Specific Troubleshooting
Segway TCP Issues
Common Problems:
- Connection timeout
- Authentication failures
- Firmware incompatibility
Solutions:
- Verify device is running compatible firmware version
- Check TCP port connectivity (typically port 8084)
- Verify Segway IoT password in settings
- Check for firewall blocking TCP connections
- Contact Segway support for firmware updates
Okai/Queclink SMS Issues
Common Problems:
- SMS not being delivered
- Delayed responses (over 60 seconds)
- Commands rejected
Solutions:
- Verify SIM has SMS capability enabled
- Check SIM balance/quota for outbound SMS
- Verify correct phone number in device configuration
- Check for carrier-level SMS blocking
- Try resending command during low-traffic hours
ZIMO MQTT Issues
Common Problems:
- MQTT connection drops
- Messages not being published
- Subscribe failures
Solutions:
- Verify MQTT broker credentials
- Check broker status and connectivity
- Verify topic subscriptions are correct
- Check for QoS mismatches
- Review MQTT client logs for errors
Omni SCOR Issues
Common Problems:
- WebSocket disconnections
- Real-time updates not working
- Bi-directional communication failures
Solutions:
- Check WebSocket connection status
- Verify SCOR protocol version compatibility
- Check for proxy/firewall interference
- Review connection logs for error codes
- Restart the IoT service if needed
Error Codes Reference
Common IoT Error Codes
| Code | Meaning | Solution |
|---|---|---|
| E01 | Authentication failed | Check device password |
| E02 | Command timeout | Retry command |
| E03 | Device busy | Wait 30 seconds, retry |
| E04 | Invalid command | Check command syntax |
| E05 | Low battery | Charge before retrying |
| E06 | GPS unavailable | Move to open sky |
| E07 | Lock mechanism fault | Physical inspection needed |
| E08 | Communication error | Check connectivity |
| E09 | Firmware error | May need update |
| E10 | Hardware fault | Device replacement needed |
Interpreting Telemetry Error Codes
When viewing telemetry, look for:
- ACK - Command acknowledged successfully
- NAK - Command rejected (check error code)
- TIMEOUT - No response from device
- ERROR_XXX - Device-reported error code
Preventive Maintenance
Daily Checks
- Review offline device count
- Check for devices with old last-seen times
- Review unmatched devices list
Weekly Checks
- Audit device battery levels
- Review command success rates
- Check for devices stuck in wrong state
Monthly Checks
- Review firmware versions
- Audit device-vehicle linking
- Check SIM card statuses
- Review device error patterns
When to Replace Devices
Consider device replacement when:
- Consistently offline for more than 7 days despite troubleshooting
- Command success rate below 50% consistently
- Physical damage visible (water ingress, antenna damage)
- Firmware cannot be updated to required version
- Battery won't hold charge (IoT internal battery)
- GPS never acquires fix even in open areas
Support Resources
For device-specific support:
- Segway: Contact Segway IoT support team
- Okai: Contact Okai technical support
- Queclink: Contact Queclink customer service
- General Issues: Email support@levyelectric.com with device IMEI and issue description