1. Overview
2. V-Raptor Driver Setup and Deployment
   1. Supported Drivers on V-Raptor
3. Teltonika Driver - Functionality Overview
   1. Driver Information
   2. Driver Name
4. Teltonika Configurator
   1. Configurator Startup
   2. Configurator Options
5. Teltonika TLS Encryption Setup
   1. Update TLS Version Firmware
   2. Enable Device TLS Encryption
   3. Upload Root Certificate
6. Teltonika Device Setup
   1. Status Information
   2. System
   3. GPRS
   4. Data Acquisition
7. V-Raptor TLS Setup - Setting Encryption Mode
8. V-Raptor Property Configuration
   1. Scaling Voltage and Temperature
      1. Add New Config Map Value
      2. Add Scaling Options to Properties
   2. Hex Conversion
   3. Conditional Byte Filter
      1. Example
9. Seeing the data in Commander
   1. Commander Device Registration - Gateways
   2. Commander Dashboard

Overview

The following document describes how to configure and set up an integration with the V-Raptor™ Teltonika driver. It also shows how to configure a device with the Teltonika Configurator, how to configure V-Raptor Teltonika driver properties, and how data sent from the Teltonika device will be represented on both the Commander™ Portal and Dashboard.

The V-Raptor Teltonika driver currently supports both Codec 8 and Codec 8 Extended data protocols. It also supports bi-directional communication through Codec 12 over GPRS. The Teltonika device’s IMEI number is used as the DeviceId (Device Name) on Commander’s Platform. V-Raptor’s ingress needs to be configured to allow incoming connections from devices to be accepted by the driver. Follow this link for the Teltonika Codec introduction page.

By the end of this guide the user will be able to:

• Deploy a V-Raptor Teltonika driver.
• Set up and configure a Teltonika device.
• Configure properties in the V-Raptor Teltonika driver.
• Receive incoming data from the device on Commander’s Portal and display this data in the Dashboard.

V-Raptor Driver Setup and Deployment

The following sections will show how to deploy the driver in the V-Raptor UI. It includes:

• Selecting the driver from supported driver collections.
• Configuring the selected driver’s information.
• Checking the deployment’s progress.

Supported Drivers on V-Raptor

To deploy a new driver on the V-Raptor interface, navigate to the “Deploy new driver” page in the V-Raptor UI. This page will show a list of supported drivers. The Teltonika driver should be available in this list.

Figure 1 - V-Raptor™ Driver Deployment Options

For more information about how to deploy a driver, please see V-Raptor’s Deployment Manager documentation.

Teltonika Driver - Functionality Overview

The V-Raptor is configured to integrate with Teltonika devices, providing language agnostic access to these devices’ functionality that supports IoT.nxt applications. The process flow of this integration can be seen in the figure shown below.

Figure 2 - Teltonika and V-Raptor™ Integration

Driver Information

Select the Teltonika driver card (click on the card). An information window will open on the right of the screen which shows more information about the selected driver.

Figure 3 - V-Raptor™ Driver Info

Driver Name

In the information window, navigate to the “Device name” input field. Add the name of the driver in the input box. The driver’s name must be entered in lower case and only a dash (–) is allowed if multiple words are used to create the name. Once the driver name has been entered, click on the “DEPLOY” button to deploy the driver. The deployment screen will display the progress of the deployment and will indicate whether the deployment succeeded or failed.

Figure 4 - V-Raptor™ Driver Name

Once the driver has been deployed, the user can configure the driver’s properties. See V-Raptor Property Configuration for more.

Teltonika Configurator

The Teltonika Configurator allows the user to:

• Set up and configure a device.
• Set up and enable TLS Encryption.
• Configure device status information.

The sections below will discuss this in more detail.

Configurator Startup

The Teltonika Configurator is a Windows application that allows you set up and configure a device. When you launch the Teltonika Configurator, all connected devices will be shown on the main screen. When you select the a device, it will take you into the Configurator’s options.

Figure 5 - Device Selection

Configurator Options

Once the relevant device has been selected, the options and settings screen will open. The top menu options include the following:

• Load From Device: Load settings currently stored on the device to the Configurator.
• Save To Device: Load settings currently stored in the Configurator to the device.
• Load From File: Load settings currently stored in a file onto the Configurator.
• Save To File: Save settings currently stored in the Configurator to a file.
• Reset: Reset the device and load defaults.
• Reboot: Reboot the device.
• Device Details Show the device IMEI number, current firmware version and configuration version.

