Contact Us

If you still have questions or prefer to get help directly from an agent, please submit a request.
We’ll get back to you as soon as possible.

Please fill out the contact form below and we will reply as soon as possible.

  • Digital Matter Site
  • Contact Us

Activate Recovery Mode via the API - 0x003

Written by Matthew Clark-Massera

Updated at March 18th, 2025

Contact Us

If you still have questions or prefer to get help directly from an agent, please submit a request.
We’ll get back to you as soon as possible.

Contact Support
  • Home
  • Device Manager (OEM Server)
  • Device Manager API
  • Device Control - Asynchronous Messages

Table of Contents

Before you start Description Request Example Troubleshooting My device didn't actually enter recovery mode?

Before you start

Ensure you have reviewed:

  • Welcome to the Device Manager API
  • Device Manager ASYNC Messaging Architecture

A full list of API calls can be found at: https://api.oemserver.com/swagger/index.html.

 

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:

Offset

Length

Data Type

Description

0

1

BYTE

Set operational mode:
NORMAL = 1,
RECOVERY = 3

1

4

UINT

Absolute time in seconds since 1 Jan 2013 after which the mode
should be cancelled.

 

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
    A screenshot of a computer

Description automatically generated
  • 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. 

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

endpoint request data retrieval

Was this article helpful?

Yes
No
Give feedback about this article

Related Articles

  • Recovery Mode Details - Edge Devices and Barra Core

Subscribe to Partner News

Subscribe to our mailing list to receive Digital Matter news, product and tehnical updates, and more.

Subscribe

Copyright © Digital Matter . All Rights Reserved.

Privacy Contact Support

Knowledge Base Software powered by Helpjuice

Expand