---
# System prepended metadata

title: Converto Json Specification
tags: [modern system]

---



###### tags: `modern system`


# Converto Json Specification

## Change Log
| Version No. | Date | Description | Author |
| :---------: | :--: | :---------- | :----: |
| 1.9.0 | 2020-04-07 | Update event fuel_stats | Neil |
| 1.8.0 | 2020-03-24 | Update padelPattern report(L3 report) <br/> Update vehicle_speeding(value add 118) <br/> Update eco_start(value add 116)<br/> Update non_eco_start(value add 117)| Neil |
| 1.7.0 | 2020-02-25 | Update padelPattern report | Ruby |
| 1.6.0 | 2020-01-16 | Add new event device_system_info| Neil |
| 1.5.0 | 2020-01-13 | Add new event cellular_loss | Greg |
| 1.4.0 | 2020-01-09 | Sync James ver. | Greg & Ruby |
| 1.3.0 | N/A | <ul><li>Update the following reports</li><ul><li>vehicle_DTC_clear</li></ul></ul> | Tina |
| 1.2.0 | 2019-12-03 | <ul><li>Create new reports <ul><li>frequent_harsh</li><li>wifi_status</li><li>vehicle_impact</li></ul><li>Update the following reports<ul><li>vehicle_change</li><li>device_firmware_change</li><li>device_config_change</li></ul></li></li><li>Change vin_change to vehicle_change</li></ul> | Tina |
| 1.1.0 | 2019-11-22 | <ul><li>Update during_trip report</li><li>Create trip_restart report </li></ul> | James |
| 1.0.0 | 2019-11-12 | The first release | Greg |

