Definitions

Entities - refer to the collection of platform organizational data of types assets & vehicles.

• Vehicles
• Assets

Resources - refer to all the other collections of platform organizational data

• Users
• Devices
• Groups
• SIMs
• Bluetooth Tags
• Geofences
• Geofence Types

Entities

When we refer to an entity on the platform we are strictly referring to either an asset or a vehicle resource. Vehicles are organizational resources that need a device directly associated to it. Meanwhile, assets are organizational resources with an optional device associated to it.

Assets that do not have a device associated to it are known as passive assets. These assets are not billable, they can be created for real-world things like pallets, boxes, and can have a peripheral attached to them such as an RFID code. Once a vehicle's device reports the RFID code the asset with that code will be associated to the vehicle, or you can manually link a passive asset to a vehicle to associate them.

An asset's device can either be associated directly via the Taurus App, or it can be associated to a vehicle's device via Entity Linking.

🚧

Billable vs Non-billable Assets

Once a device is associated to an asset it goes from passive to active and it becomes billable just like a vehicle.
If an asset has NO device associated to it then it is not billable.
Note that even if you disable the Taurus mode and remove all peripherals the asset is still billable.
To stop the billing you must delete the asset.

An asset's device IMEI will always be fake in the sense that it does not point to an actual real IMEI, but it does inherit telemetry data from a vehicle's device or your phone (in the case of Taurus).

Both vehicle and active assets are interchangeable with respect to the data they collect and can report, in other words any data requesting API such as rawdata, trips, counters, etc. will work for both.

Entity Linking / Asset Replication

Pegasus manages a concept of primary and secondary tracking entities.

Tracking devices that receive telemetry data directly and are associated to vehicles are known as primary tracking entities, while assets that have a device associated to it are known as secondary tracking entities.

When we refer to entity linking what we mean is the act of replicating a vehicle's telemetry data to an asset's device. This works only one way, from vehicle to asset and not vice versa or between entities.

To get started with Asset replication or entity linking we first need to create an asset

Note that type can be anything, and the group is a group ID that must be in the same group as the vehicle you want to link.

// POST /assets
{
     "groups": [
          141
     ],
     "first_name": "John",
     "last_name": "Smith",
     "type": "driver"
}

Next, we update the asset and enable the tracker mode, this associates a fake device IMEI to the asset, at this point it's treated as a Taurus asset which waits for the Taurus application to send data.

// PUT /assets/:aid
{
     "type": "driver",
     "tracker_mode": true
}

Finally, we update the asset again to disable the tracker mode (thereby disabling Taurus mode) and enabling the linking property so it can be treated as an enhanced asset.

// PUT /assets/:aid
{
     "tracker_mode": false,
     "properties": {
          "$linked": true
     }
}

The asset is now able to be linked manually or automatically and replicate data from the primary device.

Automatic Linking via Peripherals

Asset linking can also be achieved automatically using peripherals or accessories. Accessories that are compatible with assets include iButton, Bluetooth Tags, and RFIDs. Each one of these accessories has a unique identifier that can be assigned to an asset. Once any device reports that unique identifier the asset is automagically linked to it.

A common use case is giving drivers iButtons and creating an asset with that iButton assigned. Afterwards, whenever that iButton ID is read by any device that device will instantly be associated to that asset, achieving the automatic association of the asset to a vehicle.

Normally drivers are assigned to one particular peripheral, but many peripherals and of different types can be associated to assets.

To get started simply update the asset with the unique iButton ID, Bluetooth Tag MAC, or RFID.

// PUT /assets/:aid

{
    "ibuttons": ["0167E8271D000123"]
}

Next present the particular iButton ID, RFID, or Bluetooth Tag near the device that you want to automatically link.

🚧

Manual linking override

Note that manual linking overrides the automatic linking of entities via peripherals

Resources

Users

• Identified by email
• Give access to both the Pegasus Platform UI and to the API
• API access is controlled by scopes
• is_staff is true for administrators, which have access to all entities and resources
• For non administrators a user's entities visibility is determined by group membership