Figure 6 - Configurator Top Menu

Teltonika TLS Encryption Setup

The following section shows how to set up Teltonika’s TLS Encryption, including:

• Updating TLS firmware.
• Enabling the device’s TLS Encryption.
• Uploading the root certificate.

Update TLS Version Firmware

To enable TLS encryption, new firmware needs to loaded onto the device (FMB.Ver.03.27.01.Rev.03_TLS.e.xim).

Contact a sales provider at Teltonika if the correct version is not available. They will provide the correct link to update the firmware.

Figure 7 - Firmware Upgrade

Enable Device TLS Encryption

After loading the new firmware, the Encryption Option will be available under the GPRS/Server Settings section.

Figure 8 - TLS Encryption

Upload Root Certificate

Certificates are required to authenticate drivers with the V-Raptor’s services and can be generated from V-Raptor’s Credential Manager. These certificates can be revoked or renewed as required.

To generate new certificates, navigate to “Credential Manager” in the V-Raptor UI and click on “GENERATE CERTIFICATE”:

Figure 9 - Generate Certificate

Provide a unique subject name and click on “GENERATE CERTIFICATE”:

Figure 10 - Unique Subject Name

V-Raptor will then generate a public and private key with a digital signature. All information will be visually displayed once the certificate has been generated.

Information on how to generate certificates can be found in the Credential Manager Application section.

After generating the root certificate, it can be uploaded to the device under the Security/Certificates section in the Teltonika Configurator:

Figure 11 - Uploading Certificates

For more information, tutorials and/or configuration assistance, please see video uploads on the Teltonika Telematics YouTube channel.

Teltonika Device Setup

The sections below provide a brief overview of the information available on the Teltonika Configurator landing page for the following:

• Status (Status Information)
• System
• GPRS
• Data Acquisition

Status Information

The Status Information (Status) component on the Teltonika Configurator page displays GNSS Info, GSM Info, I/O Info and Maintenance.

GNSS Info

The GNSS (Global Navigation Satellite System) Info tab displays satellite and position information.

Figure 12 - Status - GNSS Info

GSM Info

The GSM Info tab displays the GSM (Global System for Mobile communication) information, records and GPRS (General Packet Radio Services) traffic. Information in the “Sockets” section will be displayed once the device is sending data to the V-Raptor.

Figure 13 - Status - GSM Info

I/O Info

The I/O Info tab will show live (input/output) information about the current properties on the device.

Figure 14 - Status - GNSS Info

System

The System section displays information about five features, namely System Settings, Sleep Mode, Accelerometer Delay Settings, Time Synchronization and Tracking Mode. The two relevant information blocks are System Settings and Time Synchronization.

It is recommended to enable the Time Synchronization NTP Server when the device is used indoors. This is to ensure that the device can set the date and time on startup using an NTP Server if it cannot obtain the information from satellites.

Figure 15 - System Settings

GPRS

The GPRS section allows the user to set Server Settings. This is where the V-Raptor address and port settings need to be added. The protocol type can also be selected. The V-Raptor uses a TCP connection to the Teltonika gateway.

Figure 16 - GPRS Settings

Data Acquisition

The Data Acquisition section allows the user to set reporting intervals for both when the Teltonika device is moving (“Moving”) or standing still (“On stop”).

• Min Period is the minimum period within which the device will store a packet. It is shown in seconds.
• Send Period indicates the number of packets to be accumulated before sending the data. The configuration below shows a device that will send a telemetry packet every 5 minutes (300 seconds).

Figure 17 - Data Acquisition

V-Raptor TLS Setup - Setting Encryption Mode

After driver deployment, enable encryption mode by setting the “Encryption” property in the Codec_12 section of the DevicesOptions.json file to “Tls”:

"Codec_12": {
    "Enabled": true,
    "DeviceType": "Teltonika",
    "Encryption": "Tls",
    "CertificatePath": "/etc/ssl/certs/public.rsa.pfx",
    "CertificateSubjectName": "",
    "CertificatePassword": "",
    "Debug": true,
    "PortNo": "12000",
    "PropertiesDeviceName": "DefaultProperties",
    "DroppedClientDetection": "ReadTimeout,DisconnectOtherConnections",
    "DroppedClientTimeoutSecs": 120,
    "LogAvlValues": false
}

V-Raptor Property Configuration

The following sections will provide examples of how properties can be configured in the driver. This includes examples of how to:

