Description

Recovery Mode is a device feature that can help to recover a stolen asset. 

When set, a device will begin ‘live-tracking’. Sending regular (30 sec default) position updates to the server. 

Request Example

Payload:

Switch mode, no expiry set. 

{
"MessageType":3, // Set Operational Mode 0x0003
"CANAddress":4294967295, //0xFFFFFFFF,//HOST_ADDRESS - send to device
"Data":[1], // 1 for standard Mode, 3 for Recovery mode
"ExpiryDateUTC":"2018-07-20T18:25:43.511Z" // Absolute time in seconds since 1 Jan 2013 after which the mode should be cancelled.
}

*Please note; there is an inherent expiry time of ~12 hours when no expiry is set 

Setting recovery mode with expiry set

{
"MessageType":3,
"CANAddress":4294967295,
"Data":[03,192,73,142,13],
"ExpiryDateUTC":"2020-03-19T00:00:00.000Z"
}

In this example, the async message itself will expire on March 19, 2020, 00:00 UTC. (ExpiryDateUTC)

So, if it is not actioned on the device by this time, it will expire.

The recovery mode will expire on 2020-03-17 06:40:00 UTC - as contained in the message Data

The data field is generated as follows:

• Message Type - Recovery mode - 0x03
• Expiry time as above is 227428800 seconds since 1/1/13 00:00 UTC. Converting to hex and little endian, C0 49 8E 0D
• See Times in the DM Protocol for more information and the calculator pictured below
  
• So, we must send 0x03C0498E0D
• Then we send the byte array in JSON format
  • 03 = 3
  • C0 = 192
  • 49 = 73
  • ….

Giving:

[3, 192, 73, 142, 13]

Set Operational Mode – Confirming the device has actioned recovery mode. 

The response to the API call only indicates Device Manager has received the message, and has placed it into the queue for delivery to the device when it next connects. 

We want to keep track of whether the device is/isn’t currently in recovery mode. 
This information is reported in the device payload in a few ways

1. Log Reason 36 (Recovery Mode On) and 37 (Recovery Mode Off)

When the device enters/exits recovery mode, it will connect to the server and send the corresponding log reason. 

2. Bit 7 of the Device Status Flags (from Digital Data FID 2) 

This bit will be set when in recovery mode, and unset when not in recovery mode. 

Troubleshooting

My device didn't actually enter recovery mode? 

In general, this is due to the expiry date occurring before the device received the message, as the expiry datetime is absolute, and not relative to when the device received the message.