Counters

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.

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:

📘

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

🚧

Warning for 3rd party devices that are swapped

Vehicles that use non Syrus devices are not protected against changes to the device association. In other words if you swap devices on a vehicle for any third party device (Atrack, Coban, Teltonika, etc.) the devices counters will reset to 0 (dev_dist, dev_ign, dev_idle, etc.).

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:

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

Report Counters

Durations

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