• Scale telemetry data values sent from the driver such as voltage and temperature.
• Use a Hex Conversion feature to convert data sent in integer format to Hex format.
• Use a Conditional Byte Filter to extract specific bits and bytes to get information about (for example) security flags.

Scaling Voltage and Temperature

Scaling is used when the device sends a raw value that is not commonly used (and cannot be read by Commander). For example, if the external voltage property is sent as millivolts, scaling options can be used to multiply the value by 0.001 to convert the property to volts before the telemetry data is sent to Commander. The following sections will provide examples of how this can be done in the driver.

To use scaling in the driver, a new TransformOptions.json configuration file needs to be added to the driver.

The first example below will show how to scale voltage and temperature values. Steps include:

• Adding new configurations to map values in the TransformOptions.json file.
• Adding scaling options to the driver’s Properties.

Add New Config Map Value

In the new TransformOptions.json file, add the below configuration:

{
  "TransformSets": {
    "scale_dallas_temp": [
        {
          "FunctionType": "MultiplyScaling",
          "ScalingFactor": "0.1"
        }
    ],
    "scale_external_voltage": [
        {
          "FunctionType": "MultiplyScaling",
          "ScalingFactor": "0.001"
        }
    ]
  }
}

In the code block below, scale_dallas_temp and scale_external_voltage have been added as configuration options to scale temperature and voltage by a factor of 0.1 and 0.001 respectively:

1. scale_dallas_temp - the FunctionType will be MultiplyScaling (to multiply the value), and the ScalingFactor will be 0.1 (multiply the value by a factor of 0.1).
2. scale_external_voltage - the FunctionType will be MultiplyScaling (to multiply the value), and the ScalingFactor will be 0.001 (multiply the value by a factor of 0.001).

Add Scaling Options to Properties

The scaling options created in the section above can now be added to the property that needs to be scaled in the DevicesOptions.json file.

{
   "External_Voltage": {
      "ElementId": "66",
      "name": "External_Voltage",
      "DataType": "Double",
      "TransformSetId" : "scale_external_voltage"
   },
   "Dallas_Temperature_1": {
      "ElementId": "72",
      "name": "Dallas_Temperature_1",
      "DataType": "Double",
      "TransformSetId" : "scale_dallas_temp"
   },
}

1. For the External_Voltage property in DevicesOptions.json, the TransformSetId can be set to scale_external_voltage. This will use the scaling options created in the TransformOptions.json file and scale the value of the external voltage.
2. For the Dallas_Temperature_1 property in DevicesOptions.json, the TransformSetId can be set to scale_dallas_temp. This will use the scaling options created in the TransformOptions.json file and scale the value of the temperature.

Hex Conversion

Teltonika devices send through data in integer format. The Hex Conversion feature converts integer values to a Hex string value so that users can see the values in either Big Endian or Little Endian format. This feature also allows the user to use the Conditional Byte Filter (shown below).

To add the Hex Conversion feature to the driver, add the following properties to the PropertyMaps property in DefaultProperties:

• ConvertToHex - this has to be set to true. If set to true, the data received will receive a payload as an array of bytes and convert it into a string. This will make it possible for the data to be represented in either Big Endian or Little Endian format.
• RawDataType - this is how the data is received from the device. This is generally Uint64.
• IsLittleEndian - this could be set to true or false, depending on whether the user wants the data to be in Little Endian or Big Endian format. If set to false, the data will be presented in Big Endian format.

For example:

"DefaultProperties": {
    "PropertyMaps": {
        "iButton_ID": {
            "ElementId": "78",
            "name": "iButton_ID",
            "DataType": "String",
            "ConvertToHex": true,
            "RawDataType": "Uint64",
            "IsLittleEndian": true
        }
    }
}

The example code block above uses the iButton as an example, but the Hex Conversion feature can be used for any string values or data types.

The DataType property needs to be set to “String”, as values sent to Commander will always need to be in string format (and Hex format is a string).

For ConvertToHex to be true, IsLittleEndian has to be defined. The default setting for IsLittleEndian is false (data will normally be presented in Big Endian format). To specify that the data needs to be presented in Little Endian format, set IsLittleEndian to true.

Conditional Byte Filter

The Conditional Byte Filter allows a user to select a specified byte in a byte array, specify a byte mask for that byte and then compare the resulting value with an expected value. This is useful when a user wants to extract information about a specific byte to acquire the status of a certain object.

For example, if the user wants to find out the status of a certain Security State Flag for a door, the Conditional Byte Filter can be used to find out whether DoorOpen is true or false. In order to find the correct byte in the Hex string to get this information, the user needs to:

