IoT Device Import

When adding multiple IoT devices to your fleet, the CSV import feature saves significant time compared to adding devices individually. This guide explains how to prepare your CSV file and successfully import devices in bulk.

Import Process Overview

The IoT device import process follows these steps:

1. Prepare your CSV file with device data
2. Upload the file through the IoT Devices page
3. System validates the data and shows any errors
4. Data is staged in a temporary import table
5. Import function executes to create/update device records
6. Vehicle identity cache is cleared to ensure proper linking

CSV File Requirements

File Format

• Format: CSV (Comma-Separated Values)
• Delimiter: Semicolon (;) - NOT comma
• Encoding: UTF-8 recommended
• Headers: First row must contain column headers
• Quotes: Use double quotes (") for text fields containing special characters

Required Columns

Optional Columns

Valid IoT Types

The iot_type field must be one of these values:

Preparing Your CSV File

Using Microsoft Excel

1. Open a new Excel workbook
2. Enter column headers in row 1
3. Add your device data starting from row 2
4. Save As and choose "CSV (Comma delimited)"
5. Open the saved CSV file in a text editor
6. Find and Replace all commas (,) with semicolons (;)
7. Save the file

Using Google Sheets

1. Create a new spreadsheet
2. Enter column headers in row 1
3. Add your device data starting from row 2
4. Go to File > Download > Comma-separated values (.csv)
5. Open the downloaded file in a text editor
6. Find and Replace all commas (,) with semicolons (;)
7. Save the file

Download CSV Template

Instead of creating a file from scratch, you can download a pre-formatted template:

1. Go to IoT Devices in the sidebar
2. Click Import to open the import dialog
3. Click Download Template
4. The template CSV includes all column headers and example data
5. Replace the example data with your actual device information
6. Save and upload the modified file

Example CSV Content

imei;iccid;iot_type;iot_model;owner_name;notes
867648045123456;8901260123456789012;queclink;GL530M;Operations Team;Fleet A
867648045123457;8901260123456789013;queclink;GL530M;Operations Team;Fleet A
867648045123458;8901260123456789014;segway;;Operations Team;Fleet B
867648045123459;8901260123456789015;okai;ZK200;;New shipment

Uploading the CSV File

Step-by-Step Upload

What Happens During Import

Staging Process

1. The system clears the staging table (iot_devices_import)
2. Your CSV data is inserted into the staging table
3. Basic validation is performed on required fields

Import Function

The import_iot_devices() database function:

1. Validates each row in the staging table
2. Creates new device records for new IMEIs
3. Updates existing records if IMEI already exists
4. Sets default values for missing fields:
   • online_status: false
   • activation_status: pending
   • total_rides: 0
   • trips_current_month: 0
   • current_month_revenue: 0
   • previous_month_revenue: 0
   • iot_added_on: current timestamp

Cache Clearing

After a successful import, the vehicle identity cache is automatically cleared. This ensures:

• New IMEI-to-vehicle mappings are recognized
• Updated device information takes effect immediately
• No stale data affects telemetry processing

Handling Import Errors

Common Validation Errors

File Format Errors

Resolving Errors

1. Download the error report if available
2. Fix issues in your original spreadsheet
3. Re-export with correct format
4. Upload the corrected file

Updating Existing Devices

If you import a CSV containing IMEIs that already exist in the system:

• Existing devices are updated with new values from the CSV
• Empty cells don't overwrite existing data
• The iot_added_on date is preserved for existing devices

This allows you to use CSV import for both initial setup and bulk updates.

Linking Devices to Vehicles After Import

After importing IoT devices, you'll typically want to link them to vehicles. There are several approaches:

Option 1: Import Vehicles with IMEIs

When importing vehicles via CSV, include the iot_imei column. The system will automatically link devices to vehicles based on matching IMEI values.

Option 2: Manual Linking

1. Go to Vehicles
2. Click on a vehicle
3. Edit and add the IMEI in the IoT IMEI field
4. Save the vehicle

Option 3: Link from IoT Devices Page

1. Go to IoT Devices
2. Click on an unlinked device
3. Click Link to Vehicle
4. Select the target vehicle
5. Confirm the link

Best Practices

Before Import

• Validate IMEIs - Ensure all 15-digit IMEIs are correct
• Check for duplicates - Remove any duplicate IMEI rows
• Verify subaccounts - Confirm subaccount UUIDs exist
• Test with small batch - Try importing 5-10 devices first

File Preparation

• Use consistent formatting - Same date format, case, etc.
• Remove empty rows - Delete any blank rows at the end
• Save a backup - Keep your original spreadsheet
• Document your mappings - Note which columns you used

After Import

• Verify count - Check total devices matches expected
• Spot check records - Open a few devices to verify data
• Test connectivity - Confirm devices can communicate
• Link to vehicles - Associate devices with fleet vehicles

Programmatic Import

For advanced users, IoT devices can also be imported via the API:

API Endpoint

POST /api/iot-devices/import

Request Format

{
  "csv_data": [
    {
      "imei": "867648045123456",
      "iccid": "8901260123456789012",
      "iot_type": "queclink",
      "iot_model": "GL530M",
      "notes": "Fleet A"
    },
    {
      "imei": "867648045123457",
      "iccid": "8901260123456789013",
      "iot_type": "queclink"
    }
  ]
}

Response

{
  "success": true,
  "message": "Successfully imported IoT devices",
  "total_count": 150
}

Linking Device to Vehicle via API

You can also link an IoT device to a vehicle programmatically:

PUT /api/iot-devices/import

Request Body

{
  "imei": "867648045123456",
  "vehicle_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response

{
  "success": true,
  "message": "IoT device linked to vehicle successfully",
  "vehicle_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "imei": "867648045123456"
}

This endpoint:

1. Updates the vehicle's iot_imei field with the provided IMEI
2. Clears the vehicle identity cache to ensure immediate recognition
3. Returns confirmation of the link

Troubleshooting

Import Succeeds But Devices Don't Appear

1. Check the subaccount filter - you may be viewing a different subaccount
2. Refresh the page to ensure latest data is loaded
3. Search by IMEI to locate specific devices

Devices Imported But Not Linked to Vehicles

1. Verify the IMEI matches exactly (no spaces or dashes)
2. Check that vehicles exist with matching iot_imei values
3. Try unlinking and relinking manually

Telemetry Not Arriving After Import

1. Confirm the device is powered and has connectivity
2. Verify server settings on the device match your endpoint
3. Check the "Unmatched Devices" list for any issues
4. Wait 5-10 minutes for the first heartbeat

---