Introduction

Counters refer to the absolute values that always increase for vehicles, for example: distances, timers, and consumptions. These values are expected to increase indefinitely so we normally use counters to obtain the difference of the values between a range of time.

There are two main sources for the counters values, either using the tracking device's data (referred to as dev data), or the actual vehicle's engine data (referred to as ecu data).

Since tracking devices can be replaced at any point for a vehicle, Pegasus has to take extra measures to make sure the raw values received from the devices are consistent and make sense for a vehicle entity. Measures like filling missing/null data, or protections against drops or changes between values from a previous device and a new device. These extra measures give rise to new Pegasus counters fields that are used to keep the counter data consistent, these counters have a prefix with dev_ or ecu_.

There is one more use case that gives rise to additional counter fields in the API and that's when you want to know the absolute total value, as is the case with a vehicle's odometer or hourmeter. For this case we build additional counter called vehicle counters which inherits all the benefits of the Pegasus counters but is user editable, making it ideal for setting a vehicle's odometer or hourmeter. These counters have the prefix: vehicle_

The specific counter for each type along with their raw value is as follow.

Note that the raw counters do NOT adjust to the unit preferences.

Rawdata FieldDescriptionDefault UnitsAdjusts to Unit Preferences
DISTANCE
voraw gps odometermeter❌
dev_distnormalized gps odometermeter✅
vehicle_dev_distuser edited gps odometermeter✅
ecu_distanceraw ecu odometermeter❌
ecu_distnormalized ecu odometermeter✅
vehicle_ecu_distuser edited ecu odometermeter✅
IGNITION
ceraw gps ignition timesecond❌
dev_ignnormalized gps ignition timesecond✅
vehicle_dev_ignuser edited gps ignition timesecond✅
ecu_hoursraw ecu ignition timehour❌
ecu_eusagenormalized ecu ignition timesecond✅
vehicle_ecu_eusageuser edited ecu ignition timesecond✅
IDLE
clraw gps idle timesecond❌
dev_idlenormalized gps idle timesecond✅
vehicle_dev_idleuser edited gps idle timesecond✅
ecu_hours_idleraw ecu idle timehour❌
ecu_eidlenormalized ecu idle timesecond✅
vehicle_ecu_eidleuser edited ecu idle timesecond✅
FUEL
ecu_total_fuelraw ecu fuel consumeddeci-liter❌
ecu_tfuelnormalized ecu fuel consumedliter✅
vehicle_ecu_tfueluser edited ecu fuel consumedliter✅
IDLE FUEL
ecu_idle_fuelraw ecu idle fuel consumeddeci-liter❌
ecu_ifuelnormalized ecu idle fuel consumedliter✅
vehicle_ecu_ifueluser edited ecu idle fuel consumedliter✅

Finally, custom counters can be created for any Pegasus counter - these are called shared or user counters.

API

The counters API provides an easy way to obtain total values for each of the types of counters over a period of time. It is essentially a glorified version of the rawdata API that's resampled with the difference applied to all counters. The counters API also provides the following derived calculated counters:

Derived fieldDescriptionCalculation
dev_tot_avg_speedTracking device total avg speed.dev_dist/dev_ign
ecu_tra_avg_speedECU traveling avg speed.ecu_dist/(ecu_eusage-ecu_eidle)
ecu_tot_fuel_efcyECU fuel efficiency.ecu_dist/ecu_tfuel
ecu_tra_fuel_efcyECU traveling fuel efficiency.ecu_dist/(ecu_tfuel-ecu_ifuel)
dev_tra_fuel_efcyTracking device traveling fuel efficiency.dev_dist/(ecu_tfuel-ecu_ifuel)
dev_tra_avg_speedTracking device traveling avg speed.dev_dist/(dev_ign-dev_idle)
ecu_fuelp_idlingECU fuel percentage used while idling.ecu_ifuel*100/ecu_tfuel
ecu_tot_avg_speedECU total average speed.ecu_dist/ecu_eusage
dev_tot_fuel_efcyTracking device fuel efficiency.dev_dist/ecu_tfuel

📘

Units

The default units for distance, timers, and consumptions are meters, seconds, and liters respectively, but you can use the distance, time, and volume params for conversion.

