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

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

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.

Bluetooth tag wake up reasons

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

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

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

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)

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__' />

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

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

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

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

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

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.

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

Python

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:

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

and report the following fields associated with this accessory:

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

Tire location

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

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

tire_axle = (tire_location >> 4) & 0x0F

tire_position = tire_location & 0x0F

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

Explanation of data

Tire pressure

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

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

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

AAA

BBB

"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.

AAA

BBB

"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

AAA

B

Alarm warning

C

D

Loose TTM detection

E

Alarm warning

0

1

2

3

4

5

8

Loose TTM detection

0

1

2

3

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

AAA

B

Sensor Status

C

Air Leak

D

E

Tire Temperature

F

System ID

G

Threshold detection

H

Validity

Sensor Status

0

1

2

3

Air Leak

0

1

2

3

Tire Temperature

0

1

2

3

System ID

0

1

Threshold Detection

0

1

2

3

4

5

6

7

Validity

0

1

"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.

A

B

System state.

CC

DD

ZZZ

XXXXXXXXXX

System state

0

1

2

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.