Digital Matter Devices make use of an asynchronous (ASYNC) messaging protocol to send messages between the device and server. This enables various command and control of the device including:

• Turning recovery mode off/on
• Activating or deactivating an immobiliser
• Toggling a device output

Given most devices do not remain constantly connected to the network and the server, a message queuing mechanism is built into Device Manager. 

The Device Manager API allows any ASYNC message to be queued via API call. Once the call is made the message is queued on the server until the device connects in - then it is delivered to the device. 

Implementing these calls enables the full potential of Digital Matter devices to be unlocked. 

Message Delivery and Acknowledgement

It is important to note that when using the Device Manager API, messages are sent on to devices via Device Manager. Specifically, the order of operation is:

1. 3rd Party Platform sends API call to Device Manager
2. Device Manager will acknowledge this message, sending back an ASYNC Message ID
3. Device Manager will queue the message
4. The device will connect in, and process any queued async messages, and action them if valid. 

The acknowledgement given in (2) - is not an indication that a device has entered recovery mode for example (if this is the command sent).

In general, device payload data will indicate if the ASYNC was processed by the device. This is detailed in the documentation per message type. 

Message Structure

See https://api.oemserver.com/swagger/index.html 

URL: https://api.oemserver.com/v1.0/asyncmessaging/send/[device serial]

• Content Type: application/json
• Accept Header: application/json
• Authentication: Basic or Bearer is supported. 

The DM ASYNC message structure must be adhered to which requires the following:

• Message Type
  • E.g. 0x100 (256) for immobilisation, 0x003 for operational (recovery) mode
• CAN Address - this is always 0xFFFFFFFF - meaning it is a message to be sent to a device.
• Message Expiry - time for the ASYNC message to expire if left unprocessed (i.e. device doesn't connect in)
  • Most simply just default to 30 days from the time of the original message being sent (i.e. increment the month number by 1)
• SendAfterDateUTC
  • Could be used to ‘schedule’ a message. Device Manager will store the ASYNC in it's queue and only send to the device after this date. 
  • However we cannot necessarily control when the device will connect in to Device Manager and process it
  • e.g. if we set Recovery Mode with SendAfterDateUTC to the 01/04/2025 at 10am - we know that the device will receive the ASYNC at some point after this - not exactly at this time.  
• Data (Payload specific to the message type) 

To use the API, we must simply pass the same data in JSON format, and Device Manager will forward this to the device. 

Checking Message Delivery

To check for ASYNC message delivery when testing, go to the Details tab in Device Manager by selecting the serial number.

The queue and history of messages is displayed (you can toggle between queue and history with the button)

Some messages have descriptions indicating what they are for. 

When posting an asynchronous message to a device via the WebAPI – the response only indicates that the payload was valid, and that Device Manager has received the message. It does not indicate that it has been passed down to the device and the device has actioned the message. 

The ASYNC message queue goes into more detail. 

AsyncMessaging/GET allows this queue to be retrieved/read via API call

Yet even a message being Delivered to the device does not mean we got the result we wanted - i.e. we can send an immobilisation command to a device, it will always be processed by most device types that support immobilisation. If we have not configured the parameters correctly - nothing will happen. 

It is best to validate the message has given the intended effect in the upcoming device data.