Check the units in API Overview for more information about the units in the response and accepted values.

The counters API has two important use cases:

  • Retrieving the total value between two dates for each entity passed. (ex. total distance traveled in one month)
  • Calculating the difference in smaller intervals given a larger time frame (ex. distance traveled per hour for a week. or per day for a month)

Total values

To get a vehicle's counters over a period of time simply pass the entity, whether vehicles, assets or groups param, along with a from and to date or a duration.

The response provides the total difference in counter values from the last and first event in the time range, separated by entity.

Additionally, each counter object within the counters array, contains a from and to property referring to the times of the start event and end event respectively.

Total counter values for month of April

/counters?vehicles=2600&from=2022-04-01T00:00:00&to=2022-04-30T23:59:59

{
    "units": {
        "volume": "liter",
        "distance": "meter",
        "speed": "meter/second",
        "time": "second"
    },
    "counters": [
        {
            "vid": 2600,
            "from": "2022-03-31T23:59:49",
            "to": "2022-04-30T23:54:30",
            "dev_dist": 7290574,
            "dev_ign": 745813,
            "dev_idle": 188131,
            "dev_ospeed": 23452,
            "dev_tot_avg_speed": 9.8,
            "dev_tra_avg_speed": 13.1
        }
    ]
}

Interval changes

You can also query the counters API for subranges. Say for example, you want to view the distance traveled by a vehicle per day, for the past 30 days. You could, make 30 requests, to the counters API with varying start and end days representing each day in your desired range. Simply pass the from and to dates that encapsulate the desired range, along with the delta parameter representing your desired fragment size (1D for Daily for example - accepts any ISO 8601 duration format).

Instead of 30 one day requests, you instead have 1 requests, spanning 30 days, with 1 day fragments.

Daily counters requests for the past 30 Days

/counters?vehicles=2600&duration=P30D&delta=1D

