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

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

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

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

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

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

  • ky: q712 Movon Standard Configuration
  • ky: p657 Mobileye Standard Configuration
Syrus signalLabelShort DescriptionMobileye™Movon
L01mblyerrError✔️✔️
L02mblylldwLeft Lane Departure Warning✔️✔️
L03mblyrldwRight Lane Departure Warning✔️✔️
L04mblyfcwForward Collision Warning✔️✔️
L05mblymaintMaintenance Flag✔️
L06mblyflsfFailsafe✔️
L07mblypdfcwPedestrian Forward Collision Warning✔️✔️
L08mblypddngPedestrian in Danger Zone✔️
L09mblytmprTamper alert✔️
L10mblyspdSpeeding✔️
L11mblyhdwrnHeadway Warning✔️✔️
L12mblybrkonBrakes on✔️✔️
L13mblylftsigLeft turn signal✔️✔️
L14mblyrghsigRight turn signal✔️✔️
L15mblywprsWipers on✔️
L16mblylwbmLow Beams✔️
L17mblyhibmHigh Beams✔️
L18mblytimeTime Signal✔️
L19mdasfvsaFront vehicle start alarm✔️
L20mdasfpwForward Proximity Warning✔️
NameDescription
ErrorError detected in accessory
Left Lane Departure WarningVehicle departed the left lane
Right Lane Departure WarningVehicle departed the right lane
Forward Collision Warning (FCW)Vehicle imminent collision
Maintenance Flagmaintenance required
FailsafeIndicate one of the following: blurred image, saturated image, low sun, partial blockage or partial transparent
Pedestrian Forward Collision WarningCollision warning with pedestrian detected
Pedestrian in Danger ZoneVehicle close to pedestrians
Tampertampering detected
SpeedingSpeed of vehicle above speed limit sign detected on road
Headway WarningVehicle driving too close to vehicle in front
Brakes onBrakes applied
Left turn signalLeft turn signal activated
Right turn signalRight turn signal activated
Wipers onWipers activated
Low BeamsVehicle lights turned on
High BeamsVehicle high beams turned on
Time SignalChange in time of day
Front vehicle start alarmVehicle in front has started moving, but host vehicle has remained standing still for 2 seconds
Forward Proximity WarningNotifies the driver when there is a vehicle existing in the detection range

The Syrus 4 supports the following ADAS fields in rawdata:

ADAS fields

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

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

Bluetooth Tags

Associating to asset

PUT /:bt_tags_mac

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

{
  "asset_id": 123
}

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

Note that the asset ID has to be unique when associating the tag to it. In other words there can only be 1 tag associated per asset Note that if a peripheral is associated to an asset, and that asset is later deleted, the asset_id that shows up as associated to that peripheral is 0.

Getting Bluetooth Tag Data

GET Bluetooth tag data

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

FieldTypeDescriptionRange
btt_batteryNumberBattery %0, 100
btt_buttonBooleanTrue if button is detected
btt_driverNumberAsset ID associated event
btt_freefallBooleanTrue if freefall detected
btt_humidityNumberHumidity %0, 100
btt_impactBooleanTrue if impact detected
btt_lightNumberLight %0, 100
btt_macStringTag's unique MAC address
btt_motionBooleanTrue if motion is detected
btt_presenceBooleanTrue if tag presence is detected
btt_reedBooleanTrue if reed switch is detected
btt_tempNumber°C * 10 (divide by 10 to get the temperature in °C)-100, 450 (-10°C to 45°C)
btt_wreasonStringReason for waking up

Bluetooth tag wake up reasons

btt_wreasonDescription
RReed switch.
CTime.
BButton.
MMotion.
LLight.
WLow batt.
XBeacon mode.
iFirst Time.
uUnknown.

Camera & Video

There are several accessories that provide media including images and videos to the API. To interact with these devices and view the contents of the media you can the APIs described below.

The API methods 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 a device IMEI /devices/:imei

Request to get the media methods

/vehicles/:vid/plugins/photocam

/devices/:imei/plugins/photocam


Capturing a photo or video

Example: capture a photo from the camera connected to vehicle id: 1956

GET /vehicles/1956/plugins/photocam/capture

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

📘

Capturing media is automatically done for all available cameras

The capture method will capture a video or photo with all available cameras.


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 media

Requesting the last photo taken from a vehicle with 1 camera connected

GET /vehicles/1956/plugins/photocam/last

// while the photo is uploading it will have a status_no 3
// see the list below for more information on the statuses 
{
    "status": "Photo taken, device is uploading it.",
    "source": 0,
    "status_no": 3
}

after some seconds you will see the following response

