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 |
The Syrus 4 supports the following ADAS fields in rawdata:
ADAS fields
adas_distance_from_front_vehicle
- distance from front of vehicle in metersadas_headway_measurement
- headway measurement in secondsadas_headway_warning_level
- headway warning leveladas_relative_speed_from_front_vehicle
- relative speed from front of vehicle in kphadas_speed_limit_recognition_sensitivity
- speed limit recognition sensitivityadas_speed_limit_recognition_state
- speed limit recognition stateadas_speed_limit_recognition
- speed limit recognition valueadas_speed
- adas measured speedadas_traffic_signs_recognition_warning_level
- traffic signs recognition warning leveladas_vision_only_sign_type
- vision only sign type
Bluetooth Tags
Associating to asset
PUT
/: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 /:bttag_mac with the asset_id
you want associated
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.
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 & 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
Capturing a photo or video
Example: capture a photo from the camera connected to vehicle id: 1956
{
"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
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
/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 /ibuttonsPayload 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_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
/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
/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 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 /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
{
"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__' />
Getting the last photo
https://api.pegasusgateway.com/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://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
[
{
"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
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
/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™
{
"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 /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
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 /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
{
"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
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
/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
{
"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": "[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
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.
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 °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 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_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.
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
{
...
"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.
Updated 3 months ago