{
    "units": {...},
    "counters": [
        {
            "vid": 2600,
            "from": "2021-11-01T00:00:54",
            "to": "2021-11-01T22:30:10",
            "dev_dist": 179106,
            "dev_ign": 30582,
            "dev_idle": 10879,
            "event_time": "2021-11-01T00:00:00"
        },
        {
            "vid": 2600,
            "from": "2021-11-02T00:30:10",
            "to": "2021-11-02T22:18:52",
            "dev_dist": 7865,
            "dev_ign": 4150,
            "dev_idle": 2906,
            "event_time": "2021-11-02T00:00:00"
        },
        ...
    ...
}

The results above can paint a report with the daily values of each counter

Truck AHB-293 Daily Summary Report for November

daydistanceignitionidleidling %
Nov 1179.1 km8.5 h3.0 h35%
Nov 27.9 km1.2 h0.8 h67%
...

Vehicle Counters

Vehicle counters are absolute counters that increase with the Pegasus counters and are user editable. Note that these counters need to be initialized before they're seen on the api.

List of vehicle counters:

Pegasus counterVehicle counterDefault Units
dev_distvehicle_dev_distmeters
ecu_distvehicle_ecu_distmeters
dev_ignvehicle_dev_ignseconds
dev_idlevehicle_dev_idleseconds
dev_orpmvehicle_dev_orpmseconds
dev_ospeedvehicle_dev_ospeedseconds
ecu_eusagevehicle_ecu_eusageseconds
ecu_eidlevehicle_ecu_eidleseconds
ecu_ifuelvehicle_ecu_ifuelliters
ecu_tfuelvehicle_ecu_tfuelliters

Initialize/Update

To initialize and update vehicle counter values use a PUT on the /vehicles/:vid/counters resource passing it the Pegasus counter that you want to edit.

Let's say you want to edit the vehicle's distance counter to match the odometer on your car.

Updating the vehicle_dev_dist counter to 104,203.942 km for vehicle ID 197

PUT /vehicles/197/counters

{
  "counter": "dev_dist",
  "value": 104203942
}

The next events the device report will now have an updated vehicle_dev_dist that reflects the value entered: 104203942 meters, but the Pegasus counter will remain unchanged dev_dist.

🚧

Counter sync

Note that once the vehicle's counter is changed it has to report again in order for it to be synchronized with the value set.

📘

Scope / permission to edit

Only gateway administrators and those with w scopes on "vehicles.counters" can modify the vehicle counters.

Shared User Counters

Shared user counters are counters created by users that anyone with visibility to the vehicle can see.

You can create as many of these counters are you'd like for the same vehicle.

These counters are only persisted in the /counters api, and are not available in the /rawdata api.

To see the counters you have defined you can use:

GET /vehicles/:id/counters

These counters exist only in this API, the idea here is that once you create them you can query this API again at any point to see the new values for these shared user counters.

Get the shared user counters for a particular vehicle
/vehicles/197/counters

{
  "user": [
    {
      "description": "Time since new alternator",
      "set_at": 1474660977.65856,
      "counter": "dev_ign",
      "value": 19529142,
      "offset": 9690591,
      "id": 0
    }
  ],
  "vehicle": {...}
}

Creating

Now let's create a shared user counter for those new tires you just changed

Create a shared counter that starts counting distance starting at 123 from the moment it's created

POST /vehicles/197/counters

{
    "counter": "dev_dist",
    "description": "front tires",
    "initial_value": 123
}

Updating

In order to update a shared user counter you create, you can make a PUT request to the specific counter id:
PUT /vehicles/:vid/counters/:id. The body of the request is the name of the counter, description, initial_value

{
    "counter": "dev_dist",
    "initial_value": 123,
    "description": "Some description"
}

These changes apply to that particular vehicle for the user that changed.

Live Communications

For live communications purposes the counter values can be found under the following payloads

Pegasus counter or device counters

  • device.latest.counters
{
    "object": "1188",
    "namespace": "vehicle-events",
    "payload": {
        "device": {
            "latest": {
                "counters": {
                    "dev_dist": 97723093,
                    "dev_idle": 998750.8,
                    "dev_ign": 49154762,
                    "ecu_dist": 439811000,
                    "ecu_eidle": 254780364,
                    "ecu_eusage": 26812080,
                    "ecu_ifuel": 135,
                    "ecu_tfuel": 153551,
                    "evid": 118800180663179,
                    "evtime": 1652459835,
                    "systime": 1652459998.2,
                    "trip_id": 118800050796810
                }
            }
        }
    }
}

Vehicle counters

  • device.latest.vcounters
{
    "object": "1188",
    "namespace": "vehicle-events",
    "payload": {
        "device": {
            "latest": {
                "vcounters": {
                    "evid": 118800180663179,
                    "evtime": 1652459835,
                    "systime": 1652459998.2,
                    "trip_id": 118800050796810,
                    "vehicle_dev_dist": 97600816.5,
                    "vehicle_dev_idle": 998750.8,
                    "vehicle_dev_ign": 341772654279.3,
                    "vehicle_ecu_dist": 439811370,
                    "vehicle_ecu_eidle": 254780326,
                    "vehicle_ecu_eusage": 26811900,
                    "vehicle_ecu_ifuel": 14261.5,
                    "vehicle_ecu_tfuel": 30811
                }
            }
        }
    }
}

IO Counters

IO (Input/Output) counters are also available for getting the total amount of time a particular input or output remains active. These counters use the following format counter_ followed by the io_counter

counterdescriptionunits
counter_io_in1total time with input 1 activeseconds
counter_io_in2total time with input 2 activeseconds
counter_io_in3total time with input 3 activeseconds
counter_io_out1total time with output 1 activeseconds
counter_io_out2total time with output 2 activeseconds

Report Counters

Durations

We can calculate the duration of a specify incident using the labels from RawData or the counters from Counter API.

MetricAPICalculation
Driving in NeutralRawdataLabels coastend - coast
Engine BrakingRawdataLabels enbrkoff- enbrkon
Over RPM In MovementRawdataLabels ovrpmovoff - ovrpmmov
Over RPM In IdleRawdataLabels ovrpmidlof - ovrpmidl
Engine ON TimeCounterCounters ignition
Overspeed TimeCounterCountersdev_ospeed
Idling TimeCounterCountersidle
Driving TimeCounterEngine ON Time - Idling Time