SCI Device Settings

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

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

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

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

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

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

SettingsDescriptionType
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

ParameterDescriptionType
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

  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.