Tutorial: Create your own Fleet Management System
- Contents
- 1. Introduction
- 2. Requirements
- 3. Setup and Installation
- 4. Usage
- 5. Behind-The-Scenes and more information for the implementation
- 6. Use Cases
Using Teltonika's GPS Trackers, OpenRemote offers full fleet tracking and management functionalities. Using the flexible backbone of the OpenRemote platform, the Fleet Management implementation offers 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 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.
In fact, OpenRemote's seamless import/export functions are ideal for avoiding vendor-locking, and, if configured, storing the payloads of the device themselves allows for maximum independence from the 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.
- A publically accessible Fleet Management OpenRemote Custom Project installation with SSL enabled.
- Any number of Teltonika Telematics devices
- 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, for ease of installation and recording. You can eventually take note of all of these within the OpenRemote Assets.
Important
The new Teltonika base firmware 03.29 adds MQTT support for many, previously unsupported, trackers. Make sure to check if your device can use the 03.29 firmware version! Using the MQTT connection to OpenRemote directly should always be preferred.
Set up OpenRemote's Fleet Management Custom Project on a publically accessible hostname. To do so, please look at the Quickstart page on the sidebar.
For the device to be able to connect to OpenRemote, it is required to connect to a secured MQTT port. It's not possible, due to the setup of the device, to connect to OpenRemote (or any broker) using unsecured MQTT.
- 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 fleet-management-proxy-1 container, in the directory
/deployment/letsencrypt/live/{OR_HOSTNAME}/fullchain.pem.
For the device to be able to use the file you just downloaded, you must do the following:
- Open the file. There should be 3 different certificates in the file.
- Move the first certificate to the bottom of the file, and the last certificate to the top of the file. This means that you are "reversing" the order of the file.
- Save the file, and use that file for the Teltonika device(s).
Here's an example:
The file you retrieved from the Docker container is listed here as such:
-----BEGIN CERTIFICATE-----
CERT 1
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
CERT 2
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
CERT 3
-----END CERTIFICATE-----
After your process, the file you received should be as such:
-----BEGIN CERTIFICATE-----
CERT 3
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
CERT 2
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
CERT 1
-----END CERTIFICATE-----
- There is a proof-of-concept version with support for "native" SSL capabilities, meaning that traffic is not routed through haproxy. Please come in contact for more information.
- Ensure that the OpenRemote MQTT broker is accessible using TLS and ensure the Secure MQTT port is reachable.
This implementation is able to parse any parameter from any Teltonika Telematics device model.
For OpenRemote to accomplish this, we require the generation of a specific JSON file(s). To read more about it, head to Teltonika AVL Parameter Parser. Once the file has been generated for the model type(s) of your device(s), insert those JSON files as a new Teltonika Model Configuration Asset under the "master" realm.
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, by using the Parser to create your own JSON files. With the JSON files, create a new Teltonika Model Configuration Asset, set the model number, and paste the parameter list.
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%/commandsIf 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. Otherwise, take a look at "Teltonika Legacy Device Server" for devices that may not support this at all.
-
In the Security tab:
- If required, enter your PIN number for the SIM card.
- Upload the
fullchain.pemfile to the Certificates section.
-
In the System tab:
- Select
Codec JSONin the Data Protocol section
- Select
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. Otherwise, take a look at "Teltonika Legacy Device Server" for devices that may not support this at all.
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. Otherwise, take a look at "Teltonika Legacy Device Server" for devices that may not support this at all.
-
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 designed.
-
Install the device to your vehicle (Boat, plane, car, farming equipment, etc.)
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 topics.
With the device(s) properly configured, if you navigate to the Assets tab, you will be able to see a list of Teltonika devices. By clicking on them, you can see the list of parameters sent by the device, with the labels provided by Teltonika.
If you navigate to the map, you can see the vehicle assets plotted on the last location that the devices sent as a pin with a car icon. If you click on any one of them, you can see the list of attributes of the Asset. Along with the attribute card, a new set of pins and lines will appear on the map, illustrating the location history of the vehicle from midnight of today to the current time.
The map will automatically update the location of the assets in real-time.
To send a command to the device, use the created "Send To Device" attribute. Type the command in the same way you would an SMS command to the Teltonika device, and press the send button. The "Response" attribute should then populate with the response of the device.
Use the Rules Engine to be notified of various events for your device(s) by selecting an asset (type), an attribute, and apply any restrictions you would like. In the right hand side, select the action you would like to perform when that rule is fired.
As the list of parameters that could be used in the rules engine is very long, if you want to perform an action for the entire CarAsset Type, you will need to edit the Asset type to insert predefined Attributes. The only requirement to add these attributes is to use the AVL parameter ID as the name of the attribute. The label and everything else will auto-populate.
This insights widget uses the Asset State Duration attribute to show trip data, or session data, for a specified device's Asset State Duration Attribute. It can analyze the data points between those two timestamps. Its recommended usage is around the Trip attribute and analyzing a location attribute, since it is when it is the most useful for an out-of-the-box experience.
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 should implement your own Asset Types based on the CarAsset asset type to leverage the features related to fleet management. 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.
To provide a platform on top of which fleet management features are integrated, we 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 against other values of the same type.
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. Some people also prefer the term "session". 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.
This functionality has been roadmapped to be user-definable. Currently, a very easy modification of the source code would allow for more AssetStateDuration attributes to be created, as it may take any ValuePredicate as input. Please stay tuned for user-defined Asset State Duration attributes.
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.
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.
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.
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.
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.
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; provide more information for why we're doing what we are doing during device configuration.
- 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?
DISCLAIMER: OPENREMOTE SHALL UNDER NO CIRCUMSTANCE BE LIABLE FOR ANY DAMAGES ARISING OUT OF ILLEGALLY USING UNOFFICIAL, NOT VENDOR AGREED OR APPROVED, API'S