Groups

• Groups relate users, vehicles, & assets
• Groups determine the visibility of other resources such as triggers, geofences, and reports
• The most common usage is "a group per client" but it's flexible
• We recommend keeping groups under 500 entities

Vehicles

• A vehicle can only have one device assigned at any one time
• The vehicle-device association may change over time (unit replacement), API provides association history
• Remote interaction with a device is done via the vehicle resource
• Automation triggers are triggered by vehicle events

Devices

• Tracking device that receive telemetry data
• Must be associated to a vehicle in order to navigate it's data timeline
• Can receive commands even when not associated to a vehicle
• Device API includes all latest information about the current status of the device, always up to date

SIMs

• SIMs API can be self populating, meaning the SIMs automatically appear, or manually via a POST request
• The self populating SIMs are available for Syrus devices and some third party devices which automatically read the SIM's ICCID, this action happens every time the device connects to the system so it's always up to date
• Two IDs to refer to SIMs: API ID and the SIMs actual ICCID, API ID is an incremental one that's assigned by the gateway, and the ICCID is the unique SIM ID number
• A line/phone number can be configured on the SIM resource via a PUT method (note that the PUT is made over the API ID, not the ICCID)

Filtering

select

The select parameter is used to filter data from resources. It works by specifying a path to search for; the format is select=key1_to_search,key2_to_search, with an optional nested value for some APIs: select=nested.key. You can also separate certain resources on the select parameter via a space.

For example if you want to select just the vehicle's name you would do it over the /vehicles resource and pass a select param with name.

Another example retrieving a vehicle's name, it's device location, online state, and sim information:

GET /vehicles?select=name,device:latest.loc network connection

More examples:

All members of resource

GET /users

Particular user

GET /users/123

Filter all by certain fields (does not support nested)

GET /users?select=username,prefs

Vehicle's name, info, and device latest information

GET /vehicles?select=name,info,device:last*

All vehicles in a group

GET /vehicles?groups=123&select=id

2 device's inputs & outputs state and outbox

GET /devices?imeis=450005314525050,450005314525051&select=ios_state,outbox

Device's latest location data only (supports nesting 1 level)

GET /devices?select=latest.loc

Return particular vehicle's name & device's network info

GET /vehicles?select=name,device:network&ids=2600

Return the device and vehicle counters for groups of vehicles

GET /vehicles?groups=1,2,3&select=device:latest.vcounters+latest.counters

search

The search parameter can be used to find resources with specific key-values. For example if you have custom properties per vehicle or geofences you can filter by that property. It works for all platform resources.

The way it works is that you define the key that you're searching for within the data set using the search param. For finding specific keys within a json you can reach the key by separating the keys with a period .

For example, given a vehicle's API result similar to this:

{
    "set": 2,
    "total": 2,
    "data": [
        {
            "info": {
                "make": "Honda",
                "license_plate": "ABC123",
                "year": "2014",
                "model": "CRV"
            },
            "id": 1,
            "name": "Truck 123"
        },
        {
            "info": {
                "make": "Honda",
                "license_plate": "DEF456",
                "year": "2010",
                "model": "Civic"
            },
            "id": 2,
            "name": "Truck 456"
        }
    ],
    "pages": 1,
    "page": 1
}

You can search the API for all vehicle's whose name is "Truck 123", and it will return ID: 1

GET /vehicles?search.name="Truck 123"

Or search for all vehicle's whose make is Honda, and it will return both ID: 1, 2

GET /vehicles?search.info.make=Honda

You can also combine search, so search for 2010 Hondas

GET /vehicles?search.info.make=Honda&search.info.year=2010

🚧

Case sensitivity

Note that the search is case sensitive: search.info.make=Honda != search.info.make=honda

You can even search for multiple items within an array and combine that with the select to return the location information for the entities found

GET /vehicles?search.groups=[1,2,3]&select=name,device:latest.loc

Using a custom property on geofence could be:

GET /geofences?search.properties.custom.random_key=value