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
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
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
user: developer@digitalcomtech.com
pass: deV3lopErs
Throughout the guide we’ll work on a Demo server called: Pegasus1
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
{
"domain": "pegasus1.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
{
"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 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:
- global:
60/minute; 800/hour
- per user:
3/second; 30/minute; 500/hour
- global:
120/minute, 1600/hour
- per user:
6/second, 30/minute, 500/hour
Other resources such as vehicles, groups, assets, etc. apply an anti DOS (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
Unless otherwise specified, the API handles all units for keys in the following manner by default.
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://pegasus1.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://pegasus1.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://pegasus1.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://pegasus1.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 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
Sessions
View tokens you have created
{
"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"
}
}
You can manage tokens and the current session with the /user/sessions
resource. You can also create your own tokens with a POST to the same resource
param | description |
---|---|
scheme | infinite or finite token |
limit | limit of token in seconds |
app | custom app name |
scopes | specify the group(s) id that the token has access to, and any scope |
app_scheme | pegasus application use only |
Create a scoped API token
curl -X POST https://pegasus1.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"}'
Remove a token
curl https://pegasus1.pegasusgateway.com/api/logout?auth=640c59b1df21aed608fe9cb775d56faaea9e33dd74730e31a94456e2 \
--header 'Content-Type: application/json'
{"message": "Session terminated"}
Scopes
{
"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
return particular vehicle’s name & device’s network info
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:
{
"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.
Own User
You can look at your own user with the following resource: 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
Particular group
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
Vehicles
All vehicles
Particular vehicle
All vehicle’s info & last device communication
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.
Assets
Rawdata request that groups by asset id
aid
, shows the max speed daily per driver
{
"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://pegasus1.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
Devices
All devices
Particular device
All device’s inputs & outputs state
Device’s latest data reported
api/devices/:imei?select=latest
Device’s latest location data only
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.
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 IDresource_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
{
"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
For a more detailed list of the rawdata fields please refer to:
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://pegasus1.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://pegasus1.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://pegasus1.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:@mph*44.704,speed_in_knots:@mph*0.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:["google:'https://google.com/maps?q=' + @lat__str + ',' + @lon__str"]
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
{
"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.
{
"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://pegasus1.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://pegasus1.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://pegasus1.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://pegasus1.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://pegasus1.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://pegasus1.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://pegasus1.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://pegasus1.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://pegasus1.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://pegasus1.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
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://pegasus1.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://pegasus1.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://pegasus1.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
{
...
"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.
Distance, time and volume units are stored in 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 per user.
Global vehicle counters
Global vehicle counters for vehicle 1716
api/vehicles/1716/counters
{
"user": [],
"vehicle": {
"plain": {
"dev_dist": 67972874,
"ecu_dist": 59729515,
"dev_ign": 4330585,
"dev_idle": 547952,
"dev_ospeed": 444158,
"ecu_ifuel": 3860,
"ecu_eusage": 119240,
"ecu_eidle": 29570,
"ecu_tfuel": 232508
},
"calculated": {},
"counters": {}
}
}
Updating the global vehicle dev_dist (odometer) counter for vehicle 1716
{
"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
}
This will set the dev_dist or odometer value to 123456789 meters.
Please note that these changes are global (meaning it will be seen by other users) and they affect the counters API values, thus it’s something that you should NOT update regularly.
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 |
User Counters
Get the 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": {...}
}
User counters are unique for every user. These values can be edited at any point by the user and not affect any other user’s counters.
You can create as many user counters as you’d like for the same vehicle.
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 custom user counters.
Create
Create a new user 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"
}
Let’s create a user counter for those new tires you just changed
Updating User Counters
In order to update a 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://pegasus1.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://pegasus1.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://pegasus1.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://pegasus1.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://pegasus1.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
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
{
"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"
}
]
}
]
}
Routes are created within the entities api, POST /entities/:id/routes
Required parameters
active
- true if the route is active or notcheckpoints
- array of 2 or more checkpointslat
- latitudelon
- longitudebuffer
- radius (meters)
schedules
- times of departures and arrivals of the checkpointsactive
- true if schedule is active or nottimezone
- timezonerepeat
- time of the week which the route will repeatcheckpoints
- array of the times and durations per checkpointtime
- time for checkpoint (HH:mm
)
Optional parameters
name
- name of the routeenforce
- true if the route is enforced (relevant for alerts)color
- HEX code for the color of the routedescription
- notes or descriptions of the routecheckpoints
name
- for each checkpoint
schedules
checkpoints
min_duration
- minimum duration in minutesmax_duration
- maximum duration in minutesmandatory
- 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 destinationbuffer
- radius of the path (meters)encoding
- polyline encoded path
Route states
get an entities’ route states
[
{
"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 routecolor
- color of the routeexited_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 timefinalized
- true if the time of arrival expired or the entity reached its last checkpointfinalized_cpt
- checkpoint progress, increases by one every time the checkpoints are finalizedis_outside_path
- true if the entity was outside the path.route_start
- scheduled time of the start of the routeYYMMDDHHMM
(in route’s timezone)start_epoch
- scheduled start time of the route as an epochroute_end
- scheduled time of the end of the routeYYMMDDHHMM
(in route’s timezone)end_epoch
- scheduled end time of the route as an epochroute_id
- specific id for an entity’s routecheckpoints
- array of the checkpoints for the routesgeometry
- lon, lat, and radius of the checkpointid
- identifier of the checkpointcpt.start
,cpt.#
, orcpt.end
- events - obect with events that correspond to the entrance / exit of an entity to a checkpoint
entered
- checkpoint was visited with this infoexited
- checkpoint exited with this info
Viewing 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"
}
]
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"
}
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
{
"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
{
"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.
{
"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.
{
"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
{
"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
{
"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.
View
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
{
"geometry": {
"type": "Circle",
"radius": 105,
"coordinates": [
-82.28900,
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
{
"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"
}
}
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
{
"geometry": {
"type": "Circle",
"radius": 52,
"coordinates": [
-80.289000061596184,
25.78238262858029
]
},
"properties": {
"name": "Warehouse 3",
"custom": {
"contact": "John Smith",
"amount": 123
}
}
}
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
Geofence Types
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"
}
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://pegasus1.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
messagePUT [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
ordone
) - 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
{
"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 |
Bluetooth Tags
Associating to asset
PUT
api/:bt_tags_mac
{
"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
Capturing a photo
Capture a photo from the camera connected to vehicle id: 1956
{
"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://pegasus1.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://pegasus1.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://pegasus1.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://pegasus1.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_timeThe 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
{
"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
{
"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://pegasus1.pegasusgateway.com/api/vehicles/1/plugins/photocam/lastNotice 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://pegasus1.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://pegasus1.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
[
{
"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™
{
"job": {
"POST": [
"message",
"flat",
"flon"
]
},
"message": {
"POST": [
"message",
"mtype"
],
"GET": [
"_from"
],
"DELETE": []
},
"state": {
"POST": [
"new_mode"
],
"GET": []
}
}
Get the current state of the Garmin™
{
"state": 1,
"pending": 0
}
Enable the Garmin™ mode
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
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) |
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
POSTapi/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
{
"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
[
{
"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
Multicamera/expander
Take a photo with a device that has 3 cameras connected to it
{
"msg": "instruction set to device. ",
"device_is_online": true,
"oids": [
334966
]
}
Get the last photos for vehicle id: 469
{
"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
{
"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-35*x^11 + 6.2029607E-31*x^10 – 8.2710455E-27*x^9 + 6.3466737E-23*x^8 – 3.0989103E-19*x^7 + 1.0055822E-15*x^6 – 2.2005923E-12*x^5 + 3.2320968E-09*x^4 – 3.1180082E-06*x^3 + 0.0019020671*x^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)
[
{
"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)
[
{
"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": "
AAA
BBB
,AAABBB,AAABBB,AAABBB..."
ecu_tires_psi | Description |
---|---|
AAA |
000 - 255. Tire Location. |
BBB |
Pressure (psi) |
"ecu_tires_tmp": "
AAA
BBB
,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": "
AAA
B
C
D
E
,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": "
AAA
B
C
D
E
F
G
H
,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": "
A
B
CC
DD
,
ZZZ
XXXXXXXXXX
,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
{
...
"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"
}
...
}
{
"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 configurationsSite 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:
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
{
"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_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 theapi/configurations/ky
to reach it.restricted_fw
has 3 fields, two for the min & max firmware, these have the formatABBBCCC
- 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 devicelimit_remote_qpv
limit on the amount of position queries that can be triggered per device
View
View a particular managed configuration
{
"ev_labels": {
"0": "prdtst",
"1": "trckpnt",
"2": "ignon"
},
"tracking_resolutions": {
"1": [
null,
1800
],
"2": [
null,
720
]
},
"allowed_cmds": [
">SRT;ECU<",
">SXAQQ",
">SXAICAA1",
">SXAIC"
]
}
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 |
Configuring a device
Configure a device with a managed configuration
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
{
"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
{
"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
{
"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
{
"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 toallowed_cmds
in the managed configuration
{
"message": ">RER04:SRIA123456;SI=1-1CC;ID=357042062922274"
}
See messages (commands) pending to be sent to the device
{
"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
[
{
"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
Legacy safeimmo activation
POST api/vehicles/:vid/remote/safe_immo
or
{
"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
{
"ionames": {
"io_pwr": "pwr",
"io_in1": "in #1",
"io_out1": "Engine Cut",
"io_out2": "Output #2",
"io_ign": "ign",
"io_in2": "in #2",
"io_in3": "in #3"
},
"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
}
}
Syrus devices have a immobilization mechanism that waits for certain conditions to meet before activating, in this way the immobilization is “secure”. We’ll refer to immobilization as 'safeimmo’ from now on.
The first step in knowing whether or not safeimmo is supported by a particular device is to look at the device’s configuration, if it’s using a managed (legacy) configuration then you can look at the device’s api response in the config
object,
api/devices/:imei?select=config
there’s a boolean in this response that tells you if the configuration supports safeimmo.
After you send the command you can monitor the response via api or via websockets, the api/devices/:imei/remote/state
will give you the state of the safeimmo status. Safe immobilization is complete when the key io_out1
is set to true.
Activate output 2
Activating embedded output 2 on vehicle 2063
{
"otype": "n",
"out": 2,
"state": true
}
Deactivating embedded output 1 on vehicle 2063
{
"otype": "n",
"out": 1,
"state": false
}
State of output
{
"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
{
"phone": "+13058675309"
}
Response
{
"msg": "instruction set to device. ",
"imei": 357042062920955,
"oids": [
48
]
}
View the phone number we just configured
{
"phones": [
{
"action": "1",
"access": "0",
"phone": "+13058675309"
}
],
"errors": [],
"pending": true
}
Make a call to the number +13058675309
POST https://pegasus1.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.
Edit device
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 toSEDccABCDE[...]
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
{
"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
{
"time_zone": "America/New_York"
}
keys
{
"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
{
"extra_headers": {
"Authorization": "Bearer YWRqZmFsZGpmbGFqc2RmbGFhZGxmam"
}
}
primary
{
"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 last updated 17.Dec.2018
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 last updated 17.Dec.2018
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.
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.
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
//intialize the socket
var socket = io('https://aws-live-0.pegasusgateway.com/socket')
Once you have the socket.io client loaded, lets make a fresh socket by initializing it.
Authentication
// 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://pegasus1.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 eventsnamespace
: 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://pegasus1.pegasusgateway.com",
"_source": "pcore.listener",
"_source_epoch": 1504910674.863004,
"_ver_core": "1.9.0-rc1",
"_ver_pcel": "2.1.1-r2"
}
Key | Description |
---|---|
$$hashKey | internal use |
category | event category (vehicle) |
device | information on the device more info |
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 |
site_id | unique ID for the pegasus site |
secondary | secondary entity |
secondary_id | secondary entity id |
type | type of payload |
updates | keys that are updated on this payload |
_pkey | internal use |
siteurl | pegasus site URL |
_source | internal use |
sourceepoch | internal use |
_ver_core | internal use |
_ver_pcel | internal use |
Detailed payload description
device
asset
asset information
Key | Description |
---|---|
aid | asset id |
aid_source | source of the asset, ib for ibutton, btt for bluetooth tag, fp for fingerprint |
btt_mac | bluetooth tag mac address |
ib | ibutton HEX ID |
rfid | RFID |
config
configuration description
Key | Description |
---|---|
ky | unique key for managed or device control configuration |
legacy_safeimmo_support | true if it’s using managed configuration and it supports safe_immobilization on output 1 |
connection
connection state / information
Key | Description |
---|---|
fno | internal use |
lid | internal use |
offline_reasons | reason for the device to be offline |
online | true if device is online |
pid | site_id |
reason | reason why the connection is online (typically it’s a new connection) |
seq | internal use |
_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 |
ios_state
state of the inputs and outputs
for a detailed description you can check the master field list
last_rx
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 |
legacy_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 |
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 |
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
state of the device pending messages
Key | Description |
---|---|
last_id | last message id that was queued up |
_epoch | epoch timestamp |
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 |
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 |
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 IMEIvid
: (number) Associated vehicle IDonline
: (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 Upload API
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.
Vehicle
Instructions for Gateway Administrator / End user/developer
Intro
In order to receive data from third party devices via an HTTP POST JSON, 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
For both of these steps you can contact your sales representative.
After these steps are done you’ll be given an endpoint for you to send the data to, the default Pegasus 1 endpoint is:
- https://pegasus1.peginstances.com/receivers/json
But yours will be different.
Data structure
Data is uploaded in key-value pairs in a JSON array format via an HTTP POST request.
[{"boolean":true, "number":73, "string":"value"}]
Arrays of up to 50 JSON objects can be sent simultaneously. Each object corresponds to an event generated by different telemetry devices which has locational data.
[{"event1":"value1"}, {"event2":"value2"}, ... {"event49":"value49"}]
Fields
Example Payload
[
{
"timestamp": 1561475702,
"device.name": "MyDevice12345",
"device.id": 350000000012345,
"position.latitude": 10.356101,
"position.longitude": -75.495798,
"position.direction": 245,
"position.speed": 20,
"position.altitude": 13,
"position.hdop": 0.6,
"position.satellites": 12,
"position.valid": true,
"event.enum": 24,
"event.label": "ignon",
"io.ignition": true,
"io.power": true,
"io.input1": true,
"device.battery.level": 3420,
"metric.odometer": 66675.456,
"metric.hourmeter": 375.123
}
]
The required parameters to send in the ARRAY_OF_EVENTS are:
- device.id - IMEI of the device
- position.latitude - latitude (example: 20.99385)
- position.longitude - longitude (example: -89.71079)
If these fields are not received, the message is considered a keep alive and the contents are discarded.
param | type | description | required |
---|---|---|---|
timestamp |
number | Unix epoch timestamp | |
device.name |
string | Name for the device | |
device.id |
number | IMEI on Pegasus (15 digit) | ✔️ |
position.latitude |
number | WGS84 latitude | ✔️ |
position.longitude |
number | WGS84 longitude | ✔️ |
position.direction |
number | Heading in degrees 0 - 359 (0 = North, 90 = East, etc.) | |
position.speed |
number | Speed in kph | |
position.altitude |
number | Altitude in meters | |
position.hdop |
number | Horizontal dilution of precision (Wiki) | |
position.satellites |
number | Amount of GPS Satellites | |
position.valid |
boolean | True if the positional data is valid | |
event.enum |
number | Custom numeric code | |
event.label |
string | Payload content description, see common labels | |
io.ignition |
boolean | True if ignition is detected | |
io.power |
boolean | True if main power is detected | |
io.input1 |
boolean | True if a device input is detected | |
device.battery.level |
number | Battery level in milli-volts | |
device.battery.percent |
number | Battery level as a percent | |
metric.odometer |
number | Odometer in km (decimals accepted) | |
metric.hourmeter |
number | Engine hours (decimals accepted) |
The expected response from the receiver is HTTP status 200, “ok” when the data was successfully uploaded. A wrong payload returns a 400 Bad Request.
FAQ
- The io params (io.ignition, io.power, io.input1) persist until they’re sent as false.
- Sending the valid_position parameter as true overrides the internal filters that calculate the validity of the position using other parameters, send it as true only if you are sure that it’s valid.
- If the epoch timestamp is not provided, as soon as the message is received the server will apply a Unix timestamp as the time of the event.
- Whenever you send the timestamp make sure to consider sending them in chronological order whenever the device comes back online after being offline. It’s not required, but it’s strongly recommended.
- Input 1 behaves as both a normal two state ON/OFF switch, or a panic alert depending on the label that’s associated to the payload.
- A valid 15 digit IMEI is required on the device.id
Assets
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": "pegasus1.pegasusgateway.com",
"active": true,
"token": "UTNZEHBL",
"device": 450000141115142
},
...
}
setting the configuration to the device
{
"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
{
"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 |
auth |
pegasus auth token (overrides Authenticate header) |
POST
multiple lat lon pairs
[
{
"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.
maps API endpoint https://maps.pegasusgateway.com/reversegeo
GET
{
"errors": {},
"results": {
"025.78362000:-080.29327000": "5835 Blue Lagoon Drive. MIAMI-DADE COUNTY, FL 33126 US"
}
}
{
"errors": {},
"results": {
"032.07690000:0034.81510000": "כצנלסון. גבעתיים, מחוז תל אביב 53100 IL"
}
}
{
"errors": {},
"results": {
"032.07690000:0034.81510000": "כצנלסון. גבעתיים"
}
}
{
"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 |
|
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, optionalkey
, optionalsynth
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 thekey
passed on the lat-lon object, otherwise, an internally constructed key representaing the lat+lon objectsynth
: 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. Anfmt
argument may be passed to format the result. Aninclude_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'
: Foramia_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
sql format - last updated 28.Jan.2020
Spreadsheet with example values
Field | Info | Type | Unit | Base set |
---|---|---|---|---|
ac | GPS acceleration | number | mph/s | ✓ |
ad | ADC value | number | mV | ✓ |
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_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_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_aload | Absolute load | number | % | |
ecu_ambient_air_tmp | Ambient air temperature | number | °C | |
ecu_battery | Vehicle battery level | number | mV | ✓ |
ecu_bpressure | Barometric pressure | number | kPa | |
ecu_brake_pedal | Brake pedal pressed | number | % | |
ecu_ccontrol | Cruise control state | number | ||
ecu_ccontrol_set_speed | Cruise control set speed | number | kph | |
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_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_dtc_cleared | Time since DTC cleared | number | minutes | |
ecu_eidle | Engine engine idling time | number | seconds | |
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 | seconds | |
ecu_fan_state | Fan state | number | ✓ | |
ecu_fpressure | Fuel pressure | number | ||
ecu_fuel_iconsumption | Instant fuel consumption | number | liter/hour | ✓ |
ecu_fuel_level | Analog fuel level | number | mV | ✓ |
ecu_fuel_level_real | Fuel level | number | % | ✓ |
ecu_fuel_tmp | Engine fuel temperature | number | °C | |
ecu_hours | Total engine usage | number | hours | ✓ |
ecu_hours_idle | Total engine usage while idling | number | hours | ✓ |
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 | liters | ✓ |
ecu_ifuel | Engine fuel consumed while Idling | number | liters | |
ecu_ins_efficiency | Fuel instant efficiency | number | kpl | ✓ |
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_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_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_pto | PTO status | number | ||
ecu_rbatt | Hybrid battery life | 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_rpm | Revolutions per minute | number | rpm | ✓ |
ecu_serv_distance | Distance left to service vehicle | number | km | |
ecu_speed | Engine speed | number | kph | |
ecu_tfuel | Engine total fuel consumed | number | liters | |
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 | liters | ✓ |
ecu_total_run_time | Total ECU run time | number | hour | |
ecu_tpms_provision | TPMS provision | string | ||
ecu_tpms_warnings | TPMS warnings | string | ||
ecu_tpms_conditions | TPMS conditions | 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_trip_fuel | Trip fuel | number | liters | ✓ |
ecu_trip_distance | Trip distance | number | meter | ✓ |
ecu_vin | VIN number | string | ||
ecu_water_in_fuel | Water in fuel indicator | number | ||
ecu_weights | Vehicle weights | number | 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 | ✓ | |
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 | ✓ | |
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 | |
temp_a__c | Temperature sensor probe A | number | °C | |
temp_a__f | Temperature sensor probe A | number | °F | |
temp_avg__c | Avg temperature of all probes | number | °C | |
temp_avg__f | Avg temperature of all probes | number | °F | |
temp_b__c | Temperature sensor probe B | number | °C | |
temp_b__f | Temperature sensor probe B | number | °F | |
temp_c__c | Temperature sensor probe C | number | °C | |
temp_c__f | Temperature sensor probe C | number | °F | |
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 | |
vh_hours | Deprecated, use counters api (dev_ign) | |||
vh_mins | Deprecated, use counters api (dev_ign) | |||
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