Segway IoT Integration

Levy Fleets provides native integration with Segway IoT devices using the Segway TCP Telemetry Protocol. This guide covers the complete integration including supported commands, telemetry processing, error handling, and troubleshooting.

Overview

Segway IoT devices communicate with Levy Fleets through a TCP-based protocol that provides:

• Real-time GPS tracking with NMEA-format location data
• Battery monitoring including dual-battery support
• Lock/unlock control with acknowledgment
• Heartbeat monitoring for connectivity status
• Comprehensive vehicle status including speed, odometer, and temperature
• Error and alarm handling with severity classification
• OTA firmware updates via HTTP or FTP
• Mechanical lock support for cable/wheel locks

Device Configuration

Server Settings

Configure your Segway device to communicate with Levy Fleets:

Authentication

Segway devices authenticate via API key. Ensure your deployment includes the correct API key in the x-api-key header for all communications.

Device Identification

Devices are identified by IMEI. The message format includes the device IMEI in the header:

*HBCR,NB,{IMEI},{COMMAND},...#

Supported Commands

Core Operations

Lock/Unlock Protocol

The Segway lock/unlock process involves a key exchange:

Acknowledgment Status Codes

Vehicle Status (S-Series)

Location & Tracking (D-Series)

D0 GPS Format

The D0 command uses NMEA-like format:

*HBCR,NB,{IMEI},D0,,{TIME},A,{LAT},{LAT_DIR},{LON},{LON_DIR},{SPEED},{COURSE},{DATE},{ALT},...#

• TIME: HHMMSS.sss
• A/V: Valid/Invalid fix
• LAT: DDMM.MMMM (degrees and decimal minutes)
• LAT_DIR: N/S
• LON: DDDMM.MMMM
• LON_DIR: E/W
• SPEED: Knots (converted to km/h)
• DATE: DDMMYY

Network Configuration (N-Series)

Device Features (Various)

Mechanical Lock (C-Series)

Supported lock types:

• Type 1: Cable lock
• Type 6: Wheel lock
• Type 8: Helmet/cable combo lock

OTA Updates (U-Series)

Update status codes:

• 0: Started
• 1: Downloading/Connecting
• 2: Download complete
• 3: Installing
• 4: Success
• 5: Failed
• 6: Cancelled

Extended Reports

Telemetry Processing

Heartbeat (H0)

The H0 heartbeat is the primary keep-alive signal and includes:

• Lock Status: 0 (unlocked) or 1 (locked)
• IoT Voltage: Raw voltage in centivolt units
• Signal Strength: Cellular signal level
• Battery Percent: Vehicle battery (0-100%)
• Charging State: 0 (not charging) or 1 (charging)

The system calculates IoT battery percentage from voltage:

IoT Battery % = ((voltage_mv - 3200) / (4200 - 3200)) * 100

Status Report (S6)

Provides comprehensive real-time status:

Extended Status (S8)

Detailed vehicle diagnostics:

Complete Status (P2)

The P2 command returns 30+ fields for complete vehicle diagnostics:

• Device model, firmware, hardware versions
• Battery: percent, voltage, current, temperature
• Motor and controller temperatures
• Speed: current, average, max
• Mileage: total and trip
• GPS: coordinates, speed, signal
• GSM signal strength
• Accelerometer data (X, Y, Z)

Error Code Handling

Error Code Translation

Segway E0 error codes are automatically translated to human-readable messages. The system:

1. Parses the error codes from the E0 message
2. Translates each code using the Segway error code mapping
3. Determines severity level (warning, error, critical)
4. Formats a user-friendly message
5. Updates the vehicle record with error status

Severity Levels

Complete Alarm Code Reference

Levy Fleets translates Segway alarm codes into actionable alerts. Below is the complete reference:

Security Alarms

Safety Alarms

Battery Alarms

Communication Alarms

Hardware Alarms

Alarm Categories

The system categorizes alarms into the following groups:

Email Notifications

For error codes with severity "error" or "critical":

1. System generates an email notification
2. Email is sent to configured fleet managers
3. Includes: vehicle ID, IMEI, error code, description, severity
4. Sent asynchronously to not block telemetry processing

Location Processing

GPS Data Conversion

D0 messages contain NMEA-format coordinates that are converted to decimal degrees:

