Digital Matter Support

Choosing an Integration Strategy

This article discusses the various integration strategies for DM cellular products.

List of integration options and how to get started:

1. Use Telematics Guru
Digital Matter will set up the Telematics Guru organisation for you and send you an invite link along with user guides
2. Use OEM Server with raw TCP payload
Contact your Digital Matter support team with your endpoint and we can create the connector
3. Use OEM Server with JSON HTTP payload
Contact your Digital Matter support team with your endpoint and we can create the connector
4. Bypass OEM and send data direct
Digital Matter will activate Direct config mode on your devices (Charges apply)

Definitions

OEM Server
DM's device management platform. The OEM Server is middle ware layer that simplifies device management. It manages device firmware and settings. It allows logical groupings of devices. It allows health checks and debugging. And it allows data to be routed to a variety of platforms using connectors. OEM has a web user interface at www.oemserver.com.
Connector
Defines how and where data is directed from the OEM Server. Connectors come in 2 forms:
Raw TCP Connector: 
OEM forwards data in the device's native format - raw binary data over a TCP socket. The raw TCP protocol is described in 3 documents from DM. These are available under NDA and potentially with a support fee.
JSON HTTP Connector
OEM translates the raw data from the device into JSON and uses an HTTP POST to deliver the records to an endpoint. This can be simpler to interpret, but is less performant for large numbers of devices.

Note

Data can be sent to multiple platforms simultaneously using the Multi-Connector (sometimes referred to as a 'splitter'). This is commonly used to send data to Telematics Guru and another platform.


1. Use Telematics Guru 2. Raw TCP Connector 3. HTTPS/Json Connector  4. Direct Mode

Use Telematics Guru

Telematics Guru offers some interesting integration options for 3rd party platforms. In many cases, clients use TG for its strengths (mapping, geo fences, etc) and push events into their own platform which may have other strengths. 

The diagram below shows the flow of data. Data is sent through the usual mechanism via OEM Server to TG - and then Webhooks can be set up to send information to a 3rd party plaftorm.

Examples of integration from TG could be done with:

  • Web hooks
  • Email integration into a ticket management system.

Option 1 - Integration via Telematics Guru

What are WebHooks?

WebHooks are a way that one application can send a message to another. When a specific configured event happens in one app, it triggers a WebHook to send some data to another application which can use this data and perform other actions if necessary. 

What are the applications/why would I use them?

In Telematics Guru - the way webhooks are implemented is essentially a URL can be the recipient of an Alert Notification. 

So when an alert is triggered in TG - some information is sent to that server in the form of a HTTP post. 

This is useful when Telematics Guru is being used as the tracking platform, but a user has some other system which they need some of the telemetry data. There is no cost for this service, it is included in the TG fees. 

One example is a hiring or maintenance software. This system requires updates of asset run hours and odometer values. The WebHook is configured so that at the end of a trip, the Odo/Run Hour value for the asset is sent from TG via HTTP POST to the system.

If two systems need to be used in parallel and more than a few data points are required - it is best to use the Multi-Connector option - to have device data sent to both TG and the 3rd party platform simultaneously. 

 Webhooks

Click here to read more on webhooks

OEM Server Functionality:

The OEM Server is a middle ware layer that acts as a data switch and device management platform. It provides the ability to:

  1. Control where device data is sent using connectors. Send data to TG, other platforms, or even multiple platforms. The format can be raw data over TCP sockets or JSON over HTTP.
  2. Health checks with last communication dates and device voltages.
  3. Update firmware over the air
  4. Update device settings over the air, and create settings templates.
  5. Remotely debug using data capturing.
  6. Remotely debug by adjustable on device logging verbosity
  7. Debug end server interactions with the devices and possible issues
  8. Manage devices in groups
  9. Presentation of advanced device profiling statistics. eg GPS fix count, GPS on time, etc.

Encryption:

A number of devices connect to OEM over an encrypted connection. There are 2 goals for this:

  • Authentication: verifying the device is authentic, and verifying the server is legitimate, and verifying that the data has not been tampered with.
  • Confidentiality: securely transmitting information.

The encryption is a CCM Mode block cipher scheme, using AES256 keys. Keys are shared securely between the device and server.

Notes on the encryption:

  • Check with DM as to which devices support encryption.
  • Encryption is device to OEM. After OEM, other measures are required, such as SSL, 
  • Encryption is not available in the Direct 3rd party model for the data transmitted from device to the 3rd party system. Device to OEM for configuration will still be encrypted.

OEM WebAPI:

The OEM WebAPI provides a few features which enable some control of device settings etc from a 3rd party platform. Contact DM Support for documentation.

It enables the following two sets of commands:

  1. OEM actions such as setting parameter templates and connectors
  2. Sending ASYNC messages to devices such as turning on recovery mode and controlling outputs

OEM Actions

Key features:

  • Get a list of parameter templates, and set them
  • This allows parameters to be changed programatically to pre-defined templates
  • Set the Batch String in OEM
  • Change connectors
  • Set enabled/disabled in OEM

ASYNC messages

On top of this - async messages (downlinks) can be sent to the device. The OEM WebAPI can be used to queue the message on OEM Server which will then send the message to the device. Key messages are:

  • Enable/disable Recovery Mode
  • Set/unset digital outputs
  • Turn immobilisation off/on
  • Reset the device

The WebAPI opens up some useful functionality - as the device can be controlled programatically based upon other events happening. Examples include:

  • Setting connectors/parameter templates when provisioning a device in a 3rd party front-end platform. 
  • Changing parameter templates at certain times of the day (to adjust reporting rate)
  • Turning recovery mode on automatically if movement is detected after hours.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.