Digital Matter devices work extremely well with Telematics Guru. TG is made by DM and customers are encouraged to use the platform for its rich functionality and good value. However, DM appreciates that customers may want to buy the hardware for use with other platforms. This is also possible. 


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.

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. 


Examples of integration from TG could be done with:

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


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.


3. OEM Server with the JSON HTTP 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.


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.


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.


Note: this functionality is being rolled out across the DM range. Traditionally, all devices connected via OEM. The devices that support this are: G100, Remora, Oyster, Dart2, G62, Yabby Cellular GPS, Yabby Cellular Wifi.


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.