{
  "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://api.pegasusgateway.com/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 /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 media

Browse photos

https://api.pegasusgateway.com/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 /vehicles/:vid/plugins/photocam/browse

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

GET /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

[

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

Getting an event's media

Requesting the photos associated to the event id: 5008241019

/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

/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 /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 /vehicles/:vid/plugins/photocam/from_event?event=####&time=YYYY-MM-DDThh:mm:ss

It is recommended to use the system time since sometimes the event_time can have a wrong date due to GPS 0 date.

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

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

For more info please visit our Support Site

Driver ID

See a list of all iButtons and their associations
/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 /assets/:id

Associating an iButton ID to an asset
POST /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)

/assets/1032

{
  "info": {
    "first_name": "Test",
    "last_name": "User",
    "type": "driver",
    "email": "[email protected]"
  },
  "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)

/rawdata?vehicles=617,654&fields=$basic,$counters,aid&duration=P1D&filter=(valid_position and mph > 5 and comdelay < 3600 and hdop < 3)&how=$counters:diff,mph:mean&freq=1D&group_by=aid&resample=event_time

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

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

ECU Monitor

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

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

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

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

Counters API request with ecu parameters
/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

CounterDescriptionCalculation
dev_tot_fuel_efcySyrus calculated Fuel efficiencydev_dist/ecu_tfuel
dev_tra_fuel_efcySyrus calculated Traveling fuel efficiencydev_dist/(ecu_tfuel-ecu_ifuel)
ecu_distDistance reported by ECU monitor
ecu_eidleIdle time reported by ECU monitor
ecu_eusageEngine usage time reported by ECU Monitor
ecu_fuelp_idlingFuel percentage used while idlingecu_ifuel*100/ecu_tfuel
ecu_ifuelFuel consumed while idling, reported by ECU monitor
ecu_tfuelTotal fuel consumed, reported by ECU monitor
ecu_tot_avg_speedTotal average speed, ECUecu_dist/ecu_eusage
ecu_tot_fuel_efcyECU calculated Fuel efficiencyecu_dist/ecu_tfuel
ecu_tra_avg_speedTraveling average speed, ECUecu_dist/(ecu_eusage-ecu_eidle)
ecu_tra_fuel_efcyECU calculated Traveling fuel efficiencyecu_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

/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)

/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 /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 StatusDescription
FECU Monitor accessory detected and vehicle's engine turned off
OECU Monitor accessory has not received new data from this parameter in the last 2 minutes
TECU Monitor accessory detected and vehicle's engine turned on. ECU VALID DATA

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

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

Tips

Get the ECU Monitor information for a vehicle

GET /vehicles/:vid/remote/ecu_state

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

You can get a list of the parameters that the ECU supports with the following api
GET /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.

/vehicles/:vid/plugins/lumeway

Capturing a photo

Capturing a photo for a Lumeway accessory

/vehicles/1/plugins/photocam/capture

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

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

Getting the last photo

In order to obtain the last photo you can perform a
GET /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__' />

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

Getting the last photo

https://api.pegasusgateway.com/vehicles/1/plugins/photocam/last

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

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

after some seconds you will see the following response

https://api.pegasusgateway.com/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://api.pegasusgateway.com/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 /vehicles/:vid/plugins/photocam/browse

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

GET /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

[

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

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

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

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

Getting an event's photo(s)

In order to get a particular photo we can use the method
GET /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 /vehicles/:vid/plugins/photocam/from_event?event=####&time=YYYY-MM-DDThh:mm:ss

Note that the time doesn't have to be exact to the hh:mm:ss, passing the day that the photo was taken is sufficient.

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.

Remember that lumeway photos come with source 99 so you can identify whether you need to look up the photocam or lumeway status no's.

Lumeway Status Status Numbers

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

Requesting the photos associated to the event id: 4356063141

/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 /vehicles/:vid/plugins/garmin

Get the methods available for the Garmin™

/vehicles/254/plugins/garmin

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

Get the current state of the Garmin™

/vehicles/254/plugins/garmin/state

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

Enable the Garmin™ mode

POST /vehicles/254/plugins/garmin/state

payload 
{
  "new_mode": true
}

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

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

Sending Messages

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

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

This method accepts two parameters: mtype and message

ParameterDescription
mtypeinbox means the message goes to the inbox of the garmin, screen means the message shows up on the garmin screen immediately
messagetext to be displayed on the garmin, up to 40 characters

Send a message to the inbox on the Garmin™ device

POST /vehicles/254/plugins/garmin/message

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

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

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

Getting Messages

Messages are retrieved with the GET method on /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

ParameterDescriptionRequired
uptoRetrieve up to this many messages (Number)No
skipSkip this many messages (Number)No
_fromRetrieve messages from this date (YYYY-MM-DD)Yes

GET messages from a Garmin

GET /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": "[email protected]",
      "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 /vehicles/:vid/plugins/garmin/job

This method accepts three parameters message, flat, flon

ParameterDescription
flatLatitude
flonLongitude
messageText to be displayed on the way to the job (Up to 40 characters - ASCII)

POST /vehicles/254/plugins/garmin/job

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

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

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

Input/Output Expander

Rawdata request with $io_exp set

/rawdata?vehicles=56&fields=$io_exp&duration=P1D&filter=io_exp_state%3E0

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

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

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

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

Interacting with Outputs

Activating extended output 3

POST /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

/devices/:imei?select=ios_state

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

View a log of the output changes

/devices/357042062920955/remote/outputsetlog

[
  {
    "state": true,
    "otype": "e",
    "out": 3,
    "user": "[email protected]",
    "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 /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

{

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

GET /vehicles/617/remote/outputsetlog

More info

Multicamera/expander

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

/vehicles/469/plugins/photocam/capture

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

Get the last photos for vehicle id: 469

/vehicles/469/plugins/photocam/last

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

After some seconds

/vehicles/469/plugins/photocam/last

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

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

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

The capture command for the single camera, and mutiple camera is the same, the difference is in the managed configuration. Note that the managed configuration can be configured to take 1, 2, or 3 photos per any event.

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

🚧

Temperatures out of range

Note that for analog values < 189 mV we take the value received as the temperature in °C.


Javascript

function degC(mV) {

Python

import math
Temp °CmVTemp °CmVTemp °CmVTemp °CmVTemp °CmV
60189402912054801271-203583
591923929919569-11333-213791
581953830718590-21398-224014
571993731517613-31467-234252
562033632416638-41540
552073533415663-51618
542113434414690-61700
532153335413718-71788
522193236512749-81881
512243137711780-91980
502293038910814-102085
49234294019849-112196
48239284148886-122314
47245274287925-132440
46250264436967-142574
452562545851010-152716
442632447441057-162868
432692349131106-173030
422762250921158-183202
412832152811213-193386

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

TPMS

Request tire data (doran example)

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

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

Request tire data (continental example)

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

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

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

and report the following fields associated with this accessory:

fielddescription
ecu_tires_psiTire pressure
ecu_tires_tmpTire temperature
ecu_tpms_warningsTire warnings
ecu_tpms_provisionTire provisioning
ecu_tpms_conditionsTire 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

Be aware that the first axle (Axle #0) will report position's 1 & 2, where 2 is the right most tire in that case.

Explanation of data

Tire pressure

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

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

"ecu_tires_psi": "AAABBB,AAABBB,AAABBB,AAABBB..."

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

"ecu_tires_tmp": "AAABBB,AAABBB,AAABBB,AAABBB..."

Tire temperature

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

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

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

"ecu_tires_warnings": "AAABCDE,AAABCDE,AAABC..."

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

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

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

ecu_tpms_warningsDescription
AAA
000 - 255. Tire Location.
B
Alarm warning
C
TTM defective (1 if TTM is defective)
D
Loose TTM detection
E
Battery warning.
Alarm warning
Description
0
Ok.
1
Under-inflation warning.
2
Under inflation alarm.
3
Tire leak alarm.
4
TTM (Truck tire module) mute.
5
Temperature warning.
8
TTM over temperature warning.
Loose TTM detection
Description
0
No problem
1
TTM loose
2
TTM turned
3
Not supported

"ecu_tpms_conditions": "AAABCDEFGH,AAABCDEFGH,AAABC..."

Tire Conditions (Doran)

ecu_tpms_conditions: 0341030141

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

ecu_tpms_conditionsDescription
AAA
000 - 255. Tire Location.
B
Sensor Status
C
Air Leak
D
Electrical status (not supported, always 3)
E
Tire Temperature
F
System ID
G
Threshold detection
H
Validity
Sensor Status
Description
0
Mute.
1
Signal OK.
2
Not defined.
3
Defective.
Air Leak
Description
0
No fault
1
Fast leak
2
Error
3
Not supported
Tire Temperature
Description
0
Temperature OK
1
Over temperature
2
Not used
3
Not supported
System ID
Description
0
Truck
1
Trailer
Threshold Detection
Description
0
Extreme over pressure
1
Over pressure; 25% over baseline
2
Pressure good
3
Under pressure
4
Extreme under pressure; 25% under baseline
5
Not defined
6
Error
7
Unknown
Validity
Description
0
Not valid
1
Valid

"ecu_tpms_provision": "ABCCDD,ZZZXXXXXXXXXX,ZZZXXXX..."

Tire provisioning

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

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

system 0 is a truck, whose state is 1 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_provisionDescription
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.

Note that on rare ocassions the TPMS accessory can generate 'null' or empty values for a particular tire, it just means that the sensor inside the tire could not be picked up by the accessory at that time. Before analyzing tire pressure and temperature data it's recommended to filter rows with missing tire information, or fill it in with the previous value. The system malfunction state can occur on the CPC accessory because the Central Control Unit (CCU) was programmed as a truck system, to have an Additional Receiver (Add. Rx), but physically you don't have one connected to the test system, this will generate an SPN 611 (FMI 2 or 14, depending on your physical setup) leading to System malfunction.

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.