Choosing an Integration Strategy

This article discusses the various integration strategies for Digital Matter cellular products. There are multiple ways to receive device data from our device in a 3rd party platform. 

TABLE OF CONTENTS

List of integration options

1. Use Telematics Guru and webhooks
Digital Matter will set up the Telematics Guru partner account for you and send you an invite link along with user guides
2. Use OEM Server with raw TCP payload
Just Create a Connector via the OEM UI 
3. Use OEM Server with JSON HTTP payload
Just Create a Connector via the OEM UI 
4. Direct to 3rd Party Server
The device communicates directly with the 3rd party server. This is initially configured via OEM Server when provisioning, and from then on the device communicates with the 3rd party server. For details see Setting up Direct to 3rd Party Server messaging on devices

In all options aside from 4, data flows from the Device -> OEM Server -> 3rd party platform.
In the direct mode, data is transmitted directly from the Device -> 3rd party platform.


Definitions

OEM Server
For an overview of the OEM Server and its features, see OEM Server - Getting Started
OEM Server is our 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. In all of the integration options aside from  OEM has a web user interface at www.oemserver.com.
Connector
The connector determines 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. Contact our support team for integration 
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.

Connector Set Up

Partners can create connectors as shown here - Create a Connector - set up an integration. Then simply Set the Connector on a device to have this device's data directed to your endpoint. 


Multi-Connector (sending Data to multiple endpoints)

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 Documents

Contact our support team for integration documents containing the payload information and structure. There are various documents to cover each method. The right ones to look at for your method are covered below. 


OEM Server Functionality

OEM Server Features

Please be sure to check out OEM Server - Getting Started, for full details on OEM Server's feature set. 

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 Options - the details

1. Use Telematics Guru 2. Raw TCP Connector 3. HTTPS/JSON Connector 4. Direct Mode Multi-Connector

Use Telematics Guru and Webhooks

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 scenarios where using webhooks would be an ideal choice:

  • Integration into hiring/maintenance software. TG is used for tracking, geofencing, driver behaviour monitoring, alerting etc - but the Run Hours and Odometer readings are pushed from TG into the other system periodically (like at the end of each trip)
  • Email integration into a ticket management system - to action alerts. 

Given the device/asset will be active in Telematics Guru, this implies the TG asset fee will be charged, for use of TG. There is no additional fee for the webhook, and any number can be configured.

More information

For more details on webhooks see Alert Notifications through WebHooks


Security

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:

  • Our latest range of devices all connect to OEM via an encrypted connection. This includes the following devices:
    • Bolt, Dart2, Eagle, Falcon, G62, G120, Oyster2, Remora2, Yabby GPS, Yabby Wi-Fi
  • You can tell you device is using an encrypted connection in OEM via this padlock symbol:
  • Encryption is device to OEM. After OEM, other measures are required, such as SSL. So if you require full end to end encryption, currently the only option is to use OEM and a HTTPS connector. A Secure TCP connector is planned for development. 
  • Encryption is not available in the Direct 3rd party model for the data transmitted from device to the 3rd party system as standard (see below). Device to OEM for configuration will still be encrypted. 

Complex Security Requirements:

Typically if a high level of data security is required, the direct mode must be used. This ensures that no device data is ever sent to the OEM Server (hosted on Azure Servers). However as standard, device data is sent in plaintext when using this mode. If you have a large deployment requiring encrypted payloads in the direct mode, speak to our support team.


OEM WebAPI - changing device config from a 3rd party server

The OEM WebAPI provides a few features which enable some control of device configuration 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:

  • Set device admin and system parameters.
  • Get a list of parameter templates, and set them
  • This allows parameters to be changed programmatically to pre-defined templates. There is no option to set individual parameters. 
  • 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 programmatically based upon other events happening. Examples include:

  • Setting connectors/parameter templates when provisioning a device in a 3rd party front-end platform. 
  • Changing parameters templates at certain times of the day (to adjust reporting rate)
  • Allowing parameters to be controlled from a front end UI


Did you find it helpful? Yes No

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