Digital Matter Support

Choosing an Integration Strategy

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


List of integration options:

  1. Use Telematics Guru
  2. Use OEM Server with the raw TCP connector
  3. Use OEM Server with the JSON HTTP connector
  4. Bypass OEM and send data directly to the end server.


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.

Integration option discussion:


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

So when something happens in one app - it triggers a WebHook to send some data to another - and the other app 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. 


So one example is hiring or maintenance software. This system requires updates of asset run hours and odometer values. So the WebHook is configured such that at the end of a trip, the Odo/Run Hour value for the asset is sent from TG via HTTP post to this 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. 


Click to learn more about Webhooks



2. OEM Server with the raw TCP connector

In this model, devices connect to the OEM Server. Both device data and device management is handled via the OEM Server:

  • Device data: data is sent to the OEM server, and forwarded with a connector. The connector specifies the endpoint's location (URL:port). Data is sent in the device's native protocol, which is a raw TCP protocol. A TCP socket is opened per device connection. 
  • Device management: all of the OEM device management and debugging features are available through the web user interface.


The use of the OEM server implies a fee per device per month. Contact your local DM office for this price.


Most large scale integrations favor the raw TCP connector over the HTTP connector for performance reasons.


The raw TCP protocol is described by a collection of documents available from DM. These are discussed below.


Option 2 - OEM Server with TCP Connector



3. OEM Server with the JSON HTTP/HTTPS connector

In this model, devices connect to the OEM Server. Both device data and device management is handled via the OEM Server:

  • Device data: data is sent to the OEM server, and forwarded with a connector. The OEM server translates the devices's native protocol into a JSON format and these records are sent to an endpoint over an HTTP POST. The connector specifies the endpoint location, and optionally: SSL (HTTPS); basic authentication; and some custom header options.
  • Device management: all of the OEM device management and debugging features are available through the web user interface.


The use of the OEM server implies a fee per device per month. Contact your local DM office for this price.

Additionally, following this integration path locks the user to OEM and the fee. OEM cannot be bypassed in this setup, as the JSON HTTP conversion happens on the OEM Server.


This HTTP connector is considered less performant than the TCP connector. 


The JSON HTTP protocol is described by a document available from DM. This is discussed below.


Option 3 - OEM Server with HTTP Connector



4. Direct to 3rd Party

The final integration option bypasses the OEM Server. There are some variations of this model:

  • Device data: devices are configured to connect directly to the 3rd party system. The endpoint's location (URL:port) is setup on the device. Data is sent in the device's native protocol, which is a raw TCP protocol.

  • Device management: this can be done in a few ways
    • Periodic OEM Connection: Devices can be setup to periodically connect to OEM for configuration updates. No data is sent to OEM. Devices can receive firmware and settings from OEM. Device are editable in the OEM Web UI. The debugging and health check features of OEM are not available.
    • Connect to OEM only on instruction: the devices will only connect to the 3rd party server. They can be instructed to connect to OEM with an async message (a downlink). For example, this would be done when a settings update has been queued on OEM and the 3rd party server tells the device to go and fetch it.
    • Edit configuration using async messages (downlinks) to the device. Using this mechanism the 3rd party can edit settings on the device. This is complex to implement and requires a support package from DM.


There is no monthly OEM fee for this model. There may be an "unlock" or "3rd party direct" fee to allow the device to connect to a system other than OEM. This is a once off fee and appears on the standard price list.


The unlock command can only be sent by DM. Once a device is unlocked - it cannot be used with a connector to send data as per option 2 or 3. 

Once unlocked, to again use a connector, DM can reconfigure the device for this to happen. Ideally these changes should be rare, in most cases devices should be unlocked at the time of shipping.


When doing a direct to 3rd party integration, integrators are encouraged to start doing so via the OEM Server and a raw TCP connector. This gives the DM support personnel insight into what is happening and how to assist the integration. Once this is working, the device can be setup to go directly to the 3rd party.


There is very little difference between the data received directly from a device and from the OEM TCP connector. There are some differences. OEM will filter out device debug messages and will usually filter out device profiling counters.



Option 4 - Direct to 3rd Party Server Integration


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.



Integration documents:

DM provides documentation and support resources for device integration. These are available under NDA, and sometimes subject to a support package fee.

  • Raw TCP integration: this is 3 documents:
    • DMT Device Integration - Flexi Record: this explains the various messages sent by the device, and the expected responses from the end server. The protocol uploads data in "Flexi Messages". These are variable length messages, where the payload made up of a number of data records
    • DMT Data Fields: within the data records, there are a number of fields. The data within the fields is explained by this document. Fields are of variable length, and their type and length is described by a field header (Field ID + Field Length).
    • DMT Log Reasons: The data records contain a log reason in the header. This document describes the various log reasons.
  • JSON HTTP integration: this is 1 document:
    • DMT JSON Device Integration: this describes how data is converted into JSON, and submitted to an endpoint with an HTTP POST.



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.


Some 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 us 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 are:

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