• Set the property ConvertToHex to true.
• Indicate the raw data type that needs to be used in the conversion in the RawDataType property.
• Specify whether the data format of the property is Little Endian or Big Endian, to ensure that the correct byte is inspected and extracted by the filter.

In order to execute the Conditional Byte Filter, ConvertToHex (see the section above) and the DataType both need to be set. For ConditionalByteFilter to be set to true, ConvertToHex also needs to be set to true.

"DefaultProperties": {
  "DeviceType": "DefaultProperties",
  "GroupName": "Teltonika",
  "PropertyMaps": {
    "SecurityStateFlags": {
      "ElementId": "78",
      "name": "SecurityStateFlags",
      "DataType": "String",
      "IsLittleEndian": true,
      "ConvertToHex": true,
      "RawDataType": "Uint64",
      "ConditionalByteFilter": true,
      "ConditionalByteProperties": {
        "ReverseOn": {
          "DataType": "Bool",
          "Mask": "0x80",
          "ExpectedValue":128,
          "ByteOfInterest": 4
        },
        "DoorOpen": {
          "DataType": "Bool",
          "Mask": "0x28",
          "ExpectedValue":32,
          "ByteOfInterest": 7
        }
      }
    }
  }
}

The following properties in the code example above are added in order to execute the Conditional Byte Filter feature:

The ConditionalByteProperties object includes the following fields (in the table below). These fields take the converted string from ConvertToHex to get specific bytes from that string:

Example

Assume the StateSecurityFlags property in the code block above is the Hex value 01AB7E6C1B00005F. The ReverseOn calculation will send the value “false” to Commander, and the DoorOpen calculation will send the value “false” to Commander. The calculations that provide the “false” values are explained below:

To calculate the final values (true/false) for ReverseOn and DoorOpen, the following steps take place:

1. Select the byte of interest (position).
2. Convert the byte into bits.
3. Convert the specified Mask to bits.
4. Compare the byte and Mask (compare the converted bit values).
5. The result of the masking (the comparison in the previous step) can then be compared to the ExpectedValue. If the result is the same as the Expected Value, the final value sent to Commander will be “true”. If the result is not the same as the Expected Value, the final value sent to Commander will be “false”.

“ReverseOn” Calculation:

For the ReverseOn property the following calculation will be done:

Byte array: 5F 00 00 1B 6C 7E AB 01

1. Select the byte of interest:
   • Byte (ByteOfInterest) 4: 0x6C
2. Convert byte into bits:
   • 0x6C as bits: 0110 1100
3. Convert specified Mask to bits:
   • Mask 0x80 as bits = 1000 0000
4. Compare the bit values of step 2 and 3:
   • 0110 1100
   • 1000 0000
   • Result = 0000 0000
   • 0000 0000 as decimal = 0
5. Compare result of step 4 with ExpectedValue:
   • Masking = 0
   • Expected Value = 128
   • Final ReverseOn property value to Commander = “false” (the Masking Value and Expected Value are not the same).

“DoorOpen” Calculation:

For the DoorOpen property the following calculation would be done:

Byte array: 5F 00 00 1B 6C 7E AB 01

1. Select the byte of interest:
   • Byte (ByteOfInterest) 7: 0xAB
2. Convert byte into bits:
   • 0xAB as bits: 1010 1011
3. Convert specified Mask to bits:
   • Mask 0x28 as bits = 0010 1000
4. Compare the bit values of step 2 and 3:
   • 1010 1011
   • 0010 1000
   • Result = 0010 1000
   • 0000 0000 as decimal = 40
5. Compare result of step 4 with ExpectedValue:
   • Masking = 40
   • Expected Value = 32
   • Final DoorOpen property value to Commander = “false” (the Masking Value and Expected Value are not the same).

Seeing the data in Commander

To see the data in Commander:

• Ensure device registration by using the Gateway ID (in “Gateways”).
• Configure the Dashboard to display the data for further viewing and analysis.

Commander Device Registration - Gateways

Go to “Gateways” in Commander’s Portal and use the device’s Gateway ID to see whether the device’s data, being sent via the V-Raptor, is being received correctly by Commander.

Figure 18 - Commander™ Portal page.

When viewing the device in “Gateways”, all the registered properties will be displayed.

Figure 19 - Viewing a device's properties.

Commander Dashboard

The Dashboard can now be configured to display the data being received by Commander. The data can be represented in a user-friendly way by linking properties to widgets.

Figure 20 - Commander™ Dashboard