// Convert DDMM.MMMM to decimal degrees
degrees = floor(coordinate / 100)
minutes = coordinate - (degrees * 100)
decimal = degrees + (minutes / 60)
// Apply direction (negative for S/W)

Ride Location History

During active rides, D0 messages:

1. Extract GPS coordinates and speed
2. Insert into ride_locations table
3. Include altitude and moving status
4. Trigger zone enforcement check
5. Update ride statistics

Zone Enforcement

After processing D0 location during an active ride:

1. Check if coordinates fall within any defined zones
2. Apply speed limits for slow zones
3. Disable throttle for no-go zones
4. Update ride statistics RPC

Vehicle Updates

Fields Updated by Telemetry

Timestamps

Every telemetry update sets:

• updated_at - General update timestamp
• iot_last_update - Last IoT communication
• last_signal_at - Last signal received

Location updates also set:

• last_location_update - Last GPS fix

Sending Commands

IoT Password

Configure the Segway password in Settings:

Settings > Vehicles > IoT Passwords > Segway

Default password: 0000

Available Dashboard Commands

Command Sequence

For lock/unlock:

1. Dashboard sends R0 (request key)
2. Device responds with operation key
3. Dashboard sends L0/L1 with key
4. Device executes and sends acknowledgment
5. Dashboard updates vehicle status

Configuration Reference

Device Settings (S5)

Tracking Settings (D1/D2)

Speed Settings (S1/S4)

Troubleshooting

Device Not Connecting

Symptoms: No heartbeats received, device offline

Solutions:

1. Verify server IP and port configuration
2. Check cellular connectivity and SIM activation
3. Confirm APN settings match carrier requirements
4. Power cycle the vehicle
5. Check for firewall blocking TCP connections

Lock Commands Failing

Symptoms: Lock/unlock returns error status

Check status code:

• Code 2 (Key Invalid): Password mismatch - verify IoT password in Settings
• Code 3 (Ride In Progress): End the current ride first
• Code 4 (ECU Failed): Vehicle controller issue - check E0 errors
• Code 5 (Strategy Declined): Business logic block - check vehicle status

GPS Not Updating

Symptoms: Location stays at same point or shows (0,0)

Solutions:

1. Check for "V" (invalid) fix indicator in D0 messages
2. Ensure vehicle has clear sky view
3. Wait for GPS to acquire satellites (up to 5 min cold start)
4. Verify D1 tracking intervals aren't too long
5. Check if device is in low-power mode

Battery Reading Incorrect

Symptoms: Battery shows 0%, wrong value, or doesn't change

Solutions:

1. For dual-battery vehicles, check both SOC values in S8
2. Verify BMS communication (check battery cycle counts)
3. Some readings require vehicle power on (not just IoT)
4. Check if battery is properly connected

Error Codes Appearing

Symptoms: E0 messages showing error codes

Actions:

1. Note the error code number
2. Check email notifications for translation
3. Review vehicle record for error_message field
4. Critical errors require physical inspection
5. Clear errors by power cycling if appropriate

Data Storage

Telemetry Records

All Segway messages are stored with:

• vehicle_uuid - Associated vehicle
• vehicle_number - Human-readable ID
• imei - Device identifier
• raw_payload - Complete message as JSON
• message_type - Command type (e.g., "H0_HEARTBEAT")
• timestamp - Message timestamp
• idempotency_key - Deduplication key

Idempotency

Each telemetry record includes a generated idempotency key:

{vehicleId}-{imei}-{timestamp}-{messageType}

This prevents duplicate entries from retried messages.

API Reference

Endpoint

POST /api/iot/segway

Headers

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

Request Body

{
  "imei": "867648045123456",
  "cmd": "H0",
  "raw": "*HBCR,NB,867648045123456,H0,1,420,25,85,0#",
  "timestamp": "2025-12-25T12:00:00Z",
  "parsed": {}
}

Response

{
  "success": true,
  "vehicle_number": "LV-001",
  "ride_number": null,
  "command": "H0",
  "cmd": "H0"
}

Health Check

GET /api/iot/segway

Returns:

{
  "service": "Segway TCP Telemetry Ingestion",
  "status": "healthy",
  "timestamp": "2025-12-25T12:00:00Z",
  "supported_commands": ["R0", "L0", "L1", "H0", ...]
}

---