Intro

Welcome to the Pegasus API Documentation!

This documentation gives you access to the entire Pegasus stack, including live communication, device interaction and historical data. The documentation is designed to make it easy to interact with DCT’s suite of IoT devices that are currently supported on Pegasus, allowing you to deploy highly customizable solutions.

If you find yourself stuck or don’t have a clear understanding of what’s going on, please don’t hesitate to post issues on our public repo and join the conversation in our Gitter.

The documentation was generated using Slate.

Background

Digital Communication Technologies (DCT) manufactures intelligent devices which collect data from different sensors and accessories as well as GPS satellites simulatenously.

These intelligent devices send all their data in realtime to a server called: Pegasus Gateway or just Pegasus. Pegasus works as a central server where all the data is collected, analyzed and then exposed via the API for easy viewing.

The API allows you to query any of the 300+ parameters the devices and their sensors expose. It is also a way for you to interact directly with the device, allowing you to make changes to the configuration, create rules, customizable actions depending on device states, and much more with easy to understand API commands.

Pegasus Overview

Multiple Pegasus servers can exist, in fact there are multiple Pegasus servers deployed around the world, each server having a custom URL or subdomain which is controlled by a Pegasus owner via a licensed fee.

At the core of each Pegasus site, the API is the same. The requests are built the same way, the only difference being the base URL.

Base URL

https://sitedomain.com/api

https://cloud.pegasusgateway.com/api

The base URL is the domain where the Pegasus server is hosted, in our case it’s used to identify where the requests will be built from.

API Reference

https://sitedomain.com/api-static/docs

https://cloud.pegasusgateway.com/api-static/docs

The Pegasus API reference allows you to test all the methods directly with your site, it can be found under the path /api-static/docs

Demo

API Reference Login

user: developer@digitalcomtech.com

pass: deV3lopErs

Throughout the guide we’ll work on a Demo server called: cloud

The vehicles we’ll work with are:

vehicle_id	name	imei	device	features
2600	PruIng1-TDX566	356612022409637	Syrus 2	Engine data
1956	(1) TEST HALL	357042062920955	Syrus 3G BT	Photo data
691	Stand 4 - Syrus Mobile	357042063193172	Syrus 3G BT	Device outputs (sensors / buzzers)
3168	Syrus OBDII SO3G-3	357041069434986	Syrus OBDII	Engine data
3005	Titan 4G	869912030003715	Titan	GPS data & temperature

Versioning

/api

{
  "domain": "cloud.pegasusgateway.com",
  "name": "6.0.1-aws",
  "live-url": "https://aws-live-0.pegasusgateway.com",
  "pegasus_id": 1,
  "live_url": "https://aws-live-0.pegasusgateway.com",
  "tag": "6.0.1-aws",
  "date": "Dec 22 09:41:47 2020",
  "_deprecated": [
    "live-url"
  ]
}

To consult the version of your API use the /api endpoint.

field	description
date	Time of last update
live-url	Socket communication endpoint
tag	Version tag
name	major.minor.patch

Breaking changes may occur on major and minor numbers. Patches, are not expected to affect compatibility.

For future version releases and changelog go to Github - Releases.

Also subscribe to our mailing list for updates.

Resource Patterns

Resources URI patterns try to follow the general convention:

/vehicles represents all the vehicles

/vehicles/:id represents a particular vehicle ID

/vehicles/:id/remote/state see the state of a particular vehicle ID

/vehicles/:id/routes see the routes of a particular vehicle ID

etc.

Pagination

api/vehicles?set=2&page=2

{
  "set": 2,
  "total": 5,
  "data": [...],
  "page": 2,
  "pages": 3
}

Requests to a collection of resources (such as: Users, Vehicles, Devices) are automatically paginated and will return a set of 200 resources by default. You can request up to 1000 entries per page (up to 500 Devices) by using the set parameter.

You will see the following additional parameters in the request.

parameter	description
set	Number of items in current page
page	current page
pages	total number of pages
total	total number of items

Information

General information about the API

HTTP

Verbs

verb	meaning
GET	Used for retrieving resources.
POST	Used for creating resources, sending-info, actions
PUT	Used for replacing/updating resources.
DELETE	Used for deleting resources.

Status

code	description	meaning
200	OK	General success status code.
201	CREATED	Entity has been created (POST request successful). Response body content may or may not be present.
204	NO CONTENT	Status when wrapped responses are not used and nothing is in the body (e.g. DELETE).
304	NOT MODIFIED	Used in response to conditional GET calls to reduce bandwidth usage.
400	BAD REQUEST	General error when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc.
401	UNAUTHORIZED	User is not authenticated with Gateway, does not have permission to upload data, does not have the required scopes, or does not share groups with requested entity
403	FORBIDDEN	User is not allowed to perform operation, regardless of scopes or admin level.
404	NOT FOUND	Used when the requested resource is not found, whether it doesn’t exist or if there was a 401 or 403 that, for security reasons, the service wants to mask.
409	CONFLICT	Whenever a resource conflict would be caused by fulfilling the request. Duplicate entries, deleting root objects when cascade-delete not supported are a couple of examples.
429	TOO MANY REQUESTS	Too many requests in a given amount of time, both global limits as well as per-resource and per-user limits apply. See rates.
500	INTERNAL SERVER ERROR	Catch-all error when the server-side throws an exception.

Rates

The API handles limits to the different resources on a per user and global rate for the whole site:

Rawdata & Counters:

• global: 60/minute; 800/hour
• per user: 3/second; 30/minute; 500/hour

Trips:

• global: 120/minute, 1600/hour
• per user: 6/second, 30/minute, 500/hour

Trips:

• global: 120/minute, 1600/hour
• per user: 6/second, 30/minute, 500/hour

Geofences:

• global: 1000/minute
• per user: 100/minute

Geofence Types

• global: 240/minute
• per user: 80/minute

Reversegeo

• global: 1200/minute, 15000/hour
• per user: 200/minute, 4200/hour

Other resources such as vehicles, groups, assets, etc. apply an anti DDOS (Distibuted Denial of Service) limit, which would only be reached if various machines spam the API.

Whenever you hit the limit the API returns a 429 Status Code. At which point it is important that your app suspends more subsequent requests to the API until the limit is reset.

{
  "reason": "vehicles",
  "message": "Rate exceeded",
  "limit": 10,
  "id": "ec2ec6e51a42f40d12e7009787d833b8",
  "value": 11.0455
}

> HTTP/1.1 429 TOO MANY REQUESTS
> Connection: keep-alive
> Content-Length: 135
> Content-Type: application/json
> Date: Sun, 30 Sep 2018 16:45:13 GMT
> Server: nginx
> X-Peg-Id: 1
> X-Peg-Server: F
> X-Peg-User-Id: 54
> X-RateLimit-Limit: 10
> X-RateLimit-Remaining: 0
> X-RateLimit-Reset: 1538325923


{reason: "vehicles", message: "Rate exceeded", limit: 10, id: "ec2ec6e51a42f40d12e7009787d833b8",…}

The API returns some response headers which include X-RateLimit-* keys so you know when it’s safe to make requests again.

The response on the right hand side tells us there’s a limit of 10 requests, and the client has 0 remaining, the limit resets back to 10 at the following epoch timestamp: 1445098790 - Sun Sep 30 2018 14:45:23 GMT

field	description
reason	resource that reached limit
message	description
limit	amount of request allowed
id	internal use
value	rate of requests

header	description
X-RateLimit-Limit	resource limit
X-RateLimit-Remaining	amount of requests that remain
X-RateLimit-Reset	when it’s safe to make more requests

Units

Server level caching is done on requests that are similar, therefore it’s important to specify the units of a request in order to make it as atomic as possible. By default the API uses the following units unless otherwise stated:

Metric	Unit
Distance	meter
Volume	liter
Time	second
Temperature	celsius

Speed and acceleration units vary per resource, but will normally take the form of

• distance_unit / time_unit
• distance_unit / time_unit / second

The API’s of Rawdata, Counters and Trips support unit paramaters, which can modify the output to the desired units.

Allowed values

The Gateway allows you to specify multiple values for each unit of measurement.

Metric	Allowed values
Distance	meter, km, mile
Volume	liter, gallon
Time	second, minute, hour
Temperature	C, F

You may also pass user for either the distance or volume parameters, where applicable. The API will return the values in accordance with the users preference.

Speed

Where applicable, the speed is determined by the distance and time units (default: meter/second)

The Counters and Trips API’s allows you to override this unit, by specifying one of kph , mph or user, where user falls back to either kph or mph based on the users distance preference (mile or km)

Acceleration

The acceleration field is always the speed units, per second

• meter/second/second
• mile/hour/second.

Timezone

List of available time zones
api/tz

curl https://cloud.pegasusgateway.com/api/tz? \
    --header 'Authenticate: 99ff984fbe2c90603da515cdb193fda3146c9c4c9a347bcf062b0760'

{"server_utc_epoch":1538478876.558243,"allowed":["Africa/Abidjan","Africa/Accra","Africa/Addis_Ababa","Africa/Algiers","Africa/Asmara","Africa/Bamako","Africa/Bangui","Africa/Banjul",...]}

The API by default returns all timestamps in UTC (GMT+0)

You can change the timestamp by passing a URL param tz or an HTTP header value with: "X-Time-Zone" : "time_zone_value"

&tz=America/New_York

"X-Time-Zone" : "America/New_York"

URL param

api/rawdata?vehicles=2600&fields=$basic&duration=P1D&tz=America/New_York

{
  "units": {
    "volume": "liter",
    "distance": "meter",
    "speed": "mph",
    "time": "second"
  },
  "events": [
    {
      "head": 291,
      "code": 0,
      "hdop": 0.82,
      "event_time": "2018-10-02T09:20:47",
      "type": 10,
      "vid": 2600,
      "lon": -72.50346,
      "sv": 9,
      "mph": 0,
      "label": "prdtst",
      "valid_position": true,
      "lat": 7.94937,
      "system_time": "2018-10-02T09:20:50.505475",
      "speed": 0,
      "id": 260012351115505,
      "device_id": 356612022409637
    }
  ]
}

HTTP Header

curl 'https://cloud.pegasusgateway.com/api/rawdata?vehicles=2600&fields=$basic&duration=PT1H' \
    --header 'X-Time-Zone: America/New_York' \
    --header 'Authenticate: 99ff984fbe2c90603da515cdb193fda3146c9c4c9a347bcf062b0760'

{"units": {"volume": "liter", "distance": "meter", "speed": "mph", "time": "second"}, "events": [{"head": 291, "code": 0, "hdop": 0.81999999999999995, "event_time": "2018-10-02T09:20:47", "type": 10, "vid": 2600, "lon": -72.503460000000004, "sv": 9, "mph": 0, "label": "prdtst", "valid_position": true, "lat": 7.94937, "system_time": "2018-10-02T09:20:50.505475", "speed": 0, "id": 260012351115505.0, "device_id": 356612022409637}]}

Authentication

Normal login

curl -X POST https://cloud.pegasusgateway.com/api/login \
    --header 'Content-Type: application/json' \
    -d '{"username":"developer@digitalcomtech.com",
        "password":"deV3lopErs"}'

{"message":"User successfully authenticated","app":null,"auth":"7ebbd199ecb10a156bdc189d3e0cd8ad9f9b676979deaaadca3612c0"}

Infinite token login

curl -X POST https://cloud.pegasusgateway.com/api/login \
    --header 'Content-Type: application/json' \
    -d '{"username":"developer@digitalcomtech.com",
        "password":"deV3lopErs", "scheme": "infinite"}'

{"message":"User successfully authenticated","app":null,"auth":"7ebbd199ecb10a156bdc189d3e0cd8ad9f9b676979deaaadca3612c0"}

POST api/login

Body

{
  "username": "developer@digitalcomtech.com",
  "password": "deV3lopErs"
}

Response

{
  "message": "User successfully authenticated",
  "app": null,
  "auth": "7ebbd199ecb10a156bdc189d3e0cd8ad9f9b676979deaaadca3612c0"
}

To authenticate with the API use the /login resource.

param	description
username	your username (email address)
password	your password
scheme	set to infinite to generate an infinite token
app	custom name to manage tokens
expires	expiration of token in seconds (default: 3600)

A successful login returns a token that has to be used on every subsequent request. Tokens expire after 60 minutes of no requests made with the token, unless you set the scheme to infinite.

The token that’s generated has to be sent on a header called Authenticate in order to retrieve data from the API.
Authenticate: 7ebbd199ecb10a156bdc189d3e0cd8ad9f9b676979deaaadca3612c0

When sending JSON make sure you use the following Content-Type header
Content-Type: application/json

Application tokens can be created to interact with the API, these tokens create a virtualized version of your user in order to interact with the API.

Application tokens

View tokens you have created

GET api/user/sessions

{
  "tokens": [
    {
      "origin": "--",
      "scopes": "groups=285&write=remote.output,tasks",
      "app": "myApp",
      "expires": 7183,
      "token": "9c56c37b52ff3b96ed0a501ac63e574fcb42c32a28c251c2a2033724",
      "app_scheme": "",
      "scheme": "finite"
    }
  ],
  "session": {
    "origin": "--",
    "scopes": "",
    "app": "None",
    "expires": 3600,
    "token": "7ebbd199ecb10a156bdc189d3e0cd8ad9f9b676979deaaadca3612c0",
    "app_scheme": "",
    "scheme": "normal"
  }
}

The application tokens can be managed using the user/sessions API, reference docs.

param	description
scheme	infinite or finite token
limit	limit of token in seconds
app	custom app name
scopes	url param format, params: groups allowing to write a csv of group IDs that the token will have access to, and any scope using the params write or read and setting these equal to a csv of the scopes you want to be able to write/read
app_scheme	pegasus application use only

Create a scoped application token

$ curl -X POST https://cloud.pegasusgateway.com/api/user/sessions \
    --header 'Content-Type: application/json' \
    --header 'Authenticate: 7ebbd199ecb10a156bdc189d3e0cd8ad9f9b676979deaaadca3612c0' \
    -d '{"scheme":"infinite","app":"myApp","scopes":"groups=285&write=remote.output,tasks"}'

Delete an application token

$ curl https://cloud.pegasusgateway.com/api/logout?auth=640c59b1df21aed608fe9cb775d56faaea9e33dd74730e31a94456e2 \
    --header 'Content-Type: application/json'

{"message": "Session terminated"}

Data receiver tokens

View receiver tokens you have created

GET api/tokens

{
    "origin": "--",
    "app": "my-app",
    "token": "89bfe5e6cbdd3696fd38d8d942e2def98253ae81256cfd15123456789",
    "app_scheme": "ips=12.12.12.12,13.13.13.13",
    "scheme": "infinite"
}

Create a receiver token

be sure to use an application token in the Authenticate header of the request to create the json receiver token

$ curl -X POST https://cloud.pegasusgateway.com/api/tokens \
    --header 'Content-Type: application/json' \
    --header 'Authenticate: 7ebbd199ecb10a156bdc189d3e0cd8ad9f9b676979deaaadca3612c0' \
    -d '{"resource":"receivers.json","app":"my-app","app_scheme":"ips=12.12.12.12,13.13.13.13"}'

{
    "origin": "--",
    "app": "my-app",
    "token": "89bfe5e6cbdd3696fd38d8d942e2def98253ae81256cfd15123456789",
    "app_scheme": "ips=12.12.12.12,13.13.13.13",
    "scheme": "infinite"
}

Delete a receiver token

curl -X DELETE https://cloud.pegasusgateway.com/api/tokens/89bfe5e6cbdd3696fd38d8d942e2def98253ae81256cfd15123456789 \
    --header 'Content-Type: application/json'

You can also create tokens for the data receiver endpoints, a requirement in order to start receiving data on your Pegasus Gateway from third party devices, reference docs.

param	description
resource	set to the data receiver (so far: receivers.json)
app	custom app name
app_scheme	url param format, params: ips which is a CSV of ip addresses to allow data from, and ips_blacklist when set to 1 the list of ips is treated as a blacklist.

Receiver token streams

You can view the incoming data requests that use specific tokens using token streams.

The request is a GET with the /api/tokens/:receiver_token/stream replacing :receiver_tokens with the actual receiver token.

View incoming data for the receiver token

GET api/tokens/:receiver_token/stream

