Avatar
Tony
  • Updated

EC3001 Scripted Eco Report

The Eco report measures harsh driving, speeding, the use of the seatbelt, and idling to produce an eco score for each vehicle.The EC3001 Scripted Eco report gives you lots of flexibility to define your own business rules. 

This guide shows how to set up and get started with the Eco Report. 

Screenshot_2020-06-05_at_13.23.53.png

Note: For a day to be counted, the selected period should have 24 hours of that day(12AM-12AM). 

Requirements and installation

1. Configure your Device Mapper

Your harsh driving signals should be mapped, using the Device Mapper, to the correct variables for the EC3001 report to work. Open the device mapper of your device/s:

  a. Go to Admin > Device Mapper in the application.

  b. Click Edit for the harsh driving compatible device

  c. Map the Ignition input from your device to the GpsGate variable Ignition. This is required for correct idle time.

      Note: The ignition signal might come from a different input from your device. 

Screenshot 2023-10-10 at 14.05.13.png

  d. Map the device's harsh signals to the following variables:

      Digital inputs → HarshAccelerationDigital, HarshBreakingDigital, HarshTurningDigital

      Analog inputs → HarshAcceleration, HarshBreaking, HarshTurning

  Note: It’s not required to map all harsh signals, but remember to set 0 (zero) Weight in the report parameters as shown below. 

Screenshot 2023-10-10 at 14.05.56.png

  e. Save your changes and close the Device Mapper window.

Note: Read more about Device specific configurations.

2. Download the EC3001_Scripted_Eco_Report.zip file and extract the XML-files on your computer.

3. Import the event rule (EC3001 Scripted Eco Report.xml) in VehicleTracker. Learn how to import an event rule in an application.

4. Import the report template EC3001 Scripted Eco Report (detailed).xml in Site Admin. Learn how to import a reporting template in an application.

5. Activate the EC3001 report in your Application.

Configuring EC3001 Scripted Eco report Point parameters

The report shows a single score for each vehicle based on the harsh events and idling time. To do this, a formula is used with the following parameters:

EC3001 Scripted Eco report formula
Event Points & Idle Points: Weight for each event. Default value: 5. Range: 1 - 5. A higher point value means the behavior is more serious/more undesirable. A lower point value indicates a less serious infraction.
Event Occurrences (harsh braking, acceleration, turning, excessive speeding, use of seat belt, + any other wanted measurements)

Distance: Total trip distance of a vehicle.

Minimum Distance: The minimum distance to calculate a score. Default: 100 km.

As you can see in the sample report above, the score is 100 for trips that are less than the minimum distance (100 km). The minimum distance can be configured in the event rule. 

Trip Time & Idle Time: Vehicle trip time and idle time

Idle Time Factor: The minimum allowed idle time per hour. Default: 5 minutes. For example: If the idle time is 5 min and the total trip time is 1 hour, then the idling score will be zero. 
Distance Factor: 100 / Distance. The harsh driving scores are calculated based on harsh events per distance driven
Event Score = Event Points * Event Occurrences * Distance Factor
Idle Score = Idle Points * (Idle Time - Idle Time Factor * Total Trip Time) /Idle Time Factor
Total Score = 100 - Event Score - Idle Score

Example: Calculation of Eco Score for a vehicle that ran 200 km and generated the harsh events below:

Harsh Braking: 3 Harsh Braking: 5 * 3 * 100 / 200 = 8
Harsh Acceleration: 4 Harsh Acceleration: 5 * 4 * 100 / 200 = 10
Harsh Turning: 2 Harsh Turning: 5 * 2 * 100 / 200 =5
Speeding: 4 Speeding: 5 * 4 * 100 / 200 = 10
Idle time: 10 minutes

Total Trip time = Trip time + Idle Time 

                      = 10 + 50 = 60 mins = 1 hour

Idling: 5 * (10 - 5 * 1) / 5 = 5 
Trip time: 50 minutes

  Event Score: 8 + 10 + 5 + 10 = 33

  Idle Score: 5

  Total Score: 100 - 33 - 5 = 62

 

The points are defined as variables in the script. Look for the passage in the script that is enclosed with //Replace below to get “Custom Fields” and //Replace above to get “Custom Fields” and adjust them if needed.

For each “Harsh” parameter, the default value is 5. Preview the report to determine if any of the points need to be altered.

Note: You might want to use different points for different types of vehicles (e.g. trucks, cars, etc.) in the same application. For that purpose, please have a look at Using Custom Fields further down.

See Modify Script below for more info, (steps 2-5 and 8-11).