## Quick Guide
- Events
	- [engine_start](#engine_start)
	- [engine_off](#engine_off)
	- [long_idle_end](#long_idle_end)
	- [unexpected_engine_start](#unexpected_engine_start)
	- [trip_restart](#trip_restart)
	- [during_trip](#during_trip)
	- [fuel_stats](#fuel_stats)
	- [tow_start](#tow_start)
	- [tow_end](#tow_end)
	- [keep_alive](#keep_alive)
	- [SimpleVehicleEvents](#SimpleVehicleEvents)
	- [vehicle_DTC](#vehicle_DTC)
	- [vehicle_DTC_clear](#vehicle_DTC_clear)
	- [vehicle_impact](#vehicle_impact)
	- [DriverEvents](#DriverEvents)
	    - [vehicle_idle](#DriverEvents)
        - [vehicle_speeding](#DriverEvents)
        - [harsh_RPM](#DriverEvents)
        - [harsh_acc](#DriverEvents)
        - [harsh_brake](#DriverEvents)
        - [harsh_turn](#DriverEvents)
        - [eco_start](#DriverEvents)
        - [eco_stop](#DriverEvents)
        - [non_eco_start](#DriverEvents)
        - [non_eco_stop](#DriverEvents)
        - [frequent_harsh](#DriverEvents)
	- [driver_pedal_pattern](#driver_pedal_pattern)
	- [DeviceEvents](#DeviceEvents)
	    - [gps_quality](#gps_quality)
	    - [cellular_service](#cellular_service)
	    - [cellular_connection](#cellular_connection)
	    - [wifi_station_list](#wifi_station_list)
	    - [wifi_site_survey](#wifi_site_survey)
	    - [wifi_status](#wifi_status)
	    - [device_system](#device_system)
	    - [device_firmware_change](#device_firmware_change)
	    - [device_config_change](#device_config_change)
	    - [device_reboot](#device_reboot)
	    - [vehicle_change](#vehicle_change)
	    - [calibration_status](#calibration_status)
	    - [ble_data](#ble_data)
    - [cellular_loss](#cellular_loss)
    - [device_system_info](#device_system_info)


### engine_start
:::info
derived from simple event engine start
**sent to Tripo**
once getting this, Tripo has to archive curVehicleStatus as Park object and refresh curVehicleStatus as a Trip object
:::
```jsonld
{
     "eventType": "engine_start",
     "dateTime": int, // OBD report time from common hedaer
     "IMEI": string,
     "longitude": double,
     "latitude": double,
     "accuracy": int,
     "gpsSpeed": int,
     "heading": int
 }

```

### engine_off
:::info
derived from simple event engine off
**sent to Tripo**
once getting this, Tripo has to archive curVehicleStatus as Trip object and refresh curVehicleStatus as a Park object
:::
```jsonld
{
    "eventType": "engine_off",
    "dateTime": int,
    "IMEI": string,
    "longitude": double,
    "latitude": double,
    "accuracy": int,
    "gpsSpeed": int,
    "heading": int
}
```

### long_idle_end
:::info
derived from excessive long idle end value added event
**sent to Alerto and Drivo**
vehicle idle is ended by engine off or continuing the trip (keep moving on)
if engine off, a simple event “engine_off” will be sent after this event
long_idle_end is passed to Alerto to notify the end of long idle
long_idle_end is passed to Drivo to calculate eco driving score
:::
```jsonld
{
    "eventType": "long_idle",
    "dateTime": int,
    "IMEI": string,
    "longitude": double,
    "latitude": double,
    "accuracy": int, 
    "idleEndReason": string, // “engine_off” or “moving_on”
    "idleTime": int // total idle seconds, from the start to the end
}
```

### unexpected_engine_start
:::info
derived from simple event engine start
**sent to Tripo and Alerto**
once getting this, Tripo has to archive curVehicleStatus as Park object
and refresh curVehicleStatus as a Trip object
Alerto will handle this as a critical alert (suspicion vehicle theft)
:::
```jsonld
{
    "eventType": "unexpected_engine_start",
    "dateTime": int,
    "IMEI": string,
    "longitude": double,
    "latitude": double,
    "accuracy": int,
    "gpsSpeed" : int,
    "heading" : int
}
```

### trip_restart
:::info
derived from simple event trip restart
**sent to Tripo
once getting this, Tripo has to archive curVehicleStatus as Long Idle End object and refresh curVehicleStatus as a Long Idle Start object 
:::
```jsonld
{
    "eventType": "trip_restart",
    "dateTime": int,
    "IMEI": string,
    "longitude": double,
    "latitude": double,
    "accuracy": int,
    "gpsSpeed" : int,
    "heading" : int
}
```

### during_trip
:::info
derived from L1 or L2 report
**sent to Tripo, Vehicol and Drivo**
this report will contain either L1 or L2 report data
// leave those without data as null
// Tripo has to create a tripPoint and add it to the trip.route
// when the vehicle change heading direction for more than 70 degrees
// Vehicol dashboards these info as realtime OBDII data
:::
```jsonld
{
    "eventType": "during_trip",
    "reportType": int, // 1: Level one, 2: Level two
    "dateTime": int,
    "IMEI": string,
    "longitude": double,
    "latitude": double,
    "accuracy": int, 
    "maxGpsSpeed": int,
    "avgGpsSpeed": int,
    "heading": int,
    "avgSpeed": int,
    "maxSpeed": int,
    "minSpeed": int,
    "avgAcc": int,
    "maxAcc": int,
    "avgRPM": int,
    "maxRPM": int,
    "batVoltage": double,
    "coolantTemp": int,
    "engineOilTemp": int,
    "engineLoad": int,
    "amibientTemp": int,
    "inTakeAirTemp": int,
    "massiveAirFlow": int, // this could be used to calculated fuel consumption
    "manifoldAirPressure": int,
    "curSpeed": int,
    "odoMeter": int,
    "throttlePosition": int,
    // the following info are original data from OBDII device
    // Vehicol is calculating fuel consumption from massiveAirFlow
    // we shall differentiate the original data from the calculated
    // "instantaneousFuelRate": int,
    "fuelRate": int, // optional
    "fuelEfficiency": int,
    "fuelLevel": int
}
```

### fuel_stats 
:::info
derived from L3 report
**sent to Vehicol**
:::
```jsonld
{
    "eventType": "fuel_stats",
    "dateTime": int,
    "IMEI": string,
    "longitude": string,
    "latitude": string,
    "accuracy": string,
    "gpsSpeed" : int,
    "heading" : int,

    // to measure idle fuel and hybrid car distance bonus
    "observePeriod": int,   // unit: seconds
    "idleAirUsed": int,     // g, hybrid off the engine when idle
    "distanceZeroRPM": int, // distance run when fossil engine is off, RPM=0
    "zeroRPMPeriod": int,
    "idlePeriod": int,

    // to measure the fuel vs speed to find out eco speed range
    "avgSpeed" : int,
    "airUsed" : int,
    "duration" : int  // to calculate fuel rate km/liter at speed of km/h
                     // maintain a table in the vehicle object to characterize 
                     // the car's fuel performance
}
```

### tow_start
:::info
derived from simple vehicle event
**sent to Tripo**

:::
```jsonld
{
  "eventType": "tow_start",
  "dateTime": int,
  "IMEI": string,
  "longitude": string,
  "latitude": string,
  "accuracy": string,
  "gpsSpeed" : number,
  "heading" : number
}
```

### tow_end
:::info
derived from simple vehicle event
**sent to Tripo**
:::
```jsonld
{
  "eventType": "tow_end",
  "dateTime": int,
  "IMEI": string,
  "longitude": string,
  "latitude": string,
  "accuracy": string,
  "gpsSpeed" : number,
  "heading" : number
}
```

### keep_alive
>> YC, Timer in Info might not exist
:::info
derived from keep alive value added event
**sent to Tripo**

the report content is for Tripo to update the following data when parking
// 1. main battery voltage
// 2. the vehicle location
// 3. counting keep_alive reporting time
// 4. counting vehicle move reporting time  // coming from **vehicle_move**

// Special conditions may happen when parking:
// 1. main battery low: resulting **low_battery** sent to Tripo and Alerto
//    Tripo will expect that no more keep_alive will be sent again to save device power

// 2. **freq_vehicle_move** will trigger Alerto to notify the owner of the abnormality

// 3. Tripo will monitor if the keep_alive is received at the right interval. 
//    If the keep_alive is not sent for longer than 50% of the interval, 
//    e.g 15min with formal interval of every 10min.
//    an alert shall be issued to Alerto to remind the abnormality
//    One **Timer** service may be created to handle timer service.
//    Tripo will start a timer to after 3 consecutive keep_alive message are received
//    Tripo will reset the timer when receiving one keep_alive

:::
```jsonld
{
  "eventType": "keep_alive",
  "dateTime": int,
  "IMEI": string,
  "longitude": sting,
  "latitude": string,
  "accuracy": string,
  "gpsSpeed" : number,
  "heading" : number,
  // battery voltage
  "batVoltage": number,
  // cellular Data for positioning
  "mcc": string,
  "mnc": string,
  "cellularID": string,
  "lac": string,
  // neighboring wifi ap mac address
  "wifiApMac" : [{"mac":string,"signal": number}]
}
```

### SimpleVehicleEvents
:::info
derived from vehicle simple event
**sent to Vehicol and Alerto**
// all the types share the same JSON content except the
// eventType is different:
//
// 1. engine over load = "engine_overload"
// 2. high RPM = "high_rpm"
// 3. high engine coolant = "high_coolant_temp"
// 4. low battery = “low_battery"                 // during engine off 電池蓄電能力降低
// 5. vehicle move = “vehicle_move"
// 6. alternator problem = “alternator_problem”   // during engine on 發電機故障導致電壓低
// 7. frequent vehicle move = “freq_vehicle_move” // vehicle_move happens too freq

:::
```jsonld
{
  "eventType": "// one of the above type ",
  "dateTime": int,
  "IMEI": string,
  "longitude": double,
  "latitude": double,
  "accuracy": string,
  "gpsSpeed" : number,
  "heading" : number
}
```

### vehicle_DTC
:::info
derived from DTC value-added event
**sent to Vehicol and Alerto**

// a new service carExpert is required to decode the DTC 
// Notifian will consult carExpert to get description text for DTC
// 
// DTC is has standard and proprietary definition
// internet Crawler may be required to collect Proprietary definition
// for different models and makes of ca
:::
```jsonld
{
  "eventType": "vehicle_DTC",
  "dateTime": int,
  "IMEI": string,
  "longitude": double,
  "latitude": double,
  "accuracy": number,
  "gpsSpeed" : number,
  "heading" : number,
  // DTC 
  "pendingDTC" :  {"", … , ""},    // null if no pending DTC
  "DTC" : {"",... , ""}               // null if no DTC
}
```

### vehicle_DTC_clear
:::info
derived from DTC clear value-added event
**sent to Vehicol and Alerto**

// a new service carExpert is required to decode the DTC 
// Notifian will consult carExpert to get description text for DTC
// 
// DTC is has standard and proprietary definition
// internet Crawler may be required to collect Proprietary definition
// for different models and makes of cars
:::
```jsonld
{
  "eventType": "vehicle_DTC_clear",
  "dateTime": int,
  "IMEI": string,
  "longitude": double,
  "latitude": double,
  "accuracy": number,
  "gpsSpeed" : number,
  "heading" : number,
  // DTC 
  "pendingDTC" :  boolean,    // 1 if clearing pending DTC state; otherwise 0
  "DTC" : boolean              // 1 if clearing DTC state; otherwise 0
}
```

### vehicle_speeding
:::info
derived from Over Speed value-added event 118
**sent to Tripo、Alerto**

:::
```jsonld
{
  "eventType": "vehicle_speeding",
  "dateTime": int,
  "IMEI": string,
  "longitude": double,
  "latitude": double,
  "accuracy": number,
  "gpsSpeed" : number,
  "heading" : number,
  // SPEED
  "limit" :  number,
  "curSpeed" : number
}
```
### eco_start/non_eco_start
:::info
derived from New ECO/Non-ECO Start value-added event 116/117
**sent to Drivo**

:::
```jsonld
{
  "eventType": "eco_start|non_eco_start",
  "dateTime": int,
  "IMEI": string,
  "longitude": double,
  "latitude": double,
  "accuracy": number,
  "gpsSpeed" : number,
  "heading" : number,
  // ECO DATA
  "airUsed":  number,
  "duration": number
}
```

### vehicle_impact
:::info
derived from vehicle impact value-added event
**sent to Vehicol and Alert**

:::
```jsonld
{
  "eventType": "vehicle_impact",
  "dateTime": int,
  "IMEI": string,
  "longitude": double,
  "latitude": double,
  "accuracy": double,
  "gpsSpeed" : number,
  "heading" : number,
  // g-sensor data (10 sets)
  "gsensorData":{
	{
                        "gSensorDataAxis1": number,
                        "gSensorDataAxis2": number,
                        "gSensorDataAxis3": number
                    }, … ,
	{
                        "gSensorDataAxis1": number,
                        "gSensorDataAxis2": number,
                        "gSensorDataAxis3": number
                    }
   
    }

}
```

### DriverEvents
:::info
// could be one of the following types
// all the types share the same JSON content except the
// eventType is different:
//
// 1. vehicle idle = "vehicle_idle"
// 2. vehicle speeding = "vehicle_speeding" // 已移除 20200324
// 3. harsh RPM = "harsh_rpm"
// 4. harsh acc = "harsh_acc"
// 5. harsh brake = "harsh_brake"
// 6. harsh turn = "harsh_turn"
// 7. Eco Start = "eco_start" // 已移除 20200324
// 8. Eco Stop = "eco_stop"
// 9. non eco start = "non_eco_start" // 已移除 20200324
// 10. non eco stop = "non_eco_stop"
// 11. frequent harsh = “frequent_harsh”
:::
```jsonld
{
  "eventType": "// one of the above type ",
  "dateTime": int,
  "IMEI": string,
  "longitude": double,
  "latitude": double,
  "accuracy": number,
  "gpsSpeed" : number,
  "heading" : number
}
```


### driver_pedal_pattern
:::info
derived from L3 report
sent to Drivo、Vehicol
:::
```jsonld
{
  "eventType": "driver_pedal_pattern",
  "dateTime": int,
  "IMEI": string,
  // gps info
  "longitude" : double,
  "latitude" : double,
  "accuracy" : number,
  // pedal pattern
  "observePeriod": number,
  "idlePeriod" : number,
  "accPeriod" : number,
  "brakePeriod" : number,
  "coastPeriod" : number,
  "stopAndGoCount": number,
  // fuel_stats
  "idleAirUsed": number,
  "distanceZeroRPM": number,
  "zeroRPMPeriod": number,
  "ecoRPMPeriod": number,
  // Speed Report
  "highSpeedPeriod": number,
  "mediumSpeedPeriod": number,
  "lowSpeedPeriod": number,
  "speedDuration": {
    "speed1": number,
    "speed2": number,
    "speed3": number,
    "speed4": number,
    "speed5": number,
    "speed6": number,
    "speed7": number,
    "speed8": number,
    "speed9": number,
    "speed10": number,
    "speed11": number,
    "speed12": number,
    "speed13": number,
    "speed14": number,
    "speed15": number,
    "speed16": number,
    "speed17": number
  }
}
```
### DeviceEvent

#### gps_quality
:::info
derived from level 1 report
sent to Devicio
:::
```jsonld
{
  "eventType": "gps_quality",
  "dateTime": int,
  "IMEI": string,
  "longitude" : double,
  "latitude" : double,
  "satelliteNum" : number,
  "accuracy" : number,
  "confidenceLevel" : int
}
```
#### cellular_service
:::info
derived from level 2 report
sent to Devicio
:::
```jsonld
{
  "eventType": "cellular_service",
  "dateTime": int,
  "IMEI": string,
  "longitude" : double,
  "latitude" : double,
  "accuracy" : number,
  "cellularID" : string,
  "lac" : string,
  "rat" : string, // could "2g","3g", or "4g"
  "signalStrength": string,
  "band" : number,
  "ulThroughput" : number, //units: kbps
  "dlThroughput" : number, //units: kbps
  "ulDeltaAmount" : number, //units: KB
  "dlDeltaAmount" : number, //units: KB
  "ulAmountMonth2Now" : number, // units: KB, since the month begins
  "dlAmountMonth2Now" : number // units: KB
}

```
#### cellular_connection
:::info
derived from Cellular Connection Value-added event
sent to Devicio
:::
```jsonld
{
  "eventType": "cellular_connection",
  "dateTime": int,
  "IMEI": string,
  "longitude" : double,
  "latitude" : double,
  "accuracy" : number,
  "mcc": string,
  "mnc": strinf,
  "imsi": string,
  "cellularID" : string,
  "lac" : string,
  "disconnectTime": number,
  "disconnectReason" : string // check the VM protocol
}
```

#### wifi_station_list
:::info
 derived from wifi connection value-added event
sent to Devicio
:::
```jsonld
{
  "eventType": "wifi_station_list",
  "dateTime": int,
  "IMEI": string,
  "longitude" : double,
  "latitude" : double,
  "accuracy" : number,
  "wifiStationMac" : [{"mac":string}]
}
```
#### wifi_site_survey
:::info
 derived from wifi site survey value added event
sent to Devicio
:::
```jsonld
{
  "eventType": "wifi_site_survey",
  "dateTime": int,
  "IMEI": string,
  "longitude" : double,
  "latitude" : double,
  "accuracy" : number,
  "wifiApMac" : [{"mac":double,"signal": numbers}]
}
```
#### wifi_status
:::info
derived from wifi on/off value-added event
sent to Devicio and Alerto
:::
```jsonld
{
  "eventType": "wifi_status",
  "dateTime": int,
  "IMEI": string,
  "longitude" : double,
  "latitude" : double,
  "accuracy" : number,
  // wifi internet status
  "wifiStatus" : number
}
```
#### device_system
:::info
derived from device system value-added event ( to be defined )
sent to Devicio

device system event
// VM will send one value added event to report
// CPE temperature, CPU load, Memory and Flash load periodically

:::
```jsonld
{
  "eventType": "device_system",
  "dateTime": int,
  "IMEI": string,
  "longitude" : double,
  "latitude" : double,
  "accuracy" : number,
  "cpuTemp" : number,
  "cpuLoad" : number, // percentage number
  "memLoad" : number,
  "flashLoad" : number
}
```
#### device_firmware_change
:::info
 derived from simple event engine start
// sent to Devicio
 5. device firmware change
// when receiving firmware update success/failure MQTT

:::
```jsonld
{
  "eventType": "device_firmware_change",
  "dateTime": int,
  "IMEI": string,
  "longitude" : double,
  "latitude" : double,
  "accuracy" : number,
  “changeStatus”: number, 	// 0 if success, 1 if failure
  "newFwVersion" : string	// only presents if success
}
```
#### device_config_change
:::info
derived from simple event engine start
// sent to Devicio

// 6. device config change
// when receiving firmware update success/failure MQTT

:::
```jsonld
{
  "eventType": "device_config_change",
  "dateTime": int,
  "IMEI": string,
  "longitude" : double,
  "latitude" : double,
  "accuracy" : number,
  // Config change information
  “changeStatus”: number, 	// 0 if success, 1 if failure
  "newConfigVersion" : string
}
```
#### device_reboot
:::info
 derived from simple event engine start
// sent to Devicio

// 7. device reboot 
// when receiving device reboot value added event
:::
```jsonld
{
  "eventType": "device_reboot",
  "dateTime": int,
  "IMEI": string,
  "longitude" : double,
  "latitude" : double,
  "accuracy" : number,
  "deviceMode" : string, // "tracker", "J1979","J1939", or "Ignition"
  "obdProtocolCode" : number,
  "modelName" : string,
  "serialNum" : string,
  "wifiMac" : string,
  "fwVersion" : sting,
  "configVersion" : string,
}
```
#### vehicle_change
:::info
// derived value-added report vehicle change
// sent to Devicio and Alerto
:::
```jsonld
{
  "eventType": "vehicle_change",
  "dateTime": int,
  "IMEI": string,
  "longitude" : double,
  "latitude" : double,
  "accuracy" : number,
  // vehicle change info
  “vehicleChangeType” : number,
  “vinLockStatus” : number,
  "newVIN" : string,
  "oldVIN" : string
}
```
#### calibration_status
:::info
 derived from value-added event calibration complete
// sent to Devicio
:::
```jsonld
{
  "eventType": "calibration_status",
  "dateTime": int,
  "IMEI": string,
  "longitude" : double,
  "latitude" : double,
  "accuracy" : number,
  // calibration status
  "deviceMode" : "", // "tracker", "J1979","J1939", or "ignition"
  "accOnVoltage" : float,
  "highLowVoltage" : float,
  "lowHighVoltage" : float,
  "devicePosX" : number,
  "devicePosY" : number,
  "devicePosZ" : number,
  "cosThetaX" : number
}
```
#### ble_data
:::info
 derived from L1 report tmps fields
// sent to Sensol
:::
```jsonld
{
  "eventType": "ble_data",
  "dateTime": int,
  "IMEI": string,
  // gps info
  "longitude" : double,
  "latitude" : double,
  "accuracy" : number,
  // ble info
  "iBeacon" : 
  [
     {
       "uuidByte0" : number,
       "uuidByte7" : number,
       "major" : string,
       "minor" : string
     }
  ]
}

```

### cellular_loss
:::info
derived from MQTT Broker (LWT)
**sent to Devicio, Alerto**
:::
```jsonld
{
    "eventType": "cellular_loss",
    "dateTime": int, 
    // system time when received LWT    
    "IMEI": string
}
```

### device_system_info
:::info
derived from L3 report
**sent to Devicio**
:::
```jsonld
{
    "eventType": "device_system_info",
    "dateTime": int,   
    "IMEI": string,
    // gps info
    "longitude" : string,
    "latitude" : string,
    "accuracy" : number,    
    "maxCpuTemperature" : number,
    "cpuLoad" : number,
    "ramLoad" : number
}
```