{
    "size": 25,
    "items": [
        {
            "body": "[{\"vehicle.name\":\"red truck\",\"engine.hours\":4.59,\"position.altitude\":1453,\"position.heading\":179,\"position.hdop\":0.7,\"position.latitude\":6.322105,\"position.longitude\":-75.551478,\"position.satellites\":10,\"position.speed\":6,\"position.valid\":true,\"server.timestamp\":1631014478.971503,\"timestamp\":1630937864,\"vehicle.mileage\":112766.605}]",
            "url": "http://pegasus2.peginstances.com/json",
            "headers": "X-Client-Ip: 12.12.12.12\nContent-Length: 648\nAuthenticate: 89bfe5e6cbdd3696fd38d8d942e2def98253ae81256cfd15123456789\nConnection: Keep-alive\nHost: cloud.pegasusgateway.com\nContent-Type: application/json\n",
            "time": "2021-09-07 11:34:39+00:00",
            "method": "POST",
            "remote_ip": "12.12.12.12"
        },
        ...

Scopes

api/user

{
  "username": "developer@digitalcomtech.com",
  "scopes": {
    "sims": "r",
    "tasks": "w",
    "remote.phones": "w",
    "pindrops": "w",
    "remote.tracking_resolution": "w",
    "remote.gps_status": "w",
    "remote.diagnostic": "w",
    "users": "r",
    "vehicles.counters": "r",
    "geofences:visibility.all": "r",
    "groups.vehicles": "r",
    "remote.trigger_position_event": "w",
    "remote.safe_immo": "w",
    "remote.call": "w",
    "geofences": "w",
    "remote.output": "w",
    "remote.speed": "w",
    "remote.sms_alias": "w",
    "rawdata": "w",
    "remote.state": "w",
    "remote.ecu_console": "w",
    "remote.rpm": "w",
    "remote.outputsetlog": "w",
    "groups": "r",
    "remote.configuration": "w",
    "plugins.photocam": "w",
    "remote.fwupdate": "w",
    "remote": "w",
    "assets": "r",
    "geofences:visibility.groups": "r",
    "triggers": "w",
    "vehicles": "r",
    "devices": "r",
    "groups.assets": "r",
    "groups.users": "r",
    "remote.console": "w",
    "remote.mdt": "w",
    "plugins.garmin": "w",
    "plugins.lumeway": "w"
  }
}

A user’s access to the API resources is controlled by their what groups they belong to and the scopes they have assigned.

When a user belongs to a particular group they can see all the entities (vehicles, sims, assets, devices, etc) that group has associated.

Scopes are identified by the name of the resource and then the letter’s: r or w corresponding to their access level for that resource

r : read-only permissions : GET

w : read and write permissions : POST + PUT + DELETE

For example, a user with scopes: { "triggers": "r", "vehicles": "w" } has read permission for triggers and write permissions for vehicles allowing the user to only read triggers as well as create, edit, and delete vehicles

List of available scopes - resources/users/scopes

resource	permission	description	API
assets	read	see the assets (drivers, things, etc)	assets
assets	write	create and edit assets (drivers, things, etc)	assets
configurations	read	read the managed configurations	configurations
device.mute	read	view event mute status	devices
device.mute	write	mute device events	devices
devices	read	view devices	devices
devices	write	create devices is not available, contact support
entities.link	write	associate or deassociate two entities	entities
forwarders	read	view forwarder status	forwarders
forwarders	write	contact support to create forwarders
geofences	read	view own geofences	geofences
geofences	write	create and edit your own geofences	geofences
geofences:visibility	write	view public geofences	geofences
geofences:visibility.all	write	create public geofences	geofences
geofences:visibility.groups	write	create geofences for your group	geofences
groups	read	read the groups and its’ info	groups
groups	write	create and edit groups	groups
groups.assets	write	manage assets within your group	assets
groups.users	write	manage users within your group	users
groups.vehicles	write	manage vehicles within your group	vehicles
pindrops	write	create a pindrop (safe zone) around an entity	pindrops
plugins.garmin	read	see garmin jobs & messages	plugins.garmin
plugins.garmin	write	create garmin jobs and send garmin messages	plugins.garmin
plugins.lumeway	read	read the lumeway data	plugins.lumeway
plugins.lumeway	write	take a photo with the lumeway accessory	plugins.lumeway
plugins.photocam	read	see the photos	photos
plugins.photocam	write	take photos	photos
plugins.satcom	read	see satcom parameters	satcom
plugins.satcom	write	set satcom parameters	satcom
rawdata	read	get the vehicle’s rawdata	rawdata
remote	read	see the remote GET methods	remote
remote	write	ability to execute all remote commands	remote
remote.call	write	call an authorized number	remote
remote.configuration	write	set a managed configuration	remote
remote.console	write	send console (freestyle) commands	remote
remote.fwupdate	write	execute a firmware update	remote
remote.mdt	write	send mdt (serial port) messages	remote
remote.output	write	set an output	remote
remote.phones	write	authorize a number	remote
remote.rpm	write	set rpm threshold	remote
remote.safe_immo	write	execute a safe engine immobilization	remote
remote.sms_alias	write	set an sms_alias for actions	remote
remote.speed	write	set a speed limit threshold	remote
remote.tracking_resolution	write	set tracking resolution	remote
remote.trigger_position_event	write	query device’s live location	remote
routes	read	see entity routes	routes
routes	write	create routes	routes
sims	read	see the SIMs info	sims
tasks	read	view a task	tasks
tasks	write	create/edit a task	tasks
triggers	read	see the triggers assigned to your user	triggers
triggers	write	create and edit triggers	triggers
users.application_data	read	view permissions for other users	users
users.application_data	write	assign permissions for other users	users
users.password_reset	write	set or reset the password of other users	users
users	read	read the user’s info	users
users	write	create and edit the users	users
vehicles	read	read the vehicle list and it’s information	vehicles
vehicles	write	create and edit a vehicle	vehicles
vehicles.counters	read	read the vehicle’s counters	vehicle-counters
vehicles.counters	write	edit the global vehicle counters	vehicle-counters

Entities

returns the vehicle or asset for that id

[api/entities/:id]

returns vehicle’s name & device info

api/vehicles?select=name,device:*

return particular vehicle’s name & device’s network info

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

Entities are collections of vehicles and assets. Both these resources are interchangeable with respect to the data they collect and can report, in other words both vehicle’s and assets can have rawdata, trips, counters etc. Also, vehicle’s and assets can be associated to one another.

The API manages a concept of primary & secondary IDs when associating these entities.

A primary entity is the main device that’s reporting telemetry data, while a secondary entity is any peripheral or accompanying accessory that is related/associated to a primary entity, a classic example is a vehicle as a primary entity and a driver as a secondary entity.

Other resources which include collections of things are: devices, geofences, users, groups, sims.

All of the collections mentioned above support pagination, select, and search parameter.

select

The select parameter is used to filter the data that you are looking for from the resources.

For example if you want to select just the vehicle’s name api/vehicles?select=name

or the vehicle’s name and the device’s latest location api/vehicles?select=name,device:latest.loc

or the vehicle’s name, device location, online state, and sim information api/vehicles?select=name,device:latest.loc network connection

search

Search url param:

/api/vehicles?search.name="My car"

/api/vehicles?search.info.license_plate=ABC123

{
    "name": "My car",
    "info": {
      "license_plate": "ABC123",
      "year": "2014",
      "make": "Honda",
      "model": "CRV",
      ...
    },
    ...
}

The search parameter can be used to find specific key values within a set of resources. For example if you have custom properties per vehicle or geofences you can filter by that property. It works for vehicles, assets, groups, sims, geofences, tasks, triggers, geofence_types.

The way it works is that you define the key that you’re filtering for with a url param that begins with search. For finding specific keys within a json you can reach the key by separating the keys with a period . example:

the vehicle’s result with a json similar to this:

you can search for any vehicle that matches the name My car with api/vehicles?search.name=“My car”

you can search for any vehicle that is of make Honda with api/vehicles?search.info.make=Honda

you can also combine search, so search for red Hondas api/vehicles?search.info.make=Honda&search.info.color=red

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 api/vehicles?search.groups=[1,2,3]&select=name,device:latest.loc

or search by the license_plate api/vehicles?search.info.license_plate=ABC123&select=name,device:latest.loc

an example with a custom property on geofence could be api/geofences?search.properties.custom.random_key=value

Users

All users api/users

Particular user api/users/:id

Usernames & preferences only api/users?select=username,prefs

Users are identified by email. Usernames give access to both the Pegasus Platform GUI and to the API.

A User’s API access is controlled by scopes Their entities visibility is determinated by its groups’ membership.

More info

Own User

You can look at your own user with the following resource: api/user

api/user

this is helpful in determining what permissions/scopes you have access to as well as the groups of vehicles you are assigned. Note that administrators have "is_staff": true and will have access to all scopes.

Groups

All groups

api/groups

Particular group

api/groups/:id

Groups are identified by a unique ID and a user-defined name. Groups relate users, vehicles & assets. The most common usage is “a group per client”, but it’s flexible to serve other purposes:

• Sub-setting for Vehicle selections
• Sub-setting for Triggers-tasks
• Sub-setting for Forwarders

More info

Vehicles

All vehicles

api/vehicles

Particular vehicle

api/vehicles/:id

All vehicle’s info & last device communication

api/vehicles?select=info,device:last*

Vehicles are the main entity type. Remote interaction with a Syrus is done to its associated vehicle. 90% Of Automation triggers are triggered by vehicle events.

More info

Assets

Rawdata request that groups by asset id aid, shows the max speed daily per driver

api/rawdata?groups=500&duration=P3D&fields=$basic,aid&resample=event_time&how=mph:max,vid:first&freq=1D&group_by=aid

{
  "events": [
    {
      "aid": 672,
      "mph": 47,
      "vid": 598,
      "event_time": "2016-10-04T12:00:00"
    },
    {
      "aid": 791,
      "mph": 54,
      "vid": 759,
      "event_time": "2016-10-04T12:00:00"
    },
    {
      "aid": 791,
      "mph": 47,
      "vid": 759,
      "event_time": "2016-10-05T00:00:00"
    }
  ]
}

Assign a vehicle to an asset manually

curl -X POST https://cloud.pegasusgateway.com/api/entities/link \
  --header 'Content-Type: application/json' \
  --header 'Authenticate: 99ff984fbe2c90603da515cdb193fda3146c9c4c9a347bcf062b0760' \
  -d '{"primary_id": 2600, "secondary_id": 691}'

Assets are entities that can provide a relationship between a device and an accessory, this makes them very valuable when you want to assign a driver to a vehicle for example.

The accessories that are compatible with assets are iButton, Fingerprint readers, Bluetooth tags, RFIDs and Taurus. An example use case is that the asset is assigned a unique iButton id. Whenever that unique iButton id is read by any device, that device will instantly be associated to that asset.

The typical application for an asset is for assigning a driver to a vehicle.

There are two ways to associate an asset & a vehicle together, the first is manually with the api/entities/link

The second method is with the device automatically reporting an iButton ID, Fingerprint ID, Bluetooth Tag MAC address, RFID or Taurus token and associating it to an existing asset. To do this:

First, you create an asset POST /assets

Second, you associate the unique iButton ID, Bluetooth Tag MAC, Fingerprint ID, RFID or enable the Taurus Token

Third, you present the particular iButton ID, RFID or MAC address near the device

And that’s it, afterwards the vehicle’s device will be assigned that asset until another iButton or something else takes it place.

This opens up the possibilities of making requests with asset informations. The following fields would be available:

aid or asset ID

Thus when you want to create a rawdata request, and you’d like to resample and group_by a field, you can now group_by the asset ID, thereby allowing you to have rawdata requests per asset or driver.

Associations

• iButton
• Bluetooth Tags

Devices

All devices

api/devices

Particular device

api/devices/:imei

All device’s inputs & outputs state

api/devices?select=ios_state

Device’s latest data reported

api/devices/:imei?select=latest

Device’s latest location data only

api/devices?select=latest.loc

Devices refer to any of the device’s in the DCT ecosystem, a vehicle can only have one device assigned at any one time. This vehicle-device association may change over time (unit replacement) but it will always be a one to one relationship. You may see an association history of the vehicle’s / IMEIs when you make an api/vehicles/:id request

The device’s API is very powerful and full of information related to the current status of the device, it always represents the last information that the device reported.

More info

SIMs

Get all sims GET api/sims

• /api/sims which is for any SIM

The SIMs resource is self populated, there is no method for adding SIMs to the API, the action of reading and adding a SIM to the API is performed automatically by the devices as soon as they connect to the server.

There are some IDs to keep in mind when working with SIMs resources

• id or resource_id - refers to the API’s ID for that sim, starts at 1 and increments per sim
• iccid - refers to the unique Integrated Circuit Card Identifier or 20 digit SIM’s id, example: 8901260852291475879

/api/sims

Get particular sim iccid 20 digit SIM ID resource_id API ID GET api/sims/[:iccid] GET api/sims/[:resource_id]

Configure the line number PUT api/sims/:resource_id

{
  "line_number": "+1234567890"
}

The /api/sims resource has methods for placing a line number to a particular sim, this method works over the resource’s id, not the actual 20 digit SIM ID

Rawdata

Raw data consists of a list of observations within a queried time range. The rawdata API allows you to retrieve data, with a high degree of flexibility. You can transform fields to your liking, perform small calculations, and resample data.

For large data sets, the request can be delegated to a job. This will significantly improve the chances of retrieving the data set, circumventing timeouts and potential network issues.

The rawdata api has several query params that can be passed to specify the data need.

Param	Description
from	Date from YYYY-MM-DD[Thh:mm:ss]
to	Date to YYYY-MM-DD[Thh:mm:ss]
duration	ISO_8601 Duration format (PnYnMnDTnHnMnS, PnW, PT) (ex: P1D = Past 1 Day)
vehicles	Vehicles to get data from
groups	Groups to get data from
fields	Which data fields do you want to include
exclude	Exclude the following fields
types	Event types to search for
labels	Filter by the following labels, which are for describing the event generated
codes	Filter by event code (not recommended, use labels instead)
distance	unit to return distance values in (default: meters)
volume	unit to return volume values in (default: liters)
time	unit to return time values in (defalut: second)
speed	unit to return speed values in (default: distance_unit/time_unit)
raw	Show the rawdata format
filter	Create a custom filter for the results
resample	Activate resampling, can only be event_time or system_time
freq	Resampling frequency, required for resampling.
how	resampling method to use, defaults to ‘mean’.
fill	How to fill empty rows after resampled (pad, ffill, bfill)
group_by	group events by specific fields before resampling.
order	Order the results by a particular field
head	Get top n events from result
tail	Get bottom n events from result
export	Export the data to json (default), html, csv, or tsv
async	Run the report in the background (returns a job id)

##Fields

Get a list of all rawdata fields

/api/resources/rawdata/keys

{
  "keys": {
    "io_exp_in1": {
      "short_desc": "exp in1",
      "long_desc": "I/Os expander input 1",
      "type": "boolean",
      "group": "IO related"
    },
    "code": {
      "short_desc": "EVC",
      "long_desc": "GPS Event code reported by 'EV' msg",
      "type": "number",
      "group": "Event identification"
    },
    "ecu_distance": {
      "short_desc": "VDist",
      "long_desc": "Vehicle dashboard odometer reported by ECUMon [m]",
      "type": "number",
      "group": "ECU monitor accessory related"
    },
    "ecu_idle_fuel": {
      "short_desc": "IFuel",
      "long_desc": "Fuel consumed in IDLE. Rep. by ECUMon [L x10]",
      "type": "number",
      "group": "ECU monitor accessory related"
    },
    "cf_rssi": {
      "short_desc": "rssi",
      "long_desc": "GSM Cell rssi (0-31)",
      "type": "number",
      "group": "Communication related"
    },
    "pid": {
      "short_desc": "Pegasus ID",
      "long_desc": "Pegasus site ID",
      "type": "number",
      "group": "Site identification"
    }
  }
}

The rawdata api allows you to select fields from the pegasus’ events table. Simply pass the fields parameter to the request with the fields you want.

To view a list of all the fields available to you, perform an empty GET request on the rawdata resource

By default all rawdata requests come with

• system_time
• event_time
• id
• vid

To select fields, simply pass them to fields parameter

/rawdata?fields=comdelay,speed,cf_rssi,hdop,dev_dist...

You may also pass a JSON array to the fields parameter, this allows for higher flexibility when doing complex transformations.

/rawdata?fields=["dev_ign","dev_idle","cf_rssi","hdop","dev_dist"]

For a list of the rawdata fields please refer to the

Master Fields List

For a more detailed list of the rawdata fields please refer to:

Pegasus API Fields

Sets

you can pass sets, which are a group of fields (ex. basic, counters, network, photo …) as part of the fields parameter preceeded by $

/rawdata?fields=$basic,$network

Exclude

If you want to bring some parts of a set or sets, it may be better to include the whole set, and then exclude what you dont want. In order to do this you can pass the excludes parameter.

/rawdata?fields=$basic&excludes=speed,mph

The excludes paramater also supports regular expressions, this allows you to exclude multiple fields at once: For example, bring all device counters and exclude all ecu counters

/rawdata?fields=$counters&exclude=$ecu.*^

Instead of:

/rawdata?fields=dev_dist,dev_idle,dev_ign,dev_ospeed,dev_orpm...

Transformations

In addition to selecting fields, you can rename and create new fields.

A rawdata transformation that renames rssi, latitude, and longitude
https://cloud.pegasusgateway.com/api/rawdata?vehicles=197&duration=P1D&fields=latitude:@lat,longitude:@lon,rssi:@cf_rssi,speed,head

{
  "head": 9,
  "vid": 197,
  "event_time": "2018-10-16T22:12:20",
  "system_time": "2018-10-16T22:12:24.412584",
  "longitude": -75.49467,
  "latitude": 10.35501,
  "rssi": 28,
  "speed": 0,
  "id": 5014678489
}

Renaming Fields

To rename a field, simply pass the name you want, and the field it is renaming referenced with @ and separated by a :

renamed_field:@field

odometer:@dev_dist

You can do as many of these as you want.

/rawdata?fields=rssi:@cf_rssi,satellites:@sv,gps_quality:@hdop

###Building fields

Rawdata request with a simple operator
https://cloud.pegasusgateway.com/api/rawdata?vehicles=1674&from=2018-10-05&to=2018-10-09&fields=ratio:@lat/@lon,lat,lon

{
  "system_time": "2018-10-05T00:06:40.998478",
  "ratio": -0.3205509899,
  "vid": 1674,
  "event_time": "2018-10-05T00:06:21",
  "lon": -80.16553,
  "lat": 25.69714,
  "id": 5014187981
}

Rawdata request that has more operators and manipulations
https://cloud.pegasusgateway.com/api/rawdata?vehicles=1674&from=2018-10-06&to=2018-10-07&fields=kph:@speed,mph,vehicle_battery_volts:@ecu_battery/1000,communication_delay:(@system_epoch-@event_epoch),centimeters_per_second:@mph44.704,speed_in_knots:@mph0.868976

{
  "system_time": "2018-10-06T15:51:02.014862",
  "vid": 1674,
  "event_time": "2018-10-06T15:50:58",
  "communication_delay": 4.0148599148,
  "mph": 7,
  "speed_in_knots": 6.082832,
  "centimeters_per_second": 312.928,
  "kph": 11.26538,
  "vehicle_battery_volts": null,
  "id": 5014260288
}

You can also use basic arithmetic operations to build new fields:

Divide the latitude by the longitude

ratio:@lat/@lon

or subtract epoch timestamps for the time the event was received by the time the event was generated.

comdelay:@system_epoch-@event_epoch

Remember, you can also use numbers in the transformations, for example to get the km reported by dev_dist:

km:@dev_dist/1000

vehicle_battery_volts:@ecu_battery/1000

centimeters_per_second:@mph*44.704

knots:@mph*0.868976

Casting Fields

You can also concatenate strings

/rawdata?fields:["custom:'text_to_prepend'%2B@field__str"]

Example:

/rawdata?fields:["google:'https://google.com/maps?q=' %2B @lat__str %2B ',' %2B @lon__str"]

Note that the + sign is URL encoded in the request as %2B, this is required in order for the parser to work.

/rawdata?vehicles=2600&duration=P1D&fields=%5B%22$basic%22,%22google:%27https://google.com/maps?q=%27%20%2B%20@lat__str%20%2B%20%27,%27%20%2B%20@lon__str%22%5D&distance=km&volume=liter&time=second&speed=kph&order=vid,event_time,system_time&tz=America/New_York

If you get a validation error, make sure the castings match! How? Simply append one of

• __str
• __int
• __float

Rawdata request that casts the speed as a string

https://cloud.pegasusgateway.com/api/rawdata?vehicles=1674&from=2018-10-05&to=2018-10-09&fields=speed_as_string:@speed__str,speed&speed=kph

{
  "system_time": "2018-10-06T16:36:54.534108",
  "vid": 1674,
  "event_time": "2018-10-06T16:36:45",
  "speed_as_string": "20.92142",
  "speed": 20.92142,
  "id": 5014261769
}

Example combining everything above

Results in the daily total hours with the engine on, distance traveled, last location, etc.

api/rawdata?vehicles=1673&fields=["DATE_LAST_REPORTED…

{
  "events": [
    {
      "vid": 1673,
      "event_time": "2019-01-09T00:00:00",
      "LAST_LAT": 25.74485,
      "HOURS_IDLING": 0,
      "LAST_LON": -80.22526,
      "LOCATION": "https://google.com/maps?q=25.74485,-80.22526",
      "HOURS_OF_OPERATION": 0.6,
      "DISTANCE_TRAVELED_KM": 22.2,
      "DATE_LAST_REPORTED": 1547075815000
    },
    {
      "vid": 1673,
      "event_time": "2019-01-10T00:00:00",
      "LAST_LAT": 25.78423,
      "HOURS_IDLING": 0,
      "LAST_LON": -80.29391,
      "LOCATION": "https://google.com/maps?q=25.78423,-80.29391",
      "HOURS_OF_OPERATION": 0.4,
      "DISTANCE_TRAVELED_KM": 11.1,
      "DATE_LAST_REPORTED": 1547116807000
    }
  ]
}

Filtering

Rawdata request filtered by events with valid positions
https://cloud.pegasusgateway.com/api/rawdata?vehicles=197&from=2018-10-30T08:00:00&to=2018-10-30T23:59:59&fields=mph,valid_position&filter=valid_position

{
  "system_time": "2018-10-30T12:03:08.701770",
  "vid": 197,
  "event_time": "2018-10-30T12:03:05",
  "mph": 1,
  "valid_position": true,
  "id": 5002929550
}

Rawdata request filtered by events with valid positions and mph > 30
https://cloud.pegasusgateway.com/api/rawdata?vehicles=197&from=2018-10-30T08:00:00&to=2018-10-30T23:59:59&fields=mph,valid_position&filter=valid_position+and+mph>30

{
  "system_time": "2018-10-30T12:03:08.701770",
  "vid": 197,
  "event_time": "2018-10-30T12:03:05",
  "mph": 1,
  "valid_position": true,
  "id": 5002929550
}

Rawdata request with a filter that shows events after 8 with speeds greater than 20 and valid positions
https://cloud.pegasusgateway.com/api/rawdata?vehicles=197&from=2018-10-10T08:00:00&to=2018-10-11T23:59:59&fields=mph,valid_position,event_hour&filter=system_hour>8+and+(speed>20+and+valid_position)

{
  "system_time": "2018-10-10T09:14:59.506056",
  "vid": 197,
  "event_time": "2018-10-10T09:14:57",
  "mph": 28,
  "valid_position": true,
  "id": 5014414518,
  "event_hour": 9
}

The rawdata allows you to filter fields that meet a certain criteria. Using the filter field on the request, you can pass complex boolean logic that meets your criteria.

You can apply boolean logic to filter the desired results, available operators:

>, < , >= , <=, ==, !=, and, or, not

Some examples:

valid_position and speed > 30

label == "spd" and mph < 50

(lat < -4 and lat > -5) and ( lon < -74 and lon > -75 )

system_hour == 7 and (system_minute > 0 and system_minute < 30)

speed > 50

A more complex example:

(event_wkday == 3) and cf_rssi < 10 and ( event_hour > 7 and event_hour < 17)

Which translates to: get all events on wednesdays between 7AM and 5PM with an cf_rssi value less than 10 (low GSM signal)

Codes

You can further filter by looking at individual event codes generated, event codes depend on the managed configuration of the device.

Rawdata request of only event codes 4 and 47 https://cloud.pegasusgateway.com/api/rawdata?vehicles=1674&from=2018-09-30T08:00:00&to=2018-09-30T23:59:59&fields=$basic&filter=speed+%3E+10&codes=4,47

{
  "ecu_battery": null,
  "head": 7,
  "code": 47,
  "hdop": 1.16,
  "event_time": "2018-09-30T14:14:46",
  "ecu_distance": null,
  "vid": 1674,
  "lon": -80.16431,
  "sv": 7,
  "mph": 16,
  "label": "agglnchng",
  "valid_position": true,
  "type": 10,
  "lat": 25.69373,
  "system_time": "2018-09-30T14:14:49.760305",
  "speed": 16,
  "id": 5014039405,
  "device_id": 357042060068252
}

Label

GET labels api/labels

{
  ...
  "spd": {
    "edited_at": "2017-07-21T13:56:49.184650+00:00",
    "en": "Speeding:The vehicle has exceeded the speed limit continuously for more than the threshold configured",
    "created_at": "2017-07-21T13:56:49.184766+00:00",
    "label": "spd",
    "es": "Exceso de velocidad:El vehiculo ha excedido el limite de velocidad continuamente por mas del umbral configurado"
  },
  ...
}

Filtering by labels allows you ask for all the specific events across your fleet, no matter the configuration of the device. Labels are shared for every configuration, so you can ask for all the aggressive lane changes and speeding events for all your vehicles, regardless of the configurations of the devices.

For more information about labels please visit: labels

Rawdata request from group 500 with speeding and aggressive lane change events https://cloud.pegasusgateway.com/api/rawdata?groups=500&from=2018-09-30T08:00:00&to=2018-09-30T23:59:59&fields=$basic&filter=speed>10&labels=agglnchng,spd

{
  "head": 191,
  "code": 47,
  "hdop": 0.75,
  "event_time": "2018-09-30T11:40:30",
  "type": 10,
  "vid": 1673,
  "lon": -80.20623,
  "sv": 12,
  "mph": 22,
  "label": "agglnchng",
  "valid_position": true,
  "lat": 25.82955,
  "system_time": "2018-09-30T11:40:36.382065",
  "speed": 22,
  "id": 5014035611,
  "device_id": 357042060068740
}

Types

Rawdata request for maximum speed (metric==2) in driving metric events (types=12)
https://cloud.pegasusgateway.com/api/rawdata?vehicles=1674&from=2018-10-01T00:00:00&to=2018-10-10T23:59:59&fields=metric,metric_value&filter=metric==2&order=metric&types=12&speed=mph

{
  "system_time": "2018-10-01T16:10:13.464688",
  "metric_value": 20,
  "vid": 1674,
  "metric": 2,
  "event_time": "2018-10-01T16:08:47",
  "id": 5014071812
}

Events reported by the devices are classified by types, the most common type is 10, which means it’s a regular GPS event. There are other useful types for example 12, which gives you the driving metric values of the vehicles (Max Acceleration, Deceleration and Speed per trip) In order to filter by types simply state:

types=12

Type	Description
10	EV TAIP regular events (GPS Type)
11	PV TAIP position & velocity (GPS Type)
12	RXAIT driving metrics (GPS Type)
13	GPS BackLog (GPS Type)
20	empty GPS Event (gps time = 0)
100	Keep-alive (Connection Type)
110	XART TAIP (Connection Type)
111	XARS SIM Card Operator notice (Connection Type)
150	Message
301	Duplicate GPS Event (Other Type)

Ordering

Rawdata request ordered by code (increasing), and mph (decreasing)
https://cloud.pegasusgateway.com/api/rawdata?groups=500&fields=$basic&duration=PT4H&order=code,-mph

{
  "head": 102,
  "code": 3,
  "hdop": 1.48,
  "event_time": "2018-10-17T23:24:02",
  "type": 10,
  "vid": 1483,
  "lon": -80.44694,
  "sv": 4,
  "mph": 0,
  "label": "ignoff",
  "valid_position": true,
  "lat": 25.66764,
  "system_time": "2018-10-17T23:24:05.677751",
  "speed": 0,
  "id": 5014716545,
  "device_id": 356612026170920
}

You can also order the resulting data set however you choose. Simply pass the order field to the request

order=mph

This will order the events by mph in ascending order. but what about ascending?

Simple just append a -, to the field you want to order

order=-mph

What about multilevel ordering? Sure thing, no problem:

order=vid,-mph

This will return all events sorted by vehicle id (vid) and then by speed in descending order

Limiting

Rawdata request that limits the results to the first two and last 3 events
https://cloud.pegasusgateway.com/api/rawdata?groups=500&fields=$basic&duration=PT4H&order=code,-mph&filter=code%3E1%20and%20code%3C10&head=2&tail=3

{
  "head": 280,
  "code": 8,
  "hdop": 0.64,
  "event_time": "2018-10-17T22:43:00",
  "type": 10,
  "vid": 909,
  "lon": -83.85399,
  "sv": 13,
  "mph": 0,
  "label": "slwtrfc",
  "valid_position": true,
  "lat": 10.25766,
  "system_time": "2018-10-17T22:43:03.888619",
  "speed": 0,
  "id": 5014715284,
  "device_id": 356612026180218
}

By default the rawdata request will return all the events that match your criteria.

What if you want to see the first x events. Simply pass the head argument to the request

head=100

Will return the top 100 events from the set.

Want to see the last n events? pass tail as the argument.

tail=100

Want both? How about the first 100 and bottom 50 events?

head=100&tail=50

You can even pass negative values to hide the first or last rows, for example, tail=-1 removes the first row, and head=-1 removes the last row.

Resampling

Returns the difference in all counters (max-min), resampled at 1 day intervals and grouped by vids from November 1 . This gives you the total distance traveled, ignition on time, etc. per day per vehicle
https://cloud.pegasusgateway.com/api/rawdata?vehicles=617,654&fields=$counters&from=2015-11-01T00:00:00&to=2015-11-10T00:00:00&filter=(valid_position+and+hdop+<+3)&how=$counters:diff&freq=1D&group_by=vid&resample=event_time

{
  "dev_dist": 72542,
  "vid": 909,
  "ecu_dist": 72421,
  "event_time": "2015-11-09T00:00:00",
  "dev_idle": 21069,
  "dev_orpm": 8151,
  "dev_ospeed": 0,
  "ecu_ifuel": 19.4,
  "ecu_tfuel": 212.4,
  "ecu_eusage": 36900,
  "ecu_eidle": 14400,
  "dev_ign": 40823
}

Returns the mean value of all comdelays and the mean value of the RSSI (signal strength) sampled at 1 day intervals, grouped by vehicle IDs
https://cloud.pegasusgateway.com/api/rawdata?vehicles=617,654&fields=$basic,comdelay,rssi_avg:@cf_rssi&from=2015-11-1T00:00:00&to=2015-11-10T00:00:00&filter=(comdelay+<+3600)&how=comdelay:mean,rssi_avg:mean&freq=1D&group_by=vid&resample=event_time

{
  "comdelay": 155.2830875629,
  "rssi_avg": 15.835443038,
  "event_time": "2015-11-01T00:00:00",
  "vid": 617
}

Resampling is an important part of data analysis, timed data can be normalized to evenly timed chunks.

Events that pass through the Pegasus Gateway naturally contain time noticermation.

These fields are:

• event_time : time reported by the device.
• system_time: time the event was processed by the gateway.

The Rawdata API allows you to resample data based on either one of these.

There are 5 fields important to resampling.

• resample : timed field to use in resampling (event_time or system_time)
• freq : Frequency you want to resample to (ex. by day, by month, every 30 seconds, etc)
• how : Method to use for resampling, defaults to mean (ex. sum, diff, min, max …)
• fill : How to fill gaps in the data set. ffill, pad, bfill
• group_by : group events by field(s) before performing resample. (useful for multiple vehicles)

###resample

Used to activate resampling. Can only be event_time or system_time.

###freq Establishes the frequency by which to resample. Must meet the format:

• NF

where N is equal to a number greater than 0. and F can be one of:

• M : Months
• D : Days
• H : Hours
• T : Minutes
• S : Seconds

###how Determines how to resample the data, based on the frequency established. This must be one of.

• sum
• mean : Average of values
• std : Standard deviation of values
• sem : MISSING
• max
• min
• median
• first
• last
• diff : range of values, max-min

You can also resample different fields by different methods. Simply pass the fields as a csv, with the transformation you want separated by :

field:method

how=dev_dist:diff,cf_rssi:mean,hdop:mean,hdop:max,vdop:min

want to apply the same resample method to a set? Simply:

how=$counters:diff

###group_by You can also group the events before performing a resample. this is useful if you want to keep events tied to a specific field, such as the vehicles id (vid).

group_by:vid

You can additionally group by more than one field:

group_by:vid,label

Output Formats

Export as HTML
https://cloud.pegasusgateway.com/api/rawdata?vehicles=197&from=2015-10-30T08:00:00&to=2015-10-30T23:59:59&fields=vid,lat,lon&export=html

event_time	id	label	lat	lon	vid
2015-10-30T12:03:05	5002929550	trckpnt	9.80091	-74.76004	197
2015-10-30T12:08:06	5002929669	trckpnt	9.80670	-74.73022	197

By default, events come in a JSON envelope under the events property.

The rawdata API also allows you to export in other formats:

• JSON (default)
• CSV
• TSV
• HTML table

Simply pass the export parameter on the request

export=html

Need another format? Send us a message on our Gitter or create an issue on our github

Asynchronous Requests

An asynchronous requests that generates a job id to be queried later
https://cloud.pegasusgateway.com/api/rawdata?vehicles=197&from=2015-09-30T08:00:00&to=2015-09-30T23:59:59&fields=ecu_battery,ecu_distance&filter=speed>10&async=true

{
  "message": "Job created",
  "job_id": 28813
}

While the job is being processed in the background you can see the progress under /jobs/:job_id
https://cloud.pegasusgateway.com/api/jobs/28813

{
  "control": "run",
  "stdout": "",
  "app": "pegasus2.0",
  "notice": null,
  "id": 28813,
  "user_id": 1,
  "state": "queued",
  "params": {
    "all": false,
    "event_groups": null,
    "labels": null,
    "raw": false,
    "export": null
  ...
}

Once the job is finished you can see the data here
https://cloud.pegasusgateway.com/api/jobs/28813/data.json

[
  {
    "code": 1,
    "device_id": 356612022409637,
    "ecu_battery": 13350,
    "ecu_distance": 269302153,
    "event_time": "2015-09-30T14:59:06",
    "hdop": 0.94,
    "head": 225,
    "id": 5002464983,
    "label": "",
    "lat": 4.61529,
    "lon": -74.10331,
    "mph": 11,
    "speed": 11,
    "sv": 8,
    "system_time": "2015-09-30T14:59:09.565434",
    "type": 10,
    "valid_position": true,
    "vid": 197
  }
]

Results returned by the rawdata API can get big, and we mean big. This can bring up all sorts of issues when using via a web browser.

These include but are not limited to:

• Connection issues (timeouts, disconections)
• Lack of processing power on client machine (try parsing a 500MB JSON file on chrome)

In order to circumvent these issues, and guarantee that data is always retreived as requested. You can leave the query and subsequent processes (transformations, filtering and resampling) running in the background.

The async flag delegates the rawdata request to a Job to ensure the data is stored and can be safely used and reused

Simply set the async flag on the request

async=1

The request immediately returns a job ID you can query the job ID to see the progress of the rawdata request /api/jobs/:jobid

When the job finishes you can see the by accesing the jobs data Data is stored depending on your export format.

For JSON (default) /api/jobs/:jobid/data.json

For CSV, TSV, and HTML /api/jobs/:jobid/data.{export_format}

Counters

The rawdata API allows for extreme flexibility when browsing events.

Perhaps the most frequent use case for the rawdata API, is a resampling of a vehicle(s) counters over a period of time.

For example, to view how much the vehicle’s counters changed over a large period, such as a month for example, you would make a request such as :

GET api/rawdata?vehicles=2600&duration=P1M&fields=$counters&resample=event_time&how=$counters:diff&freq=1M&group_by=vid

This would give you values such as the total distance covered, total time driving, total amount of fuel used for that month. For a more in depth view, such as what happened each day of that month, you would adjust the freq parameter to your liking. such as 1D.

Given this frequent use case, we provide a separate, specialized API for browsing counters which automatically does the resampling for you.

The counters API has nearly all of the functionality of the rawdata API, along with some added fields.

Here is a list of the paramateres accepted by the counters API.

Parameter	Description
from	Date from YYYY-MM-DD[Thh:mm:ss]
to	Date to YYYY-MM-DD[Thh:mm:ss]
duration	ISO_8601 Duration format (PnYnMnDTnHnMnS, PnW, PT) (ex: P1D = Past 1 Day)
vehicles	Vehicles to get data from
distance	unit to return distance values in (default: meters)
volume	unit to return volume values in (default: liters)
time	unit to return time values in (defalut: second)
speed	unit to return speed values in (default: distance_unit/time_unit)
groups	Groups to get data from
filter	Create a custom filter for the results
delta	fragment size.
order	Order the results by a particular field
head	Get top n events from result
tail	Get bottom n events from result
export	Export the data to json (default), html, csv, or tsv
round	Round the results to ‘x’ number of decimal places (1-10)
async	Run the report in the background (returns a job id)

You may override the speed values to either kph, mph, or user.

A speed preference of ‘user’ establishes either kph or mph based on the users distance preference (km or mile respectively)

Introduction

api/counters

{
    ...
    "base": {
        "dev_dist": "Distance reported by Syrus",
        "ecu_ifuel": "Fuel spent while idling, reported by ECU monitor",
        "ecu_eidle": "Idle time reported by ECU monitor",
        "ecu_dist": "Distance reported by ECU monitor",
        "dev_ign": "Engine time reported by Syrus",
        "dev_idle": "Idle time reported by Syrus",
        "dev_orpm": "Time with engine in high RPM's, reported by Syrus",
        "ecu_eusage": "Engine usage time reported by ECU Monitor",
        "dev_ospeed": "Time overspeeding, reported by Syrus",
        "ecu_tfuel": "Total fuel speng, reported by ECU monitor"
    },
    "derived": {
        "dev_tot_avg_speed": "Total average speed, Syrus. dev_dist/dev_ign",
        "ecu_tra_avg_speed": "Traveling average speed, ECU. ecu_dist/(ecu_eusage-ecu_eidle)",
        "ecu_tot_fuel_efcy": "ECU calculated Fuel efficiency. ecu_dist/ecu_tfuel",
        "ecu_tra_fuel_efcy": "ECU calculated Traveling fuel efficiency. ecu_dist/(ecu_tfuel-ecu_ifuel)",
        "dev_tra_fuel_efcy": "Syrus calculated Traveling fuel efficiency. dev_dist/(ecu_tfuel-ecu_ifuel)",
        "dev_tra_avg_speed": "Traveling average speed, Syrus. dev_dist/(dev_ign-dev_idle)",
        "ecu_fuelp_idling": "Fuel percentage used while idling. ecu_ifuel*100/ecu_tfuel",
        "ecu_tot_avg_speed": "Total average speed, ECU. ecu_dist/ecu_eusage",
        "dev_tot_fuel_efcy": "Syrus calculated Fuel efficiency. dev_dist/ecu_tfuel"
    }
}

Pegasus keeps track of various internal counters for each vehicle. The counters are an absolute value that always increase over time.

The counters api is used for knowing time, distance, and volume information for any vehicle within a given time range.

The default units for distance, time, and volume are meters, seconds, and liters respectively.

Sources for the counters

• Syrus [dev_*]
• ECU Monitor [ecu_*] (Accessory)

The source of the data is controlled by the managed configuration on the device. The ECU Monitor provides data from the computer onboard the vehicle, whether OBDII or J1939/1708.

Counter field	Description
dev_dist	Traveled distance
dev_ign	Ignition time
dev_idle	Time in idle
dev_ospeed	Time spent speeding
dev_orpm	Time spent over RPM threshold
ecu_dist	Engine Distance
ecu_eusage	Engine Ignition
ecu_eidle	Engine Idling
ecu_tfuel	Fuel consumption
ecu_ifuel	Idle fuel consumption

Considering these as base counters. The Pegasus API provides derived calculated counters:

Derived field	Description
dev_tot_avg_speed	Total average speed, Syrus.
dev_tra_avg_speed	Traveling average speed, Syrus.
dev_tot_fuel_efcy	Syrus calculated Fuel efficiency.
dev_tra_fuel_efcy	Syrus calculated Traveling fuel efficiency.
ecu_tot_avg_speed	Total average speed, ECU.
ecu_tra_avg_speed	Traveling average speed, ECU.
ecu_tot_fuel_efcy	ECU calculated Fuel efficiency.
ecu_tra_fuel_efcy	ECU calculated Traveling fuel efficiency.
ecu_fuelp_idling	Fuel percentage used while idling.

Browser

The counters API encapsulates some of the complexities that the rawdata provides, in order to streamline the counters information.

The counters API supports two main use cases.

• Retrieving the absolute difference between two dates for each vehicle 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)

Absolute Changes

Total counter values for month of November

api/counters?vehicles=2600&from=2018-11-01T00:00:00&to=2018-11-30T23:59:59

{
    "units": {
        "volume": "liter",
        "distance": "meter",
        "speed": "meter/second",
        "time": "second"
    },
    "counters": [
        {
            "ecu_dist": 7285823,
            "vid": 2600,
            "ecu_ifuel": 49.6,
            "dev_tot_avg_speed": 9.7753377857,
            "from": "2018-10-31T23:59:49",
            "dev_idle": 188131,
            "ecu_eidle": 75960,
            "ecu_fuelp_idling": 1.3752564742,
            "to": "2018-11-30T23:00:00",
            "ecu_eusage": 662760,
            "ecu_tot_avg_speed": 10.9931543847,
            "ecu_tfuel": 3606.6,
            "ecu_tra_avg_speed": 12.4161946149,
            "dev_orpm": 54301,
            "dev_tra_fuel_efcy": 2049.6412707338,
            "ecu_tot_fuel_efcy": 2020.1361393002,
            "ecu_tra_fuel_efcy": 2048.3055946022,
            "dev_dist": 7290574,
            "dev_ign": 745813,
            "dev_tra_avg_speed": 13.0729950043,
            "dev_tot_fuel_efcy": 2021.4534464593,
            "dev_ospeed": 23452
        }
    ]
}

To view a vehicle’s metrics over a period of time, simply pass the vehicles or groups parameter, along with a from and to date or a duration.

Like in the rawdata api, the to parameter is defaulted to the time the request is made

The resources return an envelope with the units, and counters for the given time range.

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

Fragmented changes

Daily counters requests for the past 30 Days
api/counters?vehicles=2600&duration=P30D&delta=1D

{
    "units": {...},
    "counters": [
        {
            "ecu_dist": 179603,
            "vid": 2600,
            "ecu_ifuel": 1.4,
            "dev_tot_avg_speed": 5.8565823033,
            "from": "2018-11-01T00:00:54",
            "dev_idle": 10879,
            "event_time": "2018-11-01T00:00:00",
            "dev_ospeed": 269,
            "ecu_fuelp_idling": 0.7769145394,
            "to": "2018-11-01T22:30:10",
            "ecu_eusage": 22860,
            "ecu_tot_avg_speed": 7.8566491689,
            "ecu_tfuel": 180.2,
            "ecu_tra_avg_speed": 8.67647343,
            "dev_orpm": 0,
            "dev_tra_fuel_efcy": 1001.7114093959,
            "ecu_tot_fuel_efcy": 996.6870144283,
            "ecu_tra_fuel_efcy": 1004.4910514541,
            "dev_dist": 179106,
            "dev_ign": 30582,
            "dev_tra_avg_speed": 9.0902908187,
            "dev_tot_fuel_efcy": 993.9289678135,
            "ecu_eidle": 2160
        },
        {
            "ecu_dist": 8047,
            "vid": 2600,
            "ecu_ifuel": 0.9,
            "dev_tot_avg_speed": 1.8951807229,
            "from": "2018-11-02T00:30:10",
            "dev_idle": 2906,
            "event_time": "2018-11-02T00:00:00",
            "dev_ospeed": 0,
            "ecu_fuelp_idling": 12.676056338,
            "to": "2018-11-02T22:18:52",
            "ecu_eusage": 4320,
            "ecu_tot_avg_speed": 1.8627314815,
            "ecu_tfuel": 7.1,
            "ecu_tra_avg_speed": 2.6297385621,
            "dev_orpm": 0,
            "dev_tra_fuel_efcy": 1268.5483870956,
            "ecu_tot_fuel_efcy": 1133.3802816892,
            "ecu_tra_fuel_efcy": 1297.9032258053,
            "dev_dist": 7865,
            "dev_ign": 4150,
            "dev_tra_avg_speed": 6.3223472669,
            "dev_tot_fuel_efcy": 1107.7464788723,
            "ecu_eidle": 1260
        },
        ...
    ...
}

You can also query the counters API for subranges, similar to the resampling frequency in the Rawdata API (freq paramater). This allows you to get multiple data points per request.

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.

This however, is not an optimal request. Since it requires multiple requests to complete,and may also trigger the rate limiter.

In order to circumvent this, you could instead request the counters API for a fragmented snapshot of the counters.

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)

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

Vehicle Counters

The counters mantained by pegasus are absolute, meaning they always increase. In order to facilitate the upkeep of virtual odommeters. Pegasus allows you to see counters per vehicle, globally and shared per vehicle.

Global vehicle counters

Global vehicle counters for vehicle 1716
api/vehicles/1716/counters

{
  "user": [],
  "vehicle": {
    "plain": {
      "counter_io_exp_in1": 0,
      "counter_io_exp_in2": 0,
      "counter_io_exp_in3": 0,
      "counter_io_exp_in4": 0,
      "counter_io_exp_out1": 0,
      "counter_io_exp_out1_short": 0,
      "counter_io_exp_out2": 0,
      "counter_io_exp_out2_short": 0,
      "counter_io_exp_out3": 0,
      "counter_io_exp_out3_short": 0,
      "counter_io_exp_out4": 0,
      "counter_io_exp_out4_short": 0,
      "counter_io_in1": 0,
      "counter_io_in2": 0,
      "counter_io_in3": 0,
      "counter_io_out1": 29129.0,
      "counter_io_out2": 0,
      "dev_dist": 123889,
      "dev_idle": 2665418,
      "dev_ign": 2692667,
      "dev_orpm": 0,
      "dev_ospeed": 3286
    },
    "calculated": {},
    "counters": {}
  }
}

Updating the global vehicle dev_dist (odometer) counter for vehicle 1716

PUT api/vehicles/197/counters

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

You can view a vehicles counters by inspecting the vehicle

GET /api/vehicles/:vid/counters

Updating Vehicle Counters

Let’s say you want to edit the vehicle’s distance counter to match the odometer on your car, simply make a

PUT /api/vehicles/:vid/counters

where the body of the request is the name of the counter and value

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

Note that once you make this change the device will have to report another event in order for the change to be reflected in the /counters API.

This change will only update the rawdata vehicle_'s counters (in this case vehicle_dev_dist to 123,456,789 meters), the raw dev_, ecu_, counter_io counters (dev_dist, dev_idle, counter_io_out1, etc.) are not changed and these will remain the same.

So to summarize when you edit a vehicle’s counter using the /counters api you will trigger an update on the equivalent vehicle_'s counter in the rawdata api, and it will start incrementing from that point forward.

counter	value units (these units are fixed)
dev_dist	meters
ecu_dist	meters
dev_ign	seconds
dev_idle	seconds
dev_ospeed	seconds
ecu_ifuel	liters
ecu_eusage	seconds
ecu_eidle	seconds
ecu_tfuel	liters
counter_tamper	seconds
counter_io_in1	seconds
counter_io_in2	seconds
counter_io_in3	seconds
counter_io_out2	seconds
counter_io_out1	seconds
counter_io_exp_in1	seconds
counter_io_exp_in2	seconds
counter_io_exp_in3	seconds
counter_io_exp_in4	seconds
counter_io_exp_out1	seconds
counter_io_exp_out2	seconds
counter_io_exp_out3	seconds
counter_io_exp_out4	seconds
counter_io_exp_out1_short	seconds
counter_io_exp_out2_short	seconds
counter_io_exp_out3_short	seconds
counter_io_exp_out4_short	seconds

Shared User Counters

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

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

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

Create

Create a shared counter that starts counting distance starting at 123 from the moment it’s created
POST api/vehicles/197/counters

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

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

Updating Shared User Counters

In order to update a shared user counter you create, you can make a PUT request to the specific counter id: PUT /api/vehicles/:vid/counters/:id

the body of the request is the name of the counter, description, initial_value

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

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

Trips

Request the trips for a vehicle
https://cloud.pegasusgateway.com/api/trips?vehicles=45&from=2015-12-25T10:05:00&to=2015-12-25T11:00:00&fields=distance,mean_speed,duration,moving,start_time&distance=km&time=minute&speed=kph

[
    {
        "distance": 13.405,
        "mean_speed": 43.28,
        "start_time": "2015-12-25 10:04:05",
        "moving": true,
        "duration": 18.58
    },
    {
        "distance": 0,
        "mean_speed": 0,
        "start_time": "2015-12-25 10:22:40",
        "moving": false,
        "duration": 5.87
    },
    {
        "distance": 25.33,
        "mean_speed": 36.49,
        "start_time": "2015-12-25 10:28:32",
        "moving": true,
        "duration": 41.65
    }
]

With the trips api we can get summarized data about a collection of events over a time span grouped in a convenient and natural way.

For each vehicle’s trip we can request for example the summary for counters changes and have information of important trip’s events (like for maximum speed).
This information is already calculated and stored for each trip, so it is much more efficient to get this kind of data using the trips api than the more general rawdata or counters api, and of course you don’t have to deal with how to partition the raw data to get trips’ information.

These are the currently supported query params to get trips data:

Param	Description
ids	Trips of interest
from	Time from YYYY-MM-DD[Thh:mm:ss]
to	Time to YYYY-MM-DD[Thh:mm:ss]
duration	ISO_8601 Duration format (PnYnMnDTnHnMnS, PnW, PT) (ex: P1D = Past 1 Day)
vehicles	Vehicles to get data from
fields	Which data fields do you want to include
contained	Whether to return only fully contained trips within ‘from’ and ‘to’
distance	unit to return distance values in (default: meters)
volume	unit to return volume values in (default: liters)
time	unit to return time values in (default: second)
speed	unit to return speed values in (default: distance_unit/time_unit)
export	format to export the trips data (csv or tsv)

##Fields

View the trips keys/fields and their description
https://cloud.pegasusgateway.com/api/trips/keys

{
    "mean_speed": {
        "units": "meter/second",
        "short_desc": "Mean speed",
        "long_desc": "Mean speed calculated with trip's distance and duration values",
        "type": "number"
    },
    "duration": {
        "units": "second",
        "short_desc": "Trip duration",
        "long_desc": "‘Total duration of the trip",
        "type": "number"
    },
    "distance": {
        "units": "meter",
        "short_desc": "Trip distance",
        "long_desc": "Preferred trip distance (ecu_dist or dev_dist)",
        "type": "number"
    },
    ...
}

Request only the units and the type for the trip keys https://cloud.pegasusgateway.com/api/trips/keys?data=units,type

{
    "mean_speed": {
        "units": "meter/second",
        "type": "number"
    },
    "duration": {
        "units": "second",
        "type": "number"
    },
    "distance": {
        "units": "meter",
        "type": "number"
    },
    ...
}

Getting the resource trips/keys you can check for the available fields definitions for the trips.

For this resource you can optionally request the data of interest, eg:

GET https://cloud.pegasusgateway.com/api/trips/keys?data=units,type

The available options for the data parameter are:

• all (default)
• none
• type
• short_desc
• long_desc
• units

When data=none then no data for the fields is requested and only an array of available fields names is returned.

> View the distance, duration, ignition time, idle time and the average speed per trip
> https://cloud.pegasusgateway.com/api/trips?from=2016-10-17&to=2016-10-18&vehicles=598,599&fields=distance,duration,ignition,idle,mean_speed

{
  "mean_speed": 13.17,
  "duration": 3483,
  "idle": 0,
  "distance": 45876,
  "ignition": 3483
}

When getting trips, if the fields parameter is undefined, then all available trips’ fields data will be returned by default.
You can request for a specific subset of trip information by defining the fields paramater.

GET /trips?fields=moving,distance,mean_speed,duration...

GET /trips?fields=["moving","distance","mean_speed","duration"]...

Notice that one of the possible fields is the `moving` trip's property. This flag indicates if the trip object corresponds to a *"trip"* or an *"stop"*.
This is offered like this because in the more general use case we want to get the events summary and partitioning within a time range, so both types (*trips* and *stops*) are returned.

Routes

Reference docs

The routes API is useful for creating paths on a map that can be used to know if an entity passed through the path and reached a set destination at any point in time. Routes are comprised of 2 or more checkpoints. The first and last checkpoints are known as the origin and destination checkpoints, they are required to have a time. The origin’s time is also known as the time of departure and the destination time the time of arrival.

Routes can be scheduled to repeat on a daily basis. Each checkpoint within a route can also have a minimum and maximum duration.

When the route’s time of departure starts (based on the timezone given and the first checkpoints time) the entity’s progress is recorded in the route_state API, and once it reaches any checkpoints either by location or the scheduled time of arrival expires, the location of the entity is recorded, once the entity leaves a checkpoint that’s not the last one it’s also recorded.

Multiple routes can be assigned to the same entity, and the status of multiple routes can be updated simultaneously.

Create routes

Create a route

POST api/entities/:id/routes

{
  "active": true,
  "name": "Pick up package",
  "checkpoints": [
    {
      "name": "First checkpoint",
      "buffer": 150,
      "lat": 25.78363,
      "lon": -80.29349
    },
    {
      "name": "Arrival",
      "buffer": 158,
      "lat": 25.79587,
      "lon": -80.27858
    }
  ],
  "schedules": [
    {
      "active": true,
      "timezone": "America/New_York",
      "repeat": "Sun",
      "checkpoints": [
        {
          "time": "12:05"
        },
        {
          "time": "12:30"
        }
      ]
    }
  ]
}

Reference docs

Routes are created within the entities api, POST /entities/:id/routes

Required parameters

• active - true if the route is active or not
• checkpoints - array of 2 or more checkpoints
  • lat - latitude
  • lon - longitude
  • buffer - radius (meters)
• schedules - times of departures and arrivals of the checkpoints
  • active - true if schedule is active or not
  • timezone - timezone
  • repeat - time of the week which the route will repeat
  • checkpoints - array of the times and durations per checkpoint
    • time - time for checkpoint (HH:mm)

Optional parameters

• name - name of the route
• enforce - true if the route is enforced (relevant for alerts)
• color - HEX code for the color of the route
• description - notes or descriptions of the route
• checkpoints
  • name - for each checkpoint
• schedules
  • checkpoints
    • min_duration - minimum duration in minutes
    • max_duration - maximum duration in minutes
    • mandatory - true if the checkpoint is mandatory
  • valid_until - timestamp in which the route will go inactive (YYYY-MM-DDTHH:mm:ss.000Z)
• path - object with a path for the entity to follow as it goes through the destination
  • buffer - radius of the path (meters)
  • encoding - polyline encoded path

Route states

get an entities’ route states

/route_states?entities=:id

[
  {
    "is_outside_path": false,
    "name": "Client visit route",
    "finalized": true,
    "route_end": "1903121725",
    "start_epoch": 1552410000,
    "updated_at": 1552415585.2653241,
    "route_id": 60,
    "end_epoch": 1552411500,
    "finalized_cpt": 6,
    "checkpoints": [
      {
        "max_duration": 0,
        "mandatory": null,
        "name": "Departure",
        "finalized": true,
        "geometry": [
          -80.293308917201387,
          25.78377829683669,
          50
        ],
        "min_duration": 0,
        "time": 1552410000,
        "id": "cpt.start",
        "events": {
          "entered": {
            "system_time_epoch": 1552403066.3740399,
            "gpsknit_prev_lat": 25.783390000000001,
            "gpsknit_prev_event_time__epoch": 1552395072.0,
            "lon": -80.293149999999997,
            "label": "slpoff",
            "gpsknit_prev_lon": -80.293149999999997,
            "lat": 25.783390000000001,
            "id": 147726267731374,
            "event_time_epoch": 1552403035.0
          },
          "last": null,
          "exited": {
            "system_time_epoch": 1552410955.968734,
            "gpsknit_prev_lat": 25.783390000000001,
            "gpsknit_prev_event_time__epoch": 1552410920.0,
            "lon": -80.293329999999997,
            "label": "mblybrkon",
            "gpsknit_prev_lon": -80.293149999999997,
            "lat": 25.78332,
            "id": 147726275620968,
            "event_time_epoch": 1552410932.0
          }
        }
      },
      {
        "max_duration": 5,
        "mandatory": null,
        "name": "Discovery HQ",
        "finalized": true,
        "geometry": [
          -80.302509975325123,
          25.783440582343367,
          87
        ],
        "min_duration": 3,
        "time": 1552410180,
        "id": "cpt.1",
        "events": {
          "entered": null,
          "last": null,
          "exited": null
        }
      },
      {
        "max_duration": 0,
        "mandatory": null,
        "name": "7th Street",
        "finalized": true,
        "geometry": [
          -80.301271314153468,
          25.777856051122349,
          97
        ],
        "min_duration": 0,
        "time": 1552410300,
        "id": "cpt.2",
        "events": {
          "entered": {
            "system_time_epoch": 1552411068.2377181,
            "gpsknit_prev_lat": 25.77758,
            "gpsknit_prev_event_time__epoch": 1552411057.0,
            "lon": -80.300820000000002,
            "label": "mblyspd",
            "gpsknit_prev_lon": -80.299199999999999,
            "lat": 25.77758,
            "id": 147726275733237,
            "event_time_epoch": 1552411066.0
          },
          "last": null,
          "exited": {
            "system_time_epoch": 1552411088.8534629,
            "gpsknit_prev_lat": 25.777660000000001,
            "gpsknit_prev_event_time__epoch": 1552411068.0,
            "lon": -80.304209999999998,
            "label": "aggdrv",
            "gpsknit_prev_lon": -80.301230000000004,
            "lat": 25.777699999999999,
            "id": 147726275753853,
            "event_time_epoch": 1552411083.0
          }
        }
      },
      {
        "max_duration": 0,
        "mandatory": null,
        "name": "Miliam Diary Rd",
        "finalized": true,
        "geometry": [
          -80.31160340384308,
          25.777633864577687,
          62
        ],
        "min_duration": 0,
        "time": 1552410420,
        "id": "cpt.3",
        "events": {
          "entered": null,
          "last": null,
          "exited": null
        }
      },
      {
        "max_duration": 0,
        "mandatory": null,
        "name": "12 Sth & 826",
        "finalized": true,
        "geometry": [
          -80.32114148139955,
          25.782763849356652,
          95
        ],
        "min_duration": 0,
        "time": 1552410600,
        "id": "cpt.4",
        "events": {
          "entered": {
            "system_time_epoch": 1552411389.4811511,
            "gpsknit_prev_lat": 25.78192,
            "gpsknit_prev_event_time__epoch": 1552411382.0,
            "lon": -80.320800000000006,
            "label": "trckpnt",
            "gpsknit_prev_lon": -80.320869999999999,
            "lat": 25.782399999999999,
            "id": 147726276054481,
            "event_time_epoch": 1552411384.0
          },
          "last": null,
          "exited": {
            "system_time_epoch": 1552411396.8575439,
            "gpsknit_prev_lat": 25.782399999999999,
            "gpsknit_prev_event_time__epoch": 1552411384.0,
            "lon": -80.321089999999998,
            "label": "mblyhdwrn",
            "gpsknit_prev_lon": -80.320800000000006,
            "lat": 25.784420000000001,
            "id": 147726276061857,
            "event_time_epoch": 1552411395.0
          }
        }
      },
      {
        "max_duration": 0,
        "mandatory": null,
        "name": "12 Street & 84 AVE",
        "finalized": true,
        "geometry": [
          -80.33194627365593,
          25.782811673477919,
          100
        ],
        "min_duration": 0,
        "time": 1552410960,
        "id": "cpt.5",
        "events": {
          "entered": null,
          "last": null,
          "exited": null
        }
      },
      {
        "max_duration": 0,
        "mandatory": null,
        "name": "Arrival",
        "finalized": true,
        "geometry": [
          -80.335345403836939,
          25.784850600179006,
          50
        ],
        "min_duration": 0,
        "time": 1552411500,
        "id": "cpt.end",
        "events": {
          "entered": null,
          "last": null,
          "exited": null
        }
      }
    ],
    "path": {
      "buffer": 80,
      "encoding": "q{j|CnkaiNnBCNtb@ElEVjD[bBvA_BjHCbT]CbIp@~H?rO~CnSR~JsDuCgBbGaMbN{FlIgEhEUrR^rUOrg@WjDqM@?hTZB?i@"
    },
    "route_start": "1903121700",
    "exited_path": false,
    "color": "#FFC107"
  }
]

The /route_states api is given one or many entity IDs and it returns the current status and a history of all the routes and their states. The parameter finalized is used to indicate whether the route’s time of arrival has expired or the entity has reached it’s final checkpoint. Once that value is true the rest of the object does not get updated. Thus representing the last state of the route at the time of completion.

The following results are after the route is finalized

Returned results

• name - name of the route
• color - color of the route
• exited_path - null, means that it was never inside the path, true means that it was at one point outside the route’s path, false means that it stayed in route’s path at all time
• finalized - true if the time of arrival expired or the entity reached its last checkpoint
• finalized_cpt - checkpoint progress, increases by one every time the checkpoints are finalized
• is_outside_path - true if the entity was outside the path.
• route_start - scheduled time of the start of the route YYMMDDHHMM (in route’s timezone)
• start_epoch - scheduled start time of the route as an epoch
• route_end - scheduled time of the end of the route YYMMDDHHMM (in route’s timezone)
• end_epoch - scheduled end time of the route as an epoch
• route_id - specific id for an entity’s route
• checkpoints - array of the checkpoints for the routes
  • geometry - lon, lat, and radius of the checkpoint
  • id - identifier of the checkpoint cpt.start, cpt.#, or cpt.end
  • events - obect with events that correspond to the entrance / exit of an entity to a checkpoint
    • entered - checkpoint was visited with this info
    • exited - checkpoint exited with this info

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Viewing routes

/api/entities/:id/routes

[
  {
    "edited_at": "2019-01-11T13:13:46.809564+00:00",
    "__updated": 1547212426.899816,
    "uuid": "KGRwMApTJ3BhdGgnCnAx",
    "color": "#CD0A0A",
    "created_at": "2018-10-26T01:54:00.751951+00:00",
    "description": "",
    "id": 18,
    "primary_id": 1673,
    "options": {},
    "checkpoints": [
      {
        "lat": 25.74513,
        "buffer": 204,
        "lon": -80.12540,
        "name": "Departure"
      },
      {
        "lat": 25.78412,
        "buffer": 108,
        "lon": -80.29345,
        "name": "Arrival"
      }
    ],
    "schedules": [
      {
        "active": true,
        "timezone": "America/New_York",
        "repeat": "Mon,Tue,Wed,Thu,Fri",
        "valid_until": null,
        "checkpoints": [
          {
            "max_duration": 0,
            "min_duration": 0,
            "optional": false,
            "time": "8:00"
          },
          {
            "max_duration": 0,
            "min_duration": 0,
            "optional": false,
            "time": "8:35"
          }
        ]
      }
    ],
    "active": true,
    "path": {
      "buffer": 95,
      "encoding": "ajc|Cx_thNsGjA^zViXdAEtWrBraC`IfjAoD?jCv}Bqi@tA{dDtEuGr^_Eo@"
    },
    "enforce": null,
    "name": "Daily weekday route"
  }
]

Reference docs

To view a list of the routes assigned to an entity you can use the /entities/:id/routes api

Edit a route

updating a route’s times (hour later)

PUT api/entities/:id/routes/:id

{
    "edited_at": "2019-01-11T13:13:46.809564+00:00",
    "__updated": 1547212426.899816,
    "uuid": "KGRwMApTJ3BhdGgnCnAx",
    "color": "#CD0A0A",
    "created_at": "2018-10-26T01:54:00.751951+00:00",
    "description": "",
    "id": 18,
    "primary_id": 1673,
    "options": {},
    "checkpoints": [
        {
            "lat": 25.74513,
            "buffer": 204,
            "lon": -80.225409999999997,
            "name": "Client 1"
        },
        {
            "lat": 25.784120000000001,
            "buffer": 108,
            "lon": -80.293450000000007,
            "name": "Destination"
        }
    ],
    "schedules": [
        {
            "active": true,
            "timezone": "America/New_York",
            "repeat": "Mon,Tue,Wed,Thu,Fri",
            "valid_until": null,
            "checkpoints": [
                {
                    "max_duration": 0,
                    "min_duration": 0,
                    "optional": false,
                    "time": "9:00"
                },
                {
                    "max_duration": 0,
                    "min_duration": 0,
                    "optional": false,
                    "time": "9:35"
                }
            ]
        }
    ],
    "active": true,
    "path": {
        "buffer": 95,
        "encoding": "ajc|Cx_thNsGjA^zViXdAEtWrBraC`IfjAoD?jCv}Bqi@tA{dDtEuGr^_Eo@"
    },
    "enforce": null,
    "name": "Pick up package"
}

Reference docs

A route can be edited to update just about anything as long as the finalized parameter is not marked as true.

To update a route go to that specific route ID for a particular entity and update it

Delete a route

delete a route

DELETE api/entites/:id/routes/:id

When deleting a route you have to pass it the route ID.

Automation

Trigger categories

GET /api/resources/triggers/structure

{
      "structure": {
        "site": {
              "status": {
                "rule_keys": [],
                "key": "pid"
            },
            "notification": {
                  "rule_keys": [],
                "key": "pid"
            },
            "$default": "pid"
        },
        "user": {
              "access": {
                    "rule_keys": [],
                "key": "id"
            },
            "$default": "uid"
        },
        "vehicle": {
              "device-diagnostic": {
                    "rule_keys": [],
                "key": "vehicle"
            },
            "$default": "vid",
            "event": {
                  "rule_keys": [
                        "ac",
                    "ad",
                    ...                    
                    "vid",
                    "vo"
                ],
                "key": "vid"
            },
            "counter": {
                  "rule_keys": [
                        "dev_dist",
                    "dev_idle",
                    "dev_ign",
                    "dev_orpm",
                    "dev_ospeed",
                    "ecu_dist",
                    "ecu_eidle",
                    "ecu_eusage",
                    "ecu_ifuel",
                    "ecu_tfuel"
                ],
                "key": "vehicle"
            }
        }
    }
}

Automation allows you to create specific conditions (rules), using boolean logic that apply to specific categories within the api.

The categories exposed so far are vehicle_events and counters, they can be found in /api/resources/triggers/structure.

The combination of one or more rules and any subsequent action performed is called a trigger.

Triggers

Trigger operators

GET /api/resources/triggers/rules

{
    "rules": {
        "postfix": {},
        "special": {
            "inside_fence": [...],
            "within": [...],
            "exited_fence": [...],
            "entered_fence": [...],
            "delta": [...],
            "delta+": [...],
            "delta-": [...],
            "outside_fence": [...]
        },
        "standard": [
            ">=",
            "==",
            "<=",
            "!=",
            "<",
            ">"
        ]
    }
}

To create a vehicle_events trigger the structure shows that we can use any of the rule_keys which are the fields that a device reports to the Gateway and apply logic to the values received, these fields operate over the key defined in the structure, which is the vehicle id: vid.

rules is an array of objects that represent the conditions for firing the trigger, they consist of:

• key (from rule_keys)
• operator (from standard and special)
• value (value for the rule)
• id (name of the rule)

Example that’s true when the label reported by the device is idl (Idling)

{
  "id": "idling",
  "key": "label",
  "operator": "==",
  "value": "idl"
}

Create a trigger

Step 1: Create an empty trigger with: name, type, and category

POST /api/triggers

{
      "name": "My special trigger",
    "description": "Simple trigger template",
    "type": "event",
    "category": "vehicle",
    "rules": [],
    "postfix": [],
    "vehicles": [],
    "options": {}
}

Step 2: Create the rule(s) for activating the trigger Triggers can contain multiple rules, although in most cases a few will suffice.

PUT /api/triggers/:id

{
      "name": "My special trigger",
    "description": "Trigger template with rules",
    "type": "event",
    "category": "vehicle",
    "timezone": "America/New_York",
    "rules": [
          {
                "id": "moving",
            "key": "mph",
            "operator": ">=",
            "value": 20
        },
        {
              "id": "input1_press",
            "key": "io_in1",
            "operator": "==",
            "value": true
        }
    ],
    "postfix": [],
    "vehicles": [],
    "options": {}
}

Step 3: Give the rules some logic in the postfix

The logic is combined in a post fixed notation syntax using “and”, “or”, “not”. Post-fixed notation means that the rule’s IDs are placed first, and the operator is at the end of the rule ids to be evaluated, the rule’s id and the operators are separated by a comma.

When only 1 rule is used, the postfix just needs the name of the ID used on the trigger rule.

PUT /api/triggers/:id

{
      "name": "My special trigger",
    "description": "Trigger for moving and input 1 pressed",
    "type": "event",
    "category": "vehicle",
    "timezone": "America/New_York",
    "rules": [
          {
                "id": "moving",
            "key": "mph",
            "operator": ">=",
            "value": 20
        },
        {
              "id": "input1_press",
            "key": "io_in1",
            "operator": "==",
            "value": true
        }
    ],
    "postfix": ["moving","input1_press","and"],
    "vehicles": [],
    "options": {}
}

Step 4: Assign the vehicles or groups that will be applied to the trigger

PUT /api/triggers/:id

{
      "name": "My special trigger",
    "description": "Trigger for moving and input 1 pressed on group 123 & vehicle id: 1673",
    "type": "event",
    "category": "vehicle",
    "timezone": "America/New_York",
    "rules": [
          {
                "id": "moving",
            "key": "mph",
            "operator": ">=",
            "value": 20
        },
        {
              "id": "input1_press",
            "key": "io_in1",
            "operator": "==",
            "value": true
        }
    ],
    "postfix": ["moving","input1_press","and"],
    "groups": 123,
    "vehicles": [1673],
    "options": {}
}

Step 5: Verify that the trigger generated reaches the trigger logs

Make sure the conditions are met and check the trigger logs api for results, you can use the full param to see all the details of the trigger generated

GET /api/trigger_logs?from=2020-06-01&triggers=123&full=1

{
      "category": "vehicle",
    "trigger_snapshot": {},
    "level": null,
    "tuuid": "71df2610-ae6a-11ea-8fe8-062dc07e7ac3",
    "fields": {},
    "object_snapshot": {},
    "pid": 1,
    "object_id": 1673,
    "trigger": 123,
    "time": 1592158278.843752,
    "type": "event",
    "day": 20200614
}

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Special operator

Special operators

{
    "rules": {
        "special": {
            "inside_fence": [
                "fences",
                "types"
            ],
            "within": [
                "collection"
            ],
            "exited_fence": [
                "fences",
                "types"
            ],
            "entered_fence": [
                "fences",
                "types"
            ],
            "delta": [
                "value",
                "start",
                "end",
                "pre",
                "post",
                "freq"
            ],
            "delta+": [
                "value",
                "start",
                "end",
                "pre",
                "post",
                "freq"
            ],
            "delta-": [
                "value",
                "start",
                "end",
                "pre",
                "post",
                "freq"
            ],
            "outside_fence": [
                "fences",
                "types"
            ]
        }
    }
}

The special operators are:

operator	description
within	True for a value found within an array of values
inside_fence	True while the event generated is inside a geofence, or geofence_type
outside_fence	True while the event generated is outside a geofence, or geofence_type
exited_fence	True when the event generated goes from inside to outside of the geofence or geofence_type
entered_fence	True when the event generated goes from outside to inside of the geofence or geofence_type
delta	True when a positive or negative incremental value matches
delta+	True when a positive incremental value matches
delta-	True when a negative incremental value matches

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Rules with special operators:

within

{
    "id": "out1_or_out2",
    "key": "label",
    "operator": "within",
    "value": [
        "out1on",
        "out2on"
    ]
}

inside_fence

Note: when using the fence related operators you must define a key, in this case we can set it to "lat" (latitude) always

{
    "operator": "inside_fence",
    "id": "in_geo",
    "value": {
        "fences": [
            164
        ],
        "types": [
            123
        ]
    },
    "key": "lat"
}

delta+

{
    "id": "hourmeter_1hr",
    "operator": "delta+",
    "key": "vehicle_dev_ign",
    "value": {
        "value": "3600",
        "start": "10000",
        "end": "0",
        "pre": "1200",
        "post": "1800",
        "freq": "600"
    }
}

delta+

The delta+ operator can be used to notify when a device reports in increments of a particular value. The only field required is the value which is the value that it’s going to be true every.

The delta+ operator can be customized with the following fields:

field	description
value	Value that it’s true every
start	Start at a particular value
end	End at a particular value
pre	True this much before the value
post	True this much after the value
freq	True every this much between pre and post values

For example, assuming we’re using the key dev_dist.

Notify every 10,000 km

• "value": 10,000,000 (meters)

Notify every 10,000 km from 40,000 to 60,000 km

• "value": 10,000,000
• "start": 40,000,000
• "end": 60,000,000

Notify every 10,000 km from 40,000 to 60,000 km and notify every 1,000 km, 5,000 km before and 6,000 km after the 10,000 km.

• "value": 10,000,000
• "start": 40,000,000
• "end": 60,000,000
• "pre": 5,000,000
• "post": 6,000,000
• "freq": 1,000,000

Since the odometer won’t hit exactly 10,000 km the trigger will fire the first time the value passes 10,000 km.

Trigger processes (actions)

Trigger processes are the actions performed once a trigger’s posfix rules have been met. The process can be sending an email, generating a report, consuming the API, making a voice call, text message, send a POST to any resource, etc.

Send an email

{
    "processes": [
        [
            "email_event",
            {
                "destinations": [
                    "john@email.com",
                    "luke@email.com"
                ]
            }
        ]
    ]
}

Consume resource

{
    "processes": [
        [
            "consume_resource",
            {
                "headers": {
                    "Content-Type": "application/json"
                },
                "resource": "http://50.232.21.70/api/2d1c0bf32ecc934f26c5ceeb2558dac7/lights/1/state",
                "method": "put",
                "template": "{\"on\":true, \"sat\":254, \"bri\":254,\"hue\":65535}"
            }
        ]
    ]
}

Geofences

Geofences are user defined areas on the map that can be used together with triggers and tasks for a more personalized experience, for example to let you know when a vehicle reaches a particular location on the map. Geofences are also available when you request the reversegeo information so it’s included in the address response.

Geofences can be grouped into geofence_types (also referred to as geofence collections)

The geofence API is based on the geojson spec, for more information on geojson visit geojson.org

Please note that this api is paginated.

Reference docs

View

Reference docs

In order to view geofences you have to have the scope geofences assigned to your user.

All geofences are encoded using a lossy compression algorithm.

All geofences will also have a bbox, or bounding box.

Create

Create a circular fence of 105 meter radius around 24.78238, -82.28900

Assign a custom property to this geofence

POST api/geofences

{
    "type": "Feature",
    "geometry": {
        "type": "Circle",
        "radius": 105,
        "coordinates": [
            -82.289,
            24.78238
        ]
    },
    "properties": {
        "name": "warehouse 234",
        "visibility": "groups",
        "groups": [
            500
        ],
        "custom": {
            "foo": "bar",
            "something": true
        },
        "types": [],
        "description": "this is a sample description"
    }
}

Create a square polygon geofence

Associated to geofence_type 55

POST api/geofences

{
    "type": "Feature",
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    -81.07642,
                    26.38707
                ],
                [
                    -80.96106,
                    26.27383
                ],
                [
                    -81.11487,
                    26.21471
                ],
                [
                    -81.23023,
                    26.29353
                ],
                [
                    -81.07642,
                    26.38707
                ]
            ]
        ]
    },
    "properties": {
        "name": "Square Polygon",
        "visibility": "all",
        "types": [
            55
        ],
        "description": "Warehouse with small packages"
    }
}

