Skip to content

Tutorial: Create your Fleet Management System

Jump to bottom
Panos Kalogeropoulos edited this page Nov 28, 2023 · 13 revisions

DRAFT TODO:

  • Would be cool if we could include a boilerplate configuration for all devices, and then people can load the config and then just upload their cert and host info.
  • Go through every single parameter changed to explain what it is and why it is selected as such.
  • Explain UI components TBD
  • Add more screenshots / sketches / illustrations
  • Eventually update for native ActiveMQ Artemis MQTT Broker SSL
  • Custom Asset Type creation for use with rules?

1. Introduction

Using Teltonika's GPS Trackers, OpenRemote offers full fleet tracking and management functionalities. Using the incredibly flexible backbone of the OpenRemote platform, the Fleet Management implementation offers state-of-the-art flexibility while closely integrating with Teltonika GPS trackers.

As a general idea behind this implementation, we wanted to give the flexibility of Teltonika Telematics devices, and their configuration, the attention they deserve. To explain, we attempted to have a configuration-centric implementation, that understands the data from the payload, and acts as a simple parser, analyzer, and display of the data retrieved. In a way, whilst OpenRemote still is a fully-featured all-in-one solution, that provides an intuitive user interface, and multiple ways to parse or act upon that data, we still give the user the maximum possible flexibility in their actions and configurations of the device, thus preventing vendor-locking. In fact, OpenRemote's seamless import/export functions are ideal for avoiding vendor-locking, and storing the payloads of the device themselves allows for maximum independence from a platform. Combine that with a powerful MQTT and HTTP REST API, open-source code for every part of the process, and the ease of addition of components to power more functionality, We allow the Teltonika devices to shine themselves, whilst allowing for full control of what is visible, and how the integration is used, allowing for users to use OpenRemote for all of their use-cases.

2. Requirements

  • A publically accessible OpenRemote installation with SSL enabled.
  • Any number of Teltonika GPS Devices, with:
    • The ability to use a TLS certificate;
    • The ability to transmit MQTT messages;
    • The ability to use the Codec JSON protocol.
  • The same amount of SIM cards capable of mobile data usage (and preferrably SMS messaging, to enable SMS communication).
  • Preferably, pre-assign each SIM card to a tracker, and each tracker to each vehicle, so that you know which vehicle contains which device IMEI with which phone number.

3. Setup and Installation

3.1. OpenRemote setup

Set up OpenRemote's Fleet Management Custom Project on a publically accessible hostname:

  • Use the custom-project OpenRemote deployment tutorial to deploy OpenRemote with SSL.

  • If SSL has been successfully been set up, then grab the full TLS certificate chain from the certificate.

To grab the certificate chain file, grab the file from the or-proxy-1 container, in the directory deployment/letsencrypt/live/{your domain-name}/fullchain.pem.

  • Ensure that the OpenRemote MQTT broker is accessible using TLS and ensure the Secure MQTT port is reachable.

3.2. Device Preparation and Connectivity

3.2.1 AVL Parameter Information data generator

This implementation for Teltonika device support is able to parse any parameter from any device model.

For OpenRemote to accomplish this, we require the generation of the AVL parameter data file. For it to be generated, use the Jupyter Notebook python file located in this GitHub repository. Once the file has been generated for the model type(s) of your device(s), insert those JSON files in the deployment/manager/fleet directory of OpenRemote. The data file for the FMC003 is included by default.

For more information, head to

3.2.2 Teltonika Device Configuration:

Download the most recent Teltonika Configurator that is recommended for your device.

  • In the GPRS tab:

    • Setup your own APN settings and ensure GPRS traffic is allowed.
    • Setup your Server Settings:
      • Set the Domain to your domain name;
      • Set the protocol to MQTT;
      • Set the TLS Encryption to TLS/DTLS.
    • In the new MQTT Settings category, insert:
      • MQTT Client Type: AWS IoT Custom
      • Leave Device ID empty;
      • The data topic should look like {realm Name}/{random client ID}/teltonika/%imei%/data
      • The commands topic should look like {realm Name}/{random client ID}/teltonika/%imei%/commands Teltonika GPRS Configuration page If the MQTT button is not visible, then it means that your device does not support the MQTT transfer protocol. Ensure that your device supports it, and if it does, and/or upgrade to the most recent firmware version available for your device.

  • In the Security tab:

    • If required, enter your PIN number for the sim card.
    • Upload the fullchain.pem file to the Certificates section.

  • In the System tab:

    • Select Codec JSON in the Data Protocol section

If the Codec JSON button is not visible, then it means that your device does not support the JSON data protocol. Ensure that your device supports it and/or upgrade to the most recent firmware version available for your device.

  • In the Trip / Odometer page:

    • Scenario Settings: High priority
    • Eventual settings: Disable

  • Modify any other parameters of the device needed

  • Save the configuration to the device and ensure that OpenRemote is receiving the data as required.

  • Install the device to your vehicle (Boat, plane, car, farming equipment, etc.)

3.2.3 Teltonika Legacy Device Support

In case your device does not support the MQTT data transfer protocol or the Codec JSON data protocol, we have made a TCP server that takes the TCP socket connection of a device that sends data with Codec 8 or Codec 8E and directly converts them into MQTT payloads with the same structure as Codec JSON. Ensure that the environment variables are correct and that the MQTT client connects and publishes messages to the correct locations.

4. Behind-The-Scenes and more information for the implementation

4.1. Asset Types

As the base of any fleet management system, there exists an Asset, the logical representation of an IoT device, that consists of multiple attributes. Attributes are values that describe the Asset. For example, a humidity sensor is an Asset, and the humidity measurement is one of its Attributes. It could also contain voltages of a battery that is being used or from any kind of power source.

