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

Settings	Description	Type
`alwaysOn`	Stay connected to the mobile network between reports. This allows reports to be sent back to the server without waiting to reconnect to the mobile network. Staying connected increases battery usage.	Boolean
`disableGPS`	A flag which when set to true disables the use of the GPS for position reports.	Boolean
`enable433`	A flag which when set to true enables a small RF transmitter operating at 433 MHz for direction finding.	Boolean
`flashFallback`	If set to true and the device is unable to report then the message is stored in flash memory and sent to the server on the next successful connection.	Boolean
`impactAlert`	A flag indicating that the device should report when an impact exceeding the maximum impact threshold has been detected.	Boolean
`maxImpact`	The maximum acceptable impact, expressed in g. Impacts greater than this value will trigger the device to report if an impact alert has been set.	Floating point
`logCollectCell`	Flag to indicate if mobile networks cell data should be logged when operating in normal timer state.	Boolean
`logCollectWifi`	Flag to indicate if Wi-Fi network data should be logged when in normal timer state.	Boolean
`logFullGps`	Flag to indicate if GPS data should be logged when in normal timer state.	Boolean
`loggingPeriod`	Define the interval, in seconds, between logged measurements when in normal timer state.	Integer
`logGpsTrack`	Flag to indicate if a GPS track, comprising of up to 20 GPS measurements of latitude and longitude pairs, should be recorded before a location report is made in normal timer state.	Boolean
`logProbeCapture`	Flag which when true indicates that Wi-Fi probes should be logged when in normal timer tamper state.	Boolean
`logSendOnFullBuffer`	Flag which when true indicates that a report should be made when in normal timer state and the logging buffer is almost full, to avoid loss of log data.	Boolean
`oceanMode`	Flag which when true reduces communications for power saving when no cellular networks are available.	Boolean
`sensorLoggingPeriod`	Define the interval, in seconds, between logged measurements when in normal timer state.	Integer
`timerAccuracy`	Set required position accuracy when reporting in normal (timer) state (exceeded interval between reports) (allowed value 0 to 6)	Integer
`tipAlert`	A flag indicating that the device should report when it detects the maximum tip angle has been exceeded.	Boolean
`maxTip`	The maximum acceptable tip angle, expressed in degrees. Tip angles greater than this value will trigger the device to report if a tip alert has been set.	Floating point
`wakeupPeriod`	The period between scheduled reporting times, defined in seconds.	Positive Integer
`wifiProbeCapture`	Flag which when true indicates that Wi-Fi probes should be returned with a normal report.	Boolean
`zMicroDetection`	Flag which when true indicates that tags should be detected and reported.	Boolean
`zMicroDeviceMinRSSINew`	The RSSI threshold (in dBm) that a previously unseen tag must exceed to trigger a “new tag” report to the server.	Integer
`zMicroDeviceOldTime`	The delay after a tag is last observed before a “tag gone” message is reported to the server.	Integer
`zMicroRxPeriod`	The time interval, in seconds, between the start of tag detection cycles.	Integer
`zMicroRxTime`	The period, in seconds, for which tag detection is active. The duty cycle of the radio is given by the zMicroRxTime / zMicroRxPeriod.	Integer
`wifiNetworks`	Configure the Wi-Fi network(s) to which the device should attempt to connect. The device first scans to find what networks are available, the device will attempt to connect to each in turn if it is known to the device. If the device cannot connect to any Wi-Fi network it will probe for each configured network, so that networks which do not broadcast their SSID may still be used. WPA and WPA2 networks with or without a pre-shared key are supported, enterprise networks which use a username and password are not supported. Please refer to Example 2 in Request parameters section for more details.	JSON String
`sensorEventMode`	Controls the behaviour of sending sensor event from device as they occur (allowed value 0 to 3)	Integer
`syncSensorLog`	A flag indicating that the device should enable temperature sync logging when a temperature measurement has been taken that is less than the threshold defined by the sync logging temperature limit value.	Boolean
`syncSensorLogTempLimit`	The temperature threshold, in degrees Centigrade, where the temperature sync logging will be enabled. Actual temperature greater than threshold disables sync logging. Actual temperature less than or equal to threshold will enable sync logging.	Integer
`userButtonBehaviour`	Control what happens when the user presses the button. The button can operate as an on/off switch, a report button or it can be disabled (allowed value 0 to 3)	Integer
`userLedState`	Control flashing of the button LEDs. The button can be made to periodically flash red, green or amber (allowed value 0 to 3)	Integer

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.

