Developer Guide
This page outlines the implementation of the Fleet Management Integration of OpenRemote, and the full support of Teltonika Telematics devices.
OpenRemote's existing feature-set makes it a perfect fit for Fleet Management. Based on OpenRemote, a Fleet Management solution has been built that is fully customizable and can be tailored to the needs of the customer. The solution can be used to track vehicles, monitor driver behavior, and to provide a wide range of other services in conjunction with the fleet management elements of this implementation, which already exist in the OpenRemote platform.
In addition to those OpenRemote features, full support of all Teltonika Telematics devices has been implemented. This means that all Teltonika Telematics devices can be used with OpenRemote, and that 100% of the possible parameter data received from any device, given correct configuration, is available in OpenRemote.
To understand the flow of data from the device to OpenRemote, look at the following flowchart:
This flowchart outlines the data flow from the device to OpenRemote. When set up, the device receives data from the specified MQTT topic patterns, and sends data to the specified MQTT topic handlers. The MQTT broker is configured to forward all pertinent messages to the Teltonika MQTT handler. The Teltonika MQTT handler parses the messages and stores the data to the correct Asset with the correct attributes.
When a device connects to the MQTT broker, it must subscribe to the command and data topics, that match the topics specified by the user. The device will then send data to the data topic, and receive commands from the command topic.
When the device sends a payload to the MQTT broker, the MQTT broker will forward the message to the Teltonika MQTT handler. The handler will then use the IMEI included in the topic, to generate an asset ID. The IMEI is the unique ID that is used to create, manage, and identify the device. The handler will try to find an asset with the generated ID. If the asset does not exist, the handler will create a new asset with the generated ID.
To understand the setup procedure, please read the wiki page Tutorial: Create your own Fleet Management system. The choices made there are the minimum required for OpenRemote to be able to understand the payloads it is being sent.
If the devices you have do not support MQTT connection or for Codec JSON, you can use the Teltonika TCP server that converts the incoming TCP packets into MQTT payloads with the correctly-formatted Codec JSON format. You can define the MQTT connection settings and the TCP server settings. To be released as a Docker container, but can be ran as a bare-metal NodeJS program.
The data is sent from the device in a JSON format, consisting of key-value pairs, with the key being the AVL parameter ID (which is defined by Teltonika), and the value being the value of the parameter. The information of that parameter, such as the name, description, value range, and unit, can be found in Teltonika's wiki pages for each respective model.
To implement that parameter data into OpenRemote, we have created a new Python script, that reads the data from the wiki's AVL parameter data tables, parses it into a DataFrame, and then can be exported in to any type of data file.
For our use case, we use that Python script to generate the parameter data, and we then import that JSON file into OpenRemote, currently as a Teltonika Model Configuration Asset. The data is then used to create the attributes for the assets.
Using this method, any parameter that could be generated by a Teltonika device can be parsed with the correct label, description, units, data types, and value ranges. This means that the data can be used in any way the user sees fit. As the code for that parameter data generation is open source, we can use it in OpenRemote to generate the parameter data file, thus remaining 100% open-source. To ensure correct support and labeling of parameters, it is imperative for different model types to use the correct parameter data, as the parameter IDs, and metadata, can differ between models.
Using the key-value pair of the payload, and the list of parsed Teltonika Parameters for that device, OpenRemote will then match the parameter details to the value, and based on these details, create the correct attribute for the asset. We then do this for every single key-value pair in the payload.
The command topic is used to send commands to the device. The device will subscribe to the command topic, and when a
user updates the sendToDevice attribute, the handler will format the message, and send it to that command topic. The
device will then respond to the data topic, with a different format as a normal data payload. The handler initially
tries to parse the response as a normal data payload, fails, and then tries to parse it as a response to the sent
command. If the response is a valid response, the handler will update the response attribute of the asset, for the
user to see. In this way, we support full bidirectional communication with the device.
For the message to be sent properly to the device, it needs to be connected to the OpenRemote MQTT broker. For some cases, this means that it depends on the sleep mode that the device is in. Please check your device's sleeping mode tutorial for specific connectivity states during sleep mode.
The Teltonika TCP server has support for sending the commands via the TCP legacy server being planned for the near future.
The implementation of the Fleet Management solution finds its home in the TeltonikaMQTTHandler class. It extends on
the OpenRemote MQTTHandler class, and overrides some of its methods. When a message is routed to the Teltonika MQTT
handler, it will first land in onPublish, which is considered the first point of contact of the payload to the
manufacturer-specific handler. For more information on how an MQTT handler works,
please refer to this forum post, and the
MQTTHandler abstract class in the main OpenRemote repository.
A crucial piece of code, namely the method that converts the key-value pairs of Teltonika parameter data into actual Attributes,
and then matching those up with the correct Attribute values, can be found in org.openremote.model.teltonika.State. There,
the method iterates over every key-value, and if it finds the corresponding parameter ID, uses that data to generate the
attribute, and then inserts the parsed value. Using the Teltonika Parameter data, we parse the values into correct
value-types for the asset, to allow users to perform numerical, geographical, or any other operations, if they so desire.
A user may require to additionally be able to track various values, states, or in general any boolean condition, and if it is
true or false. To do so, a new Attribute type called AssetStateDuration has been created. It simply stores a start and
end date of such a state and can only be stored with both values set.
For the attribute to be the most useful, combine it with the MetaItem STORE_DATA_POINTS to store historical data
where the state of the tracker has been what you have defined it to be.
To illustrate the functionality, the Teltonika Telematics device integration automatically generates an AssetStateDuration
Attribute that tracks the state of Parameter ID 250, the Trip parameter (if the vehicle is in a trip, according to the user's
device configuration).
Currently, there is no way to set your own condition (called Predicate from here on out) without modifying the source code
, but you can use ValuePredicate in the TeltonikaMQTTHandler, by looking at the usage of function
org.openremote.manager.custom.TeltonikaMQTTHandler.assetChangedTripState. Adding support for UI-based ValuePredicate input
will be implemented sometime in the future.