Description

Post devicecommands API can be used to modify the settings of a SCI device. The names of the settings to be modified should be listed in the command parameters together with their new values.

The server copy of the device settings may be changed at any time, however the settings do not become active until the device has initiated communication with the server and has acknowledged the server’s response. Settings that the device have confirmed to be in use are described as active settings. Settings which have been saved to the server but have not yet been confirmed to be in use by the device are described as pending settings. Pending settings will remain in place until the device has confirmed that the changes have been applied.

When device settings are queried with the query param include=deviceSettings, the result will contain settings JSON object reflecting the currently active settings. If any settings are pending, the result will also contain a pendingSettings.

Device Settings

Generic Device Settings

Environmental Settings

The following settings apply only to devices which support environmental monitoring. The number and type of environmental sensors vary by device, not all of the settings below will be relevant for all devices with environmental monitoring support.

Movement Settings

The following settings apply only to devices which support movement detection.

Tamper Settings

The following settings apply only to devices which support tamper detection; when an attempt to tamper with the device has been detected (e.g., opening of the case, and/or removal of the device) then tamper state will be activated and tamper-specific settings override their normal counterparts.

Ignition Settings

The following settings apply only to vehicle tracking devices that can detect when the ignition switch has been operated. The device will switch into ignition state and the ignition-specific settings will override their normal counterparts.

System Managed Settings

The following settings are not modifiable via DeviceCommand.

Request Parameters

Example 1: request to POST /connect/services/devicecommands/device/devicecommands?v=2.0

commandType should be SciDeviceSettings , above mentioned SCI device settings can be passed along with its value under parameters section. (cropped to focus on relevant parts)

{
  "deviceCommandReq": {
    "deviceIdentifiers": [{
            "identifier": "XXXXXXXXXXXX",
            "type": "XXXXXX"
          }],
    "commands": [{
          "commandType": "SciDeviceSettings",
          "name": "XXXXXX",
          "description": "XXXXXX",
          "parameters": {
            "wakeupPeriod": "XXX",
            "movementAccuracy": "X",
            "wifiProbeCapture": "XXXX"
          }}]
     }
}

🚧

Note

Retry mechanism is not applicable for SCI device command, so value of retryCapable will be set to false and values of maxRetries, ttlSec will be set to zero.

Example 2: DeviceCommand request to configure wifiNetworks

The configured Wi-Fi networks are represented by a JSON string with a single entry, networks, whose value is a JSON array of JSON string storing the SSID and passphrase. An example configuration for two Wi-Fi networks is given below.

{
  "deviceCommandReq": {
    "deviceIdentifiers": [{
            "identifier": "XXXXXXXXXXXX",
            "type": "XXXXXX"
          }],
    "commands": [{
          "commandType": "SciDeviceSettings",
          "name": "Configure wifiNetworks",
          "description": "Configure wifiNetworks",
          "parameters": {
            "wifiNetworks": "{\"networks\":[{\"ssid\":\"ExampleNet\",\"pass\":\"my insecure passphrase\"},{\"ssid\":\"OpenNetwork\",\"pass\":\"\"}]}"
          }}]
     }
}

Open networks should be defined with an empty passphrase. The Wi-Fi configuration is transferred to the device in a packed binary format with a maximum size of 98 bytes, the maximum number of networks which may be defined is therefore dependent upon the length of the SSIDs and passphrases used.

SCI Device Firmware Update

Post devicecommands API can be used to modify the firmware version for SCI device by using command name as DownloadFirmware. Parameter version should be provided with firmware version value. New version will be applied when the device checks in with the server. User can use 'devicecommands/SCI/firmwares' api to retrieve available firmware versions.

When device settings are queried with the query param include=deviceSettings the result will contain firmwareVersion the version of firmware currently on the device and result can also contain firmwareUpdate the version of firmware scheduled to be uploaded to the device on its next report.

Firmware Parameters

Request Parameters

E.g. request to POST /connect/services/devicecommands/device/devicecommands?v=2.0

commandType should be DownloadFirmware , under parameters section above mentioned firmware version can be passed along with its value. (cropped to focus on relevant parts)

{
  "deviceCommandReq": {
    "deviceIdentifiers": [{
            "identifier": "XXXXXXXXXXXX",
            "type": "XXXXXX"
          }],
    "commands": [{
          "commandType": "DownloadFirmware",
          "name": "XXXXXX",
          "description": "XXXXXX",
          "parameters": {
            "version": "XXX"
			}}]
     }
}

🚧

Note

Retry mechanism is not applicable for SCI firmware Download, so value of retryCapable will be set to false and values of maxRetries, ttlSec will be set to zero.

Error Response Parameters

E.g. error response to POST /connect/services/devicecommands/device/devicecommands?v=2.0

error message will be displayed in errors section with '|' separation (cropped to focus on relevant parts)

{
  "response": {
    "errors": [
            "SCI Gateway error for device : XXXXXXXXXXXX, error message : There is no supported firmware with this version, error code : 97
          ],
    "results": [{ 
                .
                .
                .
         }]
  }
 }

🚧

Note

1. tamperReset and moveRepType settings are system calculated and may show in pending settings even if they weren’t changed via DeviceCommand.

2. Device commandType SciDeviceSettings and DownloadFirmware are applicable only for SCI devices, it is not applicable for tags.

3. The status of DeviceCommand request to upgrade/downgrade firmware may not update from SENT to COMPLETED upon successful firmware upgrade. DeviceCommand status will be updated to COMPLETED whenever another DeviceCommand (initiated to change settings parameters) completes successfully. Please use device API to query the current firmware version running on the device to know if the firmware is updated.