Reference docs

When creating a geofence you have to specify the Geometry type you want to create, the API supports Polygon of 3 or more coordinates (up to 800 coordinates), Circle, or LineString types.

Polygon
geometry.coordinates = [[[lon1,lat1] ,[lon2,lat2],[lon3,lat3], [lon1,lat1]]]

Circle
geometry.radius = radius in meters (minimum 50 meters)
geometry.coordinates = [lon,lat]

LineString
geometry.radius = radius in meters
geometry.coordinates = [[lon1,lat1],[lon2,lat2]]

when creating geofences you can specify custom properties using the custom key in the properties. This accepts any JSON object value.

The visibility of the geofences are as follow:

visibility	description
all	anyone with scope to see geofences has access to see them
groups	only people within the group you belong to have access to see the geofence
private	only your user has access to see the geofence

If you set the visibility to “groups” you’ll have to specify in an array called: groups the group IDs you’d like this geofence to belong to.

Updating Geofences

Update name, radius, and add a custom property

PUT api/geofences/:id

{
    "type": "Feature",
    "geometry": {
        "type": "Circle",
        "radius": 52,
        "coordinates": [
            -80.289000061596184,
            25.78238262858029
        ]
    },
    "properties": {
        "name": "Warehouse 3",
        "custom": {
            "contact": "John Smith",
            "amount": 123
        }
    }
}

Reference docs

When updating a geofence using the API, pass the geometry and properties object.

Deleting Geofences

Delete a fence

DELETE /api/geofences/:id

204 NO CONTENT

Reference docs

Geofence Types

Reference docs

Geofence types are collections of geofences, a geofence can belong to one or many types. These collections are useful for quickly generating reports and scheduling them too.

For example, let’s say that you have a fleet of delivery trucks that make daily deliveries to specific locations. These locations can be saved as a geofence_type called: Clients. Thus when generating a trigger for Vehicle Inside Geofence and Idling for example, you want to create a single trigger that encompasses the Clients geofence type we created, rather than individual fences. Note that any future geofences you add to the Client type automatically gets updated.

Create

Create a geofence type

{
  "name": "Clients",
  "color": "#ff0404",
  "visibility": "groups",
  "groups": [5],
  "geofences": [
    25,
    1042,
    1044,
    1045,
    1414,
    1415,
    1416
  ],
  "icon": "material:location_city"
}

Reference docs

When creating a geofence type the important parameters are the name, visibility and geofences

You can optionally set a HEX color code for the geofences under the color parameter. Also you can set an icon using the material icon library

"icon": "material:location_city"

or a custom URL

"icon": "url:https://goo.gl/bQFcW5"

Reports

Job-Engines

Pegasus Gateways allow for external job-engines to create its reports. The Pegasus Gateway API handles all user authorizations and scheduling, allowing the job-engines to focus on the reporting logic, in whichever enviroment they choose.

The default job-engine for all gateways is located at:

https://d1.pegasusgateway.com/jobs-engine

You can extend your gateway with your own job-engine.

Required endpoints

Job engines require 3 endpoints to work

• 1. GET /manifest
• 2. POST /jobs
• 3. GET /jobs/:site_id/:job_id/:file

Manifest

GET [job_engine_url]/manifest

{
	"definitions": {},
	"scripts": []
}

The manifest is a JSON Schema that represents the parameters required for your scripts to work.

The manifest allows UI applications (like Pegasus App) to build forms for creating the reports, as well as scheduling and running them with your gateways /job_manager API

You can use the default engines manifest as a guide

https://d1.pegasusgateway.com/jobs-engine/manifest

definitions

definitions defined on schema

{
	"definitions": {
		"from": {
			"description": "Events starting time",
			"type": "string",
			"format": "date",
			"peg_type": "$from"
		}
	}
}

referencing definitions from the scripts object

"scripts": [
	...
	"properties": {
		"from":
			"$ref: #/definitions/from",
	...
	}
]

You can establish shared definitions that will be used throughout the scripts object. Definitions represent all the resources that you can work with on the Pegasus API (entities, geofences, triggers, etc), they cannot be modified.

use the JSON schema $ref construct to reference definitions within your script elements.

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

scripts

{
	"script": "my_report",
	"title": "My Custom Report",
	"desc": "My custom report description",
	"icon": "https://imgur.com/link/to/image.svg",
	"app_url": null,
	"category": "trip_analysis",
	"schedule": true,
	"parameters_schema": {...}
}

The scripts object contains all of the available reports on your engine.

param	type	description
script	string	unique name for the API to identify each report, no spaces allowed
title	string	name of the report, spaces are allowed here, up to 50 characters
[desc]	string	short description of the report, up to 150 characters
[icon]	string	url with the icon’s location (png or svg), url should be accessible via https
[app_url]	string	url for adding an embedded app to the Pegasus App UI, url should be accessible via https
[category]	string	allows you to group the reports on the Pegasus application UI (see table for possible categories)
schedule	boolean	true to allow the report to be scheduled periodically
[parameters_schema]	object	defines the parameters the report will use

