Device Interaction

You can use the API to interact and send remote instructions or commands to devices. Instructions can be things like editing a speed limit or activating/deactivating an output.

In order to instruct a device to activate an output for example it needs a managed configurations assigned.

Configurations

Configurations are predefined scripts with instructions for devices that make them behave in specific ways, these are found under the [/configurations](https://documenter.getpostman.com/view/389172/2s935vnLvt#d3ca932d-d689-4d38-af9a-3687ff612f1b) API. It is with the help of managed configurations that some devices can support Safe Engine Immobilization.

Get a list of configurations, each configuration has a unique ID or 'ky'

GET /configurations

Get the details of a configuration, tells you if certain features are supported such as safe engine immobilization ("safeimmo")

GET /configurations/:ky

{
  "params": {
    "safeimmo": true
  },
  "ky": "s219",
  "name": {
    "en": "Syrus standard configuration",
    "es": "Configuracion estándar de Syrus"
  }
}

You can set a configuration with a POST on the /devices/imei/configuration API.

Set a configuration to a device

POST/devices/:imei/configuration
{
    "ky": "s219"
}

🚧
Restricted devices
Note that some configurations are restricted to only work with certain device models. See the restricted_device param in the configuration details response.

Once the configuration is set you can query the status with a GET on the previous API method.

Get the configuration parameters and status of a device configuration for a device. Once the state is synched you can interact with the device using the remote methods.

GET /devices/:imei/configuration

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

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

Device interaction

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

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

GET /devices/:imei/remote

{
	"output": {
		"POST": [
      "otype",
      "out",
      "state"
    ]
	},
	"safe_immo": {
		"POST": [
			"action"
		]
	},
	"console": {
		"POST": [
			"cmd"
		],
		"GET": [
			"cid"
		]
	}
}

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

GET /vehicles/:id/remote

📘
Permissions / Scopes
In order to perform GET remote requests you need 'read' permission on remote scope, and POST methods require write permission on remote scope.

Immobilize a vehicle

Immobilizing a vehicle refers to sending a command that would activate the device's output 1. Some devices have an immobilization mechanism that waits for certain conditions to meet before activating, in this way the immobilization is safe. We'll refer to immobilization as 'safeimmo' from now on. Safeimmo requires that the device is installed by a certified professional that knows how to install a relay on a vehicle's ignition cable or starter cable with the device's output cable.

Step 1. Check if safeimmo is supported

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

/devices/:imei?select=config

Safe immobilization supported

{
		"config": {
				"kydef": {...},
				"kymod": {},
				"_config_state": 1,
				"_epoch": 1617041571.785082,
				"safeimmo_support": true,      # SAFE IMMOBILIZATION SUPPORTED
				"values": {...},
				"ky": "q740"
		}
}

If the device has the safeimmo_support in false or there's no managed configuration set on the device then you have to use a normal output activation and activate output #1.

📘
Configuration state
Be sure to wait for the configuration to be synchronized (_config_state: 3) in order to be able to send the safeimmo.

Step 2. Safely immobilize the vehicle (activate output 1 safely)

Use the /devices/:imei/remote/safe_immo API to activate output 1 safely.

Safely immobilize a vehicle

POST /devices/:imei/remote/safe_immo

{
	"action": true
}

response

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

Step 3. Monitor the state of the output

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

GET /vehicles/:vid/remote/state

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

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

📘
Things to consider
If safeimmo is active and the device's configuration is changed from one that supports safeimmo and to one that does not support it, then the output 1 will go to false, and you can use the [/remote/output](#activate-an-output) to activate/deactivate the device's outputs.

Safeimmo walkthrough

Step 1: Safeimmo supported by the device's configuration

/devices/:imei?select=config

 				"safeimmo_support": true,

Step 2: Command to immobilize is sent (you can send it to a vehicle ID and there's no need to specify in the body of the message)

POST /vehicles/:vid/remote/safe_immo

{
	"action": true
}

Step 3: Waiting for device to receive instruction

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

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

Step 4: Instruction sent

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

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

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

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

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

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

Activate an output

Device outputs can be manipulated with the /devices/:imei/remote/output api, making a POST request with otype, out, state as parameters.

❗️
Using outputs for activating safeimmo
It is not recommended to use an output for safe engine immobilization / cutting the ignition wire. When you activate an output using this method it happens immediately and doing so to an ignition wire can cause serious issues on a car that's moving.
If you consider using an output to activate a starter wire on a vehicle than it may be a good idea to do so while the car is parked and you can use the ping location method to get the current status of the vehicle and make sure it's not moving.

The parameters for the /remote/output API are:

Param	Type	Description
`otype`	String	set to `n` for outputs 1, 2, and `e` for higher outputs
`out`	Number	Output number
`state`	Boolean	`true` to activate output

Activating output 1 on vehicle 2063 (in the event that SafeImmo is false/not supported)

POST /vehicles/2063/remote/output

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

Activating output 3 on device 357042062897906

POST /devices/357042062897906/remote/output

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

Get the state of the outputs

GET /devices/:imei?select=latest.ios

{
  "imei": 814401083083440,
  "latest": {
    "prefix": "API-2::device.device.814401083083440",
    "ios": {
      "io_pwr": true,
      "io_out2_short": false,
      "io_ign": false,
      "evtime": 1685350875.0,
      "io_exp_state": false,
      "io_out1_short": false,
      "io_out1": false,
      "io_out2": false,
      "systime": 1685350912.500692,
      "io_in1": false,
      "io_in2": false,
      "io_in3": false
    }
  }
}

Send a custom command

Custom commands can be sent with the /devices/:imei/remote/console api, with the cmd parameter where you put the command you want to send.

📘
Custom commands to Syrus 2 and 3
Before you send a command to a Syrus 2 and Syrus 3 device make sure the command you want to send to the unit is in the list of allowed_cmds for that managed configuration or else it will return an Error 04.

Example send a command to add a new RFID tag to a Syrus 3 device

POST /devices/:imei/remote/console

{
		"cmd": ">SRIA123456<"
}

Response

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

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

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

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

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

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

/devices/:imei/messages/pending

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

List all commands sent to the device

/devices/:imei/messages/sent

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

Trigger a position event (ping location)

To trigger a location event or ping the device for an updated location you can use a POST on the trigger_position_event remote method.

Trigger the device to generate an event (ping it's location)

POST /devices/:imei/remote/trigger_position_event

Get the current location using the device api

GET /devices/:imei?select=latest.loc

{
  "imei": 814401083083440,
  "latest": {
    "loc": {
      "head": 0,
      "code": 37,
      "age": 1,
      "lon": -74.14734,
      "mph": 0,
      "label": "position",
      "evtime": 1685350875.0,
      "source": 1,
      "valid": false,
      "moving": false,
      "systime": 1685350912.500692,
      "lat": 4.67649,
      "trip_id": 225500112312525
    },
    "prefix": "API-2::device.device.814401083083440"
  }
}

Device Interaction

Configurations

🚧
Restricted devices

Device interaction

📘
Permissions / Scopes

Immobilize a vehicle

Step 1. Check if safeimmo is supported

📘
Configuration state

Step 2. Safely immobilize the vehicle (activate output 1 safely)

Step 3. Monitor the state of the output

📘
Things to consider

Safeimmo walkthrough

Activate an output

❗️
Using outputs for activating safeimmo

Send a custom command

📘
Custom commands to Syrus 2 and 3

Trigger a position event (ping location)

Configurations

🚧Restricted devices

Device interaction

📘Permissions / Scopes

Immobilize a vehicle

Step 1. Check if safeimmo is supported

📘Configuration state

Step 2. Safely immobilize the vehicle (activate output 1 safely)

Step 3. Monitor the state of the output

📘Things to consider

Safeimmo walkthrough

Activate an output

❗️Using outputs for activating safeimmo

Send a custom command

📘Custom commands to Syrus 2 and 3

Trigger a position event (ping location)

🚧
Restricted devices

📘
Permissions / Scopes

📘
Configuration state

📘
Things to consider

❗️
Using outputs for activating safeimmo

📘
Custom commands to Syrus 2 and 3