Settings	Description	Type
`temperatureAlert`	A flag indicating that the device should report when a temperature measurement has been taken that is outside of its permitted range, as defined by its minimum temperature and maximum temperature values.	Boolean
`temperatureLogging`	Enable temperature logging. See sensorLoggingPeriod to set the logging period	Boolean
`minTemperature`	The minimum acceptable temperature, expressed in °C. Temperatures lower than this value will trigger the device to report if a temperature alert has been set.	Floating point
`maxTemperature`	The maximum acceptable temperature, expressed in °C. Temperatures greater than this value will trigger the device to report if a temperature alert has been set.	Floating point
`humidityAlert`	A flag indicating that the device should report when a humidity measurement has been taken that is outside of its permitted range, as defined by its minimum humidity and maximum humidity values.	Boolean
`maxHumidity`	The maximum acceptable humidity, expressed as a relative humidity percentage. Humidity greater than this value will trigger the device to report if a humidity alert has been set.	Floating point
`minHumidity`	The minimum acceptable humidity, expressed as a relative humidity percentage. Humidity lower than this value will trigger the device to report if a humidity alert has been set.	Floating point
`lightLevelAlert`	A flag indicating that the device should report when a light level value measurement has been taken that is outside of its permitted range, as defined by its minimum light level and maximum light level values.	Boolean
`minLightLevel`	The minimum acceptable light level, expressed in raw sensor units. A light level lower than this value will trigger the device to report if a light level alert has been set	Floating point
`maxLightLevel`	The maximum acceptable light level, expressed in raw sensor units. A light level higher than this value will trigger the device to report if a light level alert has been set.	Floating point

Movement Settings

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

Settings	Description	Type
`enableMovementDetection`	When set to a true value instruct the device to enter movement state if the movement is detected. If false, the device will not enter movement state.	Boolean
`immediateMovementReport`	This setting removes restrictions on safe reporting rates that are normally present to prevent excessive reporting that would reduce the expected battery life.	Boolean
`movementAccuracy`	Set the required position accuracy when in movement state (value 0 to 6).	Integer
`moveWakeupPeriod`	The interval, in seconds, between reports when in movement state.	Integer
`movingLogCollectCell`	Flag to indicate if mobile networks cell data should be logged when in movement state.	Boolean
`movingLogCollectWifi`	Flag to indicate if Wi-Fi network data should be logged when in movement state.	Boolean
`movingLogFullGps`	Flag to indicate if GPS data should be logged when in movement state.	Boolean
`movingLoggingPeriod`	Define the interval, in seconds, between logged measurements when in movement state.	Integer
`movingLogGpsTrack`	Flag to indicate if a GPS track, compromising of up to 20 GPS measurements of latitude and longitude pairs, should be recorded before a location report is made in movement state.	Boolean
`movingLogProbeCapture`	Flag which when true indicates that Wi-Fi probes should be logged when in movement state.	Boolean
`movingLogSendOnFullBuffer`	Flag which when true indicates that a report should be made when in movement state and the logging buffer is almost full, to avoid loss of log data.	Boolean
`stationaryReportingDelay`	If non-zero only begin communication after the device has been stationary for the specified period, in seconds.	Integer
`autoFlightMode`	When true the device will use the accelerometer to detect when a device is on a plane. This will trigger the device to go into flight mode, and it won’t report in this mode.	Boolean
`pressureSensorFlightMode`	When true the device will use the pressure sensor to detect when a device is on a plane. This will trigger the device to enter flight mode, and it will not report whilst flight mode is active.	Boolean

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.