If you define an app_url, when clicking a report an iframe will be embedded with the app_url loaded, otherwise, pegasus loads a default template.

Example with app_url (custom template)

Example without app_url (default template)

category

category	name
live_reports	Live Reports
accessories	Accessories Reports
trip_analysis	Trip Analysis Reports
vehicle_metrics	Vehicle Metrics Reports
device_behavior	Device Behavior Reports
fleet_status	Fleet Status Reports

parameters_schema

script’s parameters_schema [job_engine_url]/manifest

	...
	"parameters_schema": {
		"type": "object",
		"required": ["from", "to"],
		"properties": {
			"from":
				"$ref: #/definitions/from",
			"to":
				"$ref: #/definitions/to",
			"bases":
				"$ref: #/definitions/bases"
			...
		}
	}

The parameters schema tells applications what parameters are required for the script to run. You define your own schemas, or reference them from your root definitions object.

param	type	description
type	string	object
required	array	which definitions are obligated to be filled in order for the report to execute
properties	object	reference the definitions from the manifest to ask the user for the parameters

You can see how pegasus reports section displays the engine’s manifest here.

POST to job_engine

Pegasus makes a POST request to your job engine POST [job_engine_url]/jobs

{
	"configuration": {
		"site_id": "gateway id",
		"site_url": "gateway URL",
		"user_id": "user_id",
		"api_token": "token",
		"tz": "timezone",
		"job_id": 1,
		"job_name": "script_name",
		"job_created_at": timestamp,
		"job_expires": 86400
	},
	"parameters": {
		/* parameters specified by the parameters_schema for this report */
	}
}

{
	"configuration": {
		"site_id": 1,
		"site_url": "https://cloud.pegasusgateway.com",
		"user_id": 86,
		"api_token": "9e34d311fc4ad45d726ab731917554ee279bf23cfa5b148df7c30e01",
		"tz": "UTC",
		"job_id": 22222,
		"job_name": "trips",
		"job_created_at": 1527613165.181
	},
	"parameters": {
		"from": "2018-01-01T00:00:00",
		"to": "2018-01-07T23:59:59",
		"vehicles": [5,6,7],
		"tz": "UTC"
	}
}

This is the endpoint where your magic comes through. Pegasus Gateway provides your job engine the necessary parameters to construct a report by sending a POST to [job_engine_url]/jobs with the following info:

param	type	description
site_id	number	unique id for every gateway site
site_url	string	url for the gateway that made the request
user_id	string	user id that made the request
api_token	string	api token for the job
job_id	number	job id used for updating the job on the pegasus api
tz	string	originating timezone
job_name	string	name of the script
job_created_at	string	time the report was ran
job_expires	string	expiration time of the job

The configuration object contains a site_url and api_token, which enables you to interact with the Gateway’s APIs (/rawdata, /counters, etc) and generate your report.

The job_expires parameter refers to the duration of the jobs time on the gateway (in seconds), it is relative to the jobs job_created_at timestamp, done_at is marked once the job is updated with result error or done.

Note The api_token is restricted to the user’s scopes. You must handle this in your reporting logic (user is asking for a geofence report but does not have access to geofences)

You must use these parameters to report the state of the job back to the gateway

PUT [site_url]/api/job_manager/:job_id

 
 
 
 
 
 
 
 
 
 

Updating the Jobs

Update a report’s progress:

PUT [site_url]/api/job_manager/15

{
	"progress": {
		"percentage": 50
	}
}

Update the parameters for a report if a vehicle id (7) was not found for example:

PUT [site_url]/api/job_manager/15

