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.

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

Distances (default units: meters)

raw value from devicePegasus countersdescription
vodev_distdevice's distance (calculated by GPS coordinates)
ecu_distanceecu_distdistance from engine's onboard computer

Timers (default units: seconds)

raw value from devicePegasus countersdescription
cedev_igndevice's ignition time
cldev_idledevice's idling time
crdev_orpmdevice's time spent over rpm limit
csdev_ospeeddevice's time spent over speed limit
ecu_hours (hours)*ecu_eusageengine's total ON time (hourmeter)
ecu_hours_idle (hours)*ecu_eidleengine's total time spent idling

to get the duration for ecu_hours and ecu_hours_idle in seconds you need to divide by 3600

Consumptions (default units: liters)

raw value from devicePegasus countersdescription
ecu_total_fuel (deci-liters)*ecu_tfuelengine's total fuel consumption
ecu_idle_fuel (deci-liters)*ecu_ifuelengine's total fuel consumption while idling

to get the amount of fuel for ecu_total_fuel and ecu_idle_fuel in liters you need to divide by 10

Note that the default units are meters, seconds, and liters but they can be changed, read units for more info.

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. 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

As mentioned above vehicle counters are user editable counters that increase with Pegasus counters.

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

👍

Units

Note that the Pegasus counter units can be updated by passing a unit parameter in the request.

  • /api/rawdata?distance=mile
  • /api/rawdata?time=hour
  • /api/rawdata?volume=gallon

Updating

To edit the vehicle counter value 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

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": 0
}

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

Did this page help you?