An example of connecting a device using Teltonika protocol
Model configuration
Teltonika equipment can be used both to monitor the condition of a vehicle and to organize more complex projects (such as carsharing), as a device for collecting, transmitting data, recording events, or managing locks.
Consider an example of connecting to the system a vehicle equipped with a Teltonika device. To do this, create the appropriate model:
The basic model includes a number of grouped parameters, as well as commands combined into the corresponding subsystem. In most cases, pre-set parameters are sufficient to use Teltonika equipment. However, when using specific equipment, a predefined template can either contain redundant elements that can be simply removed from the model, or may not contain the necessary parameters and commands – they can easily be added to the model.
Creating a new parameter
The most optimal way to create a new parameter is to copy an existing one.
Before adding a new parameter, use the model search function to verify that it hasn’t been created before.
The fields of the created parameter will be filled in automatically. The “argument” is selected as the type. The “Identifier” field can be left unchanged if API is not supposed to be used.
For more information on the purpose of the fields, see the section Model of the control object.
If you need to use the platform API, it is recommended to change the identifier automatically generated by the platform to a more understandable one.
Change the parameter name, data type, and source.
The parameter name should be convenient for further viewing in the interface, and the type should correspond to the type of the parameter value (boolean for logical states True / False, the number for numbers, etc.).
The “Source” field indicates the address of the parameter in accordance with the exchange protocol and is formed according to the following principle: in_out_<parameter number in the protocol (Property ID in AVL packet)>. If you need to take only a specific bit from the parameter at the specified address, then specify the bit number through the dot: .<bit number>. For example, in_out_85.2 – is the third bit (counting from zero) in parameter 85.
Sources of GPS-parameters corresponding to the protocol capabilities are already presented in the model (navigation.latitude, navigation.speed, etc.)
GPS-parameters in protocol Teltonika:
Name | Size, byte | Description |
|---|---|---|
| Longitude | 4 | Longitude |
| Latitude | 4 | Latitude |
| Altitude | 2 | Altitude |
| Angle | 2 | The angle in degrees from north clockwise |
| Satellites | 1 | Number of visible satellites |
| Speed | 2 | Speed in km / h (with a GPS error, the value 0x0000 is returned). |
You can also select a unit of measure and an icon with an image, where you can set levels by color (only for a number or a logical value). Levels can be indicated with arbitrary text, which will be displayed in the interface next to the parameter value.
If the new parameter was created on the basis of the existing one, it is recommended to pay attention to the “When parsing” tab, which is hidden by default. It can have a multiplier!
It is recommended to immediately spread the created parameters into semantic groups for the convenience of displaying in the interface.
To create a group of parameters (subsystem), select the value “Subsystem” in the field of the “Type” parameter.
For moving parameters between themselves or entering them into subsystems, drag-and-drop is supported with the mouse.
Creating a new command
The Teltonika protocol provides control of the controlled object using text commands. The mechanism for creating commands is similar to the mechanism for creating a parameter. You can create a new command using the menu item “add” or “copy”, accessible by clicking on the right mouse button.
It is recommended to create subsystems for commands united by semantic meaning – for example: “Information commands”, “Control commands”, “Carsharing”, etc. It is highly recommended not to create commands in the Parameters!
The list of available commands depends on the specific device and its configuration. For example, for equipment of the FMB series, a list of commands can be found on the manufacturer’s website.
After creating the command template, you need to fill in the fields “Identifier”, “Name” (will be displayed in the interface), “Description” (in any way); select “Text command” in the “Send” field and write the text of the command in the “Text” field.
If necessary, it is possible to view the representation of the command text in hexadecimal by clicking on the HEX tab.
Relay Control Commands
To control the internal relays of Teltonika devices, use the setdigout command with a specific key, entered with a space.
The key should reflect the status of all device relays, however, if the relay is not required to be controlled, its status is indicated by “?” (question mark).
So, the commands for managing a specific relay are constructed as follows:
1. The word setdigout + space
2. Relay states (the number of characters must correspond to the number of terminal relays. If a particular relay doesn’t have to change its state, then instead of the value “1” – on and “0” – off, you need to transmit a question mark “?”).
For example, to turn on the third relay (out of four possible), you need to send the command:
setdigout ??1?to turn off:
setdigout ??0?if there are only two relays, then the command to turn on the second relay will look like this:
setdigout ?1if you need to turn both relays:
setdigout 113. If necessary, indicate the duration of the relay circuit. Through spaces, the on-time for the desired relay is indicated (also positionally). For relays that should not change their state (“?”), You must set 0. Time must be transmitted for each relay.
For example, a command to turn on the fourth relay for 5 seconds will look like this:
setdigout ???1 0 0 0 5
Notes
Note 1
If the number of relays is not known, a getio command is provided, in response to which the connected device will return information about the available inputs and outputs. The number of parameters in_out_DO will be the number of relays in the connected device.
Creating an object
To communicate with the platform of a specific Teltonika device, it is necessary to create an object based on the corresponding model. To do this, go to the “Objects” menu and open the dialog for creating a new object. A model is selected from the drop-down list. In the identifier field, you must specify the IMEI of your device with the teltonika prefix (for example, teltonika: 123456789000001). This is necessary to identify the device when it is connected to the platform. Next, enter the name of the object, if necessary, fill in the remaining fields.
Once the model and object were created and the device itself was configured, it could be considered connected to the platform. Now we have to make sure that the data from the device is actually sent to the platform and displayed in its interface.
