Vehicle Meters

Meters are measurements recorded as part of the telematics data capture by devices installed on vehicles. These meters are such measurements as:

• Vehicle Odometer
• Engine Hours
• Fuel Use
• Device Battery Levels
• Total Distance
• etc

Each meter may have more than one source - for example, an odometer measurement may come from the calculated GPS distance, or from an in vehicle ECU via the CAN bus. The TN360 platform captures these meters against the specific device (ie. "device meters"), and rolls them up to the vehicle as "vehicle meters".

Where a device may capture multiple sources for the same meter (eg. odometer via GPS and CAN), at the vehicle level, only one meter source is available. As such a customer is able to configure the vehicle with the desired device meter source for the respective meter. This meter becomes the source of truth in the platform for this vehicle measurement and is used in the user interface, reports, and to drive operational processes such as maintenance schedules.

Elapsed vs Actual

Meters may be accumulated in two modes. Actual mode means that the value read or calculated for the meter is used as-is. So a CAN odometer in actual mode simply returns the value as read from the CAN bus.

This works unless there is no CAN odometer source, in which case a GPS odometer is used. The GPS odometer is a device-based distance calculation based on GPS information, and begins at 0 when the device is initially installed. This value is rarely useful as a "current" odometer value, and so is typically used in an elapsed mode.

The elapsed mode allows a customer to set a base value for the meter, and subsequent trips update the base with the accumulated trip distance. This enables the meter to be successfully re-aligned with (for example) the dash odometer reading.

Currently the 'odometer', 'hours', and 'fuel' meters support the elapsed mode.

Extracting Meters

You can retrieve the current set of vehicle meters using the following:

$ curl -H "Accept: application/json"          \
       -H "Authorization: Bearer {{api key}}" \
       https://tst.api-au.telematics.com/v1/vehicles/76440/meters

[ {
  "vehicle" : {
    "id" : 76440,
    "name" : "AU DEMO 5",
    "version" : 6,
    "status" : "ENABLED",
    "company" : {
      "id" : 14944,
      "features" : [ ],
      "geofenceProviders" : [ ]
    },
    "type" : {
      "id" : 2766
    },
    "registration" : "DMO6WNKJDS",
    "registrationState" : "ACT",
    "registrationCountry" : "AU",
    "registrationCountryName" : "Australia",
    "registrationStateName" : "Australia Capital Territory",
    "vin" : "AU_DEMO_VEHICLE_005",
    "engineNumber" : "",
    "make" : "",
    "model" : "",
    "externalId" : "AU_DEMO_VEHICLE_005",
    "tags" : "",
    "operationalVehicleModelId" : null,
    "operationalVehicleModel" : null,
    "companyId" : 14944
  },
  "type" : "distance",
  "base" : 1400385.5000000042,
  "value" : 1394449.1000000075,
  "diff" : 285670.999999966,
  "source" : "GPS",
  "createdAt" : "2023-02-13T19:19:28.000+11:00",
  "updatedAt" : "2023-09-06T18:51:17.000+10:00",
  "useDifferential" : true,
  "rebaseable" : false
}, {
  "vehicle" : {
    "id" : 76440,
    ...[snip]...
  },
  "type" : "hours",
  "base" : 5017.007777777783,
  "value" : 0.002777777777777778,
  "diff" : 4156.473611111094,
  "device" : {
    "id" : 78649,
    ...[snip]...
  },
  "source" : "GPS",
  "createdAt" : "2023-02-13T18:46:17.825+11:00",
  "updatedAt" : "2023-09-06T18:51:17.000+10:00",
  "useDifferential" : true,
  "rebaseable" : true
}, {
  "vehicle" : {
    "id" : 76440,
    ...[snip]...
  },
  "type" : "odometer",
  "base" : 0.0,
  "value" : 1394449.1000000075,
  "diff" : 621863.3999999503,
  "device" : {
    "id" : 78649,
    ...[snip]...
  },
  "source" : "GPS",
  "createdAt" : "2023-02-13T18:46:17.825+11:00",
  "updatedAt" : "2023-09-06T18:51:17.000+10:00",
  "useDifferential" : true,
  "rebaseable" : true
} ]       

Evaluating Meters

Meters contain 3 values:

• value: The last actual value of the meter
• base: The value the customer set as the base for an elapsed meter
• diff: The accumulated meter difference for an elapsed meter

To access the "current" state of the vehicle meter, a small piece of logic is required to calculate the final meter value based on whether the meter is in elapsed or actual mode.

   if useDifferential == true then
      meter = base + diff
   else
      meter = value
   end 

Meter Types