Settings	Description	Type
`enableTamperDetection`	When set to a true value instruct the device to enter tamper state if a tamper event is detected. If false, the device will not enter tamper state. Note that if tamper state is already active it can only be cleared by sending the tamperReset setting.	Boolean
`tamperAccuracy`	Set the required position accuracy when in tamper state (value 0 to 6)	Integer
`tamperLogCollectCell`	Flag to indicate if mobile networks cell data should be logged when in tamper state	Boolean
`tamperLogCollectWifi`	Flag to indicate if Wi-Fi network data should be logged when in tamper state	Boolean
`tamperLogFullGps`	Flag to indicate if GPS data should be logged when in tamper state	Boolean
`tamperLoggingPeriod`	Define the interval, in seconds, between logged measurements when in tamper state.	Integer
`tamperLogGpsTrack`	Flag to indicate if a GPS track, compromising of up to 20 GPS measurements of latitude and longitude pairs, should be recorded before a location report is made in tamper state.	Boolean
`tamperLogProbeCapture`	Flag which when true indicates that Wi-Fi probes should be logged when in tamper state.	Boolean
`tamperLogSendOnFullBuffer`	Flag which when true indicates that a report should be made when in tamper state and the logging buffer is almost full, to avoid loss of log data.	Boolean
`tamperWakeupPeriod`	The interval, in seconds, between reports when in tamper state.	Integer

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.

Settings	Description	Type
`enableIgnitionDetection`	When set to a true value instruct the device to enter ignition state if the ignition switch is operated. If false, the device will not enter ignition state.	Boolean
`ignitionLogCollectCell`	Flag to indicate if mobile networks cell data should be logged when in ignition state.	Boolean
`ignitionLogCollectWifi`	Flag to indicate if Wi-Fi network data should be logged when in ignition state.	Boolean
`ignitionLogFullGps`	Flag to indicate if GPS data should be logged when in ignition state.	Boolean
`ignitionLoggingPeriod`	Define the interval, in seconds, between logged measurements when in ignition state	Integer
`ignitionLogGpsTrack`	Flag to indicate if a GPS track, comprising of up to 20 GPS measurements of latitude and longitude pairs, should be recorded before a location report is made in ignition state	Boolean
`ignitionLogProbeCapture`	Flag which when true indicates that Wi-Fi probes should be logged when in ignition state	Boolean
`ignitionLogSendOnFullBuffer`	Flag which when true indicates that a report should be made when in ignition state and the logging buffer is almost full, to avoid loss of log data	Boolean
`ignitionOnAccuracy`	Set the required position accuracy when in ignition state. (value 0 to 6)	Integer
`ignitionOnWakeupPeriod`	The interval, in seconds, between reports when in ignition state.	Integer

System Managed Settings

The following settings are not modifiable via DeviceCommand.

Settings	Description	Type
`accessPointName`	The name of the packet data network to be used for the mobile network connection.	String
`accessPointPassword`	The password used to connect to a mobile network.	String
`accessPointUserName`	The user name used to connect to a mobile network.	String
`DNSName`	The hostname, domain name or IP address used when the device communicates with a SCI Gateway.	String
`HWServerPhoneNumber`	The mobile phone number associated with the SCI Gateway, used when messages are exchanged by SMS.	String
`port`	The UDP or TCP port number to be used when the device communicates with a SCI Gateway.	Integer
`SMSpassword`	The password that must be used to authenticate any incoming SMS commands.	String
`tamperReset`	Flag which when true indicates that the device is to exit tamper state, if tamper state is active.	Boolean
`reportPersistence`	reportPersistence	Integer
`ALTIPAddress`	ALTIPAddress	String
`masterId`	masterId	Integer
`moveRepType`	moveRepType	Integer

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

Parameter	Description	Type
`version`	firmware version	String

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

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

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

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.