{
	"parameters": {
		"from": "2018-01-01T00:00:00",
		"to": "2018-01-07T23:59:59",
		"vehicles": [5, 6],
		"tz": "UTC"
}

Update the state to done

PUT [site_url]/api/job_manager/15

{
	"state": "done"
}

Update the job when report is done

PUT [site_url]/api/job_manager/15

{
	"parameters": {},
	"progress": {
		"percentage": 100
	},
	"state": "done",
	"result": {
		"files": ["custom.json", "custom.csv", "custom.xlsx", "custom.pdf"],
		"email": {
			"files": ["custom.xlsx", "custom.pdf"],
			"message": "<h2>Custom Report</h2><br><p>Attached detail with scheduled custom report</p>",
			"subject": "Custom Report"
		},
		"error": ""
	}
}

Report returns an error message

PUT [site_url]/api/job_manager/15

{
	"parameters": { ... },
	"progress": {
		"percentage": 60
	},
	"state": "error",
	"result": {
		"error": "Failed to execute rawdata request"
	}
}

You need to inform the Gateway that started your Job of its progress and available data, to do so you can make PUT requests with the api_token given in the configuration block.

Note site_url refers to the pegasus site url

PUT [site_url]/api/job_manager/:job_id

The payload can contain one or all of the following:

• parameters: updated parameters (i.e post-validation)
• progress: progress for the job.
• state: state of the job (running, error or done)
• result:
  • files: array with files generated in the report
  • email:
    • files: array with files to send in the email
    • subject: email subject
    • message: email subject message
  • error: error message when the script fails (optional)
  • summary:

{
  "parameters": { ... },
  "progress": {
    "percentage": 50
  },
  "state": "running"
  "result": {
    "files": [],
    "email": {
      "files": [],
      "message": "",
      "subject": ""
    },
    "summary": {},
    "error": ""
  }
}


When the report is done, you must update the job with other parameters, in this case with the result field, this field has the files before explained.

Updating the job state to error or done closes the job to any further updates. You won’t be able to modify it further.

Getting data from Jobs

GET [site_url]/api/job_manager/15/script_name.json results in [job_egine_url]/jobs/1/15/script.json

{
	"vid": 5,
	"name": "Test 1",
	"from": "2018-01-01T00:00:00",
	"to": "2018-01-07T23:59:59",
	"idleTime": 258929,
	"primary_group": null,
	"resolved": true,
	"percent_idle": 57
},
{
	"vid": 6,
	"name": "Test 2",
	"from": "2018-01-01T00:00:00",
	"to": "2018-07-07T23:59:59",
	"idleTime": 57911,
	"primary_group": null,
	"resolved": true,
	"percent_idle": 25
}

Once your report is finished, This is endpoint used by pegasus to fetch the files generated:

GET [site_url]/jobs/:site_id/:job_id

For example,

GET [site_url]/api/job_manager/15/script_name.json

results in:

[job_engine_url]/jobs/1/15/script.json

Pegasus Job Manager

[site_url]/api/job_manager/engines

[
	"https://d1.pegasusgateway.com/job-engines",
	"..."
]

Each gateway has a /job_manager API designed to interact with the job-engines registered on the gateway

You can view what job-engines are available on [site_url]/api/job_manager/engines

Making the POST request

Create a report POST [site_url]/api/job_manager

{
    "script": "name",
    "name" : "report name",
    "expires": 0,
    "engine": "engine_name",
    "args" : { ... }
}

example creating an idling report from the d1 manifest

POST [site_url]/api/job_manager

{
  "script": "idling",
  "name": "Idling Usage",
  "expires": 432000,
  "engine": "http://d1.pegasusgateway.com/jobs-engine",
  "args": {
    "from": "2018-07-10T00:00:00",
    "to": "2018-07-10T23:59:59",
    "vehicles": [],
    "groups": [
      500
    ],
    "prefs": {
      "distance": "mile",
      "speed": "mph",
      "language": "es",
      "volume": "gallon"
    },
    "tz": "UTC"
  }
}

RESPONSE

{
    "engine": "http://d1.pegasusgateway.com/jobs-engine",
    "transaction": null,
    "name": "Idling Usage",
    "script": "idling",
    "created_at": 1532031389.04,
    "expires": 432000,
    "state": "created",
    "__v": 2,
    "params": {
        "tz": "UTC",
        "vehicles": [
            1673
        ],
        "to": "2018-07-10T23:59:59",
        "groups": [],
        "from": "2018-07-10T00:00:00",
        "prefs": {
            "volume": "gallon",
            "distance": "mile",
            "speed": "mph",
            "language": "es"
        }
    },
    "result": {},
    "done_at": null,
    "owner": 54,
    "progress": {},
    "cache_key": null,
    "id": 251336
}

To create a report pegasus sends a payload to the /job_manager resource [site_url]/job_manager with the following info:

param	type	description
script	string	name of the script defined in your manifest
name	string	name of the report
expires	number	expiration of job once it’s finished (seconds)
engine	string	name of the job_engine
args	object	arguments for the report that was executed

Scheduling

Scheduling a report POST [site_url]/tasks

{
  "id": "task_id",
  "name": "task_name",
  "processes": [
    [
      {
        "name": "report_name",
        "script": "script",
        "tz": "timezone",
        "engine": "job_engine_url"
      },
      {
        "vehicles": [
          5,
          6
        ],
        "recipients": [
          "example@example.com"
        ],
        "user": [
          11
        ],
        "groups": [],
        "back": {
          "days": 7,
          "hours": 0
        },
        "tz": "UTC"
      }
    ]
  ],
  "schedule": []
}

Custom report task POST [site_url]/api/tasks

{
	"name": "Custom Report Task",
	"processes": [
		{
			"name":"Custom Report",
			"script":"my_script",
			"tz": "UTC",
			"engine":"http://mycustomjobengine.com"
		},
		{
			"vehicles": [5,6],
			"recipients": ["example@example.com"],
			"users": [11],
			"groups":[],
			"back": {
				"days": 7,
				"hours": 0
			},
			"tz": "UTC"
		}
	],
	"schedule": ["0-15 9 * * 1"]
}

Jobs can additionally be scheduled, with the Pegasus /tasks API

Task parameters:

param	type	description
name	string	how you want to name the scheduled report
processes	array	Contains the configuration and parameters
schedule	string	Cron format. Allows you to define time and frequency to run the task. For more information about Cron, go here: Cron

Configuration parameters:

param	type	description
name	string	report name
script	string	script report
tz	string	originating timezone
engine	string	engine where the report will be running

Parameters:

param	type	description
resource	varies	specifies the resources from your params object in the script
recipients	string	array of emails that will receive the scheduled report
users	number	array of user ids that will receive the scheduled report
back	object	how many days / hours to run back the report
tz	string	originating timezone

Accessories

Syrus has a lot of accessories that can interface and work simultaneously with one another, below you will find the accessories integration with the API. If you are looking for installation guides and more general information about the accessories please visit our support site.

ADAS

Daily event count for Speeding, Left Turn Signal, Right Turn Signal and Headway Warning

api/rawdata?vehicles=1477&from=2016-10-15&to=2016-10-18T23:59:59&fields=$basic,count:1&labels=mblyspd,mblylftsig,mblyrghsig,mblyhdwrn,mblypddng&resample=event_time&freq=1D&how=count:sum&group_by=label

{
  "units": {
    "volume": "liter",
    "distance": "meter",
    "speed": "mph",
    "time": "second"
  },
  "events": [
    {
      "count": 5,
      "event_time": "2016-10-16T00:00:00",
      "label": "mblyhdwrn"
    },
    {
      "count": 11,
      "event_time": "2016-10-16T00:00:00",
      "label": "mblylftsig"
    },
    {
      "count": 4,
      "event_time": "2016-10-16T00:00:00",
      "label": "mblypddng"
    },
    {
      "count": 11,
      "event_time": "2016-10-16T00:00:00",
      "label": "mblyrghsig"
    },
    {
      "count": 146,
      "event_time": "2016-10-16T00:00:00",
      "label": "mblyspd"
    }
  ]
}

Syrus is compatible with the following Advanced Driver Assistance Systems (ADAS) accessories:

• Movon, which integrates via the devices RS-232 cables (RX/TX)
• Mobileye™, which integrates via the ECU Monitor accessory

The following table describes the available signals per accessory, these signals generate a label which is found in the standard configuration of each accessory.

• ky: q712 Movon Standard Configuration
• ky: p657 Mobileye Standard Configuration

Syrus signal	Label	Short Description	Mobileye™	Movon
L01	mblyerr	Error	✔️	✔️
L02	mblylldw	Left Lane Departure Warning	✔️	✔️
L03	mblyrldw	Right Lane Departure Warning	✔️	✔️
L04	mblyfcw	Forward Collision Warning	✔️	✔️
L05	mblymaint	Maintenance Flag	✔️
L06	mblyflsf	Failsafe	✔️
L07	mblypdfcw	Pedestrian Forward Collision Warning	✔️	✔️
L08	mblypddng	Pedestrian in Danger Zone	✔️
L09	mblytmpr	Tamper alert	✔️
L10	mblyspd	Speeding	✔️
L11	mblyhdwrn	Headway Warning	✔️	✔️
L12	mblybrkon	Brakes on	✔️	✔️
L13	mblylftsig	Left turn signal	✔️	✔️
L14	mblyrghsig	Right turn signal	✔️	✔️
L15	mblywprs	Wipers on	✔️
L16	mblylwbm	Low Beams	✔️
L17	mblyhibm	High Beams	✔️
L18	mblytime	Time Signal	✔️
L19	mdasfvsa	Front vehicle start alarm		✔️
L20	mdasfpw	Forward Proximity Warning		✔️

Name	Description
Error	Error detected in accessory
Left Lane Departure Warning	Vehicle departed the left lane
Right Lane Departure Warning	Vehicle departed the right lane
Forward Collision Warning (FCW)	Vehicle imminent collision
Maintenance Flag	maintenance required
Failsafe	Indicate one of the following: blurred image, saturated image, low sun, partial blockage or partial transparent
Pedestrian Forward Collision Warning	Collision warning with pedestrian detected
Pedestrian in Danger Zone	Vehicle close to pedestrians
Tamper	tampering detected
Speeding	Speed of vehicle above speed limit sign detected on road
Headway Warning	Vehicle driving too close to vehicle in front
Brakes on	Brakes applied
Left turn signal	Left turn signal activated
Right turn signal	Right turn signal activated
Wipers on	Wipers activated
Low Beams	Vehicle lights turned on
High Beams	Vehicle high beams turned on
Time Signal	Change in time of day
Front vehicle start alarm	Vehicle in front has started moving, but host vehicle has remained standing still for 2 seconds
Forward Proximity Warning	Notifies the driver when there is a vehicle existing in the detection range

The Syrus 4 supports the following ADAS fields in rawdata:

ADAS fields

api/rawdata?vehicles=1477&duration=P1D&fields=$adas

• adas_distance_from_front_vehicle - distance from front of vehicle in meters
• adas_headway_measurement - headway measurement in seconds
• adas_headway_warning_level - headway warning level
• adas_relative_speed_from_front_vehicle - relative speed from front of vehicle in kph
• adas_speed_limit_recognition_sensitivity - speed limit recognition sensitivity
• adas_speed_limit_recognition_state - speed limit recognition state
• adas_speed_limit_recognition - speed limit recognition value
• adas_speed - adas measured speed
• adas_traffic_signs_recognition_warning_level - traffic signs recognition warning level
• adas_vision_only_sign_type - vision only sign type

Bluetooth Tags

Associating to asset

PUT api/:bt_tags_mac

PUT api/bt_tags/00:07:80:EA:B9:8C

{
  "asset_id": 123
}

In order to associate a Bluetooth tag to an asset you must make a PUT request to the Tag’s MAC address /api/:bttag_mac with the asset_id you want associated

Getting Bluetooth Tag Data

GET Bluetooth tag data

GET api/rawdata?vehicles=2050&fields=$bttag&duration=P1D&filter=btt_battery>0

{
  "units": {
    "volume": "liter",
    "distance": "meter",
    "speed": "mph",
    "time": "second"
  },
  "events": [
    {
      "btt_impact": null,
      "system_time": "2017-06-23T16:12:19.462809",
      "btt_battery": 100.0,
      "vid": 2050,
      "event_time": "2017-06-23T16:12:19.462809",
      "btt_reed": false,
      "btt_motion": false,
      "btt_button": false,
      "btt_light": 0.0,
      "id": 5023175567.0,
      "btt_freefall": null,
      "btt_temp": 212,
      "btt_mac": "00:07:80:EA:B8:C0",
      "btt_humidity": 61.0
    }
  ]
}

You can use the set called: $bttag on the rawdata API to request all the fields for the bluetooth tag.

Field	Type	Description	Range
btt_battery	Number	Battery %	0, 100
btt_button	Boolean	True if button is detected
btt_driver	Number	Asset ID associated event
btt_freefall	Boolean	True if freefall detected
btt_humidity	Number	Humidity %	0, 100
btt_impact	Boolean	True if impact detected
btt_light	Number	Light %	0, 100
btt_mac	String	Tag’s unique MAC address
btt_motion	Boolean	True if motion is detected
btt_presence	Boolean	True if tag presence is detected
btt_reed	Boolean	True if reed switch is detected
btt_temp	Number	°C * 10 (divide by 10 to get the temperature in °C)	-100, 450 (-10°C to 45°C)
btt_wreason	String	Reason for waking up

Bluetooth tag wake up reasons

btt_wreason	Description
R	Reed switch.
C	Time.
B	Button.
M	Motion.
L	Light.
W	Low batt.
X	Beacon mode.
i	First Time.
u	Unknown.

Camera

Photocam is a camera that can be connected to the Syrus and it can take photos by request or with a programmable trigger.

The photocam can be accessed under the plugins namespace, the interaction happens per device or vehicle, so we need to specify either a vehicle ID api/vehicles/:vid or an api/devices/:imei

All photocam methods

/api/vehicles/:vid/plugins/photocam

/api/devices/:imei/plugins/photocam

Capturing a photo

Capture a photo from the camera connected to vehicle id: 1956

api/vehicles/1956/plugins/photocam/capture

{
    "msg": "instruction sent to device. ",
    "device_is_online": true
}

To take a photo simply send: GET /api/vehicles/:vid/plugins/photocam/capture

or

GET /api/devices/:imei/plugins/photocam/capture

When the photo is taken it will take some time to upload it, at this point you can poll the api’s last method while the photo uploads, or subscribe to the vehicle’s events via live communication to get the status updates

 


 


 


 

Getting the last photo

Requesting the last photo taken from a vehicle with 1 camera connected
https://cloud.pegasusgateway.com/api/vehicles/397/plugins/photocam/last

{
    "status": "Photo taken, device is uploading it.",
    "source": 0,
    "status_no": 3
}

after some seconds you will see the following response
https://cloud.pegasusgateway.com/api/vehicles/397/plugins/photocam/last

{
  "photos": [
    {
      "status": "jpeg photo found",
      "debug": "2016-10-17 15:40:09-05:00",
      "source": 0,
      "epoch": 1476736809,
      "imei": 356612024116677,
      "b64data": "/9j/2wCEABQODxIPDR__BASE_64__DvqS9BAKgPU1YhKKYBRQAUUAFJQB//Z",
      "status_no": 4,
      "size": 8586
    }
  ],
  "event": {
    "dphoto_ptr": 46742,
    "system_time": "2016-10-17T15:40:21",
    "event_time": "2016-10-17T15:40:09",
    "lon": -80.29358,
    "lat": 25.78397,
    "id": 5014711973,
    "device_id": 356612024116677
  }
}

Requesting the last photo taken from a vehicle with 3 cameras connected
https://cloud.pegasusgateway.com/api/vehicles/469/plugins/photocam/last

{
  "photos": [
    {
      "status": "jpeg photo found",
      "debug": "2016-09-07 14:04:12-05:00",
      "source": 1,
      "epoch": 1473275052,
      "imei": 356612024116677,
      "b64data": "/9j/2wCEABQODxIPDRQS__BASE_64_DATA__EBIXFRQYHjIhHhwcHj0sLiQySUBM"
    },
    {...},
    {...}
  ],
  "event": {
    "dphoto_ptr": 44379,
    "system_time": "2016-09-07T14:04:15",
    "event_time": "2016-09-07T14:04:12",
    "lon": -80.29348,
    "lat": 25.78357,
    "id": 5013175609,
    "device_id": 356612024116677
  }
}

In order to obtain the last photo you can perform a GET /api/vehicles/:vid/plugins/photocam/last

The photo itself mime type: jpeg and is base64 encoded, to convert this into an image you can the HTML img tag and modify the source of the image with the following format:

<img src='data:image/jpeg;base64,__INSERT__BASE__64__' />

you can also use a website such as: http://freeonlinetools24.com/base64-image

 


 


 


 


 


 


 


 

Browsing photos

Browse photos
https://cloud.pegasusgateway.com/api/vehicles/469/plugins/photocam/browse?_from=2016-05-11&_to=2016-05-12

[
  {
    "dphoto_ptr": 40656,
    "system_time": "2016-05-11T21:16:43",
    "code": 48,
    "event_time": "2016-05-11T21:16:40",
    "vid": 469,
    "lon": -80.29351,
    "label": null,
    "lat": 25.78392,
    "id": 5008241019
  }
]

You can use the browse method to see a list of events that have a photo associated to them.

GET /api/vehicles/:vid/plugins/photocam/browse

This method requires two parameters _from and _to which is the dates from and to search for photos.

GET /api/vehicles/:vid/plugins/photocam/browse?_from=YYYY-MM-DD[Thh:mm:ss]&_to=YYYY-MM-DD[Thh:mm:ss]

The time [Thh:mm:ss] is optional

The result gives us an object with different id that correspond to an event with photos

[
  {
    "dphoto_ptr": 40602,
    "system_time": "2016-05-10T20:41:00",
    "code": 48,
    "event_time": "2016-05-10T20:40:57",
    "vid": 469,
    "lon": -80.29355,
    "label": null,
    "lat": 25.78403,
    "id": 5008197387
  }
]

With this ID we can use the from_event method to obtain the photo from this event.

Getting an event’s photo(s)

Requesting the photos associated to the event id: 5008241019

api/vehicles/469/plugins/photocam/from_event?event=5008241019&time=2016-05-11

{
  "photos": [
    {
      "status": "jpeg photo found",
      "photo_id": 10000321,
      "debug": "2016-05-11 16:16:40-05:00",
      "source": 1,
      "epoch": 1463001400,
      "imei": 356612024116677,
      "b64data": "/9j/2wCEABQODxIPDRQSE__BASE_64_Data__HhwcHj0sLiQySUBMS0dARkV"
    },
    {...},
    {...}
  ],
  "event": {
    "dphoto_ptr": 40656,
    "system_time": "2016-05-11T16:16:43",
    "event_time": "2016-05-11T16:16:40",
    "lon": -80.29351,
    "photo_status": null,
    "photo_status_time": null,
    "lat": 25.78392,
    "pi": null,
    "id": 5008241019,
    "device_id": 356612024116677
  }
}

Requesting a photo from a camera that has an error
/api/vehicles/617/plugins/photocam/from_event?event=5013893009&time=2016-09-26

{
  "photos": [
    {
      "status": "Photo could not be taken. Device can not communicate with the camera.",
      "source": 0,
      "status_no": 5
    }
  ],
  "event": {
    "dphoto_ptr": 45535,
    "system_time": "2016-09-26T10:56:09",
    "event_time": "2016-09-26T10:56:01",
    "lon": -80.29352,
    "photo_status": null,
    "photo_status_time": null,
    "lat": 25.78409,
    "pi": null,
    "id": 5013893009,
    "device_id": 356612023728084
  }
}

In order to get a particular photo we can use the method GET /api/vehicles/:vid/plugins/photocam/from_event

this method requires two parameters event and time where event is the id from the event that has a photo associated to it, and time is the timestamp that the event was received on the server (system_time)

GET /api/vehicles/:vid/plugins/photocam/from_event?event=####&time=YYYY-MM-DDThh:mm:ss

If there’s a problem taking the photo, you will get a status_no which is a status number that corresponds to one of the following errors.

Photo Camera Status Numbers

status	description
0	Received photo request
1	Waiting for the camera’s capture acknowledge
2	Device is receiving photo from the camera
3	Photo is being uploaded
4	Photo ready, loading…
5	Serial camera is not responding
6	Capture command could not be sent to the camera
7	Camera did not recognize the capture command, try again
8	The information of the captured photo could not be read
9	Comms. error between camera and device
10	Device could not create photo file
11	Device could not send photo to server
12	Device could not connect to server, will retry
13	Another photo is being captured, photo in queue
14	Device memory full, could not capture
15	Error capturing photo, photo removed from queue
16	Device could not capture, ID max index reached
99	Camera inactive or initializing

For more info please visit our Support Site

Driver ID

See a list of all iButtons and their associations api/ibuttons

{
    "id": "0A000017B5E64F01",
    "entity": 1037
}

The iButton is an accessory that can be used to identify physical entities or assets such as drivers. iButtons have a unique 16 character ID that can be associated to an asset.

Associating an iButton

To associate an iButton to an entity or asset simply make a POST with the ID of the iButton (16 alpha-numerical characters) and the asset ID, to the fields id and entity respectively.

You can see the iButton ID associated to any asset by going into that particular asset’s ID: GET api/assets/:id

Associating an iButton ID to an asset POST api/ibuttons

Payload of request, this will associate ibutton ID: 1234567890123456 to asset id: 1032

{
    "id":"1234567890123456",
    "entity": 1032
}

See a particular asset’s information (including iButtons associated)
api/assets/1032

{
  "info": {
    "first_name": "Test",
    "last_name": "User",
    "type": "driver",
    "email": "user@email.com"
  },
  "name": "Test User",
  "ibuttons": [
    "1234567890123456"
  ],
  "groups": [
    1,
    479,
    566
  ],
  "device": 356612021234567,
  "type": "driver",
  "id": 1032,
  "counters": null
}

Setting Up the iButton

In order to setup the iButton effectively on the API and associate the assets correctly you need to update the device configuration to use the ;IS extended tag. To confirm that this is done for the managed configuration that your device is using check the device’s configuration commands. Look for commands that start with >RXAEF and it has to contain ;IS, this will tell us that the iButton is kept associated to the device until a new one is introduced.

Retrieving an Asset’s events

Once the user places that iButton on the device, it will update a field called: aid (asset ID) in the rawdata API and the trips API This field is kept associated to the device it was introduced until a new iButton is placed. Allowing you to associate the events by an asset ID.

This rawdata request will group the resampled events by aid (asset id)
api/rawdata?vehicles=617,654&fields=$basic,$counters,aid&duration=P1D&filter=(valid_position and mph > 5 and comdelay < 3600 and hdop < 3)&how=$counters:diff,mph:mean&freq=1D&group_by=aid&resample=event_time

The result is the daily values of the counters, and the average speed grouped by the asset ID

For more info please visit our iButton Documentation on our Support Site

ECU Monitor

The ECU monitor can be used to connect the Syrus directly to the vehicle’s onboard computer to obtain CAN data. The possible protocols that the ECU Monitor can detect are:

• J1939 CAN
• J1708/J1587
• FMS Interface
• ISO 14230 KWP2000 (OBDII)
• ISO 9141 (OBDII)
• ISO 15765 CAN (OBDII)

For more information about protocols and vehicles which are compatible visit our support site

The connection to the onboard computer automatically gives you access to precise vehicle metrics. The master fields list gives you an idea of all the possible values obtained with the ECU monitor.

Counters API request with ecu parameters api/counters?vehicles=1716&duration=P1D&round=2&time=hour&speed=mph&distance=mile&volume=gallon

{
  "units": {
    "volume": "gallon",
    "distance": "mile",
    "speed": "mph",
    "time": "hour"
  },
  "counters": [
    {
      "ecu_dist": 232.7,
      "vid": 1716,
      "ecu_ifuel": 0.5,
      "dev_tot_avg_speed": 34.12,
      "tra_avg_speed": 36.36,
      "from": "2016-10-17T13:30:51",
      "dev_idle": 0.41,
      "ecu_eidle": 1.35,
      "ecu_fuelp_idling": 1.39,
      "to": "2016-10-18T13:30:13",
      "ecu_eusage": 7.75,
      "ecu_tot_avg_speed": 30.03,
      "ecu_tfuel": 36.22,
      "ecu_tra_avg_speed": 36.36,
      "dev_orpm": 0,
      "dev_tra_fuel_efcy": 7.43,
      "ecu_tot_fuel_efcy": 6.42,
      "tot_avg_speed": 30.03,
      "ecu_tra_fuel_efcy": 6.52,
      "dev_dist": 265.44,
      "distance": 232.7,
      "dev_ign": 7.78,
      "dev_tra_avg_speed": 36.01,
      "dev_tot_fuel_efcy": 7.33,
      "idle": 1.35,
      "ignition": 7.75,
      "dev_ospeed": 0.56
    }
  ]
}

When using the counters API, you will notice that the following fields will be available, they give us precise engine data

Counter	Description	Calculation
dev_tot_fuel_efcy	Syrus calculated Fuel efficiency	dev_dist/ecu_tfuel
dev_tra_fuel_efcy	Syrus calculated Traveling fuel efficiency	dev_dist/(ecu_tfuel-ecu_ifuel)
ecu_dist	Distance reported by ECU monitor
ecu_eidle	Idle time reported by ECU monitor
ecu_eusage	Engine usage time reported by ECU Monitor
ecu_fuelp_idling	Fuel percentage used while idling	ecu_ifuel*100/ecu_tfuel
ecu_ifuel	Fuel consumed while idling, reported by ECU monitor
ecu_tfuel	Total fuel consumed, reported by ECU monitor
ecu_tot_avg_speed	Total average speed, ECU	ecu_dist/ecu_eusage
ecu_tot_fuel_efcy	ECU calculated Fuel efficiency	ecu_dist/ecu_tfuel
ecu_tra_avg_speed	Traveling average speed, ECU	ecu_dist/(ecu_eusage-ecu_eidle)
ecu_tra_fuel_efcy	ECU calculated Traveling fuel efficiency	ecu_dist/(ecu_tfuel-ecu_ifuel)

When using the rawdata API you’ll notice that you have access to all the fields in the master fields list that start with ecu_

Rawdata request with the ECU RPMs and the flag

/api/rawdata?vehicles=1716&duration=P1D&fields=ecu_rpm,ecu_rpm_flag

{
  "ecu_rpm_flag": "F",
  "system_time": "2016-10-17T16:58:39.711674",
  "vid": 1716,
  "event_time": "2016-10-17T16:58:37",
  "ecu_rpm": 0,
  "id": 5014706111
}

Filtered by rpm_flag = “T” (show’s valid values)

api/rawdata?vehicles=1716&duration=P1D&fields=ecu_rpm,ecu_rpm_flag&filter=(ecu_rpm_flag==%22T%22)

{
  "ecu_rpm_flag": "T",
  "system_time": "2016-10-17T13:39:34.614058",
  "vid": 1716,
  "event_time": "2016-10-17T13:39:31",
  "ecu_rpm": 692,
  "id": 5014700250
}

Use /api/resources/rawdata/keys to get the sets of rawdata fields that are available, for example:

• $ecu
• $ecu_advanced
• $ecu_aftertreatment
• $ecu_common
• $ecu_custom
• $ecu_distances
• $ecu_dpf
• $ecu_durations
• $ecu_error_codes
• $ecu_exhaust
• $ecu_fluids
• $ecu_fuel
• $ecu_levels
• $ecu_obdii
• $ecu_pedal
• $ecu_pressures
• $ecu_states
• $ecu_temp
• $ecu_turbo
• $ecu_weights

All the ECU Monitor parameters have the following flags associated
ecu_***_flag (where *** corresponds to any of the ECU parameters found in the Master fields list)

Flag Status	Description
F	ECU Monitor accessory detected and vehicle’s engine turned off
O	ECU Monitor accessory has not received new data from this parameter in the last 2 minutes
T	ECU Monitor accessory detected and vehicle’s engine turned on. ECU VALID DATA

As seen above, only when the flag is “T” will the ECU parameters be valid and should be used for calculations, thus when making the rawdata request you could add this as a filter

&filter=(ecu_rpm_flag==%22T%22)

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Tips

Get the ECU Monitor information for a vehicle

GET api/vehicles/:vid/remote/ecu_state

{
  "protocol_name": "J1708",
  "protocol": null,
  "upgrading": false,
  "ecu_fw": 40,
  "_epoch": 1508232214.0765109,
  "detected": true,
  "ecu_parameters_1": 0,
  "ecu_parameters_0": 468383157349548003,
  "params_numbers": [],
  "ecu_fw_full": "4.3.0",
  "params": [
    [
      "Vehicle's speed",
      "Vehicle's speed in km/h."
    ],
    [
      "Engine's oil pressure",
      "Engine's oil level pressure in psi."
    ],
    [
      "Total traveled distance",
      "Total traveled distance reported by the vehicle in meters."
    ],
    [
      "Total fuel consumption",
      "Total fuel consumption reported by the vehicle in liters. This value must divided by 10 to obtain the actual value."
    ],
    [
      "Vehicle's throttle position",
      "Vehicle's throttle position value as a percentage. 100% means that the throttle is fully depressed."
    ],
    [
      "Engine RPM",
      "Engine RPM value."
    ],
    [
      "Instant Fuel Consumption",
      "Vehicle's instant fuel consumption in liters/hour. This value must be divided by 100 to obtain the actual value."
    ],
    [
      "Diagnostic message",
      "ECU Monitor diagnostic messages"
    ],
    [
      "Cruise control and/or PTO state availability",
      "0 indicates that neither parameter is available. 1 indicates that either or both parameters are available."
    ],
    [
      "Parking break status.",
      "Parking break status."
    ],
    [
      "Vehicle's battery",
      "Vehicle's battery level value in millivolts."
    ],
    [
      "Fuel Percentage (read by vehicle's computer)",
      "Fuel level read by vehicle's computer. Tank's Percentage"
    ],
    [
      "Engine's coolant temperature",
      "Engine's coolant temperature in ºC"
    ],
    [
      "Engine usage",
      "Total engine usage time reported by the vehicle in hours. This value must divided by 100 to obtain the actual value."
    ],
    [
      "Total time while engine in idle",
      "Total time while engine is in idle reported by the vehicle in hours. This value must divided by 100 to obtain the actual value."
    ],
    [
      "Tires temperature",
      "Indicates if the protocol used by the vehicle supports the Tires' temperature parameter"
    ],
    [
      "ECUMon communication quality indicator",
      "ECUMon communication quality indicator"
    ],
    [
      "Ambient air temperature",
      "Ambient air temperature"
    ],
    [
      "Engine's oil temperature",
      "Engine's oil temperature"
    ]
  ],
  "ecu_updateepoch": 1508232214.076124,
  "engineison": false
}

You can get a list of the parameters that the ECU supports with the following api GET /api/vehicles/:vid/remote/ecu_state

check the response on the right hand side (JSON)

Fatigue Sensor

The Lumeway accessory is a fatigue alert sensor that works essentially the same as the Photocam accessory, the API requests are very similar, with a few exceptions to some commands you can send to configure the Lumeway.

The lumeway can be accessed under the plugins namespace, this interaction happens per vehicle, so we need to specify a vehicle ID first :vid

sending this request will give us all the possibilities with the lumeway accessory.

/api/vehicles/:vid/plugins/lumeway

Capturing a photo

Capturing a photo for a Lumeway accessory

api/vehicles/1/plugins/photocam/capture

{
  "msg": "Capture commands set",
  "device_is_online": true,
  "oids": [
    436085
  ]
}

When the photo is taken it will take some time to upload it, at this point you can poll the api’s last method while the photo uploads.

Getting the last photo

In order to obtain the last photo you can perform a GET /api/vehicles/:vid/plugins/photocam/last

The photo itself is mime type jpeg and base64 encoded, to convert this into an image you can the HTML img tag and modify the source of the image with the following format:

<img src='data:image/jpeg;base64,__INSERT__BASE__64__' />

Getting the last photo
https://cloud.pegasusgateway.com/api/vehicles/1/plugins/photocam/last

Notice how the source is 99, this is always the case when the photos are generated from the Lumeway accessory

{
  "photos": [
    {
      "status": "Photo taken, device is uploading it.",
      "source": 99,
      "status_no": 3
    }
  ],
  "event": {
    "dphoto_ptr": 8308,
    "system_time": "2016-10-12T18:11:10",
    "event_time": "2016-10-12T18:11:08",
    "lon": -69.09872,
    "lat": -24.25018,
    "id": 4357500360,
    "device_id": 356612024713036
  }
}

after some seconds you will see the following response

https://cloud.pegasusgateway.com/api/vehicles/397/plugins/photocam/last

{
  "photos": [
    {
      "status": "jpeg photo found",
      "debug": "2016-10-12 17:47:11-05:00",
      "source": 99,
      "epoch": 1476312431,
      "imei": 356612024713036,
      "b64data": "/9j/4AAQSkZJRgABAQAA....5H5gVt3I=",
      "status_no": 4,
      "size": 3269
    }
  ],
  "event": {
    "dphoto_ptr": 8306,
    "system_time": "2016-10-12T17:47:13",
    "event_time": "2016-10-12T17:47:11",
    "lon": -69.12449,
    "lat": -24.25723,
    "id": 4357497035,
    "device_id": 356612024713036
  }
}

Browsing photos

Browse photos from any date to any date
https://cloud.pegasusgateway.com/api/vehicles/1/plugins/photocam/browse?_from=2016-10-01&_to=2016-10-01T10:39:40

You can use the browse method to see a list of events that have a photo associated to them.

GET /api/vehicles/:vid/plugins/photocam/browse

This method requires two parameters _from and _to which is the dates from and to search for photos.

GET /api/vehicles/:vid/plugins/photocam/browse?_from=YYYY-MM-DD[Thh:mm:ss]&_to=YYYY-MM-DD[Thh:mm:ss]

The time [Thh:mm:ss] is optional

The result gives us an object with different id that correspond to an event with photos

[
  {
    "dphoto_ptr": 8033,
    "system_time": "2016-10-01T10:39:40",
    "code": 84,
    "event_time": "2016-10-01T10:39:39",
    "vid": 790,
    "lon": -69.12207,
    "label": "lumenodrv",
    "lat": -24.25782,
    "id": 4356063141
  }
]

With the ID of the photos we just browsed, we can use the from_event method to carry obtain that photo

https://cloud.pegasusgateway.com/api/vehicles/790/plugins/photocam/browse?_from=2016-10-01&_to=2016-10-01T10:39:40

[
  {
    "dphoto_ptr": 8033,
    "system_time": "2016-10-01T10:39:40",
    "code": 84,
    "event_time": "2016-10-01T10:39:39",
    "vid": 790,
    "lon": -69.12207,
    "label": "lumenodrv",
    "lat": -24.25782,
    "id": 4356063141
  }
]

using the id 4356063141 - we can get that particular photo with the from_event method

Getting an event’s photo(s)

In order to get a particular photo we can use the method GET /api/vehicles/:vid/plugins/photocam/from_event

this method requires two parameters event and time where event is the id from the event that has a photo associated to it, and time is the time that the event was generated

GET /api/vehicles/:vid/plugins/photocam/from_event?event=####&time=YYYY-MM-DDThh:mm:ss

If there’s a problem taking the photo, you will get a status_no which is a status number that corresponds to one of the following errors.

Lumeway Status Status Numbers

Status Code	Description
00	Lumeway ready.
03	Sending photo to the FTP server.
04	Photo was successfully sent to the FTP server.
05	Lumeway is not responding.
06	Capture command could not be sent to the camera.
08	The information of the captured photo could not be read.
09	Wrong checksum.
10	Could not create photo file on the Syrus
11	Could not send photo to the FTP server, because the Syrus’s FTP service is busy.
12	Could not connect to the FTP server.
13	Another photo is being captured. Photo in queue.
14	Error capturing photo. Queue full or camera disconnected.
15	Error capturing photo. Photo removed from queue.
16	Error max photo id reached. “999999999”.
17	Error limit of requests reached
99	Inactive mode or initializing.

Requesting the photos associated to the event id: 4356063141
api/vehicles/790/plugins/photocam/from_event?event=4356063141&time=2016-10-01

{
  "photos": [
    {
      "status": "jpeg photo found",
      "photo_id": 990003450,
      "debug": "2016-10-01 05:39:39-05:00",
      "source": 99,
      "epoch": 1475318379,
      "imei": 356612024713036,
      "b64data": "/9j/4AAQSkZJRg...+18kcnsehrWguYorYEkfSv/Z",
      "status_no": 4,
      "size": 3261
    }
  ],
  "event": {
    "dphoto_ptr": 8033,
    "system_time": "2016-10-01T05:39:40",
    "event_time": "2016-10-01T05:39:39",
    "lon": -69.12207,
    "photo_status": null,
    "photo_status_time": null,
    "lat": -24.25782,
    "pi": null,
    "id": 4356063141,
    "device_id": 356612024713036
  }
}

For more info please visit our Support Site

Garmin™

The Garmin™ accessory has the following methods exposed

• message
• job
• state

you can send a message to a Garmin™ device and have that message appear in the inbox of the Garmin™ screen, you can also send a job or a location you want the Garmin™ to navigate you to.

These methods are also found in GET /api/vehicles/:vid/plugins/garmin

Get the methods available for the Garmin™

api/vehicles/254/plugins/garmin

{
  "job": {
    "POST": [
      "message",
      "flat",
      "flon"
    ]
  },
  "message": {
    "POST": [
      "message",
      "mtype"
    ],
    "GET": [
      "_from"
    ], 
    "DELETE": []
  },
  "state": {
    "POST": [
      "new_mode"
    ],
    "GET": []
  }
}

Get the current state of the Garmin™

api/vehicles/254/plugins/garmin/state

{
  "state": 1,
  "pending": 0
}

Enable the Garmin™ mode

POST /api/vehicles/254/plugins/garmin/state

payload 
{
  "new_mode": true
}

To start interacting with the Garmin™, make sure the state is online in order to check the state of the Garmin™ you can send

GET /api/vehicles/:vid/plugins/garmin/state

Sending Messages

Messages are sent with the garmin/message method under the plugins API

POST /api/vehicles/:vid/plugins/garmin/message

This method accepts two parameters: mtype and message

Parameter	Description
mtype	inbox means the message goes to the inbox of the garmin, screen means the message shows up on the garmin screen immediately
message	text to be displayed on the garmin, up to 40 characters

Send a message to the inbox on the Garmin™ device

POST api/vehicles/254/plugins/garmin/message

payload 
{
  "message":"testing",
  "mtype":"inbox"
}

a successful response means that the instruction / message was sent to the Garmin™ device

{
  "msg": "instruction set to device. ",
  "ts_message_id": 48,
  "device_is_online": true,
  "oids": [
    124272
  ]
}

Getting Messages

Messages are retrieved with the GET method on api/vehicles/:vid/plugins/garmin/message by passing the _from parameter. This will give you all the messages received and sent to the Garmin device from that particular date.

Request Parameters

Parameter	Description	Required
upto	Retrieve up to this many messages (Number)	No
skip	Skip this many messages (Number)	No
_from	Retrieve messages from this date (YYYY-MM-DD)	Yes

GET messages from a Garmin

GET api/vehicles/254/plugins/garmin/message?_from=2017-08-03

{
  "skip": 0,
  "set": 1,
  "total": 1,
  "data": [
    {
      "update_time": null,
      "deleted": false,
      "msg": "Hello World",
      "isread": false,
      "user": "user@email.com",
      "time": 1502064044116,
      "imei": 450000169939621,
      "type": "TS",
      "id": 1284
    }
  ]
}

Assigning a Job

A job is a geographical destination that can be sent along with a message to the Garmin™. Once this job is created it will appear on the screen of the Garmin™ device where the driver can click on it and give step by step directions to the destination.

An example of this would be if you wanted to send a driver the location of where to pick up a package.

In order to assign a job we need to use the garmin/job method under the plugins API

POST api/vehicles/:vid/plugins/garmin/job

This method accepts three parameters message, flat, flon

Parameter	Description
flat	Latitude
flon	Longitude
message	Text to be displayed on the way to the job (Up to 40 characters - ASCII)

POST api/vehicles/254/plugins/garmin/job

payload 
{
  "message": "package #3242 pick up @ 1:30pm",
  "flat" : 25.78393,
  "flon" : -80.29353
}

successful response means that the instruction was sent to the Garmin™

{
  "msg": "instruction set to device. ",
  "job_message_id": 25,
  "device_is_online": true,
  "oids": [
    124279
  ]
}

Input/Output Expander

Rawdata request with $io_exp set
api/rawdata?vehicles=56&fields=$io_exp&duration=P1D&filter=io_exp_state%3E0

{
  "io_exp_in1": false,
  "io_exp_in2": true,
  "io_exp_in3": true,
  "io_exp_in4": true,
  "vid": 56,
  "event_time": "2016-10-17T17:21:09",
  "io_exp_out1": true,
  "io_exp_out2": false,
  "io_exp_out2_short": null,
  "io_exp_out4": false,
  "system_time": "2016-10-17T17:21:51.625232",
  "io_exp_state": true,
  "io_exp_out3_short": null,
  "io_exp_out1_short": null,
  "io_exp_out4_short": null,
  "id": 4384626550,
  "io_exp_out3": false
}

The input/output expander allows your device to control an additional 4 more inputs and 4 more outputs.

You will have an additional 13 fields available in the rawdata api, you may use the $io_exp set to easily access the fields

• io_exp_inX (True if Input ‘X’ is detected ON)
• io_exp_outX (True if Output ‘X’ is ON)
• io_exp_outX_short (True if Output ‘X’ is in short circuit)

Interacting with Outputs

Activating extended output 3
POST api/vehicles/:vid/remote/output

{
  "otype": "e",
  "out": 3,
  "state": true
}

Response

{
  "msg": "instruction set to device. ",
  "device_is_online": false,
  "oids": [
    449500
  ]
}

View the status of the extended inputs/outputs

api/devices/:imei?select=ios_state

{
  "imei": 357042062920955,
  "ios_state": {
    "io_pwr": true,
    "io_exp_in1": false,
    "io_exp_in2": false,
    "io_exp_in3": false,
    "io_exp_in4": false,
    "_epoch": 1538175893.721557,
    "io_ign": true,
    "io_out2_short": false,
    "io_exp_out1": false,
    "io_exp_out2": false,
    "io_exp_out3": false,
    "io_exp_out4": false,
    "io_exp_state": true,
    "io_out1_short": false,
    "io_exp_out2_short": false,
    "io_in2": false,
    "io_out1": false,
    "io_out2": true,
    "io_exp_out1_short": false,
    "io_exp_out4_short": false,
    "io_in1": true,
    "io_exp_out3_short": false,
    "io_in3": false
  }
}

View a log of the output changes

api/devices/357042062920955/remote/outputsetlog

[
  {
    "state": true,
    "otype": "e",
    "out": 3,
    "user": "developer@digitalcomtech.com",
    "time": 1452542329.846
  }
]

In order to activate/deactivate the outputs of the IO Expander, you can use the output remote method, with the otype as e
POST /api/vehicles/:vid/remote/output

• otype (‘e’ for extended outputs)
• out (1-4 for the 4 outputs)
• state (true if you want to activate, false to deactivate)

Payload for activating the output 3 of the expander

{
  "otype": "e",
  "out": 3,
  "state": true
}

You can view the changes done to the device’s outputs with the

GET api/vehicles/617/remote/outputsetlog

More info

Multicamera/expander

Take a photo with a device that has 3 cameras connected to it

api/vehicles/469/plugins/photocam/capture

{
  "msg": "instruction set to device. ",
  "device_is_online": true,
  "oids": [
    334966
  ]
}

Get the last photos for vehicle id: 469

api/vehicles/469/plugins/photocam/last

{
  "photos": [
    {
      "status": "Device is taking/uploading the photo.",
      "source": 1,
      "status_no": 0
    },
    {
      "status": "Device is taking/uploading the photo.",
      "source": 2,
      "status_no": 0
    },
    {
      "status": "Device is taking/uploading the photo.",
      "source": 3,
      "status_no": 0
    }
  ]
}

After some seconds

api/vehicles/469/plugins/photocam/last

{
  "photos": [
    {
      "status": "jpeg photo found",
      "photo_id": 10000122,
      "debug": "2016-11-13 15:04:23-05:00",
      "source": 1,
      "epoch": 1447445063,
      "imei": 356612024116677,
      "b64data": "/9j/2wCQOxI__BASE64_DATA__bOTGSTSa6q9z/2Q==",
      "status_no": 4,
      "size": 9232
    },
    {
      "status": "jpeg photo found",
      "photo_id": 20000122,
      "debug": "2016-11-13 15:04:23-05:00",
      "source": 2,
      "epoch": 1447445063,
      "imei": 356612024116677,
      "b64data": "/9j/2wCEODxy+vHO__BASE64__DATA__KFFMQ0gP//Z",
      "status_no": 4,
      "size": 5532
    },
    {
      "status": "jpeg photo found",
      "photo_id": 30000122,
      "debug": "2016-11-13 15:04:23-05:00",
      "source": 3,
      "epoch": 1447445063,
      "imei": 356612024116677,
      "b64data": "/9j/2wCEApoZWM__BASE64_DATA__eKkCsfselAH//Z",
      "status_no": 4,
      "size": 6894
    }
  ],
  "event": {
    "dphoto_ptr": 30798,
    "system_time": "2016-11-13T15:04:27",
    "event_time": "2016-11-13T15:04:23",
    "lon": -80.29337,
    "photo_status": null,
    "photo_status_time": null,
    "lat": 25.78379,
    "pi": null,
    "id": 5003163587,
    "device_id": 356612024116677
  }
}

The serial expander can be used to connect multiple serial communication (RS-232) accessories simultaneously. This allows you to take up to 3 photos simultaneously with the camera.

Depending on the Syrus configuration you use you can have the option to associate an event to take a photo with 1, 2 or 3 of the cameras connected.

For more info please visit our Support Site

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Temperature/Analog Sensor

The analog interface or temperature sensor has 3 sensors that can detect temperature at different points

Getting Temperature

The temperature comes in 3 fields ea_a ea_b ea_c

These values can be queried with rawdata

the results of these values correspond to a temperature value:

here’s a graph that has the Temperature vs mV relation Graph

You’ll see there’s a 12th degree polynomial function that’s used to calculate the temperature value.

f(x) = -2.0368055E-35x^11 + 6.2029607E-31x^10 – 8.2710455E-27x^9 + 6.3466737E-23x^8 – 3.0989103E-19x^7 + 1.0055822E-15x^6 – 2.2005923E-12x^5 + 3.2320968E-09x^4 – 3.1180082E-06x^3 + 0.0019020671x^2 – 0.70336715*x + 141.46249

Javascript

function degC(mV) {
    return parseFloat((-2.0368055E-35 * Math.pow(mV,11) + 6.2029607E-31 * Math.pow(mV,10) + -8.2710455E-27 * Math.pow(mV,9) + 6.3466737E-23 * Math.pow(mV,8) + -3.0989103E-19 * Math.pow(mV,7) + 1.0055822E-15 * Math.pow(mV,6) + -2.2005923E-12 * Math.pow(mV,5) + 3.2320968E-09 * Math.pow(mV,4) + -3.1180082E-06 * Math.pow(mV,3) + 0.0019020671 * Math.pow(mV,2) + -0.70336715*mV + 141.46249).toFixed(2))
}

Python

import math

def degC(mV):
    return -2.0368055E-35 * math.pow(mV,11) + 6.2029607E-31 * math.pow(mV,10) + -8.2710455E-27 * math.pow(mV,9) + 6.3466737E-23 * math.pow(mV,8) + -3.0989103E-19 * math.pow(mV,7) + 1.0055822E-15 * math.pow(mV,6) + -2.2005923E-12 * math.pow(mV,5) + 3.2320968E-09 * math.pow(mV,4) + -3.1180082E-06 * math.pow(mV,3) + 0.0019020671 * math.pow(mV,2) + -0.70336715*mV + 141.46249

Temp °C	mV	Temp °C	mV	Temp °C	mV	Temp °C	mV	Temp °C	mV
60	189	40	291	20	548	0	1271	-20	3583
59	192	39	299	19	569	-1	1333	-21	3791
58	195	38	307	18	590	-2	1398	-22	4014
57	199	37	315	17	613	-3	1467	-23	4252
56	203	36	324	16	638	-4	1540
55	207	35	334	15	663	-5	1618
54	211	34	344	14	690	-6	1700
53	215	33	354	13	718	-7	1788
52	219	32	365	12	749	-8	1881
51	224	31	377	11	780	-9	1980
50	229	30	389	10	814	-10	2085
49	234	29	401	9	849	-11	2196
48	239	28	414	8	886	-12	2314
47	245	27	428	7	925	-13	2440
46	250	26	443	6	967	-14	2574
45	256	25	458	5	1010	-15	2716
44	263	24	474	4	1057	-16	2868
43	269	23	491	3	1106	-17	3030
42	276	22	509	2	1158	-18	3202
41	283	21	528	1	1213	-19	3386

For more information about the temperature sensor please visit our support site

TPMS

Request tire data (doran example)

api/rawdata?vehicles=1113&fields=ecu_tires_psi,ecu_tires_tmp,ecu_tpms_conditions,ecu_tpms_provision&duration=P1D&head=1

[
    {
        "ecu_tires_psi": "019107,018103,017102,016107,035106,03472,033104,032111,050110,049135,002113,001113",
        "ecu_tires_tmp": "01920,01819,01721,01623,03531,03433,03338,03229,05028,04931,00234,00136",
        "ecu_tpms_provision": "100412,01919,01818,01717,01616,03535,03434,03333,03232,05050,04949,0022,0011",
        "event_time": "2020-11-22T18:40:39",
        "ecu_tpms_conditions": "0341030141",
        "system_time": "2020-11-22T18:40:42.747017",
        "vid": 9,
        "id": 916863107747
    }
]

Request tire data (continental example)

api/rawdata?vehicles=1113&fields=ecu_tires_psi,ecu_tires_tmp,ecu_tpms_warnings,ecu_tpms_provision&duration=P1D&head=1

[
    {
        "ecu_tpms_warnings": "0320030,0330030,0340030,0350030,0000030,0160030,0170030,0180030,0190030",
        "system_time": "2018-10-01T16:51:07.881648",
        "vid": 1113,
        "event_time": "2018-10-01T16:51:05",
        "ecu_tpms_provision": "010310,0191825501010,0181835292341,0171834981980,0161834979294,0351831256396,0341831255008,0331835297967,0321835293060,0011834981950,0001835292410",
        "ecu_tires_psi": "019107,018107,017109,016106,035109,034107,033109,032109,001110,000111",
        "id": 111312277332881,
        "ecu_tires_tmp": "01923,01820,01720,01623,03527,03424,03324,03227,00129,00028"
    }
]

Syrus is capable of reading data from different Tire pressure monitoring system sensors, specifically:

• Doran 360™ TPMS from Doran™
• ContiPressureCheck from Continental™

and report the following fields associated with this accessory:

field	description
ecu_tires_psi	Tire pressure
ecu_tires_tmp	Tire temperature
ecu_tpms_warnings	Tire warnings
ecu_tpms_provision	Tire provisioning
ecu_tpms_conditions	Tire conditions (exclusively for Doran hardware)

All the fields report in a csv format with the corresponding Tire and it’s value.

Tire location

The tire location can be calculated by taking the low order 4 bits, which represent a position number, counting left to right when facing in the direction of normal vehicle travel (forward). The high order 4 bits represent a position number, counting front to back on the vehicle

You can use the following code to calculate the tire_axle & tire_position (assuming that tire_location is converted from string to integer)

tire_axle = (tire_location >> 4) & 0x0F

tire_position = tire_location & 0x0F

Example: tire location 019, corresponds to tire_axle: 1 & tire_position: 3

Explanation of data

Tire pressure

ecu_tires_psi: 019107,018107,017109,016106,035109,034107,033109,032109,001110,000111

tire: 019 has a pressure of 107 psi, etc.

“ecu_tires_psi”: “AAABBB,AAABBB,AAABBB,AAABBB…”

ecu_tires_psi	Description
AAA	000 - 255. Tire Location.
BBB	Pressure (psi)

---

“ecu_tires_tmp”: “AAABBB,AAABBB,AAABBB,AAABBB…”

Tire temperature

ecu_tires_tmp: 01923,01820,01720,01623,03527,03424,03324,03227,00129,00028

tire: 019 has a temperature of 23 °C, etc.

ecu_tires_tmp	Description
AAA	000 - 255. Tire Location.
BBB	Temperature (°C)

---

“ecu_tires_warnings”: “AAABCDE,AAABCDE,AAABC…”

Tire Alerts (Continental) for Doran’s hardware check out the tire conditions below

ecu_tpms_warnings: 0320030,0330030,0340030,0350030,0000030,0160030,0170030,0180030,0190030

tire 032 has no 0 Alarm warning, 0 TTM not defective, 3 TTM not supported and 0 no battery warnings

ecu_tpms_warnings	Description
AAA	000 - 255. Tire Location.
B	Alarm warning
C	TTM defective (1 if TTM is defective)
D	Loose TTM detection
E	Battery warning.

Alarm warning	Description
0	Ok.
1	Under-inflation warning.
2	Under inflation alarm.
3	Tire leak alarm.
4	TTM (Truck tire module) mute.
5	Temperature warning.
8	TTM over temperature warning.

Loose TTM detection	Description
0	No problem
1	TTM loose
2	TTM turned
3	Not supported

“ecu_tpms_conditions”: “AAABCDEFGH,AAABCDEFGH,AAABC…”

Tire Conditions (Doran)

ecu_tpms_conditions: 0341030141

tire 034 has the sensor status OK (1), no airleak (0), 3 which is always present, the tire temperature is OK (0), system ID is a trailer (1), pressure threshold is extreme under pressure (4) and the data is valid (1)

ecu_tpms_conditions	Description
AAA	000 - 255. Tire Location.
B	Sensor Status
C	Air Leak
D	Electrical status (not supported, always 3)
E	Tire Temperature
F	System ID
G	Threshold detection
H	Validity

Sensor Status	Description
0	Mute.
1	Signal OK.
2	Not defined.
3	Defective.

Air Leak	Description
0	No fault
1	Fast leak
2	Error
3	Not supported

Tire Temperature	Description
0	Temperature OK
1	Over temperature
2	Not used
3	Not supported

System ID	Description
0	Truck
1	Trailer

Threshold Detection	Description
0	Extreme over pressure
1	Over pressure; 25% over baseline
2	Pressure good
3	Under pressure
4	Extreme under pressure; 25% under baseline
5	Not defined
6	Error
7	Unknown

Validity	Description
0	Not valid
1	Valid

---

“ecu_tpms_provision”: “ABCCDD,ZZZXXXXXXXXXX,ZZZXXXX…”

Tire provisioning

continental ecu_tpms_provision: 010310,0191825501010,0181835292341,0171834981...

doran ecu_tpms_provision: 100518,03535,03434,03333,03232,06767,01919,...

system 0 is a truck, whose state is 0 OK, the number of axles is 03, and the number of TTMs or Tire sensors is 10

the tire ID 019 has a Sensor ID of 1825501010 dec, or 6CCEEF52 in HEX.

on Doran’s hardware you’ll notice that the Sensor ID and the tire ID are the same.

ecu_tpms_provision	Description
A	System ID (0: Truck, 1: Trailer)
B	System state.
CC	Number of axles.
DD	Number of tire sensors
ZZZ	000 - 255. Tire Location.
XXXXXXXXXX	Sensor ID (decimal)

System state	Description
0	Ok.
1	System malfunction (could indicate DTC errors or bad configuration of the CCU)
2	System deactivated.

It is recommended to use the tire provisioning field always when working with the TPMS data, for example when determining which sensor was the one that reported the mute alert, it’s not enough to just read the TPMS warnings field, rather you have to compare it with the tpms provisioning field at that time.

Pushing data to server

TPMS Temperature sent along with event data to external resource

POST http://yourserver.com/webserver/receiver

{
  ...
  "lat": -33.51001,
  "lon": -70.70053,
  "event_time": "2018-09-25T21:19:24+00:00",
  "tpms_tmp": [
    {
      "position": 0,
      "axle": 0,
      "value": 24
    },
    {
      "position": 1,
      "axle": 0,
      "value": 22
    },
    {
      "position": 0,
      "axle": 1,
      "value": 24
    },
    {
      "position": 1,
      "axle": 1,
      "value": 22
    },
    {
      "position": 2,
      "axle": 1,
      "value": 21
    },
    {
      "position": 3,
      "axle": 1,
      "value": 22
    },
    {
      "position": 1,
      "axle": 2,
      "value": 16
    },
    {
      "position": 2,
      "axle": 2,
      "value": 16
    }
  ]
}

The TPMS data can be sent to an external server via a forwarder in separate fields.

Labels

/api/core_labels

{
  ...
  "ignon": {
    "edited_at": "2017-09-28T14:58:06.220521+00:00",
    "en": "Vehicle ON",
    "created_at": "2017-07-19T21:47:45.858997+00:00",
    "label": "ignon",
    "es": "Vehículo encendido"
  },
  "spd": {
    "edited_at": "2017-10-05T01:51:17.662842+00:00",
    "en": "Speeding:Speeding",
    "created_at": "2017-07-21T13:56:49.184766+00:00",
    "label": "spd",
    "es": "Exceso de velocidad:Exceso de velocidad"
  }
  ...
}

/api/labels

{
  "spdingeo": {
    "edited_at": "2017-08-07T02:40:36.570574+00:00",
    "en": "Speeding in Geofence:Speeding inside of geofence",
    "created_at": "2017-07-21T13:57:35.002875+00:00",
    "label": "spdingeo",
    "es": "Exceso en geocerca:Exceso de velocidad en geocerca"
  },
  "ip3onspd10": {
    "edited_at": "2017-11-08T19:55:50.029681+00:00",
    "en": "Input 3 activated and speed between 0-10kph for 10s:Input 3 activated and speed between 0-10kph for 10s",
    "created_at": "2017-11-08T19:55:50.029775+00:00",
    "label": "ip3onspd10",
    "es": "IP3 activo y velocidad entre 0 y 10 kph durante 10 seg:IP3 activo y velocidad entre 0 y 10 kph durante 10 seg"
  }
}

Example where the telemetry device reported an idling event

{
  "events": [
    {
      "head": 263,
      "code": 0,
      "hdop": 0.79,
      "event_time": "2019-01-08T16:31:14",
      "type": 10,
      "vid": 1673,
      "lon": -80.29328,
      "sv": 10,
      "mph": 0,
      "label": "idl",
      "valid_position": true,
      "lat": 25.78386,
      "system_time": "2019-01-08T16:31:17.193250",
      "speed": 0,
      "id": 167320829742193,
      "device_id": 357042062897906
    }
  ]
}

Labels are short strings that represent the action that took place on any device, they are meant to give meaning/significance to the messages a telemetry device sends. For example if the Ignition cable on the device was detected ON, the device will associate the label ignon to the event that was generated. If the device was going over the speed limit, it will use the label spd, and so on.

For Syrus devices, labels are assigned on the managed configuration of a device. The managed configuration has an ev_labels object which relates the code reported by a device (0-99) with a label.

There are two types of labels: core, and site labels.

• Core labels cannot be deleted, they are for standard gateway configurations

• Site labels are labels that gateway administrators can create, edit and delete.

Core labels can be accessed via api/core_labels. The description of these labels can be updated from the /labels api, but core labels cannot be deleted.

Site labels along with core labels can be accessed via api/labels.

Methods

The methods to modify the labels can be found here:

• Create
• Update
• Delete

Common labels

label	description
prdtst	Periodic report with ignition OFF
trckpnt	Periodic report with Ignition ON (default if no label is set)
ignon	Ignition was turned ON
ignoff	Ignition was turned OFF
panic	report when a panic button is pressed
pwrloss	Main power was lost
pwrrstd	Main power was restored
lwbatt	Low internal device battery
spd	Speeding
idl	Idling
stt	Device motion
stp	Device stopped moving
in1on	Input 1 ON
in1off	Input 1 OFF
in2on	Input 2 ON
in2off	Input 2 OFF
in3on	Input 3 ON
in3off	Input 3 OFF

Device Interaction

Device interaction or the remote control API is used for editing the parameters of managed configurations, managed configurations are limited in the amount of editable parameters that can be edited, whereas the device control configurations are much more flexible in the definition and execution of commands.

Configurations

There are two ways you can configure your Syrus device. One is with managed or legacy configurations, and the other is with advanced device control configurations.

Managed configurations are predefined scripts with instructions for devices that make them behave in specific ways, these are found under the /configurations API. These configurations are used to define basic reporting, and their behavior is more restricted in the sense that they have predefined thresholds and limited parameters that can be edited.

Device control configurations are completely flexible and allow you to create your own configurations as well as edit parts of it using your own parameters. Essentially, with device control you can build your own API to configure the unit.

Managed (Legacy) Configurations

Get a list of the managed/legacy configurations

GET api/configurations

{
	"s219": {
		"name": {
			"en": "Syrus Standard low data consumption",
			"es": "Estándar de Syrus bajo consumo de datos"
		},
		"warnings": [],
		"limit_remote_console": "20/hour",
		"limit_remote_qpv": "1/hour",
		"restricted_fw": {
			"max_number": 9999999,
			"allow_only_flavor_string": null,
			"min_number": 2001005
		},
		"ky": "s219"
	}
}

To get a list the current managed configurations you have access to, go to:

GET api/configurations

Response

Field	Description
ky	Unique key that identifies each configuration
name	Name of the configuration
restricted_device	Configuration is restricted to specific device types
restricted_fw	Min and max device firmwares allowed to upload configurations (applies to Syrus devices only)
warnings	internal use
limit_remote_console	Limits the amount of commands able to be sent per device via the console
limit_remote_qpv	Limits the amount of position queries able to be sent per device

• ky refers to a unique key that identifies each configuration, when you’re looking at the parameters for a particular configuration you use the api/configurations/ky to reach it.

• restricted_device is a restriction for a specific device model, for example a custom third party device can be reporting to Pegasus and you can create a configuration for that specific device

• restricted_fw has 3 fields, two for the min & max firmware, these have the format

• ABBBCCC

  • where A is the first digit of the firmware

  • BBB is the second digit

  • CCC is the third digit

  • Using the example on the right for "min_number": 2001005

  • It’s 2 001 005, removing the 0 in front, we end up with a minimum device firmware required to upload the configuration of 2.1.5, compare this to the version field in the /devices api to know if your device supports that configuration

• limit_remote_console a limit in the amount of console commands able to be sent per device

• limit_remote_qpv limit on the amount of position queries that can be triggered per device

View

View a particular managed configuration

GET api/configurations/:ky

{
	"ev_labels": {
		"0": "prdtst",
		"1": "trckpnt",
		"2": "ignon"
	},
	"tracking_resolutions": {
		"1": [
			null,
			1800
		],
		"2": [
			null,
			720
		]
	},
	"allowed_cmds": [
		">SRT;ECU<",
		">SXAQQ",
		">SXAICAA1",
		">SXAIC"
	]
}

Example third party device configuration

{
    "restricted_device": "custom",
    "ev_labels": {
        "in1on": "dooropn",
        "in2on": "buzzeron",
        "spd": "excess"
    },
    "ios_names": {
        "io_in1": "SOS",
        "io_in2": "Input #2"
    },
    "params": {
        "safeimmo": false
    }
}

To view a managed configuration’s contents

GET api/configurations/:ky

Response

Field	Description
name	Name of configuration
allowed_cmds	Commands that are permitted to be sent via the /remote/console command
ev_labels	Event labels
gps_codes_names	Names of the events deprecated - use labels instead
ignition_off_event_code	deprecated
ignition_on_event_code	deprecated
ky	Unique id for the configuration
params	Editable parameters in this config (used in /remote)
restricted_fw	Minimum firmware needed to load the configuration
sms_alias_actions	SMS alias actions
tracking_resolutions	Tracking resolutions

Event Labels

Update the event labels of a configuration

PUT api/configurations/:ky

{
	"ev_labels": {
		"in1on": "dooropn",
        "in2on": "buzzeron",
        "spd": "excess"
    }
}

Map the numeric codes reported by a device to labels

PUT api/configurations/:ky

{
    "ev_labels": {
        "0": "prdtst",
        "2": "ignon",
        "4": "spd"
    }	
}

The event labels can map to codes reported by the Syrus and other devices, or convert one label to another (not both).

Configuring a device

Configure a device with a managed configuration

POST api/device-config/:imei

Body

{
		"ky": "s219"
}

Response

{
	"msg": "instruction set to device. ",
	"device_is_online": false,
	"oids": [
		543757
	]
}

View progress of configuration on device

GET api/devices/:imei/configuration

Response shows us the state of this configuration is pending (state: 1)

{
	"values_rpmlimit_rpm": null,
	"values_satcom_wait_time": null,
	"values_slowtraffic_distance": null,
	"values_satcomevents": null,
	"values_speedlimit_secs": 10,
	"values_satcom_networktest_time": null,
	"values_tracking_resolution": 5,
	"values_idle_secs": null,
	"values_slowtraffic_secs": null,
	"values_tt_alarm_from_deattach": 0,
	"values_photocamevents": "",
	"id": 7765,
	"state": 1,
	"values_timeonlyreport_mins": null,
	"values_speedlimit_mph": 50
}

View pending commands waiting to be sent to the device

GET api/devices/:imei/messages/pending

{
	"queue": [
		{
			"useky": false,
			"uid": 1115,
			"last_try": 1553530605.6320829,
			"_tries": 1,
			"ctype": "consolecmd",
			"time": 1553530605.0752239,
			"msg": "QVR",
			"id": 461
		}
	],
	"outbox": {
		"_epoch": 1553530605.075285,
		"last_id": 462
	}
}

In order to change the managed configuration of the device you need to make a POST request to api/device-config/:imei passing ky in the body of the request, which corresponds to a particular configuration.

Once the configuration has been set, you can view the status of the configuration with: GET api/devices/:imei/configuration

the state field has the following values

state	description
-2	Configuration error
-1	Configuration mismatch, invalid configuration
0	Inital state, nothing done since configuration assigment
1	Device has pending configuration messages
3	Configuration ready (synchronized)

Allowing a command

allow command >SRIA (add RFID tags) on a managed configuration

PUT api/configurations/:ky

{
	"allowed_cmds": [
		">SXAWA",
		">SXAV",
		">SXAQQ",
		">SRT;SFBUFF",
		">SRT;ECU<",
		">SSSU",
		">SXAGH",
		">SXATT",
		">SXASP",
		">SXAIL",
		">SRIA"
	]
}

Lets say that you have an existing configuration and you want to add some RFID tags using the >SRIA Syrus command to a device, but the remote/console command is returning >RER04 in the response of the command message sent.

What you need to do is update the managed configuration to allow the >SRIA command to be sent via the /remote/console method.

To do this simply send a PUT request to the managed configurations/ky with the allowed_cmds array with a new entry for the command you want to allow.

Remote control

View a list of remote commands to interact with a vehicle’s device

GET api/devices/:imei/remote

{
	"fwupdate": {
		"POST": []
	},
	"configuration": {
		"POST": [
			"ky"
		]
	},
	"console": {
		"POST": [
			"cmd"
		],
		"GET": [
			"cid"
		]
	}
}

Once a device has a managed configuration you are able to interact with other commands.

GET /api/devices/:imei/remote

You can also use the vehicle’s API to get the remote commands for that particular vehicle’s device:

GET /api/vehicles/:id/remote

Commands	Method	Params	Description
call	POST	index	Call an authorized number
configuration	POST	ky	Send a managed configuration* deprecation warning - alternative
console	GET	cid	View the response of a command sent
console	POST	cmd	Send a command to a unit
diagnostic	GET		Quick connect the unit to the diagnostic server
ecu_state	GET		View the status of the ECU Monitor parameters
fwupdate	POST		Firmware update to the latest stable version
gps_status	POST		Get the device’s GPS diagnostic information
mdt	POST	message	Send a message via the MDT
output	POST	otype, out, state	Set the device’s output
outputsetlog	GET		View a list of the output commands sent
phones	DELETE	phone	Delete an authorized number
phones	GET		View a list of the authorized phone numbers
phones	POST	phone	Authorize a phone number on the device
rpm	GET		Get the current rpm limit configuration
rpm	POST	rpm, persistencesecs	Set the RPM threshold that generates an ‘over rpm’ event
safe_immo	POST	action	Send a Safe Immobilization to the device
sms_alias	GET		View the SMS alias that are configured
sms_alias	POST	smsaliases	Create a new SMS alias
sms_alias	PUT	alias, action	Update an SMS alias
speed	GET		View the current speed limit threshold
speed	POST	mph, persistencesecs	Set the speed limit threshold
state	GET		Get the status of the device’s inputs and outputs
tracking_resolution	GET		View the current configuration of the tracking resolution
tracking_resolution	POST	resolution	Set a new tracking resolution for the device
trigger_position_event	POST		Query the location and generate an event

Send a device command

Add a new RFID tag to the device

POST /api/devices/:imei/remote/console

{
		"cmd": ">SRIA123456<"
}

Response

{
		"msg": "instruction set to device. ",
		"imei": 357042062922274,
		"via": "outbox",
		"cid": 981,
		"oids": [
				981
		]
}

See the response of the message (command) you just sent

GET api/devices/:imei/remote/console?cid=:cid

This response >RER04 means that the command is not permitted, add it to allowed_cmds in the managed configuration

{
		"message": ">RER04:SRIA123456;SI=1-1CC;ID=357042062922274"
}

See messages (commands) pending to be sent to the device

api/devices/:imei/messages/pending

{
		"queue": [
				{
						"useky": true,
						"_last_try": 1505466920.614913,
						"_tries": 183,
						"state": false,
						"ctype": "setoutput",
						"otype": "e",
						"time": 1505426401.141027,
						"msg": "SSSXE40",
						"id": 980,
						"out": 4
				},
				{
						"msg": "SRT",
						"id": 981,
						"ctype": "consolecmd",
						"time": 1505712766.7529349
				}
		],
		"outbox": {
				"_epoch": 1505712766.752985,
				"last_id": 982
		}
}

List all commands sent to the device

api/devices/:imei/messages/sent

[
	{
		"outb": {
			"useky": false,
			"uid": 1115,
			"last_try": 1553530605.6320829,
			"_tries": 1,
			"ctype": "consolecmd",
			"time": 1553530605.0752239,
			"msg": "QVR",
			"id": 461
		},
		"epoch": 1553530605.638777
	},
	{
		"outb": {
			"useky": false,
			"uid": 1115,
			"last_try": 1553521312.5816419,
			"_tries": 1,
			"ctype": "consolecmd",
			"time": 1553521312.0280581,
			"msg": "SRIA123456",
			"id": 460
		},
		"epoch": 1553521312.588011
	}
]

Sending a device command (also referred to as device messages) can be done with the api/devices/:imei/remote/console api, with the cmd parameter where you put the command you want to send.

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Immobilize a vehicle

Safely immobilize a vehicle

POST api/vehicles/:vid/remote/safe_immo

or via the device api

POST api/devices/:imei/remote/safe_immo

{
	"action": true
}

response

{
		"msg": "instruction set to device. ",
		"imei": 356612022409637,
		"response": null,
		"oids": [
				166
		]
}

you can monitor the state of the immobilization via API or Websockets

GET api/vehicles/:vid/remote/state

GET api/devices?imeis=:imei&select=outbox,ios_state,safeimmo_state

		{
			"safeimmo_state": {
				"instruction": true,
				"_epoch": 1618318377.628331,
				"uid": 1,
				"set_at": 1618318372.517008,
				"cid": 8994
			},
			"imei": 357042062897906,
			"ios_state": {
				"io_pwr": true,
				"io_out2_short": false,
				"_epoch": 1618318402.044902,
				"io_tamper": false,
				"io_ign": false,
				"io_exp_state": false,
				"io_out1_short": false,
				"io_out1": true,             <- output1 indicates when the immobilization is activated
				"io_out2": false,
				"io_in1": false,
				"io_in2": false,
				"io_in3": false
			},
			"outbox": [
				
			]
		}

Syrus devices have an immobilization mechanism that waits for certain conditions to meet before activating, in this way the immobilization is safe. We’ll refer to immobilization as ‘safeimmo’ from now on. Safeimmo of course requires that the device is installed by a certified person that knows how to install a relay on a vehicle’s ignition cable or starter cable with the device’s output 1 (blue/red) cable. Note that output 1 is always used for safeimmo.

The first step in knowing whether or not safeimmo is supported by a particular device is to look for the key safeimmo_support in the device’s configuration using the device api.

api/devices/:imei?select=config

Safe immobilization supported

{
		"config": {
				"kydef": {
						"lumeway": false,
						"secugen": false,
						"garminmode": false,
						"safeimmo": true,
						"satcom": false,
						"_read_at": null,
						"photocam": false,
						"ios_names": {}
				},
				"kymod": {},
				"_config_state": 1,
				"_epoch": 1617041571.785082,
				"safeimmo_support": true,
				"values": {
						"values_rpmlimit_secs": null,
						"values_rpmlimit_rpm": null,
						"values_speedlimit_secs": 10,
						"values_speedlimit_mph": 50
				},
				"ky": "q740"
		}
}

Important Notes If safeimmo is active and the device’s configuration is changed from one that supports safeimmo and to one that does not support it, then the output 1 will go to false, and you can use the /remote/output to activate/deactivate the device’s outputs.

Once a configuration is sent to the device, it takes some time for the instructions to reach the device, you can look at the _config_state and if it’s = 1 it’s pending, 3 = it’s done.

We recommend waiting for the configuration to be in synched state before sending any instruction to safely immobilize a vehicle.

After you send the command you can monitor the response via api or via websockets, the api/devices/:imei?select=outbox,ios_state,safeimmo_state,config will give you the state of everything relevant about the safe immobilization.

outbox: whether or not there is an instruction pending to be sent to the device. Here you’ll see an array of objects with instructions of "ctype": "seco" if the "msg": "SXASES1" it indicates it’s an activation of safeimmo. If you see "msg": "SXASES0" it’s a deactivation of safeimmo.

safeimmo_state: indicates the pending instruction and the time of it’s last activation

ios_state: indicates the status of the device’s output, io_out1 is always used for the safeimmo support.

config: indicates whether or not the device supports safeimmo using the safeimmo_support key.

Safeimmo Walkthrough

Step 1: Safeimmo supported by the device’s configuration

api/devices/:imei?select=config

 				"safeimmo_support": true,

Step 2: Command to immobilize is sent

POST api/devices/:imei/remote/safe_immo

{
	"action": true
}

Step 3: Waiting for device to receive instruction

GET api/devices/:imei?select=outbox,ios_state,safeimmo_state,config

{
		"outbox": [
				{
						"useky": true,
						"uid": 1,
						"last_try": 1618318372.491439,
						"_tries": 1,
						"ctype": "seco",
						"time": 1618318372.419283,
						"msg": "SXASES1",
						"id": 8994
				}
		]
}

Step 4: Instruction sent

GET api/devices/:imei?select=outbox,ios_state,safeimmo_state,config

outbox is empty, but the io_out1 is still not active, waiting for the instruction to be executed on the device

	{
		"safeimmo_state": {
				"instruction": true,
				"_epoch": 1618318377.628331,
				"uid": 1,
				"set_at": 1618318372.517008,
				"cid": 8994
		},
		"imei": 357042062897906,
		"ios_state": {
				"io_pwr": true,
				"io_out2_short": false,
				"_epoch": 1618316545.294416,
				"io_tamper": false,
				"io_ign": false,
				"io_exp_state": false,
				"io_out1_short": false,
				"io_out1": false,
				"io_out2": false,
				"io_in1": false,
				"io_in2": false,
				"io_in3": false
		},
		"outbox": []
}

Step 5: Action executed confirming that the safe immobilization is complete

GET api/devices/:imei?select=outbox,ios_state,safeimmo_state,config

{
		"safeimmo_state": {
				"instruction": true,
				"_epoch": 1618318377.628331,
				"uid": 1,
				"set_at": 1618318372.517008,
				"cid": 8994
		},
		"imei": 357042062897906,
		"ios_state": {
				"io_pwr": true,
				"io_out2_short": false,
				"_epoch": 1618318402.044902,
				"io_tamper": false,
				"io_ign": false,
				"io_exp_state": false,
				"io_out1_short": false,
				"io_out1": true,
				"io_out2": false,
				"io_in1": false,
				"io_in2": false,
				"io_in3": false
		},
		"outbox": []
}

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Activate output 2

Activating embedded output 2 on vehicle 2063

POST api/vehicles/2063/remote/output

{
		"otype": "n",
		"out": 2,
		"state": true
}

Deactivating embedded output 1 on vehicle 2063

POST api/vehicles/2063/remote/output

{
		"otype": "n",
		"out": 1,
		"state": false
}

State of output

GET api/vehicles/:vid/remote/state

{
		"ionames": {...},
		"ios": {
				"io_pwr": true,
				"evid": 19711112435180,
				"io_in1": false,
				"evtime": 1505711767,
				"io_exp_state": false,
				"io_out1": false,
				"io_out2": false,        <<<<<<<<<<<<<<<<<<<
				"systime": 1505711770.180109,
				"trip_id": 19711108701981,
				"io_ign": true,
				"io_in2": false,
				"io_in3": false
		}
}

Activating output 2 is done with the /api/vehicles/:vid/remote/output api, making a POST request with otype, out, state as parameters.

If using an IO expander accessory check out this section.

Param	Type	Description
otype	String	Use device embedded output: “n”, or external IO Expander accessory: “e”
out	Number	Output number
state	Boolean	True to activate output (when an output is activated it’s grounded)

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Make a Call

Authorize phone number +13058675309

POST api/devices/:imei/remote/phones

{
	"phone": "+13058675309"
}

Response

{
	"msg": "instruction set to device. ",
	"imei": 357042062920955,
	"oids": [
		48
	]
}

View the phone number we just configured

GET api/devices/:imei/remote/phones

{
	"phones": [
		{
			"action": "1",
			"access": "0",
			"phone": "+13058675309"
		}
	],
	"errors": [],
	"pending": true
}

Make a call to the number +13058675309

POST https://cloud.pegasusgateway.com/api/vehicles/1956/remote/call

{
		"index": 0
}

This section describes how to generate calls directly from the device (this is unlike the trigger’s phone call generation because this is directly from the device, triggers uses a third-party api in order to make the call). Note that in order for your device to be able to make a phone call the SIM card has to be provisioned with voice services.

Start by authorizing a phone number on one of the 5 available slots for every device. (index 10-14)

POST /api/vehicles/:vid/remote/phones

or

POST /api/devices/:imei/remote/phones

{
  "phone":"+13058675309"
}


then make a call to that number with the remote method call

POST /api/vehicles/:vid/remote/call

{
  "index": 0
}


Note that the indexes must be between 0 and 4.

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Device actions

Silencing events

The api/device-mute/:imei API enables muting, un-muting Syrus’ event codes generation. Muting means that the events are processed internally on the device and never reach the server. This is useful in cases where the device is generating a lot of false events like inputs activation, and you’d like to stop the events from generating because it’s consuming lots of data. Simply mute the event, then if the problem is fixed un-mute the event.

When a mute action is POSTed for an imei the following occurs:

• If code is already-muted, nothing is done.
• else QEDcc is pushed to outbox.
• The response REDccABCD[...] is transformed to SEDccABCDE[...] and stored
• SEDccSBCDE[...] is pushed to outbox.

When an un-mute action is POSTed:

• If device is already in un-muted/un-listed, nothing is done
• else, the previously stored SEDccABCDE[...] is pushed to outbox

GET

GET api/device-mute/356612024151062

{
	"evc-1": {
		"state": "querying",
		"oid": 161,
		"ev_code": 1,
		"uid": null,
		"time": 1520865531.0303299
	}
}

As device object too (live package and /devices API):

{
	"imei": 356612024151062,
	"muted_evs": {
		"_epoch": 1520881684.852546,
		"events": {
			"evc-1": {
				"uid": 1,
				"oid": 123,
				"qed_response": "RED01NV0;C00+",
				"state": "muted",
				"restore_command": "SED01NV0;C00+",
				"ev_code": 1,
				"time": 1520881682
			}
		}
	}
}

An object containing muted-events is returned. Its keys follow the format evc-{evcode}

Note

Only possibly muted event codes are returned. Check state to confirm event is actually muted/un-muted

Muted event object

Param	Description
ev_code	Event code
state	Muted-state, see below
oid	OutBox ID of last OutBox push
uid	User that gave the last instrucion (mute/un-mute)
time	Object update epoch

state

State	Description
querying	QED sent, waiting response. Code is in process of being muted
muting	Got QED response, SEDxxS sent. Code is in process of being muted
muted	Got confirmation of SEDzzS. Code is muted.
un-muting	SEDxx-restore sent. Code is in process of being un-muted
un-muted	Got response to SEDxx-restore. Code is un-muted. This state is is equivalent as not having the muted-event returned on the muted-events object. This is state is temporal, yields to object being eliminated.
ev-undefined	Tried silencing an undefined event. This is state is temporal, yields to object being eliminated.

POST

POST api/device-mute/460001331053605

{
	"code": 1,
	"action": "mute"
}

{
	"action": "mute",
	"imei": 350000000000001,
	"code": 1,
	"events": {
		"evc-1": {
			"state": "querying",
			"oid": 42,
			"ev_code": 1,
			"uid": 1,
			"time": 1520868125.9707451
		}
	}
}

POST Params

Params	type	description
action	string	mute or un-mute
code	number	numeric event code

Returns

Param	Description
action	action
code	code
imei	device imei
events	the same object returned by GET /device-mute/

Forwarders

/forwarders

Forwarders are realtime redirections of data to any endpoint. They are useful when you want to obtain all the data from all your entities and store it in a database. Forwarders have an active queue and require a confirmation that a message was received by the endpoint, thus with forwarders you’re able to achieve database replication.

Pegasus supports forwarding data in an array of JSON objects where each object corresponds to a entity event which includes any location information or data reported by the entity’s device.

Intro

The way it works is that you define a URL (endpoint) that’s going to be used as a receiver for the HTTP POST requests sent from Pegasus.

Pegasus forwards

>>>> [{"lat": 25.23432, "lon": -80.24912, "id":10001},{"lat": 25.23435, "lon": -80.24913, "id":10002}]

The forwarder service expects the endpoint to ‘confirm’ the reception of the message Pegasus sends.

In order to confirm the reception of all events successfully, you can respond with an empty array []

Response from client

<<<< []

Should there be any events that we sent in the forward that you did not process correctly in your database you can reply with the ID of the event that was not processed

<<<< [10002]

and Pegasus forwards that event again

>>>> [{"lat": 25.23435, "lon": -80.24913, "id":10002}]

In order for Pegasus to forward data to your endpoint you must allow HTTP traffic to a path in your server where the code will reside.
Check to make sure there are no firewall restrictions and the site is reachable by an external application.

By default the fields that are forwarded are the one’s found in the Master Fields List.

Depending on what accessories the device has connected, the fields will be sent accordingly. In other words only a device with an ECU Monitor accessory connected will report ecu_ related fields, otherwise these fields will not be forwarded in the POST request.

At the moment, forwarders can only be created by DCT, once created however, if you are an administrator you’ll be able to edit it.

Parameters

Don’t forget to send the entire payload

dates_format

PUT /api/forwarders/:id

{
    "dates_format": "%Y-%m-%d %H:%M:%S"
}

this gives you dates with: YYYY-MM-DD hh:mm:ss, example: 2018-12-25 23:59:59

---

time_zone

PUT /api/forwarders/:id

{
    "time_zone": "America/New_York"
}

---

keys

PUT /api/forwarders/:id

{
    "general": {
        "keys": [
            "lat",
            "lon",
            "speed",
            "primary_name",
            "event_time"
        ]
    }
}

[
    {
        "lat": -34.88844,
        "lon": -56.11606,
        "speed": 33,
        "primary_name": "Blue Toyota",
        "event_time": "2018-12-17T14:22:09+00:00",
        "system_time": "2018-12-17T14:51:37.969868+00:00"
    }
]

---

extra_headers

PUT /api/forwarders/:id

{
    "extra_headers": {
        "Authorization": "Bearer YWRqZmFsZGpmbGFqc2RmbGFhZGxmam"
    }
}

---

primary

PUT /api/forwarders/:id

{
    "include_primary": true,
    "keys_include": [
        "primary"
    ]
}

[
    {
        "vid": 2292,
        "lon": -80.19266,
        "primary": {
            "info": {
                "range_unit": "mile",
                "description": "Sample vehicle",
                "tank_volume": null,
                "color": "Black",
                "make": "Peterbilt",
                "vin": null,
                "license_plate": "ABC123",
                "alias": "foxtrot",
                "range": 400,
                "year": "2020",
                "model": "567",
                "tank_unit": "gallon"
            },
            "associations": [
                {
                    "device": 862831032123456,
                    "time": 1592847039,
                    "id": 86,
                    "association": true,
                    "vehicle": 2292
                }
            ],
            "__updated": 1596475523.951629,
            "associated_at": 1592847871,
            "name": "My special car",
            "primary": 9,
            "__created": 1592607412.826321,
            "images": {
                "photo": false,
                "on_icon": false,
                "idle_icon": false,
                "off_icon": false,
                "icon": false
            },
            "token": null,
            "properties": {
                "custom_properties": "yes",
                "network": "4G",
                "city": "FLORIDA",
                "sensor": "v1.2",
                "ID": "10073367",
                "region": "SOUTH",
                "my_info": {
                    "code": "11223344",
                    "state": "UPDATING"
                },
                "country": "US"
            },
            "groups": [
                6
            ],
            "__version": "5.3.2",
            "device": 862831032123456,
            "configuration": "0000",
            "type": "vehicle",
            "id": 2292
        },
        "label": "new",
        "lat": 26.68205,
        "device_id": 862831032123456
    }
]

param	type	description
dates_format	string	default: ISOFORMAT (YYYY-MM-DDTHH:MM:SS+HH:MM), python dateformat compatible
time_zone	string	default: UTC (recommended), timezone
extra_headers	object	default: Content-Type: application/json
include_vinfo	boolean	if true, sends an object with the entities information
general	object	update the general config (see below)

To update a forwarder, you can use a PUT request on the forwarder ID to update the general configuration. When sending the request, make sure to use the entire JSON object as the body of the PUT request, with the modifications.

general params	type	description
discard	boolean	discards old messages in queue & any new messages
keys	array	use it to only forward certain keys
keys_all	boolean	use it to forward all keys
keys_include	array	use it to include keys that are not defined in the base set (has priority over keys)
keys_exclude	array	use it to exclude any keys from the forwarder
stop_send	boolean	when true it stops the forwarder and queues events
stop_queue	boolean	when true it stops queuing events, discarding any new events
labels_in	array	only allows certain labels to forward data
labels_out	array	exclude the following labels from forwarding data
default_values	object	key and default value, ex: {"ib": "000000000000"}
include_primary	boolean	when true along with the field primary in keys or keys_include it includes a key called primary which contains the vehicle’s information and custom properties

legacy general params	type	description
legacy	boolean	when true it sends the lat/lon as whole integers values
protocol	string	when set to “rpc”, it wraps the json array of events in the following envelope {"params":[2,[{EVENT_1},{EVENT_2}]],"method":"pushevents","id":1}
codes_map	json	object with key-value pairs, the keys should be the original event_code, the value represents the value to which it will be switched
filter_in	array	only forwards events from these event codes
filter_out	array	removes any unwanted event codes from forwarding data

Tutorials

PHP & phpMyAdmin

The following tutorial demonstrates how to handle the messages forwarded by the Pegasus Sites through PHP (version 5.3 or later).

To start download or clone the receiver code from our repo

The root file must be allowed access from a url, such as http[s]://[YOURDOMAIN]/[PATH TO TEMPLATE]/ this will be your endpoint.

In the config.php, modify the constants to suit your PHP installation and Database access credentials.

date_default_timezone_set("UTC");

define("DB_SERVER", "YOURDATABASE_SERVER");
define("DB_USER", "DATABSE_USER");
define("DB_PASS", "DATABASEP_PW");
define("DB_NAME", "DATABASE_NAME");
define('DB_TABLE_NAME', 'UNIT_EVENTS_RPC');

Once you have verified your Database credentials, remove/comment the first exit() statement within the ‘index.php’ file.

// in the index.php comment or remove the following line
//exit()

// make sure to have the PEGASUS_PROTOCOL as JSON
define('PEGASUS_PROTOCOL', JSON);

By default, when you test the forwarder it will create a table with the following keys (assuming it’s not already created) eventKeysMySQL.sql

If you do not want to store the data to a database, you can disable it by setting the variable ‘$db_storage’ to false within the ‘config.php’ file. This will prevent the table from being created, and will prevent all new events from being inserted into the database.

// set to true to to store the data in the db
$db_store = true;

Note: This does not delete the table if it has been previously created, this only prevents the sql statement that creates the table from executing.

Events Object data structure

In most cases, it may be may be suitable for the events object to be handled differently or in addition to the database storage mechanism discussed in the previous section.

In this instance you may add your logic directly into the peg_insert_array function of the config.php file. You can use the $data object at your discretion, and modify it to your will. The $data object is a PHP associative array which contains all the events sent from the pegasus gateway. You may add any logic here, which can include sending emails, forwarding the data to another script, or storing to a file. You must make sure that any errors are handled appropriately.

NOTE: It is important that you make sure your logic returns an empty array []. As this lets pegasus know that the events have been handled accordingly and the queue can be cleared.

Once done you can test the forward here: Testing the Forward

Windows, .NET, Microsoft SQL

Download the following zip ms_receiver.zip

In the receiver.ashx there’s 3 places where you must input data

Line 50: Replace [dbo].[UNIT_EVENTS_RPC] with your Database Table Name

Line 105: Replace SERVERNAME with the name of your server

Line 106: Replace Pegasus_db with the name of your database

Please note that this solution uses: Windows Authentication Mode

Run the following in Microsoft SQL Server to create the DB. eventKeysMSSQL.sql

Make sure your Microsoft server has IIS, Active Directory services running and port binding correctly done. DNS/DHCP services are optional but recommended.

Testing the forward

In order to simulate what Pegasus would send to your server/database you may use an application that sends HTTP requests, like POSTman, or cURL. Just use the URL with the path to your JSON listener and follow one of the examples on the right.

Full example with all keys

curl -X POST "http://yourlistener.com/path/to/receiver" \
-H "Content-Type: application/json" \
-d '[{"io_pwr": true, "ac": 2, "code": 1, "type": 10, "vid": 1392, "cf_lac": 103, "ip": "208.131.186.63", "port": 26052, "pid": 110, "al": 521, "vo": 6356212, "io_ign": true, "event_time": "2016-01-12T19:40:31+00:00", "source": 3, "lon": -77.32573, "io_exp_state": false, "id": 4348333385, "cv10": 580, "cv11": 0, "cv12": 268, "cv13": 0, "head": 315, "vdop": 83, "hdop": 97, "bl": 4394, "mph": 28, "valid_position": true, "lat": 18.08918, "pdop": 128, "device_id": 357666050758579, "system_time": "2016-01-12T19:40:32.799671+00:00", "cf_rssi": "10", "age": 2, "sv": 9, "io_out1": false, "io_out2": false, "io_in1": false, "io_in2": false, "io_in3": false}]'

Tips & Recommendations

Receiving data from multiple forwarders

If you are looking to receive data in your database from multiple forwarders, it is recommended that you create tables based on the PID field. This field corresponds to the Pegasus site ID, every forwarder received from different servers will have a unique PID per site.

Working with large data

When working with large data it is important to separate the database into manageable tables. For example, you could have a table for every 1 or 2 vehicles.

You may partition the vehicle tables per week or trimester. Every partition has a constraint over the Date column that way you only look over the table with the dates you’re looking for. This is especially important when you have to drop tables in the future.

Enabling a Forwarder on your site

In order to enable to create the forwarder please make sure you test with cURL or POSTman. After successfully testing you may request enabling your forwarder on your site using the following form: Submit Application

It takes approximately 8-24 hours to enable the application on your Gateway.

Source IP addresses

The source IP address for forwarded data are any of the following addresses:

• 104.238.146.47 main
• 159.203.80.12 backup
• 169.46.109.164 backup to the backup
• 169.46.109.172 backup to the backup’s backup

Live Communications

Pegasus supports live communications via web-sockets.

Web sockets allow you to subscribe to a variety of events generated from pegasus. As a developer you can catch these events, and bring some life to your applications.

Pegasus Live communications ease programming by pushing the events to you, the developer, removing the need for periodic requests.

All live communications are handled by the server found in your site’s /api response under live_url.

You can go use that site to find a demo on how it’s used, once loaded use the JS console to see the payload of the devices.

The supported socket-io.client library is v2.x.x

Note that polling is disabled on the server, you must use websocket as a transport to succesfully connect.

Use the Javascript tab on the right hand side to see sample code

Requirements

Pegasus’ Live communications uses socket.io as its backbone. We highly recommend you take a look at their website to get a deeper understanding of how websockets work, as well as their implementation. socket.io

In order to use the live functionality on your application. You need to download and run then socket.io client. Get the socket client

Emits

The live server emits some basic data, simply register some callbacks to the following handlers

socket.on('...', function(data){...})

Handler	Description
_authenticated	Authentication successful, sent when the live server has validaded your token with your gateway’s API. Includes output of resources handler.
_error	Generic error message. Authentication not successful, missing permissinos, etc.
_update	Generic update message. ex. ‘Listening to …’, or ‘Stopped listenting to …’, etc.
resources	Returns the resources you are allowed to register to. (vehicle ids, for vehicle events, triggers, etc.)
events	Primary events entry point. All events you have registered to will come in through here.

You can also emit some messages, with data to the live server as soon as you connect.

Handler	Description
authenticate	Send source and auth token to inititate authentication with live server.
resources	Request resources that are available to you.
listen	subscribe to some or all entities for a given namespace
stop	unsubscribe to some or all entities in a given namespace

Namespaces

All events generated by the Pegasus Gateway fall into namespaces. By understanding the namespaces in use, you can further tune your application to only the events you need. This allows for more specialized programming.

Currently the gateway manages the following Namespaces:

Namespace	Description
jobs	Job related events (running, error, finished, etc)
triggers	Trigger fired, trigger disabled, etc.
vehicle-events	events generated by the devices.
vehicle-nstat*	deprecated on 1.9 changes in vehicle connectivity: ONLINE/OFFLINE state

Creating a socket

// Initialize the socket
// you must use websocket as the transport, polling (default) is disabled
var socket = io('https://aws-live-0.pegasusgateway.com/socket', {transports: ['websocket']})

Once you have the socket.io client loaded, lets make a fresh socket by initializing it.

Authenticating

// Set up basic handlers
socket.on('_authenticated', function(data){
    // this will fire when we are succesfully authenticated.
    // 'data' is equal to the output of /api/user/resources
    console.log(data)
})
socket.on('_error', function(message){
    console.error(message)
})
socket.on('_update', function(message){
    console.info(message)
})
socket.on('resources', function(resources){
    console.log(resources)
})
socket.on('events', function(envelope){
    console.log(envelope)
    namespace = envelope.namespace
    vehicle = envelope.object
    events = envelope.payload
})

var credentials = {
    pegasus: "https://cloud.pegasusgateway.com", // replace with your gateway.
    auth  : "aebf772e8aa25491ed273c699baf4d35aa5c4c0342cd7b51606bbf8c" // Retrieve the token by logging via /api/login
}

socket.emit("authenticate", credentials)

The first step in receiving events live from your Pegasus Gateway, is getting authenticated.

On successful authentication you’ll be returned with the api/user response.

Now that you’re authenticated you can subscribe to namespaces.

Listening

...

var envelope = {
    "namespace":"vehicle-events",
    "objects": 617, // [197,297] or "all"
}

socket.emit("listen", envelope)

In order to start listening to events, you must send an envelope via the listen message to the live server.

the evenlope must have the following properties.

• namespace : Then namespace you are subscribing to (eg “vehicle-events”)
• objects : id or list of ids that you are subscribing to. You may also pass “all” to subscribe to all entities you have access to.

Check the console for any error or info messages reporting the status of the operation. Remember that these were handled via the _error and _update callbacks.

If everything checks out you will start receiving envelopes from the vehicle-events namespace via the events message.

socket.on('events', function(envelope){ ... })

The envelope will contain the following properties :

• object : the object the events belong to.
• payload : event or events
• namespace: namespace the events belong to.

Payload

The payload varies according to namespace.

vehicle-events

Received whenever a vehicle sends a tracking event.

The payload has a lot of keys, but the most important/relevant ones are:

device - contains information about the device, like connection/network status, trip info, state of the Inputs/Outputs event - contains the values of the event keys reported primary - info on the primary object/entity (vehicle, asset, etc) secondary - info on the secondary object/entity (asset, bluetooth tag, etc) updates - tells you what key updated (the event, or device, or both)

As mentioned above the primary and secondary keys correspond to the vehicle or asset that reported the value.
For example, when a driver (an asset) is identified via an iButton with the vehicle, the primary would be the vehicle, and secondary would be the asset. When the secondary_id is null it means that the secondary info shows the last active info. In other words, if the secondary_id shows a value it means the secondary is current, if there’s no value in secondary_id the secondary is the last known. So this would be useful for knowing if a vehicle currently has an asset assigned, if so, which one, and if not, which was the last asset assigned.

The payload keys and values are the same as the one’s you will expect when consulting via Rawdata

Please note that the same payload may be received twice, what you have to keep track of is the updates key, because it will tell you if it’s a device update such as a connection state change (from online to offline for example) or an event update, which means that a new event came in. On your applications you’ll want to show only when a new event came in, and handle the connection states when the device key is received.

Payload

Payload for vehicle-events

{
    "$$hashKey": "object:1229",
    "category": "vehicle",
    "device": {"ios_state": {…}, "gpsknit": {…}, "network": {…}, "lastrx": {…}, "trip_setup": {…}, …},
    "event": {"code": 12, "gpsknit_prev_lat": 3257884, "sv": 8, "dev_dist__mi": 3899, "event_time": 1504909832, …},
    "pid": 1,
    "primary": {"info": {…}, "associations": Array(3), "__updated": 1504110100.755031, "name": "Syrus 3 SIENNA", "trackers": Array(0), …},
    "primary_id": 686,
    "secondary_id": null,
    "type": "events",
    "updates": ["device"],
    "_pkey": "pka.05",
    "_site_url": "https://cloud.pegasusgateway.com",
    "_source": "pcore.listener",
    "_source_epoch": 1504910674.863004,
    "_ver_core": "1.9.0-rc1",
    "_ver_pcel": "2.1.1-r2"
}

Key	Description
category	event category (vehicle)
device	information on the device
event	event information reported by device
pegasus_id	unique ID for the pegasus site
pid	unique ID to the pegasus site
primary	primary entity
primary_id	primary entity id
pseq	internal use
route_state	state of the route
secondary	secondary entity
secondary_id	secondary entity id
site_id	unique ID for the pegasus site
type	type of payload
updates	keys that are updated on this payload
_pkey	internal use
_site_url	pegasus site URL
_source	internal use
_source_epoch	internal use
_ver_core	internal use
_ver_pcel	internal use
$$hashKey	internal use

Detailed payload description

DEVICE

accel_state

Acceleration state

Key	Description
ap_cur_deg_x	current degrees x plane
ap_cur_deg_y	current degrees y plane
ap_cur_deg_z	current degrees z plane
ap_cur_mag	current magnitude (vector force in the direction it’s moving)
ap_mov	true if moving
ap_ref_deg_x	reference or configured x plane value at the time of calibration
ap_ref_deg_y	reference or configured y plane value at the time of calibration
ap_ref_deg_z	reference or configured z plane value at the time of calibration

asset

asset information

Key	Description
aid	asset id
aid_source	source of the asset, ib for ibutton, btt for bluetooth tag, fp for fingerprint, rfid for RFID
btt_mac	bluetooth tag mac address
bttag	bluetooth tag associated info
bttag.asset_id	bluetooth tag asset id
bttag.created_at	bluetooth tag date of creation
bttag.edited_at	bluetooth tag date of edition
bttag.mac	bluetooth tag mac address
bttag.short_code	bluetooth tag short code
ib	ibutton HEX ID
last_aid_source	the last asset id source
rfi_full_id	rfid

config

configuration description

Key	Description
devconfig_id	unique id for the device’s configuration
ky	unique key for managed configurations
kydef	configuration definition data (includes information about support for accessories and names of inputs/outputs)
kymissmatch	only present if the device is sending a ky different then the one configured on pegasus
kymod	last configuration modification time
pending	true if there’s a configuration pending to be set
pending_count	number of commands pending to be sent to the device from the new configuration
safeimmo_support	true if it’s using managed configuration and it supports safe_immobilization on output 1
total_count	total number of commands pending to be sent
values	configuration values such as the speedlimit and rpm limit, among others.
_config_state	1 if pending, 3 if synchronized
_epoch	time of the last config modification

connection

connection state / information

Key	Description
last	last connection information
off_codes	codes for reasons why it went offline
on_codes	codes for reasons why it came back online
online	true if device is online
_epoch	epoch timestamp of last connection change

dcounters

device counters

for a detailed description you can check the counters description

gpsknit

gps information

Key	Description
ack_id	internal use
event_time__epoch	epoch timestamp of the event time
lat	latitude
lon	longitude
no_gps_time_count	time in seconds with no gps coordinates
no_location_count	number of consecutive events with no gps
no_location_fepoch	no location epoch timestamp
prev_ack_id	internal use
prev_event_time__epoch	previous event epoch timestamp
prev_lat	previous latitude
prev_lon	previous longitude
_epoch	epoch timestamp

imei

IMEI is the imei of the device

ios_state

state of the inputs and outputs

for a detailed description you can check the master field list

lastrx

last communication time

Key	Description
msg_type	type of message
value	timestamp it reported that message type
_epoch	timestamp it was received

latest

latest data reported by the device

Key	Description
counters	latest counters reported
data	latest data reported, same keys as rawdata more info
ios	latest ios reported
loc	latest location information
prefix	internal use
vcounters	latest vehicle counters

lcounts

Listener counts, more information coming soon

legacy_set_out_state

current state of the outputs, useful for knowing if output is pending to be set/reset

Key	Description
io_out[index]	outputs 1-2 on device
io_exp_out[index]	io expander output 1-4
cid	command id
instruction	current instruction
set_at	epoch time it was set at
uid	user id that set it

lrates

Listener rates, more information coming soon

muted_evs:

Muted or silenced events on the device information

net_reg

Network registration information

Key	Description
cf_cid	Cell ID
cf_lac	Location Area Code
cf_mcc	MCC
cf_mnc	MNC
cf_rssi	RSSI
cf_type	Registration type (2g, 3g, lte, etc)
_epoch	Network information last update epoch

network

network information from device

Key	Description
cnum	carrier sim phone number (doesn’t always reflect the number of the sim card due to restrictions from some carriers)
imsi	sim imsi
op	operator
sim	sim id
_epoch	epoch timestamp

outbox

Array with the commands pending to be sent to the device

Key	Description
ctype	Command type
id	Command ID
msg	Message to be sent to the device
time	Time message was placed on queue
uid	User ID that sent the message
useky	Internal use

photos

state of the cameras connected to the device

Key	Description
cams	object with each camera’s event id
evid	event id for photo captured
ncams	number of cameras connected to device
_epoch	timestamp the data was reported

position_response

Information about the latest response to a position message while the device was offline.

satcom

Last satcom related information

safeimmo_state

current state of the safe immobilization

Key	Description
cid	command id
instruction	current instruction
set_at	epoch time it was set at
uid	user id that set it
_epoch	timestamp

set_out_state

Output activation information, whether or not an instruction is pending to be sent to manipulate an output

sigfox

Last sigfox related information

sim

SIM card related information including iccid, imsi, operator, and more.

trip

device trip information

Key	Description
aid	asset id associated to trip
dev_msgs	internal use
groups	id of the groups the vehicle belongs to during trip
id	trip id
ky	device configuration
method	trip’s method (gps)
moving	true if vehicle is currently on a trip, false means parked
signal	internal use
src_id	internal use
src_type	internal use
start_evdistance	distance traveled at the start of trip
start_lat	start latitude
start_lon	start longitude
start_time_epoch	event time at start of trip
system_time_epoch	system time at start of trip
vid	vehicle id
_epoch	epoch timestamp

trip_session

device trip session information

Key	Description
closing_data	data that closes the trip
first_event	opening event of trip
latest_event	latest event
max_speed	max speed in mph
max_speed_hdop	max speed in hdop (value must be divided by 100)
max_speed_lat	max speed location latitude
max_speed_lon	max speed location longitude
max_speed_time	epoch timestamp of max speed
opened_at	time the trip session was opened
__persistent	internal use
__version	internal use
_epoch	epoch timestamp of trip_session

trip_setup

Key	Description
method	how the trip is formed (whether with tracker or gps events)
state	raw trip message setup from Syrus, for more info check XATT on syrus manual
_epoch	epoch timestamp

vcounters

user editable vehicle counters, for more information go to counters

vehicle

vehicle information

version

Key	Description
device	device model
extras	firmware extra information
msg	device message
number	version firmware number

virtual_distance

virtual distance calculated via lat lon deltas

Key	Description
evtime_epoch	time the event was generated
lat	latitude
lon	longitude
value	distance for device
_epoch

virtual_ignition

virtual ignition calculated based on the status of the io_ign

Key	Description
delta_dist	Delta total distance traveled
event_time	Event time of last io_ign
idle_buffer	Idle buffer
idle_counter	Idle time in seconds
ign_counter	Ignition time in seconds
io_idle	Idle state
io_ign	Ignition state
vid	Vehicle ID
_epoch	Time of last virtual_ignition change

event

list of event parameters reported by device, check out master field list for more info

vehicle-nstat *

Deprecated on 1.9 Received whenever a vehicle changes its ONLINE/OFFLINE status.

Payload keys:

• imei : (number) Device IMEI
• vid : (number) Associated vehicle ID
• online : (boolean) Connectivity status

You may receive other keys, they exist for testing, they may not exist on future releases.

Stopping

...

var envelope2 = {
    "namespace":"vehicle-events",
    "objects": "all", // [197,297] or 617
}

socket.emit("stop", envelope2)

In order to stop receiving events from some objects in a certain namespace, you simply send an envelope identical to the one used for subscribing via the stop message

FAQ

Device Network State

The device network state can be found under device.connection.online, true whenever the device is ONLINE.

Valid Position

There are 3 keys that can be used to find out whether the position of the event is valid, they’re all essentially the same: device.data.valid_gps also in the event’s keys: event.valid_gps device.data.valid_position also in the event’s keys: event.valid_position device.latest.loc.valid

Authentication Errors

Try updating the socket.io client to version 2.0.3 or higher.

Data Receivers

Pegasus allows you to upload custom device data via an HTTP POST method. For example, position related information from other telemetry devices for analysis in the Pegasus API & visualization in the Pegasus Application.

Data can be uploaded and associated to an entity type vehicle or to an entity type: asset.

Receive for a vehicle

Read the following instructionss on how to get started uploading data to your Pegasus Gateway from third party platforms/devices - documentation for Gateway administrators / documentation for end user/developer

Intro

In order to start receiving data from third party devices via an HTTP POST, you’ll need to:

• Step 1: Activate the JSON receiver for your Pegasus Gateway
• Step 2: Add the device IMEI that you’ll be sending data from to the API
• Step 3: Create an application token

For the first 2 steps you can contact your account representative.

For the last step you can use the Webservices section of Pegasus Gateway or see the tokens api section to create data receiver tokens.

Receive for an asset

Authentication

POST /api/assets

creating an asset

{
  "first_name": "name of asset",
  "type": "tracking_device"
}

200 OK (id: 3315)

{
  "info": {},
  "__updated": 1553211859.1255651,
  "name": "name of asset ",
  "ibuttons": [],
  "__created": 1553211859.1255569,
  "fingerprints": [],
  "primary": null,
  "properties": {},
  "images": {},
  "token": null,
  "tracker": {
    "active": false,
    "asset_id": 3315,
    "token": null
  },
  "groups": [],
  "device": null,
  "rfids": [],
  "type": "asset",
  "id": 3315,
  "counters": null
}

enabling the Taurus tracker code

PUT /api/assets/3315

{
  "tracker_mode": true
}

200 OK

{
  ...
  "tracker": {
    "asset_id": 3315,
    "site_id": 1,
    "site_url": "cloud.pegasusgateway.com",
    "active": true,
    "token": "UTNZEHBL",
    "device": 450000141115142
  },
  ...
}

setting the configuration to the device

POST /api/device-config/450000141115142

{
  "ky": "s000"
}

200 OK

{
  "kydef": {},
  "kymod": {},
  "total_count": 19,
  "_config_state": 1,
  "_epoch": 1553253405.348958,
  "ky": "s000",
  "devconfig_id": 9188,
  "pending": true
}

To get started we’ll need to generate a token that we’ll use to reference the asset that we want to populate data with on Pegasus Gateway. In order to create this token you’ll have to create a new asset via the POST /assets here you can populate the asset with the included parameters such as first_name, last_name, email, type (type is required), etc.

After you create the asset you’ll need to activate a token for it, to do this make a PUT /assets with tracker_mode: true.

This will generate a unique token for that particular asset that we can use to POST data to. Example token: UTNZEHBL

To prepare the asset to receive data we have to assign the device associated to this asset a configuration. This can be done with POST /api/device-config/:imei sending a key ky with the value s000

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Upload data

POST https://api.pegasusgateway.com/assets/event?tracker=UTNZEHBL

note that the POST is always made to ‘api.pegasusgateway.com’

using server time

{
  "latitude": 20.993852,
  "longitude": -89.710796,
  "mph": 10,
  "heading": 342,
  "altitude": 10,
  "label": "ignon",
  "use_server_time": true
}

200 OK

{
  "message": "event processed successfully"
}

using an epoch

{
  "latitude": 21.993852,
  "longitude": -90.710796,
  "mph": 99,
  "heading": 193,
  "altitude": 200,
  "label": "ignoff",
  "use_server_time": false,
  "epoch": 1553187370
}

In order to publish telemetry data to Pegasus server, send POST request to the following URL: https://api.pegasusgateway.com/assets/event?tracker=:token

replacing :token with the token generated previously.

The only keys the upload API is accepting at the moment are:

param	type	description
latitude	number	WGS84 latitude
longitude	number	WGS84 longitude
mph	number	speed in mph
heading	number	heading in degrees 0-359 0=north, 90=east, etc.
altitude	number	device altitude in meters
[label]	string	event label (if not specified a trckpnt is automatically assigned) see list of labels below
use_server_time	boolean	true to use a server timestamp for the incoming data

Common labels

label	description
prdtst	Periodic report with ignition OFF
trckpnt	Periodic report with Ignition ON (default if no label is set)
ignon	Ignition was turned ON
ignoff	Ignition was turned OFF
panic	report when a panic button is pressed
pwrloss	Main power was lost
pwrrstd	Main power was restored
lwbatt	Low internal device battery
spd	Speeding
idl	Idling
stt	Device motion
stp	Device stopped moving
in1on	Input 1 ON
in1off	Input 1 OFF
in2on	Input 2 ON
in2off	Input 2 OFF
in3on	Input 3 ON
in3off	Input 3 OFF

For a full list of the core labels please check out the core labels api: api/core_labels

Please note that if the use_server_time is not set, the server-side timestamp will be assigned to uploaded data!

In case your device is able to get the client-side timestamp, you can use following format:

{“epoch”:1532452713}

In the example above, we assume that “1532452713” is a unix timestamp with seconds precision. ‘1532452713’ corresponds to ‘Tuesday, July 24, 2018 5:18:33 PM GMT’

Reverse Geocoding

There are two reversegeo APIs, the first one is /api/reversegeo this one returns the names of any geofences found in the location you pass it, as well as an address. The second reversegeo api is maps.pegasusgateway.com/reversegeo which is more up to date in terms of the addresses it returns and is capable of returning bulk addresses in multiple language formats, read below to find out.

api/reversegeo

GET

api/reversegeo?lat=25.78362&lon=-80.293265&zones=true

{
    "zones": [
        "DCT",
        "US - Florida"
    ],
    "location_full": "(DCT)(US - Florida) 33126, Miami-Dade County, Florida, US",
    "address": "33126, Miami-Dade County, Florida, US"
}

The GET request can be used to retrieve a single lat,lon result. The response will show you the:

• zones (name of any geofence that this point is in)
• location_full (zones + address)
• address (address of location)

GET /api/reversegeo params

URL params	description
lat	latitude
lon	longitude
zones	set to true to return the zones the point is in
auth	pegasus auth token (overrides Authenticate header)

 
 
 
 

POST

multiple lat lon pairs

api/reversegeo

[
  {
    "key": "one",
    "lat": 25.78362,
    "lon": -80.293265
  },
  {
    "key": "two",
    "lat": 25.79362,
    "lon": -80.293265
  }
]

200 OK

{
    "two": {
        "zones": [
            "US - Florida"
        ],
        "location_full": "(US - Florida) 33126, Miami-Dade County, Florida, US",
        "address": "33126, Miami-Dade County, Florida, US"
    },
    "one": {
        "zones": [
            "DCT",
            "US - Florida"
        ],
        "location_full": "(DCT)(US - Florida) 33126, Miami-Dade County, Florida, US",
        "address": "33126, Miami-Dade County, Florida, US"
    }
}

With the post request you can pass multiple latitude, longitude pairs.

When you send multiple points you must specify a key, this will help you identify which json object corresponds to which lat, lon requested

POST /api/reversegeo params

params	description
lat	latitude
lon	longitude
key	required key when using multiple lat lon

maps/reversegeo

The maps/reversegeo reverse geocoding API allows you to convert lat,lon coordinates into a human-readable address. The API synchronizes daily with OSM to bring the latest address information. The neat thing is this means you can edit something on OSM and see it reflected on the reversegeo API. Another notable difference is that this API does not provide the zones information.

maps API endpoint https://maps.pegasusgateway.com/reversegeo

GET

reversegeo?r=25.78362,-80.293265

{
    "errors": {},
    "results": {
        "025.78362000:-080.29327000": "5835 Blue Lagoon Drive. MIAMI-DADE COUNTY, FL 33126 US"
    }
}

reversegeo?r=32.0769,34.8151

{
  "errors": {},
  "results": {
    "032.07690000:0034.81510000": "כצנלסון. גבעתיים, מחוז תל אביב 53100 IL"
  }
}

reversegeo?r=32.0769,34.8151&fmt={$one-line-short}

{
  "errors": {},
  "results": {
    "032.07690000:0034.81510000": "כצנלסון. גבעתיים"
  }
}

reversegeo?r=32.0769,34.8151&lang=en

{
  "errors": {},
  "results": {
    "032.07690000:0034.81510000": "Katsanelson. GIVATAYIM, TEL AVIV DISTRICT 53100 IL"
  }
}

reversegeo?r=32.0769,34.8151&include_data=1&lang=en&return_as=debug&fmt={address}

{
  "how": {
    "items": 1,
    "dt": 0.004695892333984375,
    "borders": [
      "israel-and-palestine"
    ],
    "rate": 212.95207148659625
  },
  "result": [
    {
      "lat": 32.0769,
      "lon": 34.8151,
      "_revgeo": {
        "dt": 0.004678964614868164,
        "result": {
          "text": "Katsanelson",
          "data": {
            "address": "Katsanelson",
            "boundary_ref_all_csv": "Givatayim, Tel Aviv District",
            "street": "Katsanelson",
            "boundary_admin_level_8": "Givatayim",
            "pcode": "53100",
            "boundary_all_two-line": "Givatayim, Tel Aviv District",
            "ccode": "il",
            "boundary_admin_level_4": "Tel Aviv District",
            "address_ns": "Katsanelson",
            "aprox": "",
            "address_sn": "Katsanelson",
            "boundary_ref_admin_level_4": "Tel Aviv District",
            "boundary_ref_admin_level_8": "Givatayim",
            "boundary_ref_b": "Tel Aviv District",
            "boundary_ref_a": "Givatayim",
            "boundary_a": "Givatayim",
            "boundary_b": "Tel Aviv District",
            "boundary_all_csv": "Givatayim, Tel Aviv District"
          },
          "reduced": {
            "boundaries": [
              {
                "admin_level": 8,
                "parent_place_id": 466107,
                "name": "Givatayim",
                "ref": null,
                "place_id": 461879,
                "osm_id": 1382923,
                "osm_type": "R",
                "type": "administrative",
                "extratags": {
                  "website": "http://www.givatayim.muni.il",
                  "contact:website": "http://www.givatayim.muni.il",
                  "wikipedia": "en:Giv'atayim",
                  "wikidata": "Q152413",
                  "place": "town",
                  "population": "57508"
                }
              },
              {
                "admin_level": 4,
                "parent_place_id": 462199,
                "name": "Tel Aviv District",
                "ref": null,
                "place_id": 466107,
                "osm_id": 1400916,
                "osm_type": "R",
                "type": "administrative",
                "extratags": {
                  "wikidata": "Q192811",
                  "wikipedia": "de:Bezirk Tel Aviv"
                }
              }
            ],
            "building": {
              "_inside": false,
              "admin_level": 15,
              "parent_place_id": 447044,
              "name": null,
              "distance": 78.6753360331113,
              "housenumber": "18",
              "place_id": 392216,
              "_same_street": false,
              "osm_type": "W",
              "street": "סירקין",
              "osm_id": 236768869,
              "_w_index": null,
              "extratags": null,
              "class": "building"
            },
            "pcode": "53100",
            "streets": [
              {
                "distance": 2.19657702619019,
                "parent_place_id": 129276,
                "name": "Katsanelson",
                "ref": null,
                "place_id": 407406,
                "osm_id": 248990288,
                "osm_type": "W",
                "type": "tertiary",
                "extratags": {
                  "oneway": "yes"
                }
              },
              {
                "distance": 13.2604261534137,
                "parent_place_id": 129276,
                "name": "Katsanelson",
                "ref": null,
                "place_id": 379054,
                "osm_id": 157019162,
                "osm_type": "W",
                "type": "tertiary",
                "extratags": {
                  "oneway": "yes"
                }
              }
            ],
            "ccode": "il"
          }
        }
      }
    }
  ]
}

For a single address request

• Synth method is forced to "amia_text"

URL params	description
r	, pair
auth	pegasus auth token (overrides Authenticate header)
fmt	synth.fmt
lang	synth.lang
include_data	synth.include_data
return_as	same as on POST

POST

fmt options

{$multi-line}

137 Pilkington Avenue 
SUTTON COLDFIELD
BIRMINGHAM
B72 GB

{$one-line}

137 Pilkington Avenue. SUTTON COLDFIELD, B72 BIRMINGHAM GB

{$two-line}

137 Pilkington Avenue
SUTTON COLDFIELD, B72 BIRMINGHAM GB

{$one-line-short}

137 Pilkington Avenue. SUTTON COLDFIELD

---

basic "return_as": "dict"

body

{
  "list": [
    {
      "lat": 25.7711,
      "lon": -80.2774
    },
    {
      "lat": 52.54874,
      "lon": -1.81602
    },
    {
      "lat": 4.6702,
      "lon": -74.0541
    }
  ],
  "synth": {
    "method": "amia_text",
    "lang": "es"
  },
  "return_as": "dict"
}

response

{
  "errors": {},
  "results": {
    "025.77110000:-080.27740000": "5050 West Flagler Street. MIAMI, 33134 FL US",
    "052.54874000:-001.81602000": "137 Pilkington Avenue. SUTTON COLDFIELD, B72 BIRMINGHAM GB",
    "004.67020000:-074.05410000": "Carrera 14 85-68. CHAPINERO, BOGOTÁ CO"
  }
}

---

dict with custom keys

body

{
  "list": [
    {
      "lat": 25.7711,
      "lon": -80.2774,
      "key": "mykey1"
    },
    {
      "lat": 52.54874,
      "lon": -1.81602,
      "key": "mykey2"
    },
    {
      "lat": 4.6702,
      "lon": -74.0541,
      "key": "mykey3"
    }
  ],
  "synth": {
    "method": "amia_text",
    "lang": "es"
  },
  "return_as": "dict"
}

response

{
  "errors": {},
  "results": {
    "mykey3": "Carrera 14 85-68. CHAPINERO, BOGOTÁ CO",
    "mykey2": "137 Pilkington Avenue. SUTTON COLDFIELD, B72 BIRMINGHAM GB",
    "mykey1": "5050 West Flagler Street. MIAMI, 33134 FL US"
  }
}

---

return as list (experimental)

body

{
  "list": [
    {
      "lat": 25.7711,
      "lon": -80.2774
    },
    {
      "lat": 52.54874,
      "lon": -1.81602
    },
    {
      "lat": 4.6702,
      "lon": -74.0541
    }
  ],
  "synth": {
    "method": "amia_text",
    "lang": "es"
  },
  "return_as": "list"
}

response

{
  "errors": [],
  "results": [
    "5050 West Flagler Street. MIAMI, 33134 FL US",
    "137 Pilkington Avenue. SUTTON COLDFIELD, B72 BIRMINGHAM GB",
    "Carrera 14 85-68. CHAPINERO, BOGOTÁ CO"
  ]
}

---

formatting text

body

{
  "list": [
    {
      "lat": 25.7711,
      "lon": -80.2774
    },
    {
      "lat": 52.54874,
      "lon": -1.81602
    },
    {
      "lat": 4.6702,
      "lon": -74.0541
    }
  ],
  "synth": {
    "method": "amia_text",
    "lang": "es",
    "fmt": " {address}"
  },
  "return_as": "list"
}

response

{
  "errors": [],
  "results": [
    "5050 West Flagler Street",
    "137 Pilkington Avenue",
    "Carrera 14 85-68"
  ]
}

---

text and data

body

{
  "list": [
    {
      "lat": 25.7711,
      "lon": -80.2774
    },
    {
      "lat": 52.54874,
      "lon": -1.81602
    },
    {
      "lat": 4.6702,
      "lon": -74.0541
    }
  ],
  "synth": {
    "method": "amia_text",
    "lang": "es",
    "fmt": " {address}",
    "include_data": true
  },
  "return_as": "list"
}

response

{
  "errors": [],
  "results": [
    {
      "text": "5050 West Flagler Street",
      "data": {
        "address_ns": "5050 West Flagler Street",
        "boundary_ref_county": "12-086",
        "boundary_ref_city": "Miami",
        ...

---

override synth for a single lat-lon object

body

{
  "list": [
    {
      "lat": 25.7711,
      "lon": -80.2774
    },
    {
      "lat": 41.4063,
      "lon": 2.2046
    },
    {
      "lat": 32.0769,
      "lon": 34.8151,
      "synth": {
        "method": "amia_text",
        "lang": "en",
        "fmt": "{$multi-line}"
      }
    }
  ],
  "return_as": "dict",
  "synth": {
    "method": "amia_text",
    "lang": "es",
    "fmt": "{$one-line}",
    "include_data": false
  }
}

response

{
  "errors": {},
  "results": {
    "025.77110000:-080.27740000": "5050 West Flagler Street. MIAMI, 33134 FL US",
    "041.40630000:0002.20460000": "Carrer de Pallars 318. BARCELONA, 08019 CT ES",
    "032.07690000:0034.81510000": "Katsanelson - Katsanelson\nGIVATAYIM\nTEL AVIV DISTRICT\n53100 IL\n"
  }
}

The POST method is used to pass single or multi line lat,lon reverse geocoding

• Authenticate header required: Any token from a valid pegasus session
• Rates: Per user, site, and global. Rate control is not based on number of POST requests but on number of locations requests for reverse-geo processing. Enforced via http 429. On 429, current returned object is pretty crude, and gives no info on when the ban is lifted, however, indication of which rate is violated is given.

Request object keys

• list: A list of lat-lon objects to resolve (max 100 per call)
  • lat-lon Object with lat lon, optional key, optional synth
• return_as: String: dict|list: Indicates how to return results. list yields to a list with the same size as the passe one. dict returns a dict whose keys are either the key passed on the lat-lon object, otherwise, an internally constructed key representaing the lat+lon object
• synth: Object. Controls how data results are returned/formatted. This object may be defined also per lat-lon object to override the request-wide set. This should be used when some of the lat-lon objects on list need to be synthetized different than the majority of items.

synth keys:

• method: String. Method to process:
  • 'std_text': return text. Legacy format
  • 'amia_text': return text. An fmt argument may be passed to format the result. An include_data boolean may be passed so that data objects, as well as text is returned.
  • 'reduced': Returns an useful object to play with.
  • If method is not passed, a long debug object is returned.
• 'lang': String (en|es|it|fr|... etc). When available, try to return names in this language.
• 'fmt': For amia_text method. An interpolation string to format the returned text. Some fields to pick: Interpolation: python formatter. Use !u and !l to convert upper, lower case, see combos below for examples

address formatting (fmt)
{boundary_ref_county}
{boundary_ref_city}
{street}
{ccode}
{address}
{boundary_county}
{boundary_ref_b}
{boundary_ref_a}
{boundary_a}
{boundary_city}
{pcode}
{boundary_b}
{boundary_ref_state}
{intersect}
{aprox}
{hnumber}
{boundary_state}
{address_sn}

---

{$one-line}

body

{
  "list": [
    {
      "lat": 25.7711,
      "lon": -80.2774
    },
    {
      "lat": 52.54874,
      "lon": -1.81602
    },
    {
      "lat": 4.6702,
      "lon": -74.0541
    }
  ],
  "return_as": "dict",
  "synth": {
    "method": "amia_text",
    "lang": "es",
    "fmt": "{$one-line}",
    "include_data": false
  }
}

response

{
  "errors": {},
  "results": {
    "012.15370000:-086.24860000": "27a Avenida N.E. - Carretera Norte. MANAGUA (MUNICIPIO),11005 MANAGUA NI",
    "007.10940000:-073.11670000": "Calle 55 - Carrera 21. BUCARAMANGA, SAN CO",
    "-34.88420000:-056.16940000": "Doctor Juan José de Amézaga - Cufré. MONTEVIDEO, 11800MONTEVIDEO UY"
  }
}

---

{$two-line}

body

{
  "list": [
    {
      "lat": 25.7711,
      "lon": -80.2774
    },
    {
      "lat": 52.54874,
      "lon": -1.81602
    },
    {
      "lat": 4.6702,
      "lon": -74.0541
    }
  ],
  "return_as": "dict",
  "synth": {
    "method": "amia_text",
    "lang": "es",
    "fmt": "{$two-line}",
    "include_data": false
  }
}

response

{
  "errors": {},
  "results": {
    "012.15370000:-086.24860000": "27a Avenida N.E. - Carretera Norte\nMANAGUA (MUNICIPIO), 11005 MANAGUA NI",
    "007.10940000:-073.11670000": "Calle 55 - Carrera 21\nBUCARAMANGA, SAN CO",
    "-34.88420000:-056.16940000": "Doctor Juan José de Amézaga - Cufré\nMONTEVIDEO, 11800 MONTEVIDEO UY"  
  }
}

---

{$multi-line}

body

{
  "list": [
    {
      "lat": 25.7711,
      "lon": -80.2774
    },
    {
      "lat": 52.54874,
      "lon": -1.81602
    },
    {
      "lat": 4.6702,
      "lon": -74.0541
    }
  ],
  "return_as": "dict",
  "synth": {
    "method": "amia_text",
    "lang": "es",
    "fmt": "{$multi-line}",
    "include_data": false
  }
}

response

{
  "errors": {},
  "results": {
    "012.15370000:-086.24860000": "27a Avenida N.E. - Carretera Norte\nMANAGUA (MUNICIPIO)\nMANAGUA\n11005 NI\n",
    "007.10940000:-073.11670000": "Calle 55 - Carrera 21\nBUCARAMANGA\nSANTANDER\nCO\n",
    "-34.88420000:-056.16940000": "Doctor Juan José de Amézaga - Cufré\nMONTEVIDEO\nMONTEVIDEO\n11800 UY\n"
  }
}

---

{$one-line-short}

body

{
  "list": [
    {
      "lat": 25.7711,
      "lon": -80.2774
    },
    {
      "lat": 52.54874,
      "lon": -1.81602
    },
    {
      "lat": 4.6702,
      "lon": -74.0541
    }
  ],
  "return_as": "dict",
  "synth": {
    "method": "amia_text",
    "lang": "es",
    "fmt": "{$one-line-short}",
    "include_data": false
  }
}

response

{
  "errors": {},
  "results": {
    "012.15370000:-086.24860000": "27a Avenida N.E. - Carretera Norte. MANAGUA (MUNICIPIO)",
    "007.10940000:-073.11670000": "Calle 55 - Carrera 21. BUCARAMANGA",
    "-34.88420000:-056.16940000": "Doctor Juan José de Amézaga - Cufré. MONTEVIDEO"
  }
}

combos formatting	fields
{$multi-line}	{address} {boundary_a!u} {boundary_b!u} {pcode} {ccode!u}
{$one-line}	default when no fmt is passed {address}. {boundary_a!u}, {pcode} {boundary_ref_b!u} {ccode!u}
{$two-line}	{address} {boundary_a!u}, {pcode} {boundary_ref_b!u} {ccode!u}
{$one-line-short}	{address} {boundary_a!u}

Master Fields List

By default all fields marked in the Base set are included in forwarders unless you filter it in the general config. To add fields use the keys or keys_include options in the general field of the forwarders configuration

json format

sql format

Spreadsheet with example values

Field	Info	Type	Unit	Base set
ac	GPS acceleration	number	mph/s	✓
ad	ADC value	number	mV	✓
adas_distance_from_front_vehicle	ADAS distance from front of vehicle	number	meters
adas_headway_measurement	ADAS headway measurement	number	seconds
adas_headway_warning_level	ADAS headway warning level	number
adas_relative_speed_from_front_vehicle	ADAS relative speed from front of vehicle	number	kph
adas_speed_limit_recognition_sensitivity	ADAS speed limit recognition sensitivity	number
adas_speed_limit_recognition_state	ADAS speed limit recognition state	number
adas_speed_limit_recognition	ADAS speed limit recognition	number
adas_speed	ADAS measured speed	number	kph
adas_traffic_signs_recognition_warning_level	ADAS traffic signs recognition warning level	number
adas_vision_only_sign_type	ADAS vision only sign type	number
age	GPS age	number		✓
aid	Asset id	number
al	Altitude	number	meters	✓
an_diff_in1_in2	Analog diff. input 1, input 2	number	mV
an_diff_in3_in4	Analog diff. input 3, input 4	number	mV
an_diff_in5_in6	Analog diff. input 5, input 6	number	mV
an_diff_in7_in8	Analog diff. input 7, input 8	number	mV
an_fdiff_in1_in2	Analog filtered diff. input 1, input 2	number	mV
an_fdiff_in3_in4	Analog filtered diff. input 3, input 4	number	mV
an_fdiff_in5_in6	Analog filtered diff. input 5, input 6	number	mV
an_fdiff_in7_in8	Analog filtered diff. input 7, input 8	number	mV
an_in1	Analog input 1	number	mV
an_in2	Analog input 2	number	mV
an_in3	Analog input 3	number	mV
an_in4	Analog input 4	number	mV
an_in5	Analog input 5	number	mV
an_in6	Analog input 6	number	mV
an_in7	Analog input 7	number	mV
an_in8	Analog input 8	number	mV
ap_cur_deg_x	Current angle in x-axis	number	degrees
ap_cur_deg_y	Current angle in y-axis	number	degrees
ap_cur_deg_z	Current angle in z-axis	number	degrees
ap_cur_mag	Instant acceleration	number	milli-g
ap_mov	Movement by accelerometer	boolean
ap_ref_deg_x	Reference angle in x-axis	number	degrees
ap_ref_deg_y	Reference angle in y-axis	number	degrees
ap_ref_deg_z	Reference angle in z-axis	number	degrees
axl_weight_trailer	Axle weight for trailer	number	tons
axl_weight_trailer_total	Total axle weight for trailer	number	tons
axl_weight_truck	Axle weight truck	number	tons
axl_weight_truck_total	Total axle weight for truck	number	tons
axl_weights	All axle weights	string	tons
axl_weights_01	Axle 1 weight	number	tons
axl_weights_02	Axle 2 weight	number	tons
axl_weights_03	Axle 3 weight	number	tons
axl_weights_04	Axle 4 weight	number	tons
axl_weights_05	Axle 5 weight	number	tons
axl_weights_06	Axle 6 weight	number	tons
axl_weights_07	Axle 7 weight	number	tons
axl_weights_08	Axle 8 weight	number	tons
bl	Device battery level	number	mV	✓
btt_battery	Bluetooth tag battery	number	mV
btt_button	Bluetooth tag button	boolean
btt_driver	Bluetooth tag driver	number
btt_driver_set	Presence of bt tag driver	boolean
btt_freefall	Bluetooth tag freefall	boolean
btt_humidity	Bluetooth tag humidity	number	%
btt_impact	Bluetooth tag impact	boolean
btt_light	Bluetooth tag light	number	%
btt_mac	Bluetooth tag MAC	string
btt_motion	Bluetooth tag motion	boolean
btt_presence	Bluetooth tag presence	boolean
btt_reed	Bluetooth tag reed switch	boolean
btt_temp	Bluetooh tag temperature	number	°C
btt_wreason	Bluetooth tag wake up reason	string
ce	Device ignition on timer	number	seconds
cf_cid	Cell ID	number	HEX	✓
cf_lac	Local area code	number	HEX	✓
cf_mcc	GSM Mobile country code	number
cf_mnc	GSM Mobile network code	number
cf_rssi	RSSI	number	dBm	✓
cf_type	Radio link technology	string
checkpoint	Checkpoint id	number
cl	Device idle on timer	number	seconds
climb_detection	Climb detected	boolean
code	Event Code	number		✓
comdelay	Communication delay	number	seconds
counter_ack_duration	Counter GSM	number
counter_bytes_mo	Counter GPRS	number
counter_bytes_mt	Counter GPRS bearer	number
counter_io_tamper	Total duration of tamper detection (case opened for Syrus 3/3G/CC devices only)	number	seconds
counter_io_in1	Total duration of input 1 activation	number	seconds
counter_io_in2	Total duration of input 2 activation	number	seconds
counter_io_in3	Total duration of input 3 activation	number	seconds
counter_io_out2	Total duration of output 1 activation	number	seconds
counter_io_out1	Total duration of output 2 activation	number	seconds
counter_io_exp_in1	Total duration of IO expander input 1 activation	number	seconds
counter_io_exp_in2	Total duration of IO expander input 2 activation	number	seconds
counter_io_exp_in3	Total duration of IO expander input 3 activation	number	seconds
counter_io_exp_in4	Total duration of IO expander input 4 activation	number	seconds
counter_io_exp_out1	Total duration of IO expander output 1 activation	number	seconds
counter_io_exp_out2	Total duration of IO expander output 2 activation	number	seconds
counter_io_exp_out3	Total duration of IO expander output 3 activation	number	seconds
counter_io_exp_out4	Total duration of IO expander output 4 activation	number	seconds
counter_io_exp_out1_short	Total duration of IO expander output 1 short-circuit activation	number	seconds
counter_io_exp_out2_short	Total duration of IO expander output 2 short-circuit activation	number	seconds
counter_io_exp_out3_short	Total duration of IO expander output 3 short-circuit activation	number	seconds
counter_io_exp_out4_short	Total duration of IO expander output 4 short-circuit activation	number	seconds
counter_reset_gprs	Counter retransmissions	number
counter_reset_gprs_bearer	Counter bytes transmitted	number
counter_reset_gsm	Counter bytes received	number
counter_retransmissions	Counter transmissions	number
counter_transmissions	Counter acknowledge duration	number
cr	Device over rpm time	number	seconds
cs	Device over speed	number	seconds
cv00-49	Counter value	number		✓
dev_dist	Absolute total distance traveled	number	meters
dev_idle	Absolute total idling count	number	seconds
dev_ign	Absolute total ignition ON count	number	seconds
dev_orpm	Absolute total over RPM time	number	seconds
dev_ospeed	Absolute over speed time	number	seconds
device_id	IMEI (unique identifier per device)	number		✓
dphoto_ptr	Photo ID	number	seconds
ea_a	Analog / temp sensor probe A	number	mV / °C	✓
ea_b	Analog / temp sensor probe B	number	mV / °C	✓
ea_c	Analog / temp sensor probe C	number	mV / °C	✓
ecu_ac_high_pressure_fan	A/C high pressure fan switch	number
ecu_ac_state	AC state	number
ecu_accumulated_charge	Accumulated charged electric quantity	number	kwh
ecu_accumulated_discharge	Accumulated discharged electric quantity	number	kwh
ecu_aftmt_doc_intk_tmp	Aftertreatment DOC intake temp	number	°C
ecu_aftmt_dpf_diff_psi	Aftertreatment DPF diff pressure	number	psi
ecu_aftmt_dpf_intake_tmp	Aftertreatment DPF intake temp	number	°C
ecu_aftmt_dpf_outlet_tmp	Aftertreatment DPF outlet temp	number	°C
ecu_aftmt_dpf_soot_load	Aftertreatment DPF soot regeneration	number	%
ecu_aftmt_intake_nox	Aftertreatment intake NOx	number	ppm
ecu_aftmt_outlet_nox	Aftertreatment outlet NOx	number	ppm
ecu_aftmt_purge_air_act	Aftertreatment purge air actuator	number
ecu_aftmt_scr_intake_tmp	Aftertreatment SCR intake temp	number	°C
ecu_aftmt_scr_outlet_tmp	Aftertreatment SCR outlet temp	number	°C
ecu_air_flow_state	Air flow state	number
ecu_aload	Absolute load	number	%
ecu_ambient_air_tmp	Ambient air temperature	number	°C
ecu_b2v_pack_current	Battery pack current	number	A
ecu_b2v_pack_in_high_voltage	Voltage inside the battery	number	V
ecu_battery	Vehicle battery level	number	mV	✓
ecu_bms1_high_voltage_alarm	The voltage of the cell monomer is too high	number
ecu_bms1_highest_temp_batt_pack	Highest temperature battery pack	number	C
ecu_bms1_low_voltage_alarm	The voltage of the cell monomer is too low	number
ecu_bms1_lowest_temp_batt_pack	Lowest temperature battery pack	number	C
ecu_bms1_negative_insulation_resistance	BMS1 negative insulation resistance	number	kOhm	✓
ecu_bms1_positive_insulation_resistance	BMS1 positive insulation resistance	number	kOhm	✓
ecu_bms1_soc	BMS1 SOC - State of charge	number	%	✓
ecu_bms1_total_amps	BMS1 Total current	number	A	✓
ecu_bms1_total_voltage	BMS1 Total voltage	number	V	✓
ecu_bms2_batt_max_temp	Battery maximum temperature	number	C
ecu_bms2_batt_min_temp	Battery minimum temperature	number	C
ecu_bms2_higher_voltage_cell	Maximum voltage of a single cell	number	V
ecu_bms2_lower_voltage_cell	Minimum voltage of a single cell	number	V
ecu_bms3_fullbatt_threshold_fail	full battery voltage threshold fail	number
ecu_bms3_lowbatt_threshold_fail	Low battery voltage threshold fail	number
ecu_bms3_max_charge_current_allowed	Maximum charge current allowed	number	A
ecu_bms3_max_charge_voltage_allowed	Maximum charge voltage allowed	number	V
ecu_bms3_max_cont_charge_current_allowed	Maximum continuous charge current allowed	number	A
ecu_bms3_max_discharge_current_allowed	Maximum discharge current allowed (positive value)	number	A
ecu_bms4_batt_nominal_voltage	Battery nominal voltage	number	V
ecu_bms4_total_batt_case	Total battery case	number
ecu_bms4_total_batt_temp_nodes	Total battery temperature nodes	number
ecu_bms4_total_cell_chain	Total cell chain	number
ecu_bms5_charger_connected	Charger connected	number
ecu_bms6_batt_cooling_request	Battery cooling request	number
ecu_bms7_batt_current_sensor_fail	Battery current sensor fail	number
ecu_bms7_batt_temp_sensor_fail	Battery temperature sensor fail	number
ecu_bms7_batt_terminal_temp_sensor_fail	Battery terminal temperature sensor fail	number
ecu_bms7_charge_alarm_comm	Communication with charge alarm	number
ecu_bms7_charge_overcurrent_alarm	Charge overcurrent alarm	number
ecu_bms7_comm_slave_alarm	Communication with the slave alarm	number
ecu_bms7_discharge_overcurrent_alarm	Discharge overcurrent alarm	number
ecu_bms7_low_total_voltage_alarm	Low total voltage alarm	number
ecu_bms7_total_overvoltage_alarm	Total overvoltage alarm	number
ecu_bms9_nominal_current_capacity	Nominal current capacity of the battery	number	A
ecu_bms9_nominal_power	Nominal power	number	W
ecu_bms9_remaining_power	Remaining power	number	W
ecu_bms9_total_nominal_voltage	Total nominal voltage	number	V
ecu_bpressure	Barometric pressure	number	kPa
ecu_brake_pedal	Brake pedal pressed	number	%
ecu_ccontrol_set_speed	Cruise control set speed	number	kph
ecu_ccontrol	Cruise control state	number
ecu_clutch_pedal	Clutch pedal	number
ecu_cool_lvl	Coolant level	number	%	✓
ecu_cool_psi	Coolant pressure	number	psi	✓
ecu_cool_tmp	Coolant temperature	number	°C	✓
ecu_ddemand	Driver’s demand engine torque	number	%
ecu_def_consumed	Diesel exhaust fluid consumed	number	liters
ecu_def_level	Diesel exhaust fluid level	number	%
ecu_def_tmp	Diesel exhaust fluid temperature	number	°C
ecu_dist	Engine distance traveled	number	meter
ecu_distance	Total distance	number	meters	✓
ecu_door_closed	Door closed	number
ecu_dpf_intake_psi	Diesel particulate filter intake pressure	number	psi
ecu_dpf_soot_load	Diesel particulate filter soot load	number	%
ecu_dpf_status	Diesel particulate filter active regeneration status	number
ecu_drive_state	Drive state	number
ecu_dtc_cleared	Time since DTC cleared	number	minutes
ecu_eidle	Engine engine idling time	number	centihours
ecu_eload	Engine load	number	%
ecu_eng_crank_psi	Engine crankcase pressure	number	psi
ecu_eng_egr_diff_psi	Engine exhaust gas recirculation differential pressure	number	psi
ecu_eng_egr_maf	Engine exhaust gas recirculation mass flow rate	number	kg/hr
ecu_eng_egr_tmp	Engine exhaust gas recirculation temperature	number	°C
ecu_eng_egr_valve_control	Engine exhaust gas recirculation valve control	number
ecu_eng_egr_valve_pos	Engine exhaust gas recirculation valve position	number
ecu_eng_exhaust_psi	Engine exhaust gas pressure	number	psi
ecu_eng_exhaust_tmp	Engine exhaust gas temperature	number	°C
ecu_eng_intake_manif_psi	Engine intake manifold pressure	number	psi
ecu_eng_load	Engine percent load at current speed	number	%
ecu_eng_maf	Engine intake air mass flow rate	number	kg/hr
ecu_eng_oil_lvl	Oil level	number	%	✓
ecu_eng_oil_psi	Oil pressure	number	psi	✓
ecu_eng_oil_tmp	Oil temperature	number	°C	✓
ecu_eng_pto_governor_enable	Engine PTO governor enable switch	number
ecu_eng_pto_pprog_speed_control	Engine remote pto governor preprogrammed speed control switch	number
ecu_eng_ref_torque	Engine reference torque	number	N m
ecu_eng_turbo_intake_psi	Engine turbocharger compressor intake pressure	number	psi
ecu_eng_turbo_intake_tmp	Engine turbocharger compressor intake temperature	number	°C
ecu_eng_turbo_rpm	Engine turbocharger speed	number	rpm
ecu_eng_vgt_act	Engine turbocharger actuator	number
ecu_eng_vgt_control_mode	Engine variable geometry turbocharger control mode	number
ecu_eng_vgt_position	Engine turbocharger actuator position	number	%
ecu_eon	Time since engine ON	number	seconds	✓
ecu_error1-7	Engine error code	number		✓
ecu_eusage	Engine ignition on count	number	centihours
ecu_ev_battery_vol_status_df	Electric vehicle battery vol status df	number
ecu_ev_charger_door_status	Electric vehicle charging compartment door status	Number
ecu_ev_charging_current	Electric vehicle charging current	number	A
ecu_ev_charging_end_hours	Electric vehicle charging end hours	number	hours
ecu_ev_charging_end_minutes	Electric vehicle charging end minutes	number	minutes
ecu_ev_charging_end_secs	Electric vehicle charging end secs	number	secs
ecu_ev_charging_start_hours	Electric vehicle charging start hours	number	hours
ecu_ev_charging_start_minutes	Electric vehicle charging start minutes	number	minutes
ecu_ev_charging_start_secs	Electric vehicle charging start secs	number	secs
ecu_ev_charging_voltage	Electric vehicle charging voltage	number	voltage
ecu_ev_first_level_fault_code	Electric vehicle first level fault code	number
ecu_ev_fourth_level_fault_code	Electric vehicle fourth level fault code	number
ecu_ev_front_air_pressure	Electric vehicle odometer	Number	km
ecu_ev_front_door_status	Electric vehicle front door status	Number
ecu_ev_insulation_alarm_df	Electric vehicle insulation alarm df	number
ecu_ev_insulation_status_df	Electric vehicle insulation status df	number
ecu_ev_mid_door_status	Electric vehicle middle door status	Number
ecu_ev_motor_current	Electric vehicle motor current	Number	A
ecu_ev_motor_voltage	Electric vehicle motor voltage	Number	V
ecu_ev_rear_air_pressure	Electric vehicle rear air pressure	Number	kPa
ecu_ev_s1_anode_temp	Electric vehicle s1 anode temp	number	C
ecu_ev_s1_cathode_temp	Electric vehicle s1 cathode temp	number	C
ecu_ev_s2_anode_temp	Electric vehicle s2 anode temp	number	C
ecu_ev_s2_cathode_temp	Electric vehicle s2 cathode temp	number	C
ecu_ev_second_level_fault_code	Electric vehicle second level fault code	number
ecu_ev_third_level_fault_code	Electric vehicle third level fault code	number
ecu_fan_state	Fan state	number		✓
ecu_fault_level_of_insulation_detection	Fault level of insulation detection	number
ecu_fpressure	Fuel pressure	number
ecu_fuel_iconsumption	Instant fuel consumption	number	centi-liters/hours	✓
ecu_fuel_level_real	Fuel level	number	%	✓
ecu_fuel_level	Analog fuel level	number	mV	✓
ecu_fuel_tmp	Engine fuel temperature	number	°C
ecu_handbrake	Handbrake	number
ecu_heater_state	Heater state	number
ecu_hours_idle	Total engine usage while idling	number	centihours	✓
ecu_hours	Total engine usage	number	centihours	✓
ecu_hydr_oil_lvl	Hydraulic oil level	number	%	✓
ecu_hydr_oil_psi	Hydraulic oil pressure	number	psi	✓
ecu_hydr_oil_tmp	Hydraulic oil temperature	number	°C	✓
ecu_idle_fuel	Fuel consumed while idle	number	deciliters	✓
ecu_ifuel	Engine fuel consumed while Idling	number	centiliters
ecu_ignition_state	Ignition state	number
ecu_ins_efficiency	Fuel instant efficiency	number	deci-km/l	✓
ecu_insulation_detection_status	Work status: Insulation detection status	number
ecu_intake_air_tmp	Intake air temperature	number	°C
ecu_intake_manif_tmp	Intake manifold temperature	number	°C	✓
ecu_maf	Malfunction Indicator Lamp code	number		✓
ecu_main_pos_relay_flt	Fault of vehicle main-positive contactor	number
ecu_max_available_temp_batt	Maximum available temperature of battery pack	number	C
ecu_max_available_voltage_batt	Maximum available voltage of battery pack	number	V
ecu_mil_error_code	Malfunction Indicator Lamp code	number		✓
ecu_mil_error_count	Malfunction Indicator Lamp count	number		✓
ecu_mil_state	Malfunction Indicator Lamp state	boolean		✓
ecu_min_available_temp_batt	Minimum available temperature of battery pack	number	C
ecu_min_available_voltage_batt	Minimum available voltage of battery pack	number	V
ecu_negative_insulation_value	Negative insulation value	number	kohm
ecu_neutral_state	Neutral state	number
ecu_nominal_friction_torque	Nominal friction percent torque	number	%
ecu_obd_auxios	OBD auxiliary I/Os	number
ecu_obd_ftype	Fuel type	number
ecu_oxygen	Oxygen level	number	mV	✓
ecu_pg1-4	Custom PGNs	number		✓
ecu_positive_insulation_value	Positive insulation value	number	kohm
ecu_pto	PTO status	number
ecu_rated_capacity_battery	Rated capacity of battery	number	Ah
ecu_rated_total_energy_battery	Total energy of battery	number	kWh
ecu_rated_voltage_battery	Rated voltage of battery	number	V
ecu_rbatt	Hybrid battery life	number	%
ecu_ready_state	Ready state	number
ecu_regenerative_brake_level	Regenerative brake level	number
ecu_remote_accel_enable	Remote accelerator enable switch	number
ecu_remote_accel_pedal	Remote accelerator pedal position	number	%
ecu_retarder_brake_assist	Retarder enable - brake assist switch	number
ecu_reverse_state	Reverse state	number
ecu_rpm	Revolutions per minute	number	rpm	✓
ecu_serv_distance	Distance left to service vehicle	number	km
ecu_single_charge_electric	Single charged electric quantity	number	kwh
ecu_speed	Engine speed	number	kph
ecu_stability_control_level	Stability control level	number
ecu_stability_control	Stability control	number
ecu_state_of_charge	SOC. State of charge	number	%
ecu_state_of_health	SOH. State of health	number	%
ecu_tfuel	Engine total fuel consumed	number	deciliters
ecu_throttle	Throttle pedal position	number	%	✓
ecu_tires_psi	Tires pressure	string	psi
ecu_tires_tmp	Tires temperature	string	°C	✓
ecu_torque	Torque position	number	%	✓
ecu_total_fuel	Total fuel consumed	number	deciliters	✓
ecu_total_run_time	Total ECU run time	number	hour
ecu_tpms_conditions	TPMS conditions	string
ecu_tpms_provision	TPMS provision	string
ecu_tpms_warnings	TPMS warnings	string
ecu_trans_lvl	Transmission oil level	number	%	✓
ecu_trans_psi	Transmission oil pressure	number	psi	✓
ecu_trans_tmp	Transmission oil temperature	number	°C	✓
ecu_transmission_gear	Transmission gear	number
ecu_trip_distance	Trip distance	number	meter	✓
ecu_trip_fuel	Trip fuel	number	liters	✓
ecu_vin	VIN number	string
ecu_water_in_fuel	Water in fuel indicator	number
ecu_weights	Vehicle weights	string	kg	✓
ecu_with_mil_distance	Distance traveled with MIL on	number	meter	✓
ecu_with_mil_time	Time traveled with MIL on	number	minutes
event_epoch	Event time as epoch	number
event_time	Time the event was generated by the device (YYYY-MM-DDThh:mm:ss)	string		✓
flow_meter_state	Flow Meter State	boolean
flow_meter_display_state	Flow Meter Display State	boolean
flow_meter_current_flow	Flow Meter Current Flow	number
flow_meter_src_pwr_disc	Flow Meter Source Power Disconnected	number
flow_meter_sensor_disc	Flow Meter Sensor Disconnected	number
flow_meter_calibration_pattern	Flow Meter Calibration Pattern	number
flow_meter_volume_dispatched	Flow Meter Volume Dispatched	number
flow_meter_total_volume	Flow Meter Total Volume	number
fpr_code	Fingerprint code	number		✓
fpr_conn	Fingerprint connection	boolean		✓
fpr_id	Fingerprint ID	number		✓
groups	Group ids	array
hdop	HDOP value	number		✓
head	Vehicle direction 0 = North, 180 = South	number	degrees	✓
ib	iButton ID	string		✓
ib_set	iButton present	boolean
id	Event unique ID (up to BIGINT)	number		✓
ii	Second IMEI	number		✓
io_exp_in1	Expanded input 1	boolean		✓
io_exp_in2	Expanded input 2	boolean		✓
io_exp_in3	Expanded input 3	boolean		✓
io_exp_in4	Expanded input 4	boolean		✓
io_exp_out1	Expanded output 1	boolean		✓
io_exp_out1_short	Expanded output 1 short circuit	boolean		✓
io_exp_out2	Expanded output 1	boolean		✓
io_exp_out2_short	Expanded output 1 short circuit	boolean		✓
io_exp_out3	Expanded output 1	boolean		✓
io_exp_out3_short	Expanded output 1 short circuit	boolean		✓
io_exp_out4	Expanded output 1	boolean		✓
io_exp_out4_short	Expanded output 1 short circuit	boolean		✓
io_exp_state	IO expander state	boolean		✓
io_ign	Ignition	boolean		✓
io_in1	Input 1	boolean		✓
io_in2	Input 2	boolean		✓
io_in3	Input 3	boolean		✓
io_out1	Output 1/Safe immobilization	boolean		✓
io_out1_short	Output 1 short circuit	boolean		✓
io_out2	Output 2	boolean		✓
io_out2_short	Output 2 short circuit	boolean		✓
io_pwr	Device power	boolean		✓
io_tamper	Tamper detected (case opened)	boolean
ip	IP address	number		✓
jamm_detected	Communication jamming detected	boolean		✓
kph	GPS speed	number	kph
ky	Device configuration key	string
label	Label	string		✓
lat	GPS Latitude	number		✓
light_sensor	Light sensor	boolean		✓
lon	GPS Longitude	number		✓
message	Device event message	string
moving	Moving	boolean
mph	Speed	number	mph	✓
pc	Pulse counter	number		✓
pdop	PDOP value	number		✓
pid	Pegasus site ID	number		✓
port	Port	number		✓
primary_name	Entity name	string
re_index	Region index	number		✓
re_sense	Region sense	boolean		✓
re_type	Region type	number		✓
rfi_fac	RFID facility code	number
rfi_full_id	Full rfid code	string
rfi_id	RFID	number
sa_seqn	Sequential ack	number
sa_type	Sequential acknowledge type	number
source	GPS source	number		✓
sv	Satellites in view	number		✓
system_epoch	Epoch time event was received on the server	number
system_time	Time event was received on the server (YYYY-MM-DDThh:mm:ss.sssss)	string		✓
timestamp	Epoch timestamp	number
server.timestamp	Epoch timestamp of the server	number
tcXX	Time counter values	number		✓
tec_1_ff	Technoton 1 frequency	number	Hz
tec_1_fn	Technoton 1 level	number	liters
tec_1_ft	Technoton 1 temperature	number	°C
tec_1_st	Technoton 1 state	boolean
tec_2_ff	Technoton 2 frequency	number	Hz
tec_2_fn	Technoton 2 level	number	liters
tec_2_ft	Technoton 2 temperature	number	°C
tec_2_st	Technoton 2 state	boolean
tec_3_ff	Technoton 3 frequency	number	Hz
tec_3_fn	Technoton 3 level	number	liters
tec_3_ft	Technoton 3 temperature	number	°C
tec_3_st	Technoton 3 state	boolean
tec_ff	Technoton fuel frequency	number	Hz
tec_fn	Technoton fuel level	number	liters
tec_ft	Technoton fuel temperature	number	°C
tec_st	Technoton state	boolean
temp	General purpose temperature	number	°C
temp1	General purpose temperature 1	number	°C
temp2	General purpose temperature 2	number	°C
temp3	General purpose temperature 3	number	°C
temp4	General purpose temperature 4	number	°C
temp5	General purpose temperature 5	number	°C
temp6	General purpose temperature 6	number	°C
temp7	General purpose temperature 7	number	°C
temp8	General purpose temperature 8	number	°C
temp9	General purpose temperature 9	number	°C
temp10	General purpose temperature 10	number	°C
ti_sense	Signal sense	boolean
ti_signal	Signal	string
ti_thr	Signal threshold	number
ti_val	Signal value	number
trip_id	Trip ID	number
tx	RS-232 MDT data	string		✓
type	Event type	number		✓
usense_hour	Ultrasonic fuel sensor hour	number	hour
usense_minute	Ultrasonic fuel sensor minute	number	minute
usense_filtered_value	Ultrasonic fuel sensor filtered value	number
usense_signal_strength	Ultrasonic fuel sensor signal strength	number
usense_software_code	Ultrasonic fuel sensor software code	number
usense_hardware_code	Ultrasonic fuel sensor hardware code	number
usense_raw_value	Ultrasonic fuel sensor raw unfiltered value	number
usense_median_value	Ultrasonic fuel sensor median value	number
usense_valid_signal	Ultrasonic fuel sensor valid signal	number
usense_tilt_angle	Ultrasonic fuel sensor tilt angle	number
valid_position	Valid position	boolean		✓
vdop	VDOP value	boolean		✓
vehicle_dev_dist	User editable device distance	number	meters
vehicle_dev_dist__km	User editable device distance	number	km
vehicle_dev_dist__mi	User editable device distance	number	miles
vehicle_dev_idle	User editable total idle time	number	seconds
vehicle_dev_ign	User editable total engine on time	number	seconds
vehicle_dev_orpm	User editable over rpm time	number	seconds
vehicle_dev_ospeed	User editable over speed time	number	seconds
vehicle_ecu_dist	User editable engine odometer	number	meters
vehicle_ecu_dist__km	User editable engine odometer	number	km
vehicle_ecu_dist__mi	User editable engine odometer	number	miles
vehicle_ecu_eidle	User editable engine idle time	number	seconds
vehicle_ecu_eusage	User editable engine on time	number	seconds
vehicle_ecu_ifuel	User editable fuel consumed while idling	number	liters
vehicle_ecu_tfuel	User editable total fuel consumed	number	liters
vid	Vehicle id	number
vinfo	Vehicle info	object
vo	Deprecated, use counters api (dev_dist)

Examples

Please visit our Github repo for examples to get started with real life examples using the API