What is Integration?

Device Manager is simply a management and configuration platform, your customers will not be able to use their devices to track shipments, prevent theft, or monitor usage without sharing device data into another system. As a result, Device Manager has been built to easily on-send data in a variety of formats, but with the exception of Telematics Guru, your organization will always be responsible for the connection and maintenance of any software downstream of the Device Manager Platform. Once you have read through your integration options below and made a choice, your next step may be to set up your integration in Device Manager by creating a Connector. Once created, you will then need to set your Connector against your devices for it to function.
 

List of Integration Options

There are several options for integrating, which are outlined below.

Message Format

Regardless of which strategy you choose, you will need to understand the data formats available:

• Raw TCP Connector: Device Manager forwards data in the device's native format - raw binary data over a TCP socket. The raw TCP protocol is described in documentation from Digital Matter. Contact our support team for these integration documents.
• JSON HTTPS Connector: Device Manager translates the raw data from the device into JSON and uses an HTTPS POST to deliver the records to an endpoint. This can be simpler to interpret but is less performant for large numbers of devices.

Integration Documents

Digital Matter provides documentation and support resources for device integration. These are available under NDA, and are sometimes subject to a support package fee. Contact our support team for integration documents containing the specifics of payload information and structure. 

For information about which specific documentation you will require, please review the recommendations under your chosen integration option below.

1. Telematics Guru and Webhooks

System Design

While nominally representing a full-featured IoT software platform in its own right, Telematics Guru (TG) offers some interesting integration options for 3rd party platforms. Your end users may choose TG for traditional telematics software features (mapping, geo fences, etc) but also need to push selected events into another system. For this, Telematics Guru can use webhooks to curate selected events onwards to another system.

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. 

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

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 functionality, and any number can be configured.

Setup in Device Manager

Your devices should already have a TG connector set by Digital Matter administrators. If this is not the case, please contact support.

Integration Documents Required:

None. For more details on webhooks see Alert Notifications through WebHooks.

2. Device Manager with TCP connector

System Design

In this model, devices first connect to Device Manager, which then takes charge of sending any device data onwards through a Connector.

• Device data - telemetry/sensor data is sent first to Device Manager, and then 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 device management and debugging features are available through the Device Manager web user interface.

Many large-scale integrations favour the raw TCP connector over the HTTPS connector for its widespread use throughout the industry.

Setup in Device Manager

Create a Connector in Device Manager, then Set the Connector on your device(s) - to send data from these devices to your endpoint.

Integration Documents Required:

For Raw TCP integration you will require these 4 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, which is the reason why the record was generated (i.e. movement, heading change, input change)
   
• Integration Guide: Provides some context to the data fields and tips on the integration process.

3. Device Manager with the JSON HTTP/HTTPS connector

System Design

In this model, devices first connect to Device Manager, which then takes charge of sending any device data onwards through a Connector.

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

Device Manager cannot be bypassed in this setup, as the JSON HTTPS conversion happens on Device Manager. The HTTP/JSON connector is considered marginally less performant than the TCP connector. 

 

Many users prefer this option over the TCP option, as messages do not need to be parsed out of the TCP stream of bytes - which can be a learning curve for developers not used to writing TCP listeners. In contrast, many developers will be used to working with JSON - so it can be faster to integrate devices using this method. 

To Get Started

Create a Connector in Device Manager, then Set the Connector on your device(s) - to send data from these devices to your endpoint.

Integration Documents Required:

For JSON HTTP integration you will require these 2 documents:

• DMT JSON Device Integration: this describes how data is converted into JSON, and submitted to an endpoint with an HTTP POST.
   
• Integration Guide: Provides some context to the data fields and tips on the integration process.

4. Direct Integration (Raw TCP Payload to 3rd Party Server)

System Design

The final integration option bypasses Device Manager entirely and sends data direct from the device to a 3rd party server. 

There is no monthly Device Manager fee for this model. 

There is very little difference between the data received directly from a device and from the Device Manager TCP connector. Mainly, integrations via Device Manager will filter out device debug messages and many device profiling counters, whereas a direct integration will not.

When doing a direct to 3rd party integration, integrators are encouraged to start doing so via the Device Manager and a raw TCP connector. This provides much more diagnostic information and the full Device Manager suite of tools for removing variables when troubleshooting. Once this is working, the devices can be instructed to send directly to the 3rd party. 

For managing firmware updates and parameter adjustments there are three main approaches: 

• Periodic Device Manager connection - Devices can be set up to periodically connect to Device Manager to check for configuration updates on a schedule. 🌟This is our recommended option when going direct.
  
  
  • No other data is sent to Device Manager
     
  • Devices can receive firmware and settings from Device Manager
     
  • Devices are editable in the Device Manager Web UI
     
  • The debugging and health check features of Device Manager are not available.
     
  • The Web API can be used to remotely set up parameters that each device should update without using the Device Manager front-end (see below).
     
• Check-in with Device Manager only on instruction - the devices will normally only connect to the 3rd party server. At the integrators discretion they can be instructed to connect to Device Manager with an async message (a downlink) to check in with Device Manager and take any queued updates. For example, this would be done when a settings update has been queued on Device Manager and the 3rd party server tells the device to go and fetch it.
   
• Bypass Device Manager altogether - parameters can be configured via downlink. This is tantamount to developing your own bespoke device management platform. This should only be attempted under exceptional circumstances (e.g. security concerns). Contact your Digital Matter representative to arrange a support package if this is your only option.
   

  Firmware-Over-The-Air (FOTA)

  There is no capability to perform firmware updates Over the Air outside of Device Manager - the device must reconnect to Device Manager to update firmware. If you have the device in hand, a Wired Provisioning Tool can be used to manually update devices. 

   

OEM WebAPI

The OEM WebAPI provides a few features that enable some control of device configuration from a 3rd party platform.

Device Manager 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 Device manager
• Change connectors
• Set enabled/disabled in Device Manager

Async messages

Async messages (downlinks) can be sent to the device. The OEM WebAPI can be used to queue the message on Device Manager 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

For more information and detailed documentation, please contact Digital Matter support.
 

Multi-Connector Integration

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

Security and Encryption

A number of devices connect to Device Manager over an encrypted connection. The encryption is a CCM Mode block cipher scheme, using AES256 keys. Keys are shared securely between the device and server.

Encryption is device to Device Manager. After Device Manager, other measures are required, such as SSL. So if you require full end-to-end encryption, currently the best option is to use Device Manager and a HTTPS connector. Speak to Digital Matter to discuss your security requirements.