This article discusses the various integration strategies for *most* Digital Matter cellular products. There are multiple ways to receive device data from our device in a 3rd party platform.
Integration for Edge Devices
Our "Edge" devices make use of our Location Engine to resolve positions. The only available integration option for these devices is an HTTPS JSON integration. Contact support for details
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:
- 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.
- Health checks and reports with last communication dates and device voltages.
- Update firmware over the air
- Update device settings over the air, and create settings templates.
- Remotely debug using data capturing.
- Remotely debug by adjustable on device logging verbosity
- Debug end server interactions with the devices and possible issues
- Manage devices in groups
- Presentation of advanced device profiling statistics. eg GPS fix count, GPS on time, etc.
- Retrieve billing information
- Handles critical functionality for optimum device performance and battery life such as updating GNSS aiding data. Without this, performance degrades.
Integration Options - the details
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
OEM Server with the raw TCP connector
To Get Started
Create a Connector in OEM Server, then Set the Connector on your device(s) - to send data from these devices to your endpoint.
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
Integration documents
Contact our support team for documentation.
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, 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.
OEM Server with the JSON HTTP/HTTPS connector
To Get Started
Create a Connector in OEM Server, then Set the Connector on your device(s) - to send data from these devices to your endpoint.
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 device'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. The HTTP/JSON connector is considered less performant than the TCP connector.
Option 3 - OEM Server with HTTP 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.
Integration documents:
DM provides documentation and support resources for device integration. These are available under NDA, and sometimes subject to a support package fee.
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.
- Integration Guide: Provides some context to the data fields and tips on the integration process.
Direct to 3rd Party
The final integration option bypasses the OEM Server entirely and sends data direct from the device to a 3rd party server.
To Get Started
Follow the set-up instructions here: Setting up Direct to 3rd Party Server messaging on devices
Proceed with Caution!
OEM Server provides several key functions (like GNSS aiding data downloads to devices) which are critical to device performance. See Direct to 3rd Party Server integration - Considerations to make sure you are aware of the implications
- Device data: devices are configured to connect directly to the 3rd party system. The endpoint's location (IP/DNS and 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. Devices 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.
- What the above 2 points mean is that if we wish, we can log into OEM Server and queue up a parameter update using the UI like we usually do - the device will pick up the change on it's next periodic, or instructed check in. No need to implement downlinks to handle this, and we still pay no ongoing fees.
- 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 capability to perform firmware updates Over the Air outside of OEM Server - the device must reconnect to OEM to update firmware. If you have the device in hand, a Wired Provisioning Tool can be used to manually update devices.
There is no monthly OEM fee for this model.
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
Multi-Connectors
To Get Started
Set up a Multi Connector through the OEM UI - Create a Connector
The OEM Server Connectors allow device data to be 'switched' to different end points. The end points are usually front end servers that aggregate the device data. The connectors can send data in raw form over TCP (as the devices send it) or convert it to JSON and send it over HTTP.
For Example you can set up a Multi connector to Telematics Guru and a 3rd party platform, or two of your own servers.
This connector model also allows for the "multi-connector". This allows multiple connectors to be assigned to the device. The OEM Server will send data to each of the end points. This allows platforms to compliment each other. For example, Telematics Guru may provide the mapping and fleet management, but a partner may want to add some value in a unique way by consuming the data themselves.
Important points:
- The multi connector can specify 2 or more connectors.
- BOTH connectors must allow data to be successfully committed, otherwise the device upload will fail. The device will disconnect and retry. It will resend the same data until it gets a successful commit response. This implies that if one connector is broken, neither system will work.
- You can specify HTTP/JSON and TCP/Raw connectors in a multi-connector group.
- There is an additional charge per multi-connector. Contact your local sales channel to understand this.
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.
- 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.
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:
- OEM actions such as setting parameter templates and connectors
- 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