Modifying the Script

  1. Choose an editor, e.g. Notepad++.
  2. In the application, open the Admin > Event Rules window.
  3. Notice the new rule called EC3001 Scripted Eco Report that you just imported. This rule includes a Script Expression including most of the calculations for the report.
  4. Click Edit in the Script Expression under the 4. Expression section
  5. Get familiar with the output of the script by pressing the test button and observing the result
  6. Copy the whole script and paste it into the editor.
  7. Open one of the files, (included in the .zip-file you just downloaded), called EcoAddFunctionality.txt
  8. Modify your script, see different alternatives below.
  9. Make sure the script runs, then accept and save the event rule.
  10. Make sure to reprocess the data for the report. Read how to reprocess a report.
  11. Generate the report and see updated results.

Optional: Using Real Speed Limits

  1. Install the SpeedingExpression plugin.
  2. Follow steps 1-7 in the Modify Script section.
  3. Replace what’s in between Replace below - “Get Dynamic Speedlimits from OSM” and Replace above - “Get Dynamic Speedlimits from OSM”. There are two parts; a function and some variables. Both are needed.
  4. Follow steps 9-11 in the “Modify Script” section.

Optional: Using Custom Fields

You might want to use different weights for different vehicle types (trucks, cars, etc.) in the same application:

  1. Follow steps 1-7 in the “Modify Script” section.
  2. Replace what’s in between Replace below - “Get Custom Fields” and Replace above - “Get Custom Fields”.
  3. Create these custom fields and use them in the script (e.g. ‘harshAccWeight’ in the picture below).
  4. Follow steps 9-11 in the “Modify Script” section.
//Replacebelow toget "Custom Fields"
var harshAccWeight = parseFloat(session.user.getCustomFieldValue('harshAccWeight') || 0);
var harshBrakeWeight = parseFloat(session.user.getCustomFieldValue('harshBrakeWeight') || 0);
var harshTurnWeight = parseFloat(session.user.getCustomFieldValue('harshTurnWeight') || 0);
var oSpeedWeight = parseFloat(session.user.getCustomFieldValue('oSpeedWeight') || 0);
var sBeltWeight = parseFloat(session.user.getCustomFieldValue('sBeltWeight') || 0);
var tripIdleWeight = parseFloat(session.user.getCustomFieldValue('tripIdleWeight') || 0);
var idletimeBase = parseFloat(session.user.getCustomFieldValue('idletimeBase') || 0);
var excellent = parseFloat(session.user.getCustomFieldValue('excellent') || 0);
var good = parseFloat(session.user.getCustomFieldValue('good') || 0);
var fair = parseFloat(session.user.getCustomFieldValue('fair') || 0);
//Replace  above toget "Custom Fields"

custom_fields.pngOptional: Report driver instead of the vehicle

If you have a driver connected to your vehicle, you can report that driver instead of the vehicle:

  1. In the application, open the Admin > Event Rules window.
  2. Change “Who this rule applies to” to a tag with your drivers instead of your vehicles
  3. Follow steps 1-7 in the “Modify Script” section.
  4. Search for the lines of code below in the script and comment out driver.username in 3 different places so that the script looks like the code below.
  5. Follow steps 9-11 in the “Modify Script” section.

After editing, it should be:

DriverOrVehicle: session.driver.username, // place 1
//DriverOrVehicle: session.vehicle.username, //
 
var newDriverOrVehicle = (state.DriverOrVehicle != session.driver.username);//place 2
//var newDriverOrVehicle = (state.DriverOrVehicle != session.vehicle.username);
 
state.DriverOrVehicle = session.driver.username; // place 3
//state.DriverOrVehicle = session.vehicle.username;

Driver classification

The report can display the driver classification based on the score the driver has received according to the logic described above. The classification is as follow:
  • below 30 points - Risky
  • between 30 and 65 points - Fair
  • between 65 and 85 points - Good
  • Between 85 and 100 points - Excellent

The values can be adjusted by editing the expression in the cell in the report template containing the following code:

$math.eval(( 100 - [EventArgument12]/[EventArgument] - [EventArgument15] ) < 30 ? "Risky" : $math.eval(100 - [EventArgument12]/[EventArgument] - [EventArgument15] ) < 65 ? "Fair" : $math.eval(100 - [EventArgument12]/[EventArgument] - [EventArgument15] ) < 85 ? "Good": $math.eval(100 - [EventArgument12]/[EventArgument] - [EventArgument15] ) <= 100 ? "Excellent": $math.eval(100 - [EventArgument12]/[EventArgument] - [EventArgument15] ))

The values can be replaced by the custom variables if you add them (see section Optional: Using Custom Fields)

See attached report (EC3001 Scripted Eco Report (detailed with classification) for reference.

Device-specific configuration guides

You need to configure your devices to send harsh driving information for the report to work. The guides below will help you with the configuration of some device brands to enable or set the harsh parameters properly in those devices:

Related articles