To designate an element within a Fleet Management system, we created a new type of Asset called "CarAsset". That Asset contains special attributes for identifying specific attributes of a vehicle. Using the hierarchical model of Asset Types, we are able to create various groups and relationships between Asset Types. This is especially useful for identifying the different types of vehicles, trackers, or devices within a fleet management system.

You are allowed to implement your own Asset Types based on the CarAsset asset type to leverage the features related to fleet management.

4.2 Fleet Management Handlers

To provide a platform on top of which fleet management features are integrated, we also created an MQTT handler specifically for Teltonika Telematics devices. The purpose of this handler is that it handles all of the MQTT messages that are sent to OpenRemote by Teltonika devices. This handler is able to read the messages and create a CarAsset for each device with all of the parameters that were sent from the device in a human-readable format. The values are also read as the correct Attribute type, meaning that you can use them to perform various calculations, for example performing checks again other values of the same type.

4.3 Car Asset

The Car Asset is the basic fleet management asset type used. For added functionality, you can inherit the Car Asset Type and extend its attributes, optional or not.

4.4 Teltonika Device-specific AVL Parameter to JSON Converter

To automatically be able to parse the data supplied by the tracker for any type of Teltonika device, other than being able to communicate with the device and retrieve its data, we will also need to be able to decode the message's contents.

Teltonika transfers its data by providing a parameter ID and then that parameter's value. Each Teltonika GPS Tracker model may have different IDs for different devices, and different sets of parameters for different devices. For example, an advanced tracker with CAN connectivity will not have the same amount of available parameters as a device that does not interface with the car other than the car's battery. It could also have different parameters for

Hence, we have written a custom Python program that is able to retrieve the parameter data. By running that script for your model name, you are able to retrieve the official parameter data from Teltonika's website. By default, the parameter data for our test device, the FMC003, is included in the installation. You can add your own files for your respective device.

4.5 MQTT Handler

To be able to retrieve and use the data sent by each Teltonika device, a special Teltonika MQTT Handler has been implemented within OpenRemote. It is adjusted to understand the JSON payload sent by the device. It analyzes the data and inserts each parameter (attribute) sent, into the appropriate CarAsset.

4.6 Trip, and by extension State, Management

To maintain the character of agility and flexibility of the OpenRemote platform, while implementing the Trip functionality, we created a new Attribute Type. This Attribute Type, called Asset State Duration, simply stores two timestamps, the timestamp of when a state was engaged, and the timestamp of when a state was stopped. You can replace the word "state" with the word "trip" here. Using that Attribute Type, we can update a specific attribute (For example a Trips attribute) after a trip is over. The just-saved trip's start and end dates are then stored within the attribute's history.

To then retrieve the trips, because of the architecture described above, we can request the data-points of the Trips attribute for any time period. To then conduct further analysis on the Trips, we can iterate over every trip, using its start and end timestamps as the times to request further datapoints of other attributes.

For example, to get the maximum speed for every trip over the past 3 months, we would simply need to request the datapoints of the Trips attribute for the past 3 months, and then for each datapoint retrieved, request each datapoint between the two timestamps. By then iterating through those speeds, we can find the maximum speed of the previous 3 months.

This also allows for a more flexible analysis of any state; We could also repeat the same exact procedure for the overspeed parameter, for the geofencing parameter, and in general any parameter that represents a state, simply by changing the parameter ID and expected value that represents the state we would like to capture.

4.7 Using Fleet Management with Rules

One important use case is to receive alerts in case certain parameters of the tracker are found to be outside a range. Whether that is the coordinates of the device, the speed, or even the temperature of the carriage, Teltonika's flexible devices and OpenRemote's generic interfacing have got you covered.

To be able to use custom parameters for rules, we would need to extend the attributes available by inheriting the Car Asset. By including specific parameters that you would need, you would then be able to use those parameters for your rules, that apply for either every asset of your asset type, or a specific vehicle.

Example 1

As a rental company, it is important to be aware of the location of all vehicles at any point in time. By installing a Teltonika GPS tracker, management is able to not only track its location, but to understand the driving behavior of each driver, and depending on the behavior, act automatically, using rules.

Implementation

To ensure that all clients remain within a certain range, or within a certain province, country, or region, we can employ the when-then rules for the location attribute on all assets of type CarAsset, requiring them to be within the range of our choice. By creating that rule, the data of the geofence is sent to the device which saves the data in its configuration. Along with that rule, we can send a webhook, email, or push notification, to specific users, when it is triggered. With SECO-enabled trackers, we can securely cutoff the engine by stopping electricity flow to the fuel pump.

Thus, we are able to stop any client from leaving the specified areas, and then let the administration with push notifications, emails, custom webhooks, etc.

Example 2

For a refrigerated shipping company, it is important to be aware of any undesired fluctuations in the temperature of the refrigerated carriage. As such, the vehicles in their fleet are all equipped with the FMC650, and the trucks have been connected to the respective cooler units.

Solution

By implementing the CarAsset, we are able to add the required parameter IDs as attributes, for example Zone 1 Temperature. When configured in the rules, we can set the parameter to be set between -7 and -1 degrees. If the temperature is outside this threshold, management is notified, at which point the driver is able to be notified to diagnose the issue.

DISCLAIMER: OPENREMOTE SHALL UNDER NO CIRCUMSTANCE BE LIABLE FOR ANY DAMAGES ARISING OUT OF ILLEGALLY USING UNOFFICIAL, NOT VENDOR AGREED OR APPROVED, API'S

Source · Documentation · Forum · Issues · Docker Images · OpenRemote Inc.

Clone this wiki locally