Users can have access rights to various items: units, groups of units, resources and accounts, routes, and other users. Depending on the available rights, the user can view and take some actions on a particular item.

Most often, full access to the unit (all rights) have only those users who configure it, while other users have limited rights sufficient to work with the unit. To avoid the incorrect changes of settings, it is important to assign to users only those rights that they really need.

Observed issue and the method of solving it

In everyday work, the rights to the unit are defined appropriately and do not change. However, there may be difficulties when changing rights, or sometimes rights can change without your participation, and the resulting settings may differ from what you expect. In this article, we'll consider standard issues of this kind. Choose one of the options below according to the situation you are experiencing.

1. After reducing the rights, the user still has more rights

A unit can belong to the group, towards which the user also has rights. In this case, the user will possess a wider list of rights of the two possible.

To correct the situation, try excluding the unit from the group or removing user rights to the group that the unit belongs to. After making these changes, set the desired rights towards the unit again.

2. When removing all rights to a unit, an error is displayed and the changes are not applied

Most likely, this user is the creator of the unit. At the moment, it is impossible to remove from the creator all the rights to the item created by him or her. If you try to do this, an error will be displayed with the text "You cannot withdraw access rights from the creator of an object".

To correct the situation, you need to change the creator of this unit. To do this, you can transfer the unit to another account. The unit must be in the account of a user who directly uses this unit.

We’ve created a video on how to use the Switch account tool from the management interface (CMS):

3. When extending the rights, changes are not saved

Wialon uses the following hierarchy principle: it is impossible to give a user more rights to a certain item than the creator of this user has to the same item. If you extend the list of rights, but the changes are not saved, it may mean that the user's creator doesn't have enough rights to the unit.

To correct the situation, assign a wider list of rights towards the unit to users who are higher in the hierarchy. After that — to the user, who needed to extend the rights (that is, go through the entire branch of the account hierarchy from top to bottom).

4. Rights change even though you don't make changes

To change access rights to a unit, the user must have the Manage access to this object right towards that unit. Multiple users can have access to a unit simultaneously. Accordingly, several users can make changes. You can track changes using the Log, which you can view on the Messages tab or in a report using the same-name table.

To correct the situation, analyze the Log and disable the ability to change access rights for those users who should not do this.

5. Rights change even though no user is making changes

Most often, such changes may occur in a certain equal period or under certain conditions. In this case, the reason is the work of Jobs with the Change access to units type or Notifications with the action method Change access to units or Add or remove units from groups.

To correct the situation, check that jobs and notifications are configured correctly (if necessary, you can delete or stop them).

6. Rights change even though users, jobs and notifications don't do this

Wialon has the ability to change item settings (including changing rights) via API requests. Such requests are still executed on behalf of a specific user, at the same time, logging in and out of the system using an API request to some third-party application is logged. This information can be tracked in the user properties on the Log tab or in the management interface (CMS) on the Users tab in the Last visit column.

To correct the situation, analyze the operating logic of the third-party application. If the application uses a user token created specifically for working with a third-party application, then this user can change the list of rights and disable the Manage access to this object right, or change the flags of his or her token. If the application uses the token of the same user that is used to enter the monitoring interface, it is necessary to revise the application logic, getting rid of changing user rights towards units.

Ekaterina Grib,Customer Service Engineer 2022-05-16

For the efficient operation of the entire service, it is important to adhere to the correct hierarchy. Hierarchy in Wialon is a connecting thread on which functions, rights, and objects of Wialon are strung like beads.

The importance of the hierarchy manifests itself at the time of maturity of the service when its structure has already formed. At the initial stage of working with Wialon, there may be no problems, but later it turns out that the created structure is not optimal. This leads to issues with managing access rights, shared resources, and restrictions on the operation of such services as Google maps and SMS, for example. In such cases, it is worth correcting the structure and transferring the system objects to a new place in the hierarchy.

This article proposes tools for correcting the hierarchy by transferring system objects to help make operating the service more convenient and secure. Depending on the type of transferred objects, both automatic and manual transfer tools are available.

Automatic transfer

The automatic transfer means a full-fledged transfer that preserves all the properties and relationships of the transferred objects. Still, it is only available for two types of objects — accounts and units. Below, we will consider the instructions for transferring these objects within the same service.

Accounts

During the automatic transfer, accounts are transferred entirely, preserving all content, all relationships, user passwords, session IDs, etc. This transfer is carried out using internal Wialon tools and is not available in the user interface. To transfer accounts automatically, send a request to support@gurtam.com. Automatic account transfer is available only for Wialon Hosting.

In case when you need to transfer only part of the account objects, you must use manual transfer. We provided instructions for such cases below.

Units and messages

To transfer units, you should use the Transfer units from one account to another tool in the CMS Manager interface.

The following video will provide you with detailed instructions on transferring units from one account to another and possible questions related to this case.

Manual transfer

The manual transfer involves re-creating the necessary objects in a new location and setting them up afterward. Some of the settings can be transferred using the import and export tool. Additionally, in this case, you will have to re-set user rights and relationships between micro-objects (for example, geofences in report templates and notifications), as well as user passwords.

Below, we will consider instructions for transferring individual system objects within a single service.

Accounts

An account is a fundamental service object which consists of a resource, a user, and a billing plan. Therefore, the transfer of an account is a complex process that includes:

• transferring the user-creator;
  
• creating a new account;
  
• assigning the desired billing plan;
  
• transferring the content of the resource;
  
• transferring the other objects belonging to the original account: users, units, groups of units, and retranslators.
  

To transfer an account, log in to the CMS Manager interface and follow the instructions:

1. Export the settings of the user-creator of the account to a WLP file (Export to file → Complete copy).
2. Change the names of the account and its user-creator. For example, you can add _old to the end of the name.
3. Create a copy of the user-creator of the account. Hold down the Ctrl key and click on the required user in the list. When copying a user, their properties that are not exported (such as access rights and email addresses) will be transferred. While copying, follow the next steps:
   
   • Enter and confirm the user's password. It is important to note that user passwords are not transferred. If the service owner has saved the current passwords, the users can set the same passwords after the transfer. In the other case, the users will have to set new passwords.
   • In the Creator field, select the user-creator of an account, under which you plan to place the new account.
     
     
4. Import user settings from the WLP file.
5. Create a new account. When creating, select the Existent user option and select the user created in step 3.
6. If necessary, transfer the remaining objects of the account according to the instructions below.
7. After making sure that all the account settings and contents have been transferred correctly, delete the old account marked _old in the name.

Resources content

A resource is a storage for the following objects:

• geofences and groups of geofences;
• jobs and notifications;
• report templates;
• drivers, trailers, passengers, as well as groups of drivers, trailers, and passengers;
• orders.

All the resource content objects are available for the transfer except for orders. You can transfer both the entire content and individual objects. To transfer, follow the next steps:

1. Export the content of the transferred resource to a WLP file, selecting the objects you want to transfer.
   
2. Import the content of the existing resource into a new one.

Orders can be exported and imported directly in the Logistics application.

Users

1. Export the settings of the original user to a WLP file (Export to file → Complete copy).

2. Rename this user, for example, by adding _old to the end of the name.
   
3. Create a copy of the user. In CMS Manager, hold down the Ctrl key and click on the required user in the list. When copying a user, their properties that are not exported (such as access rights and email addresses) will be transferred. While copying:
   
   • Enter and confirm the user's password. It is important to note that user passwords are not transferred. If the service owner has saved the current passwords, the users can set the same passwords after the transfer. In the other case, the users will have to set new passwords.
     
   • In the Creator field, select the user-creator of a parent account of a new user.
     
     
4. Import user settings from the WLP file.
   
5. After making sure that all the account settings and contents have been transferred correctly, delete the old user marked _old in the name.
   

Unit groups

1. Create a copy of the unit group. In CMS Manager, hold down the Ctrl key and click on the desired unit group in the list.
   
2. When copying the group, select the user-creator of the account you want to transfer to in the Creator field.

Retranslators

It is currently impossible to export the retranslator settings. To transfer a retranslator, you need to recreate it in the required account and manually copy the settings of the original retranslator into it.

Retranslators cannot be created on behalf of another user. Therefore, to create a retranslator in a particular account, you must be logged in as the user-creator of that account.

Routes

It is currently impossible to export the route settings. To transfer a route, you need to recreate it along with the schedule in the required account and manually transfer the settings of the original route into it.

Kristina Malakhovskaya,Customer Service Engineer 2023-02-28

Often there is a need to change the hierarchy of the Wialon service for more efficient management. We covered the transfer of objects within the same service in another article, but sometimes there is a need to transfer them to another service.

This article proposes tools for transferring objects between services. Depending on the type of transferred objects, both automatic and manual transfer tools are available.

Automatic transfer

There is an additional service for automatic transfer of accounts between Wialon Hosting services using internal Wialon tools. Automatic transfer implies a full-fledged transfer that preserves all the properties and relationships of the transferred objects. It has the following restrictions:

• only entire accounts are transferred;
  
• the total number of transferred active units is from 50 and above;
  
• services must be located in the same data center;
• the entire content of the service is not available for transfer;
• after the transfer, the number of the units in the final service should not exceed the recommended limit.

To transfer accounts automatically, send a request to partners@wialon.com.

Manual transfer

The manual transfer involves re-creating the necessary objects in a new location and setting them up afterward. Some of the settings can be transferred using the import and export tool. Additionally, in this case, you will have to re-set user rights and relationships between micro-objects (for example, geofences in report templates and notifications), as well as user passwords.

Below, we will consider instructions for transferring individual system objects between services.

Accounts

An account is a fundamental service object which consists of a resource, a user, and a billing plan. Therefore, the transfer of an account is a complex process that includes:

• creating a new account;
  
• transferring the user-creator of the account;
  
• assigning the desired billing plan;
  
• transferring the content of the resource;
  
• transferring all the other objects belonging to the original account: users, units, groups of units, retranslators, and routes.
  

To transfer accounts, log in to the CMS Manager interface and follow the instructions:

1. Export the settings of the user-creators of the accounts to WLP files (Export to file → Complete copy). When exporting the settings of several users at once, an archive with WLP files is created.
   
2. Change the names of the accounts and their user-creators in the original service. For example, you can add "_old" to the end of the names.
3. Create all the necessary accounts in the new service.
4. Extract the files from the archive you downloaded earlier and import the settings of the respective users from the WLP files. It is important to note that user properties such as email addresses, access rights, and passwords are not transferred during export, and you need to reset them manually. If the service owner has saved the current passwords, he can set the same passwords for users after the transfer. In the other case, new passwords for users have to be set.
   
5. If necessary, transfer the remaining objects of the accounts according to the instructions below.

Units and messages

Using messages export/import

1. Export unit settings to WLP files. If several units are being exported at once, an archive with WLP files is created.
2. In the original service, change the ID and phone numbers specified in the units properties. For example, you can add "_old" to the ID and an extra digit to the phone number.
3. Extract the files from the archive you downloaded earlier and create units from the WLP files.
4. Export messages from the units in the original service. Use WLN or WLB format.
   
5. Import the messages into the appropriate units in the new service.

Using messages retransmitting

1. Export unit settings to WLP files. If several units are being exported at once, an archive with WLP files is created.
2. Extract the files from the archive you downloaded earlier and create units from the WLP files.
3. When creating units, an error will be displayed with the text "Could not import all or some of the data”. This error occurs due to a conflict between the same ID and phone number in the original and destination services. When the unit properties window opens, you need to specify the device type as Wialon Retranslator and ID as the ID of the unit in the original service.
4. Create a retranslator in the original service and add the units with the messages to transfer.
5. Start the retranslator as it is created stopped.
6. Open the retranslator settings, activate the Retransmitting data for a past period option, and specify the required period.
7. When the retransmitting data for a past period is complete, change the ID and phone number of the units in the original service. For example, add "_old" to the ID and an extra digit to the phone number.
8. Import the WLP files again and select Device configuration when importing. Re-import is necessary to specify the correct device type and phone number of the units in the new service.

Resources content

A resource is a storage for the following objects:

• geofences and groups of geofences;
• jobs and notifications;
• report templates;
• drivers, trailers, passengers, as well as groups of drivers, trailers, and passengers;
• orders.

You can transfer both the entire content and individual objects. To transfer, follow the next steps:

1. Export the content of the resources in the original service to a WLP file after selecting the objects you want to transfer.
   
2. Import the content of the resources from the WLP files into the new service.

Orders can be exported and imported directly in the Logistics application.

Users

1. Export the settings of the original user to a WLP file (Export to file → Complete copy). When exporting the settings of several users at once, an archive with WLP files is created.
2. Rename the users in the original service, for example, by adding "_old" to the end of each name.
   
3. Create users in the new service.
4. Extract the files from the archive you downloaded earlier and import the settings of the respective users from the WLP files. It is important to note that user properties such as email addresses, access rights, and passwords are not transferred during export, and you need to reset them manually. If the service owner has saved the current passwords, he can set the same passwords for users after the transfer. In the other case, new passwords for users have to be set.
   

Unit groups

It is currently impossible to export the settings of unit groups. To transfer unit groups, you have to manually create them in an account in the new service, add the necessary unit to them, and grant users the appropriate access rights.

Retranslators

It is currently impossible to export the retranslator settings. To transfer a retranslator, you need to recreate it in the required account and manually copy the settings of the original retranslator into it.

Retranslators cannot be created on behalf of another user. Therefore, to create a retranslator in a particular account, you must be logged in as the user-creator of that account.

Routes

It is currently impossible to export the route settings. To transfer a route, you need to recreate it along with the schedule in the required account and manually transfer the settings of the original route into it.

Kristina Malakhovskaya,Customer Service Engineer 2023-02-28

If you know the device type, its configuration, and how it was installed, you may know which parameter to choose for the sensor in Wialon. But if you have just started working with Wialon and have doubts, this article can help you select a parameter based on how other users usually do it.

General recommendations

1. You can find the list of parameters and their description on the page of a specific device on wialon.com in the Hardware section. To do this, enter the desired device model in the Search hardware line. You can also select one of the categories of hardware types and find the desired model on the list. Then, on the hardware page, go to the Parameters tab (an example of such a page for WiaTag).

   If there is no parameter description on the hardware page, please contact hardware specialists via hw@gurtam.com.
2. In most cases, you can understand the value of a parameter by its English name. For example, the fuel_lvl parameter will most likely display the fuel level value, the total_mileage parameter — mileage sensor values, and so on. Parameter names received from CAN bus usually begin with the prefix can.
   
   
3. Parameters sent by the device can be described in the hardware documentation. As a rule, documentation is available on the manufacturer's website.
   
   
4. There is a list of virtual parameters defined in the system by default and suitable for almost any type of hardware:
   • speed — speed of movement;
   • altitude — height above sea level;
   • sats — number of satellites;
   • course — direction of movement;
   • lat — latitude;
   • lon — longitude;
   • time — UNIX time of the message;
   • regtime — time of the message registration on the server.

The method for searching and checking the selected parameter depends on the type of sensor in which it is used. Below, we’ll cover a few examples for the most commonly used types of sensors.

Engine ignition sensor

Engine ignition sensor is a digital sensor that indicates whether the engine is running or not. When the value of a digital sensor is zero, it is considered off, and when the value is non-zero, the sensor is considered on.

One of the digital inputs can be used as a parameter for the Engine ignition sensor (the I/O format parameter at the end of messages). It describes the state of all digital inputs and outputs simultaneously, and you can use it to determine the state of a particular digital input inN (the logic for selecting the input number N is described in another article).

You can also try to create an engine ignition sensor based on the external voltage parameter (usually named pwr_ext). In this case, you need to create the Calculation table in the sensor properties. The user guide provides an example of such a table. When using this example, you only need to change the voltage threshold at which the ignition will be considered on.

Practical method for selecting and checking a parameter

1. Turn off the engine and wait for a few messages from the tracker.
2. Start the engine and wait for a few more messages.
3. Compare the messages received in points 1 and 2. If there was an abrupt change of only one parameter, it is most likely that it will indicate the ignition status. If several parameters changed, you can select the desired one using the additional check described in the following point.
4. Examine the messages with non-zero speed. It is assumed that the ignition is on when there is speed, as well as in several messages before and after the speed exists. At the same time, it is recommended to consider intervals with a duration of at least five minutes, since some trackers can change the mode of sending messages after the start and the end of the movement.

Mileage sensors

Currently, Wialon has two sensors for tracking mileage:

• Mileage sensor shows the entire mileage of the unit since the sensor was installed.
• Relative odometer shows the mileage between the current and previous messages.

Both mileage sensors use kilometers (or miles) as measuring units. If the incoming parameter has other measuring units, you should apply a coefficient for converting to kilometers (or miles). For example, if the can_odo parameter displays the value in meters, then in the Parameter line in the sensor parameters, you will need to write the following formula to convert to kilometers: can_odo/const1000

Practical method for selecting and checking a parameter

You can use the Distance tool to check whether the parameter for Mileage sensor or Relative odometer is selected correctly. The parameter values and the distance measured between two messages most often do not completely coincide, but are comparable. This is due to the fact that the Distance tool mathematically calculates the distance between two points with the selected coordinates, and sensors usually calculate kilometers traveled based on the number of wheel rotations and its diameter.

You can use the parameter in the Mileage sensor if

• its value does not change when the unit stands;
• its value increases when the unit is moving;
• the difference of its values in two adjacent messages is comparable with the value obtained by using the Distance tool.

You can use the parameter in the Relative odometer if

• it is zero when the unit stands;
• it has a positive value when the unit is moving;
• it has approximately equal values when the unit is moving at the same speed;
• its value is comparable with the value obtained by using the Distance tool.

Fuel sensors

Currently, Wialon has several types of fuel sensors:

• Absolute fuel consumption sensor (AbsFCS) shows the fuel consumption for the entire period of unit operation. Therefore, to obtain data on the fuel consumption for a specific period, you should use the following algorithm: calculate the difference in sensor readings at the end and the beginning of the considered interval.
• Instant fuel consumption sensor (InsFCS) shows the amount of consumed fuel since the previous measurement (message). Therefore, to obtain data on the fuel consumption for a specific period, you should use the following algorithm: calculate the sum of the sensor readings in all messages in the considered interval.
• Impulse fuel consumption sensor (ImpFCS) — the operating principle of this sensor is similar to Instant fuel consumption sensor.
• Fuel level sensor (FLS) is designed to calculate the amount of fuel in the tank. You can use it to calculate fuel consumption, as well as control fuel drains and fillings.
• Fuel level impulse sensor (ImpFLS), like the previous sensor, is designed to calculate the amount of fuel in the tank. You can use it to calculate fuel consumption, as well as control fuel drains and fillings. The difference from FLS is that the data from the previous message is used in the calculation, and the difference in the impulse values of two adjacent messages is divided by the time difference between them. This type of sensor is almost never used in practice – instead, most users prefer a traditional FLS.

Fuel information can be contained in parameters with the following names: fuel_lvl, fuel_used, cons_total, can_fuel, rs485_lls, adc1, adc2, etc.

You should select the sensor type based on how the parameter value changes. Let’s consider the different behavior of parameters below.

AbsFCS

You can use the parameter in the Absolute fuel consumption sensor if

• its value does not change when the engine is off;
• its value increases when the engine is running;
• its value increases faster when driving or operating under a load than when stopped or with no load.

InsFCS and ImpFCS

You can use the parameter in the Instant fuel consumption sensor or Impulse fuel consumption sensor if

• it is zero when the engine is off;
• it has a positive value when the engine is running;
• it has approximately equal values when the unit is moving at the same speed or operating under the same load.

FLS

You can use the parameter in the Fuel level sensor if

• its value does not change when the engine is off;
• its value gradually decreases when the engine is running;
• its value decreases faster when driving or operating under a load than when stopped or with no load;
• its value fluctuates around the actual value during engine operation and movement;
• its value increases sharply during fuel filling.

Below is an example of the FLS parameter changing chart, which covers the trip and filling intervals.

Ekaterina Grib,Customer Service Engineer 2022-03-16

Digital input and digital output are electrical contacts (connector pins) that are energized by the voltage of only two levels: one of them corresponds to the on-state (1, or On), and the other one — to the off-state (0, or Off). Hence, digital inputs and outputs are used to connect tracker and devices or circuits that transmit only two possible states. For example, you can connect a door status sensor to the tracker's digital input so that the tracker can determine whether the door is open or not. And you can connect an anti-theft device to the tracker's digital output that will be controlled by the tracker and block the ignition.

I should note that if the client requires an exact numerical value, an analog connector is needed. Because if you, for example, use a digital input for FLS, you can only find out whether there is fuel in the tank or not.

The number of digital inputs and outputs on the tracker may be quite large (for example, Galileosky 7x may have from 6 to 10 digital inputs, depending on modification and configuration). Therefore, users often wonder to which digital input or output the installer connected the device a client is interested in. Follow the instructions below to get the answer.

Displaying digital inputs/outputs

At first, it should be noted that the state of digital inputs and outputs in Wialon is represented as two hexadecimal numbers (HEX) obtained from binary numbers (BIN), in which each bit corresponds to an input/output with the same number. The parameter with these values is named I/O (short for Inputs/Outputs) and contains two numbers separated by a slash: to the left, there is the value corresponding to the state of all inputs, and to the right — the state of the outputs.

Why was this implementation chosen? Let's look at an example.

Suppose that some vehicle attachments are connected to digital inputs 1, 3, 4 and 7 and outputs 1, 3, 6 and 8. Also, suppose that all the mentioned inputs and outputs are activated in the considered message. If separate parameters were used for each of them in the message, you would see the following:

in1=1, in2=0, in3=1, in4=1, in5=0, in6=0, in7=1, in8=0, out1=1, out2=0, out3=1, out4=0, out5=0, out6=1, out7=0, out8=1

In the current implementation in Wialon, you will see the following entry:

I/O=4D/A5

The obvious conciseness of the entry is a key advantage.

Defining the number of an activated digital input/output

If the number N of an input or output is known, the corresponding parameter will be inN, and the output parameter will be outN. For example, the fourth input is in4 and the output — out4.

However, if you don't know the number of an input or output to which the hardware is connected, you can use one of two methods: selection or a mathematical approach.

Selection

When connecting hardware, installers most often use the first inputs/outputs. So, if we talk about a device or circuit that transmits information to the tracker, you should check in1-in4, and if it's about a device or circuit that the tracker controls — out1-out4.

To find the needed input, you can create 4 sensors with the Custom digital sensor type based on these parameters (for example, the first sensor will have in1 in the Parameter field, the second — in2, and so on). Then go to the Messages panel, select the Data Messages type, and specify Sensor values ​​in the menu below. After that, query messages for the interval when the hardware was first turned off and then turned on to find the moment of transition from Off to On in one of the columns, each of which corresponds to the created sensor.

This is the fastest practical way to find the needed input (similarly, you can work with outputs, but in this case, you should use the parameters out1, out2, and so on). If it doesn't work, you can use a mathematical approach.

Mathematical approach

If you don't know the number of an input/output to which the hardware is connected, you can use the following instructions:

1. Go to the Messages panel, select the Data Messages type, and specify Initial data in the menu below.
2. Query messages for the interval when the hardware was first turned off and then turned on.
3. After displaying the table with messages from the tracker, pay attention to the Parameters column and find the I/O parameter there (it's located at the very end of the line).
   
   Suppose that the message where the hardware was turned off has the I/O=102/0 parameter, meaning that digital outputs are deactivated (or not even connected), and some digital inputs are activated.
   
   
4. Open the Calculator application (it is preinstalled on every computer, or you can find its analogs on the internet) and switch it to the Programming mode (or a similar one that allows you to convert values from one numeral system to another).
5. Switch the calculator to a hexadecimal numeral system (HEX).
6. Enter the value 102 found earlier.
7. The application will automatically (or by pressing the enter key) show you the given number in different numeral systems. We need the binary format entry (BIN), which consists only of zeros and ones.
   
   
   
   
8. Examine the resulting binary number. Note that the bit number is counted from right to left (as in the decimal system, where ones are to the right, tens are to the left of them, then hundreds, thousands, and so on): 0001 0000 0010

9. Determine the bit numbers for a given number (bit numbering in Wialon starts from 1):

   Number	12	11	10	9	8	7	6	5	4	3	2	1
   Value	0	0	0	1	0	0	0	0	0	0	1	0

10. From this entry, we can conclude that in this message, inputs 2 and 9 are activated (i.e., in2=1, in9=1), and all other inputs are deactivated (i.e., their value is zero).
11. Now find the message where the hardware was turned on. Suppose it contains the I/O=10A/0 parameter.
12. Repeat steps 4-8 for the 10A value.
    
    
    
    

13. Determine the bit numbers for a given number:
    

    Number	12	11	10	9	8	7	6	5	4	3	2	1
    Value	0	0	0	1	0	0	0	0	1	0	1	0

14. In this message, inputs 2, 4 and 9 are activated (i.e., in2=1, in4=1 and in9=1).
15. Compare the results of steps 10 and 14. As you can see, they differ only in the state of the in4 parameter, which means the hardware in the given example was connected to input 4.

Using digital inputs/outputs

You can use the digital input or output parameter the same way as any other parameter.

When creating sensors for digital inputs/outputs, types from the Digital group are most suitable since they imply only two states (On and Off).

A unique use case, which is only available for digital inputs, is a notification with the Digital input type, for which you don't even need to create a sensor.

Oleg Zharkovsky,Customer Service Engineer 2022-02-03

One of the first and crucial stages of working with Wialon is setting up sensors in the unit. If the sensors are set up correctly, then some standard algorithms will give more accurate results and you will get access to functionality that has not been available before. The calculation table, a tool from the tab of the same name, is considered in detail in this article since this exact tool most often causes difficulties when setting up sensors.

General principle of sensors operation

Wialon supports many types of trackers; you can find their current number on the wialon.com website in the Hardware section. Each of the trackers "speaks" in its own way. Therefore, the parameters which come from different types of trackers and which are displayed on the Messages tab may contain the same information (for example, about temperature or mileage) but have different names. It is necessary to create sensors for each unit in Wialon to prevent users from noticing the differences when using units with various trackers. Also, sensors have a specific type, which allows the system to understand which algorithm to choose to process input values.

However, a simple selection of a sensor type and specifying a parameter in it is often not enough because the parameter value comes in an unobvious to the user way. For example, temp=125 could mean 125°F, 125°C, 12.5°C, or even -3°C. There are three methods to convert the input parameter to the desired type:

1. Expression in the Parameter field;
2. Calculation table;
3. Validation.

They can be used individually or combined. If you use several methods simultaneously, they will be applied in the exact order they are listed above.

Schematically, the use of sensors can be represented as follows:

• The sensor connected to the tracker measures some physical quantity; let’s denote it by S.
• The sensor converts this value and transmits it to the tracker. The X parameter comes from the tracker to Wialon.
  
• Based on the parameter, a sensor is created in Wialon. Then, f(X) transformations are applied to the parameter in the sensor to obtain a human-readable Y value.
  
• Ideally, after transformations in the sensor, the value Y=f(X) should be equal to the value S measured in the first stage. Further, Y will be used in tooltips, reports, notifications, and other Wialon functionality.
  

Since this article only explains the process of setting up the calculation table in Wialon, we will pay attention only to the following elements from the scheme above:

When to use a calculation table

Usually, the calculation table is used in cases where it is necessary to convert the input parameter. However, all three methods mentioned above serve to do this. In what scenario is it worth choosing the calculation table?

In terms of practical application, the calculation table might be used for:

• the calibration table (for example, for weight sensors or fuel level sensors);
• digital sensors based on analog input data (for example, ignition sensors based on voltage);
• sensors based on codes that describe different states but come in one parameter (for example, device_status=4 means the ignition is on, and device_status=13 means the panic button is pressed, etc.);
• sensors that should display positive and negative values, although the parameter associated with them has only positive values (for example, for temperature sensors);
• any sensors in which it is necessary to separate the range of correct and erroneous values (for example, if the sensor sends specific values in a parameter that indicate errors).

Calculation table settings

The calculation table involves working with the simplest linear functions. That means that the calculation table converts the data in accordance with the Y=a⋅X+b formula — one of the variants of the straight-line equation.

If you understand how each component of this equation works, you can implement valuable and unusual solutions with its help. Next, we will review each area of the Calculation Table tab separately and visualize its impact on the result using a chart.

XY pairs

On the right side, you can see the XY pairs block. Filling it in is not enough for the calculation table to work, but it can simplify its settings.

You can add pairs manually or by importing CSV or TXT files (export is available in CSV only). After filling in all the fields of this block, you must click the Generate button (meaning, generate a calculation table based on XY pairs). This action will lead to the values of X, a, and b calculation in the left part of the window.

Each of the added XY pairs corresponds to a point on the chart. As you know, you can draw a line through two points. Therefore, if you enter five XY pairs, you will get four straight lines on the chart.

X is an input value

The central block of the Calculation Table tab contains rows with X, a, and b values. Each of the rows corresponds to a straight line on the chart. The value of X in each row means the beginning of a new straight line, that is, it sets the interval where new values of a and b will be used.

As an example, consider a table with the following values:

Otherwise, this condition can be written as follows:

• From −∞ to 3 (not including), the equation Y=1⋅X-2 is applied.
  
• From 3 (including) to 5.5 (not including), the equation Y=0⋅X+3 is applied.
  
• From 5.5 (including) to +∞, the equation Y=-0.5⋅X+2 is applied.
  

An example of a chart obtained when filling in the calculation table

a is a slope coefficient of the line

With a=0, the slope will be 0°; thus, the line will be parallel to the X-axis.
With a=1, the slope will be 45°; thus, the larger the coefficient, the closer the line will be to the Y-axis.
With a=-1, the slope will be −45 °; thus, negative values of this coefficient tilt the line down, and positive values — up.

An example of a chart of the Y=a⋅X line with different slope coefficients

b determines the displacement of the line along the Y-axis

When b=0, there is no displacement.
When b>0, the straight line is displaced upward relative to the X-axis.
When b<0, the displacement is downward.

An example of lines with different displacements

Lower and upper bounds

Lower and upper bounds allow you to cut off erroneous sensor values according to a simple principle — if the value is outside the range between the lower and upper bounds, the sensor will display a dash (error).

Let’s consider an example with a fuel level sensor. Assume that parameter values from 3 to 250 correspond to fuel volumes from 0 liters to 100 liters. And the 0 or 255 values of the parameter mean errors that we want to exclude so that they are not interpreted as a realistic volume since the tank in the example cannot have less than 0 or more than 100 liters of fuel. For this example, you can propose a solution with the Apply after calculation option turned off:

There is also a solution with the Apply after calculation option enabled:

From the example, you can see that the Apply after calculation option affects which values the bounds apply to: if it is off, then the system filters out the values along the X-axis (the input values before applying the calculation table), and if it is enabled, then it filters out the values along the Y-axis (sensor values after applying the calculation table).

To visualize how the bounds work, consider another example in which the same bounds applied to the same straight line and the difference lies only in the Apply after calculation option, which significantly affects the result.

The lower bound equals 2, the upper bound equals 3, the Apply after calculation option is disabled

The lower bound equals 2, the upper bound equals 3, the Apply after calculation option is enabled

The principle of the calculation table operation

Sometimes, to understand the essence of a phenomenon, it's better to go backward. If we know the precise formula Y=f(X), which relates the input and output values over the entire range, then there is no need to use the calculation table. It's better to use the expression in the Parameter field instead. Let's consider such a case.

Suppose that an input value is related to an output value by the Y=0.5⋅X² formula.
Let's take adc3 as a parameter. To describe such a formula in Wialon, insert the following expression into the Parameter field: const0.5*adc3^const2

The chart of the Y=0.5⋅X² function

But what if we don't know the precise Y=f(X) formula? In this exact case, the calculation table will help us.

Suppose that we know the values of the measured value (it will be Y), and we can check what value the parameter will take in Wialon at those points (it will be X). Thus, you can get values, for example, at four points: (0; 0), (1; 0.5), (2; 2), (3; 4.5). Next, plot these points (X, Y) on the chart and connect them with red lines.

Reproduction of a part of the function Y=0.5⋅X² by lines built on four points

It is easy to see that the result is close to that obtained by the formula, but there are still differences. In some cases, this accuracy will be sufficient, but if it is not enough, you can measure values ​​at more points. The chart below shows an example for six points: (0; 0), (0.5; 0.125), (1; 0.5), (1.5; 1.125), (2; 2), (3; 4.5).

Reproduction of a part of the function Y=0.5⋅X² by lines built on six points

Rationale and use cases

In this section, we will consider several cases where the calculation table saves the day.

The curve that describes the relationship between X and Y can be quite complex.

For example, using a fuel level sensor requires calibrating the fuel tank, and the shape of the chart built according to the calibration table will depend on the geometry of the tank, which is never ideal (it may have roundings, dents, internal stiffeners, and so on).

The chart based on the calibration table with small steps between measurements

It is problematic to describe such dependence in one formula. An easier way to describe this curve is to break it down into intervals where it behaves roughly like a straight line and determine the formulas for those lines. You can do it using XY pairs.

Reproduction of a complex curve by breaking it down into lines passing through eleven points

Also, sometimes the relationship between X and Y can vary over several intervals. To describe it, you need to use a system of several expressions, which cannot be done in the Parameter field in the sensor properties.

For example, some temperature sensors work as follows: X values in the range from 0 to 127 correspond to a positive temperature, and in the range from 128 to 255 — to a negative temperature. You will need a calculation table with two rows to handle such a case:

X=0; a=1; b=0
X=128; a=1; b=-256

The temperature chart where higher parameter values correspond to negative temperatures

Digital sensors are another prime example of a situation where the relationship between X and Y varies over several intervals. For example, an ignition sensor can be created based on a voltage parameter, and this requires two conditions taken into account: Y=0 when X<14 and Y=1 when X≥14. As we already know, this cannot be done using an expression in the sensor properties. But on the Calculation Table tab, this will require only two lines:

X=0; a=0; b=0
X=14; a=0; b=1

The ignition status chart depending on voltage

Oleg Zharkovsky,Customer Service Engineer 2023-02-21

In most cases, the parameters coming from the trackers have a fixed format and describe a certain state of the object. Therefore, they can be unambiguously interpreted by Wialon and displayed in messages. However, some trackers can record information of different content or even several different blocks of information in one parameter. In this case, for its correct display in Wialon, you will need to configure the sensor in a special way. To do this, you need to use bitwise parameter control, which we will discuss in this article.

Challenge

Some trackers allow transmitting user parameters with content that may vary depending on the device configuration.

For example, Wialon may display the user_value = 2646793773 parameter, although the tracker was supposed to pass one of the following values:

• 2646793773, an unsigned integer;
  
• 56877 and 40386 — several integers;
  
• −499310125, an integer with a sign bit;
  
• −5.15811×10⁻²¹ or −0.00000000000000000000515811, a floating-point number;
  
• etc.

Theoretically, this problem can be solved on the Wialon side by changing the script that parses the data coming from the tracker. However, this will affect all the users, and they may have different tracker configurations, meaning they may expect different results of data parsing from the script. Fortunately, a method for solving this problem that will work for everyone exists: creating a sensor with the right formula. At the same time, it will be based on the representation of the parameter in the binary numeral system since we already know that the representation in the decimal numeral system can be different. In binary form, the value of the parameter from the example above is written as follows: 1001 1101 1100 0010 1101 1110 0010 1101. Now let's figure out how to work with the binary numeral system.

Theoretical background

This section will cover the information needed to apply further formulas.

Numeral systems

In mathematics, different numeral systems are used. The most conventional for most people sense are positional numeral systems, where the value of a digit is determined by its position. For example, within the decimal system, the number 1, depending on the position in the number, can mean one unit (1), one ten (10), one hundred (100), and so on.

The number of characters used in positional numeral systems is called the base.

The table below lists a few common numeral systems:

To quickly convert numbers from one numeral system to another, you can use the Calculator application (it is preinstalled on every computer, or its analogs can be found on the internet) in the Programming mode (or similar).

You can come up with and use any numeral system, for example, base thirteen, but it is not generally accepted, which can lead to difficulties in parsing data on the receiving side.

The use of different numeral systems has not only historical or cultural reasons but also practical grounds. The binary system is unusual for humans but significantly simplifies mathematical calculations for electronic devices. Also, the binary system is convenient in terms of ease of recognizing values in the presence of noise, since it is easier to distinguish the absence of voltage from its presence than to determine a specific voltage level from 0 to 9.

Bits and bytes

A bit is one digit of a binary code.

A byte is a group of 8 bits.

A nibble is a half-byte, a group of 4 bits that corresponds to one character in a hexadecimal numeral system.

For convenience, binary numbers are often separated by spaces into nibbles. That is, instead of the entry 10011101110000101101111000101101, the entry 1001 1101 1100 0010 1101 1110 0010 1101 will be used.

Floating-point numbers

A floating-point number is an exponential form of representing real numbers where a number is stored as a mantissa and an exponent.

Below are some examples of such numbers:

125000 = 1.25 × 10⁵ — here, the mantissa is 1.25 and the exponent is 5.

0.000000125 = 1.25 × 10⁻⁷ — here, the mantissa is 1.25 and the exponent is −7.

125000000000000 = 1.25 × 10¹⁴ — here, the mantissa is 1.25 and the exponent is 14.

The advantage of using such a notation is that it is possible to significantly expand the range of transmitted values while maintaining the number of bits involved.

The IEEE 754 standard is most commonly used to represent floating-point numbers in digital devices.

Practical application

In this section, different options for user parameters and formulas for their interpretation in Wialon will be considered.

A binary to an integer decimal number conversion

To understand the conversion formula, you should first look at decimal numbers from a slightly unusual perspective. We will consider the decimal number 125. It consists of one hundred, two tens, and five units: 125 = 1 × 100 + 2 × 10 + 5 × 1.

As we already know, the base of the decimal system is the number 10. We also note that hundreds are in the third position, tens are in the second position, and units are in the first position. With this in mind, the number can be represented as the sum of the values in each position multiplied by the base of the numeral system to a power equal to the base minus one:

125 = 1 × 10³⁻¹ + 2 × 10²⁻¹ + 5 × 10¹⁻¹ = 1 × 10² + 2 × 10¹ + 5 × 10⁰

To calculate a whole decimal number from binary, the same formula is used but the base will already be the number 2: the sum of the bits multiplied by the base of the number system to the power equal to the bit number minus one.

,

where d is a number in the decimal numeral system, i is the bit number of the binary number, N is the number of bits, and b_i is the value of the i-th bit.

This formula can also be presented in the following way:

d = b_N × 2^N−1 + ... + b_i × 2ⁱ⁻¹ + ... + b₂ × 2²⁻¹ + b₁ × 2¹⁻¹

Let’s consider an example with the same number:

(BIN) 0111 1101 = (DEC) 0 × 2⁸⁻¹ + 1 × 2⁷⁻¹ + 1 × 2⁶⁻¹ + 1 × 2⁵⁻¹ + 1 × 2⁴⁻¹ + 1 × 2³⁻¹ + 0 × 2²⁻¹ + 1 × 2¹⁻¹ =

= (DEC) 0 × 2⁷ + 1 × 2⁶ + 1 × 2⁵ + 1 × 2⁴ + 1 × 2³ + 1 × 2² + 0 × 2¹ + 1 × 2⁰ = (DEC) 2⁶ + 2⁵ + 2⁴ + 2³ + 2² + 2⁰ =

= (DEC) 64 + 32 + 16 + 8 + 4 + 1 = (DEC) 125.

If the value comes in a parameter named user_value, then, taking into account the Wialon syntax, the formula will take the following form:

user_value:8*const2^const7+user_value:7*const2^const6+user_value:6*const2^const5+user_value:5*const2^const4+user_value:4*const2^const3+user_value:3*const2^const2+user_value:2*const2^const1+user_value:1*const2^const0

This formula writing format seems longer, but it makes it easy to track the numbering of bits and powers, which makes it possible not to make mistakes when writing the formula. But if you know the powers of two well, then a simplified version of this formula may suit you:

user_value:8*const128+user_value:7*const64+user_value:6*const32+user_value:5*const16+user_value:4*const8+user_value:3*const4+user_value:2*const2+user_value:1*const1

The length of the conversion formula will depend on the number of bits taken into account, so copying it directly from the article will not work. If, according to the tracker protocol, 1 byte (8 bits) is allocated for the parameter value, then the formula will be similar to the one above (it will only be necessary to replace the parameter name in it). And if 3 bytes are allocated for the parameter, then the formula will be three times longer, and constants up to 2²³ = 8388608 will be used in it.

Extracting a part of a parameter

As mentioned earlier, sometimes a single parameter can contain several different values at once. In this case, you must use the formula given in the previous section but only consider some bits.

As an example, consider the user_value parameter with the value (DEC) 32200 = (BIN) 0111 1101 1100 1000. Its first byte describes the value of the first counter, and the second byte describes the value of another counter. It is necessary to create two separate sensors with formulas that will use only the required bytes.

The formula for the first sensor will be similar to the formula from the previous section since the bit numbers of the original and the desired values are the same:

user_value:8*const2^const7+user_value:7*const2^const6+user_value:6*const2^const5+user_value:5*const2^const4+user_value:4*const2^const3+user_value:3*const2^const2+user_value:2*const2^const1+user_value:1*const2^const0

The formula for the second sensor will be different since we will be accessing the bits 9-16 but treating them as the bits 1-8:

user_value:16*const2^const7+user_value:15*const2^const6+user_value:14*const2^const5+user_value:13*const2^const4+user_value:12*const2^const3+user_value:11*const2^const2+user_value:10*const2^const1+user_value:9*const2^const0

As a result, from one number 32200 we can get:

(BIN) 1100 1000 = (DEC) 200 — it is the value of the first counter.

(BIN) 0111 1101 = (DEC) 125 — it is the value of the second counter.

Considering the sign of a number

In some cases, the value of the high-order bit may not be significant, but signed, that is, it contains information not about the magnitude of the value, but about whether this number is positive or negative.

For example, if the tracker sends the value 13 or −5 in the user parameter, then Wialon does not know about it, and in both cases, we will see the same parameter user_value = 13, because:

(DEC) 13 = (BIN) 1101

(DEC) −5 = (BIN) 1101 — the high-order bit is responsible for the minus, and (BIN) 101 = (DEC) 5.

To interpret the sign bit correctly, you need to change the formula for converting a binary number to a decimal integer by adding to its beginning −1 to the power of the high-order bit:

,

where d is a number in the decimal numeral system, i is the bit number of the binary number, N is the number of bits, and b_i is the value of the i-th bit.

This formula can also be presented in the following way:

d = (−1)^b_N × (b_N-1 × 2^(N−1)−1 + ... + b_i × 2ⁱ⁻¹ + ... + b₂ × 2²⁻¹ + b₁ × 2¹⁻¹)

This formula works because (−1)⁰ = 1 and (−1)¹ = −1 which allows you to display the sign of a number using one bit.

If we assume that the sign bit is a bit number 32, then to take it into account in Wialon, add the following formula to the beginning of the expression in the sensor:

(const-1)^user_value:32*...

A binary to a decimal floating-point number conversion

We are talking about converting a normalized binary number to a 32-bit format according to the IEEE 754 standard. This standard does not imply the transfer of the floating-point number itself, but the transfer of some values by which the desired number can be calculated using the following formula:

d = (−1)^S × 2^(E−127) × (1 + M/2²³),

where d is a number in the decimal numeral system, S is the sign of the number, E is the biased exponent, and M is the remainder of the normalized mantissa.

To apply this formula, its full understanding is not required. The standard describes which bits store S, E, and M so you just need to substitute them into the expression.

As an example, let’s consider the number −5.15811×10⁻²¹, which will be displayed in the parameter as user_value = 2646793773:

(DEC) 2646793773 = (BIN) 1001 1101 1100 0010 1101 1110 0010 1101

Using the formula for converting a binary number to a decimal integer, we obtain the values ​​of M and E.

The remainder of the normalized mantissa M will be equal to:

user_value:23*const2^const22+user_value:22*const2^const21+user_value:21*const2^const20+user_value:20*const2^const19+user_value:19*const2^const18+user_value:18*const2^const17+user_value:17*const2^const16+user_value:16*const2^const15+user_value:15*const2^const14+user_value:14*const2^const13+user_value:13*const2^const12+user_value:12*const2^const11+user_value:11*const2^const10+user_value:10*const2^const9+user_value:9*const2^const8+user_value:8*const2^const7+user_value:7*const2^const6+user_value:6*const2^const5+user_value:5*const2^const4+user_value:4*const2^const3+user_value:3*const2^const2+user_value:2*const2^const1+user_value:1*const2^const0

The biased exponent E will be equal to:

user_value:31*const2^const7+user_value:30*const2^const6+user_value:29*const2^const5+user_value:28*const2^const4+user_value:27*const2^const3+user_value:26*const2^const2+user_value:25*const2^const1+user_value:24*const2^const0

Now let's write the final formula, taking into account the Wialon syntax:

(const-1^user_value:32)*const2^(user_value:31*const2^const7+user_value:30*const2^const6+
user_value:29*const2^const5+user_value:28*const2^const4+user_value:27*const2^const3+
user_value:26*const2^const2+user_value:25*const2^const1+user_value:24*const2^const0-const127)*(const1+
(user_value:23*const2^const22+user_value:22*const2^const21+user_value:21*const2^const20+
user_value:20*const2^const19+user_value:19*const2^const18+user_value:18*const2^const17+
user_value:17*const2^const16+user_value:16*const2^const15+user_value:15*const2^const14+
user_value:14*const2^const13+user_value:13*const2^const12+user_value:12*const2^const11+
user_value:11*const2^const10+user_value:10*const2^const9+user_value:9*const2^const8+
user_value:8*const2^const7+user_value:7*const2^const6+user_value:6*const2^const5+
user_value:5*const2^const4+user_value:4*const2^const3+user_value:3*const2^const2+
user_value:2*const2^const1+user_value:1*const2^const0)/const2^const23)

After a simplification, we get:

(const-1^user_value:32)*const2^(user_value:31*const128+user_value:30*const64+user_value:29*const32+
user_value:28*const16+user_value:27*const8+user_value:26*const4+user_value:25*const2+
user_value:24*const1-const127)*(const1+(user_value:23*const4194304+user_value:22*const2097152+
user_value:21*const1048576+user_value:20*const524288+user_value:19*const262144+
user_value:18*const131072+user_value:17*const65536+user_value:16*const32768+user_value:15*const16384+
user_value:14*const8192+user_value:13*const4096+user_value:12*const2048+user_value:11*const1024+
user_value:10*const512+user_value:9*const256+user_value:8*const128+user_value:7*const64+
user_value:6*const32+user_value:5*const16+user_value:4*const8+user_value:3*const4+user_value:2*const2+
user_value:1*const1)/const8388608)

When substituting the numbers, we get:

(−1)¹ × 2^(59−127) × (1 + 4382253/2²³) = −0.00000000000000000000515811 = −5.15811×10⁻²¹

As you can see, the result obtained differs significantly from the initial value of the parameter 2646793773.

From the following block, feel free to conveniently copy the formula for converting a binary number to a decimal floating-point number (IEEE 754 32-bit format):

(const-1^user_value:32)*const2^(user_value:31*const128+user_value:30*const64+user_value:29*const32+user_value:28*const16+user_value:27*const8+user_value:26*const4+user_value:25*const2+user_value:24*const1-const127)*(const1+(user_value:23*const4194304+user_value:22*const2097152+user_value:21*const1048576+user_value:20*const524288+user_value:19*const262144+user_value:18*const131072+user_value:17*const65536+user_value:16*const32768+user_value:15*const16384+user_value:14*const8192+user_value:13*const4096+user_value:12*const2048+user_value:11*const1024+user_value:10*const512+user_value:9*const256+user_value:8*const128+user_value:7*const64+user_value:6*const32+user_value:5*const16+user_value:4*const8+user_value:3*const4+user_value:2*const2+user_value:1*const1)/const8388608)

Oleg Zharkovsky,Customer Service Engineer 2023-05-16

Incorrect mileage can affect the calculation of average speed, average fuel consumption per kilometer, service intervals and, of course, the indicator of the distance traveled. Therefore, it is crucial to track and fix problems that arise both on the hardware and software side.

If you’re faced with the problem of incorrect mileage detection in a report, on a track, or in messages, the first thing you should do is to check what type of mileage counter is selected on the General tab in the unit properties:

• GPS
• GPS + ignition sensor
• Mileage sensor
• Relative odometer

After finding out which counter is used in your unit, choose the appropriate section of the article.

1. GPS

When using this type of counter, the mileage correctness can be affected by the unstable communication with satellites, data transmission failures, as well as the use of additional sensors. Let's consider these options in more detail.

a. Outliers of coordinates and incorrect message chronology

Outliers of coordinates may appear due to poor communication with satellites of the Global Navigation Satellite System (GNSS). To determine that outliers occurred, go to the Messages tab and upload data for the required unit for the problematic time interval. On the map, you will see a track that can be used to determine the fact of outliers: coordinates of messages are significantly spaced from the actual unit location.

In this example, a clear indication of problems with determining the unit location is the HDOP parameter — it has values >1.

Possible solutions:

• Use Message validity filtration;
• Change the Trip Detector settings.

In the example above, we managed to get rid of outliers by using the ignition sensor in the trip detector, since they are detected in the interval when the ignition is switched off:

b. Using the mileage sensor

In some cases, the counter (the General tab in the unit properties) works based on GPS coordinates, but a separate mileage sensor is also created (the Sensors tab in the unit properties). In reports, for example, with the Trips table, the Mileage column will display the value based on GPS (total distance between coordinates), but the value of the Initial/Final mileage columns will be calculated using the following methods:

• If the first/last message of the interval has the mileage sensor value, the system uses these values.

• If there is no mileage sensor value in the first message of the interval, the system looks for the first available message with the mileage sensor value for this interval, and then the mileage before the start of the trip, calculated from GPS coordinates, is subtracted from it.

• If there is no mileage sensor value in the last message of the interval, the system looks for the last available message with the mileage value for this interval, and then the mileage at the end of the trip, calculated from GPS coordinates, is added to it.

• If there is no mileage sensor value in the first and last messages, the system looks for the first available sensor value, and then subtracts the mileage calculated from GPS coordinates from it to get the initial value, and to get the final value, on the contrary, adds the mileage calculated from GPS coordinates to the mileage sensor value.

In such a situation, if due to some failures the mileage sensor didn’t work and sent 0 km, negative mileage values may appear:

In this example, a mileage sensor was created for the unit based on the can_mileage parameter, which is absent in messages until 12/18/2019 4:38:54 PM:

After 4:38 PM onwards, the parameter always has the value 0, and the sensor, respectively, has the value 0 km.

Possible solutions:

• Remove the mileage sensor and completely switch to the mileage using GPS coordinates;
• Fix the problem on the hardware side or switch to a parameter with correct values.

In the example above, the solution was to remove the sensor and switch to GPS mileage only, since the parameter values were not read from the CAN bus.

2. GPS + ignition sensor

When using this type of counter, the mileage correctness can be affected by the unstable communication with satellites, data transmission failures, as well as the use of additional sensors. However, a significant difference from the GPS type and a fairly common cause of issues in this type of counter will be the use of an ignition sensor that doesn’t work correctly. Let's consider this option in more detail.

Incorrect value of the ignition sensor

The GPS + ignition sensor option is selected as the mileage counter. When building a track (via the Messages, Tracks or Reports tab), the mileage is 0 km, while the track itself is displayed on the map:

The track on the map is built according to coordinates from messages, while the mileage calculation algorithm takes into account not only coordinates and distance between messages, but also checks if the ignition is on.

In this example, a sensor with the Ignition type is not created for the unit, so the system ignores all messages and displays 0 km of mileage:

Possible solutions:

• Switch the mileage counter to GPS;
• Add a correctly working ignition sensor.

In the example above, the unit doesn’t send a parameter based on which the ignition state can be determined, therefore the problem is solved by switching to the GPS counter type.

3. Mileage sensor

The readings of any sensors, including mileage, can be exposed to external factors such as power shutdown, pickups, sensor malfunctions, errors of calibration and sensor/terminal configurations. Let's consider some examples of errors in more detail.

a. Resetting values of the mileage parameter

Some terminals stop transmitting mileage sensor readings for a short period of time (for example, due to power shutdown, pickups in the power supply circuit, other hardware issues). In such cases, the accumulated total mileage of the unit may differ from the last available sensor value:

In the example, the total mileage on the mileage counter is 26943 km, and on the mileage sensor — only 7069 km.

The reason is the reset of the mileage sensor parameter.

In such a situation, there occurs a reset to 0 km and then again an increase to 6452 km (in the example, such resets were repeated several times).

Possible solutions:

• Use the Lower bound in the sensor settings;
• Use Validation if the reset occurs under certain circumstances, and you can identify the dependence with other parameters (sensors).

In the example above, it is enough to apply the lower bound (0.01), since the reset occurs randomly and there is no dependence on other sensors.

Thus, by applying the lower bound, we managed to eliminate zero values (reset to 0 km) and avoid the incorrect mileage calculation.

b. Messages with the same timestamp (the With overflow option enabled)

Terminals may send messages too frequently. Wialon has a limitation: no more than 1 message should come from a unit per 1 second. When receiving data with a higher frequency, its chronology may be disrupted and a lower mileage value may end up in the database after a message with a larger value, an example is in the picture below:

In such situations, the counter overflows to the maximum possible value — 2147483648.

Possible solutions:

• Disable the With overflow option in the sensor settings (if it was enabled).

In the example above, the With overflow option was enabled. Turning it off, we got a more correct mileage value:

с. Messages with the same timestamp (the With overflow option disabled)

Messages may come with the same timestamp, disrupting the chronology, for example:

In general, in the picture above, the mileage looks correct — 25.01 km, in contrast to the previous example, where the error was obvious. However, if we take from the messages the initial value of the mileage sensor in the interval — 9917.81 km and the final value — 9942.44 km, subtract the difference, then we get the mileage — 24.63 km.

The difference is 0.38 km on a relatively small section of the track. The inaccuracy will grow with the increasing amount of data (number of trips). The reason for this error is, of course, the disruption of message chronology. The system expects the sensor value to increase. In the example, we see a drop from 9931.03 km to 9930.85 km and a subsequent increase to 9931.29 km. The mileage between messages with the sensor value 9930.85 km and 9931.29 km is recalculated, i.e., an extra 0.44 km is added.

Possible solutions:

• Switch the mileage counter to GPS;
• Fix the problem on the hardware side;
• Switch the mileage sensor to the Relative odometer type and apply validation.

In the example above, we managed to get more correct mileage values by switching the mileage sensor to the Relative odometer type with the added validation. The relative odometer sensor is based on a parameter represented as: mileage-#mileage. The validator is based on a parameter represented as: time-#time. The lower bound for the validator is 0, and the validation type is Not-null check. The mileage counter in the General tab is switched to Relative odometer.

After applying the validation, the mileage was 24.65 km. Messages with the same timestamp are excluded from the calculation.

Pavel Chebotarev,Customer Service Engineer 2022-08-03

Eco driving control is essential to determine the drivers who help their company reduce costs and those who wear and tear their vehicles. Using this feature the dispatcher can see the eco driving rank of the reporting vehicle for any period of time and each trip separately. This article provides a theoretical basis and practical recommendations that are important for setting up the eco driving control.

Theoretical background

The key characteristic that helps evaluate eco driving is acceleration. This physical quantity does not seem intuitively clear, so in the framework of training it can be compared with a more familiar quantity such as speed.

Speed and acceleration

The speed characterizes the change in position over a certain time interval:

v = S / Δt,

where v is the speed, S is the distance covered in the considered time interval (or the difference in the vehicle mileage at the end and the beginning of the trip), and Δt is the duration of the interval.

We can say this formula determines the average speed within the trip. But the shorter the time interval is considered the closer the result will be to the speed that is displayed on the vehicle's speedometer.

Acceleration characterizes the change in speed over a certain time interval:

a = Δv / Δt,

where a is the acceleration, Δv is the difference in speed at the end and at the beginning of the considered time interval, and Δt is the duration of the interval.

The average value of the acceleration per trip is almost never used in the analysis of the movement of the vehicle, so it makes sense to calculate only the acceleration over the minimum time interval.

Units of measurement

The unit of speed in the International System of Units (SI) is the meters per second (m/s), but in everyday life, we commonly use the off-system unit of measurement which is the kilometers per hour (km/h).

The SI unit for acceleration is meter per second squared (m/s²), but other off-system units like g or kmph/s unit are used more often. We use g in Wialon, while kmph/s is not supported.

g is the acceleration due to gravity on the surface of the Earth, it equals to 9.80665 m/s² (the approximation g ≈ 10 m/s² is often used). In our case, this is the standard value by which the acceleration value is divided in order to compare with something more familiar (as pressure is often displayed not in pascals, but in standard atmospheres).

The following table helps to form an idea of the average value of acceleration for various types of movement:

Accelerometers

Accelerometers are devices for measuring acceleration. Modern technologies make it possible to create miniature accelerometers that are less than one millimeter in size. They are widespread and used in many types of technological equipment: smartphones, fitness bracelets, trackers, vehicles, etc.

Since acceleration is a vector quantity, meaning, it has a direction, its full measurement requires three accelerometers installed perpendicular to each other. Together they form one three-axis accelerometer, where, for example, the X-axis shows acceleration or deceleration, the Y-axis shows turns, and the Z-axis shows ascents and descents.

It will not be possible to install the accelerometer perfectly evenly on the unit, therefore it requires calibration after installation. In general, the calibration procedure involves several stages: driving in a straight line, turns, smooth and hard braking, driving with and without violations. However, for different devices, the calibration can vary significantly. You can learn about it from the device documentation.

Since accelerometers and trackers use the same element base (microcircuits), their readings will not differ by more than 15% (and if the calibration is performed correctly, this value will be even less).

Implementation in Wialon

The general logic of eco driving control in Wialon can be represented as follows:

• Creating rules (all the relevant settings and criteria) for further evaluation takes place in the properties of the unit on the Eco Driving tab.
  
• Evaluation of messages by criteria occurs when running a report with certain tables (Eco Driving table or some others) or when working with the Eco Driving app.
  

Further attention will be focused on the points that most often raise questions from users.

General setting approach

Eco driving settings depend on the data coming from the tracker. All the existing approaches are described below and sorted by accuracy from highest to lowest.

Here are some details on each of the approaches:

1. Tracker sends calculated eco driving parameters

In Wialon, eco driving parameters are wln_accel_max, wln_brk_max, and wln_crn_max. To simplify, we can say that these parameters contain values corresponding to the maximum acceleration recorded between two consecutive messages. This allows you to set the tracker to any frequency of saving messages without affecting the accuracy of the result.

The system recognizes such parameters automatically, so there is no need to create additional sensors. It is enough to set up the calculation of acceleration by the eco driving parameters and create criteria with the Acceleration, Braking, Turn, and Reckless driving types.

2. Tracker sends calculated acceleration parameters in a custom format

Such trackers also use special algorithms for processing data from the accelerometer, which allows you to set the tracker to any frequency of saving messages without affecting the accuracy of the result.

However, these trackers send information about acceleration in a custom format, and therefore the system does not recognize such parameters automatically. Thus, to take them into account, it is necessary to create sensors (it is most logical to select the Accelerometer type), and then, based on these sensors, create criteria with the Custom type.

3. Tracker sends raw values of acceleration along the axes

If trackers do not have special algorithms for processing data from the accelerometer, then they send parameters with readings along three axes at the time the message is generated. In this case, the higher the frequency of saving messages, the higher the accuracy of the result, however, this will lead to an increase in the GPRS traffic consumed by the tracker. The recommended frequency is one message every two seconds.

Such parameters are not automatically recognized by the system, therefore, to take them into account, it is necessary to create two sensors (it is most logical to choose the Accelerometer type): one will be based on the parameter from the X axis (a positive value will correspond to acceleration, and a negative value will correlate with deceleration), and the second will be based on the parameter from the Y-axis (a positive value will indicate turns in one direction, and a negative value will show turns in the other direction). The Z-axis is associated with vertical acceleration and will not be used for calculations. Then, based on these two sensors, create criteria with the Custom type.

4. Tracker does not send any data of acceleration

If the trackers do not have an accelerometer, that is, they cannot measure acceleration, then it can be calculated mathematically from GPS data. In this case, the higher the frequency of saving messages, the higher the accuracy of the result, but this will lead to an increase in the GPRS traffic consumed by the tracker. The recommended frequency is one message every two seconds.

Next, you need to set up the calculation of acceleration by GPS and create criteria with the Acceleration, Braking, Turn, and Reckless driving types.

Recommended criteria values

The value of acceleration when driving a vehicle depends on many factors: engine power, the technical condition of the vehicle, vehicle weight, body load, tire grip, road surface quality, meteorological conditions, etc. Because of this, the generally recommended standards of acceleration when driving a vehicle do not exist.

The source of information about average values of acceleration in various situations (smooth acceleration, sharp turn, emergency braking, etc.) can be specialized literature, which contains information about specific vehicle models. It would also be possible to adjust to the values that insurance companies use, however, due to the nature of their activities, they do not publish such information in open access.

Based on this, it is worth setting the right expectations from the Eco Driving module. It allows you to detect violations following the configured criteria and perform a comparative assessment of several units or drivers.

Criteria presets

To simplify the criteria settings, Wialon has three standard presets: for an automobile, a truck, and a bus. With their help, you can get several criteria at once, which can be left in their original form, changed a little, or simply used as an example for self-configuration.

It is also a good recommendation to test the criteria in practice. To do this, it is enough to make several trips on the vehicle: in one it is worth adhering to a normal driving style, and in the other, try to commit the very violations that should be monitored further. After that, it will be enough to view messages from the tracker or run a report with the Eco Driving table in order to determine the acceleration values ​​for different driving styles, and then, based on them, determine the boundaries for violations.

Oleg Zharkovsky,Customer Service Engineer 2023-05-03

Some trackers don't send information about fuel, or a unit is not equipped with fuel sensors, but users still want to see fuel consumption data in the report.

As an alternative to fuel sensors, you can use Consumption by rates, which is configured on the Advanced tab. Its calculation algorithm is simple: the mileage per interval is multiplied by the specified consumption rate (l/100 km), which may vary depending on the season. But in this article, we will cover another option for calculating fuel consumption without a sensor, which requires more explanation — Fuel consumption by math, aka Math consumption. Moreover, its field of application is not limited to one use case.

Where can you use math consumption?

First of all, math consumption is used in reports to compensate for the absence of fuel sensors or verify their readings. To display the results of a mathematical calculation, add the Consumed by math, Avg consumption by math columns, or other columns that have "by math" in their title to the table.

Math consumption is also used in fuel algorithms. Firstly, to detect fuel drains if the Time-based calculation of drains option is enabled. Secondly, to calculate the consumption on intervals with invalid values, if the Replace invalid values with math consumption option is enabled. Both mentioned options are in the additional settings of FLS.

How does math consumption work?

The system determines the expected consumption for an interval using a mathematical model. It is built on the basis of:

• engine operation sensors (ignition or absolute/relative engine hours) that indicate the fuel consumption rate at idle;
• engine efficiency sensors (EES), each of which indicates the influence of some factor on fuel consumption (engine rotation speed, temperature, axle load, air conditioning, attached equipment, and so on).

Math consumption per interval is the sum of consumptions between all messages on the interval. The following formula is used to calculate math consumption between the current message and the previous message:

Δt ⋅ ( C_{I 1} + C_{I 2} + ... + C_{I N} ) ⋅ (K_{EES 1} + (K_{EES 2} - 1) + (K_{EES 3} - 1) + ... + (K_{EES M} - 1)),

where Δt — the time between messages; C_{I j} — consumption rate at idle from the j-th engine operation sensor, which was enabled in the considered message; N — the number of engine operation sensors created in the unit; K_{EES i} — the value of the i-th engine efficiency sensor in the considered message; M — the number of engine efficiency sensors created in the unit.

Why bind engine operation sensors, engine efficiency sensors, and FLS?

Some units have several engines. In most cases, this is special-purpose machinery, and a concrete mixer truck is a good example: its main engine makes the vehicle move, and an additional autonomous engine rotates the mixing drum. Accelerating the vehicle or turning on the air conditioner may affect the fuel consumption of the main engine but will not affect the consumption of the additional one. Consequently, some factors affecting consumption (we take them into account using engine efficiency sensors) affect only one of the engines (we take them into account using engine operation sensors). At the same time, the unit may have several fuel tanks (we take them into account using FLS), which also need to be bound with a specific engine.

To bind mentioned sensors, you should enter the properties of the ignition sensor or absolute/relative engine hours sensors and select the appropriate engine efficiency sensors. Similarly, in the FLS properties, you can configure its binding with engine operation sensors.

How to quickly create a mathematical model?

To create a basic mathematical model, use Math Consumption Wizard located on the Sensors tab in the unit properties. In the Math Consumption Wizard window, you need to enter information about fuel consumption in different operating modes, as well as the seasonal coefficient and the season's start and end dates. Let's take a closer look at these fields:

• Fuel consumption (l/h) refers to consumption at idle, i.e., with the engine running and the vehicle not moving. The Min. moving speed is taken from the Trip Detector.
• Urban cycle and Suburban cycle (l/100 km) are standard vehicle characteristics you can find in documents, on the internet, or calculate in practice. At the same time, different countries use different approaches to defining these cycles. In Wialon, the urban cycle rate corresponds to a speed of 36 km/h, and the suburban one — 80 km/h.
• Seasonal coefficient (%) refers to the percentage increase in fuel consumption during the specified season compared to the rest of the year. You can disable the seasonal factor if there are no significant temperature changes throughout the year in the area where the vehicle is used.

By filling in Math Consumption Wizard, you will create a basic mathematical model that considers only the unit speed and seasonal influence. Such a model is approximate because, in practice, speed doesn't affect consumption — the engine rotation speed does, as well as the season doesn't affect consumption — the temperature does. However, by default, most trackers don't send information about engine rotation speed and temperature. That's why we've chosen a model that is suitable for all trackers.

It's impossible to automatically create a more accurate model, but you can do it manually by adding engine efficiency sensors.

How do engine efficiency sensors work?

The value of an engine efficiency sensor in each message should show how many times an influencing factor increases the consumption at idle compared to the consumption without the influence of this factor. For a better understanding, let's look at an example.

Let’s assume that the consumption at idle is 2 l/h, and when the heating system is turned on, the consumption increases to 2.2 l/h. Therefore, the ratio of these values is: 2.2/2 = 1.1
Let's also assume that the in4 parameter indicates the state of the heating system: if this parameter is equal to 0, the heating is off, and if it’s equal to 1, the heating is on.
In this case, to take into account the heating system influence on the consumption, you need to create a sensor with the Engine efficiency sensor type, specify in4 in the Parameter line, and add the following lines to the Calculation Table:

x = 0; a = 0; b = 1
x = 1; a = 0; b = 1.1

So, when the heating system is off, the engine efficiency sensor increases the consumption by 1 time (i.e., it doesn’t change it), and when the system is on, the consumption is increased by 1.1 times. Note that a zero value of the engine efficiency sensor would also not affect fuel consumption.

Using the method described above, you can take into account the influence of one factor on the expected consumption. If there are several engine efficiency sensors, all their values are taken into account simultaneously, forming the expected consumption rate on the interval between two messages (see the formula above).

How to make math consumption more accurate?

We should note that if you activate the Time-based calculation of drains option in the fuel level sensor properties, the system will compare math consumption with the FLS consumption. Unfortunately, the readings of the latter are not very accurate. Hence, there is no need to try to make an ideal mathematical model since this may not affect the result of comparison with FLS in the end.

However, you can try to increase the model accuracy in the following ways.

Consider more factors

You can create more engine efficiency sensors based on parameters from the tracker that describe factors affecting consumption.

Note that numerous factors influence consumption, but the degree of their influence may vary. For example, there’s probably no need to install an air humidity sensor, although humidity can also affect consumption. It makes more sense to measure tire pressure, but on the other hand, it’s better to avoid using under-inflated tires. But don't expect the high accuracy of the mathematical model if you ignore the cargo weight, which can be measured using an axle load sensor. In other words, you should choose the factors to consider according to the degree of their influence on the result.

Increase the accuracy of parameter measurement

This recommendation follows from the previous one. To improve the result, you can not only increase the number of sensors but also use higher accuracy sensors.

Increase the frequency of messages

If the factors influencing consumption change frequently, the tracker must also generate messages frequently; otherwise, you won’t be able to take all factors into account. For example, this applies to trips around the city, when a car can stand at several traffic lights within 10 minutes. But if only one message is recorded in the tracker's memory during this time, the mathematical model simply cannot take into account each speed change.

Why does math consumption show incorrect values?

There may be several reasons for such behavior.

1. The rates used in Math Consumption Wizard may differ from the actual ones (for example, due to the wear and tear of a vehicle). In this case, you can check their compliance with reality in practice.
2. This may be due to the incorrect setting of math consumption. Check that a non-zero value is specified in the Consumption, l/h line in the engine operation sensor properties. Also, make sure that the engine operation sensor and the engine efficiency sensor are bound.
3. The frequency of messages generated by the tracker may be too low.
4. This may be due to a breakdown of the sensor, which readings are used in the mathematical model.
5. In some cases, the system may think that the ignition was on all the time when the tracker didn’t send messages. In this case, the mathematical model will show that the engine should have been wasting fuel during all this time. To fix the situation, try to set the correct value of the Maximum interval between messages option on the Advanced tab in unit properties. You can achieve the same result using the Timeout option in the ignition sensor properties.

Oleg Zharkovsky,Customer Service Engineer 2022-02-04

This page only highlights the key differences between fuel algorithms. I don’t intend to list all possible combinations of settings from the fuel level sensor properties, although they all affect data processing to a certain extent. To study each option, I recommend watching a webinar or testing it in practice. Notice that you can change settings without worrying about the initial data because changing the fuel options doesn’t change messages but only affects the displayed result.

Which algorithm to choose

Below is a list of algorithm features that should help you make a choice.

Mileage-based algorithm

1. Suitable for most moving units.
2. Relatively easy to set up.
3. Used by default.

Time-based algorithm

1. Suitable
   
   • for stationary units,
   • for units with long idling intervals,
   • for units with vehicle attachments, which increases fuel consumption,
   • if you suspect fuel drains while driving,
   • if the mileage-based algorithm doesn’t produce expected results.
2. More difficult to set up.
3. For activation, it’s recommended to simultaneously enable the following options in the fuel level sensor properties:
   • Time-based calculation of fuel consumption
   • Time-based calculation of fillings
   • Time-based calculation of drains – to process drains, you also need a consumption mathematical model, which you can create, for example, using the Math Consumption Wizard.

What is the difference between algorithms?

First, we should note that, to some extent, a more correct name for the mileage-based algorithm would be a speed-based algorithm because it ignores messages in which speed is less than the Min moving speed set in the Trip detector. But since the mileage increases when moving, the current name is also appropriate.

It follows from the above that the key difference between algorithms is that the time-based algorithm analyzes all messages, while the mileage-based algorithm excludes some of the messages from the analysis, using simplification. It is based on the fact that you can assess the fuel level change during stops or parkings (i.e., on the low-speed interval) by two messages before and after a given stop or parking. For example, if a vehicle was in the parking lot from 14:00 to 16:00, and the fuel drain happened between 15:00-15:10, you can learn about the fact of drain simply by comparing fuel levels at 14:00 and 16:00.

Consumption

Both algorithms calculate consumption for an interval similarly: the fuel level value at the end of the interval is subtracted from the fuel level value at the beginning of the interval, and then the volume of fuel filling for this interval is added to them. However, the key difference between algorithms still implies that they take into account different intervals.

In addition, I’d like to note that the drain volume is included in the consumption by default until the Exclude drains from fuel consumption option is activated in the report template settings.

Fuel fillings

Detecting fillings is also the same for both algorithms: the system searches for messages with a sequential increase in the fuel level sensor readings. However, the mileage-based algorithm calculates fuel fillings during stops by only two points (fuel level at the end of the previous movement interval and at the beginning of the next one), without analyzing all messages for the given interval.

Fuel drains

Drain are detected using different methods:

• The mileage-based algorithm detects the drain during parking by two points (fuel level at the end of the previous movement interval and at the beginning of the next one), without analyzing all messages for the given interval.
• The time-based algorithm compares the actual consumption according to the fuel level sensor with the expected consumption determined by the mathematical model.

Oleg Zharkovsky,Customer Service Engineer 2021-12-08

Fuel fillings are displayed in reports when the data received from the tracker meets all the criteria for detecting fillings. However, in some cases, the Fuel Fillings table doesn’t display the results, although you know for sure that the fuel filling was performed, and the chart in the report shows a sharp increase in the Fuel level line. By following simple recommendations from this article, you can fix the situation and understand the logic of some fuel settings.

Possible causes and their elimination

Sometimes, it will be enough to follow only one recommendation from the list below to solve a problem. More often, you will have to follow several tips at once. But in some cases, you won’t be able to avoid detailed analysis of all fuel level sensor settings, as well as of the features of incoming messages and parameters.

At the same time, fixing the situation with the displaying of one filling often results in the emergence of other inconsistencies in fuel reports. That’s why there should be a comprehensive approach to the fuel data analysis, considering not one filling but several at a time.

1. Filling is ignored due to smoothing

Try to reduce the filtration level in the fuel level sensor settings.

You can also try enabling adaptive median filtration.

2. Filling is filtered by volume

Try to reduce the value of the Minimum fuel filling volume option in the fuel level sensor settings.

3. Filling takes place in motion

Adjust the Trip Detector settings by increasing the Min moving speed ​​if the speed is not related to the actual trip of the unit but is related to the error in the initial data. However, if the speed in such messages is comparable to the speed of actual trips (for example, more than 10 km/h), you can probably delete such messages, and to avoid similar situations in the future, you can try to filter them out. Please keep in mind that you will not be able to recover messages deleted manually or as a result of message validity filtration, so pay special attention to these steps.

Another method for solving a problem is to enable the Detect fuel filling only while stopped option and increase Timeout to detect final filling volume in the fuel level sensor settings.

Oleg Zharkovsky,Customer Service Engineer 2022-01-13

Fuel drains are displayed in reports when the data received from the tracker meets all the drain detecting criteria. However, in some cases, the Fuel Drains table doesn’t show the results, although you know for sure that fuel was drained and can see a sharp drop in the Fuel level chart in the report. By following simple recommendations from this article, you can fix the situation and understand the logic of some fuel settings.

Possible causes and their elimination

Sometimes it will be enough to follow only one tip from the list below. More often, you will have to follow several recommendations at once. But in some cases, you won’t be able to avoid detailed analysis of all fuel level sensor settings, as well as of the features of incoming messages and parameters.

At the same time, fixing the situation with the displaying of one drain often results in the emergence of other inconsistencies in fuel reports. Thus, there should be a comprehensive approach to the fuel data analysis, considering not one drain but several at a time.

1. Drain is ignored due to smoothing

Try to reduce the filtration level in the fuel level sensor settings.

You can also try enabling adaptive median filtration.

2. Drain is filtered by volume

Try to reduce the value of the Minimum fuel drain volume option in the fuel level sensor settings.

3. Drain takes place during short stops

Try to reduce the Minimum stay timeout option to detect fuel drain in the fuel level sensor settings.

4. Drain takes place in motion

Activate the Detect fuel drain in motion option in the fuel level sensor settings if the unit was actually moving at the moment of drain. Please note that in this case, in order to display the correct result, it’s recommended to enable the Time-based calculation of drains.

Another method is to increase the minimum moving speed on the Trip Detector tab if the speed is not related to the actual trip of the unit but is related to the error in the initial data. However, if the speed in such messages is comparable to the speed of actual trips (for example, more than 10 km/h), you can probably delete such messages, and to avoid similar situations in the future, you can try to filter them out. Please keep in mind that you will not be able to recover messages deleted manually or as a result of message validity filtration, so pay special attention to these steps.

Oleg Zharkovsky,Customer Service Engineer 2021-10-15

If data received from the tracker meets all the drain detecting criteria, the Fuel Drains table will contain records about it, even if there was no actual drain. Such fuel drains are called false.

To correctly configure fuel drain detection, you need to know not only the technical features of Wialon algorithms but also the operating principles of hardware (trackers, sensors, and the unit's fuel system). This article provides simple instructions, following which you can eliminate false fuel drains by focusing on the fuel level chart only.

Required steps before applying instructions

• A unit is created in Wialon, data messages from the tracker are displayed in the system.
• The fuel level sensor is connected to the tracker, the fuel tank is calibrated.
• A sensor with the Fuel level sensor (FLS) type is created in the unit.
• The Calculate data in reports by the sensor option is activated in the FLS settings.
• The calibration table (XY pairs) is added to the fuel level sensor Calculation table, whereafter the Generate button is clicked.
• A report template with a Regular type chart is created, which displays the Processed fuel level.
• The chart also displays fuel drain markers and the background of trips (it's pink by default), stops (blue), and engine hours (yellow).

Chart behavior in the location of false fuel drain

Choose one of the options below according to what you see on the chart where the fuel drain marker is located.

1. Jumps during motion or engine operation

During engine operation, driving on uneven surfaces or basically any movement, fuel fluctuations occur, and the FLS reads them. Depending on the tank volume and shape, as well as the FLS location, these fluctuations can reach dozens of liters, which can result in detected fuel drains. In general, you can compensate them with the help of a smoothing algorithm.

To do this, set filtration type to Adaptive median filtration in the fuel level sensor settings. In this case, the algorithm automatically calculates the appropriate value of filtration level.

As an alternative you can set filtration type to Median filtration to manually tune the smoothing algorithm. E.g. set the filtration level to 3. Keep in mind that high filtration levels should be used only with a high frequency of message sending (1-5 seconds between messages). After applying the filtration, fuel algorithms will work not with the raw data but with smoothed data.

To check if smoothing is effective, add the Fuel level line (before smoothing) to the chart and compare it with the Processed fuel level line (after smoothing). If the Processed fuel level line fluctuations still seem significant to you, try to increase the filtration level (an increment of 1 is recommended). But don't forget that smoothing may distort the input data, that's why you have to find the middle ground: Processed fuel level line fluctuations no longer seem significant (or they are eliminated), but at the same time, the lines before and after smoothing are still not much different in distinctive points (for example, during actual fillings/fuel drains).

2. A sharp jump immediately after the start or stop of motion

FLS readings can change abruptly at the moment of motion start/stop, which can result in fuel drain detection. If the chosen filtration level doesn't smooth out these jumps, and you don't want to increase it (for example, in your case, this causes significant distortion of input data at other intervals), then you can use one of the two time filters in the fuel level sensor settings:

• Ignore messages after the start of motion — this option allows you to exclude a specified number of seconds after starting the movement from the fuel drain analysis.
• Minimum stay timeout to detect fuel drain — if the duration of the interval without movement doesn't exceed the specified one, then this interval won't be analyzed for fuel drains (thus, you can cut off fuel level fluctuations, for example, during short stops at traffic lights).

3. Smooth falling with the running engine and no movement

There are two algorithms for fuel analysis in Wialon: the mileage-based algorithm (used by default) and the time-based algorithm. For stationary units and units with long idle intervals, it's recommended to use the time-based algorithm. To do this, activate three options in the fuel level sensor settings: Time-based calculation of fillings, Time-based calculation of drains, and Time-based calculation of fuel consumption. We should clarify that in this very case, it would be possible to do only with the Time-based calculation of drains option, but the simultaneous activation of all options will allow you to achieve better convergence of all fuel indicators in the reports.

When using the time-based algorithm, the FLS fuel consumption value is compared with the calculated fuel consumption value, i.e., with the value calculated by the mathematical model. At idle intervals, the calculated fuel consumption value is generally determined by the engine ignition sensor or engine hours counters. Therefore, open the ignition or engine hours sensor properties and check if the correct consumption rate per hour is set in the Consumption field.

4. Fuel drain during driving, although the chart looks normal

Most likely, you are using the time-based fuel analysis algorithm, and you've also activated the Detect fuel drain in motion option in the fuel level sensor settings. In this case, the FLS fuel consumption value is compared with the mathematically calculated consumption. If the consumption by calculation is set incorrectly, a false fuel drain can be detected when the unit is just making a trip; therefore, it's recommended to check the mathematical model of the calculated consumption. It's set via:

• engine ignition sensors or engine hours counters — in the properties in the Consumption field specify the consumption rate per hour at idle;
• engine efficiency sensors — this sensor can use any parameter that affects fuel consumption and based on its value, it determines the fuel consumption change coefficient, which is then multiplied with the consumption value from the previous point.

A basic mathematical consumption model can be created using the Math consumption wizard on the Sensors tab in the unit properties. This model includes the affect of speed and season on the consumption with a help of engine efficiency sensors. Further, you can complement this model, adding more engine efficiency sensors that take into account other factors affecting the consumption (cargo weight, temperature, operation of vehicle attachments, and so on).

5. Significant jumps to the minimum/maximum

If the chart shows jumps of the Processed fuel level line to 0 or to the maximum value (often 2¹⁶-1 = 65535) and back to the actual value, then even after applying the smoothing, these jumps can cause the detection of false drains. Such jumps in readings can be connected with the wrong configuration or the connection of the fuel level sensor itself.

It's recommended to fix this problem on the hardware side; however, on the Wialon side, you can try to cut off these readings using the Calculation table. To do this, go to the FLS settings, go to the Calculation table tab, and set the values of the Lower bound and/or the Upper bound corresponding to an empty and full tank. In the lower bound, however, it's better to set not 0 but a value close to zero (for example, 0.1) to cut off false jumps in readings to 0.

6. Significant jumps not to the minimum/maximum

If the FLS readings change by significant values (but not to 0 or the maximum value) and then return to the actual value, even after applying the smoothing, these jumps can cause the detection of false drains. Such behavior can be connected with voltage surges, which can be seen on the chart using the Voltage line if you have a Voltage sensor.

It's recommended to fix such situations on the hardware side; however, on the Wialon side, you can try to neutralize the impact via Validation. To do this, follow the instructions:

1. Open the Messages tab and request raw data messages for the interval that includes the considered fuel level jump.
2. Manually or using a filter, find another parameter that changes simultaneously with the FLS readings.
   Suppose this is the pwr_ext parameter, which for most trackers corresponds to the external voltage.
3. Determine, upon passing which value of the found parameter, the FLS readings change.
   Suppose that if pwr_ext is less than 12, then the FLS starts sending incorrect readings.
4. Enter the unit properties and create a sensor with the Custom digital sensor type using the parameter from point 3, and then define a Calculation table for it with the following lines:
   X = 0; a = 0; b = 0
   X = 12; a = 0; b = 1
5. Save the created sensor and the changes of unit properties by clicking OK twice.
6. Enter the unit properties again, and then the FLS properties. Specify the sensor from point 4 as a validator with the Not-null check type.

In the example above, a real case is considered since low voltage actually often leads to the distortion of readings of different sensors. This means there is a direct connection between the transmitted parameters of voltage and fuel level. However, you can also use a correlation if you notice a simultaneous change in the FLS readings and any other parameter. Perhaps the tracker doesn't send a voltage value, but it does send a temperature value, and the temperature sensor also fails and sends, for example, 451 °F at the moment of a power surge. In this case, using validation, try to connect the FLS and the temperature value, which should also correct the situation.

7. Smooth falling after filling when there are several interconnected tanks with an FLS in each

Such a change in the FLS readings may be because the unit has several interconnected tanks and fuel flows between them. After filling one of the tanks, the equalization of levels between several tanks may take some time. If you created fuel level sensors in Wialon separately, the system can detect false drain in one of the tanks immediately after filling.

When working with several interconnected tanks, we recommend you to create a Custom sensor for each FLS (for example, named “FLS 1” and “FLS 2”) and add your calibration table into them. After that, create a separate sensor with the Fuel level sensor type, don't add the calibration table into it, but instead just use the following formula: [FLS 1]+[FLS 2]

8. Sharp falling when reaching a certain level

This situation can be observed for tanks of a specific shape at the moment of transition from a wide part to a narrow one (for example, L-shaped tanks). This is particularly likely if the calibration was performed using too few points, and often it's done using only two points (for an empty and full tank). Therefore, it makes sense to re-calibrate the tank using small portions.

9. Smooth change at the same time

Sometimes the fuel level drops/rises at specific points in time, and in some cases, later even returns to the actual value. This can happen at night, or during a trip (especially when loaded), or after approximately equal time after the end of the trip — it's difficult to identify a common rule.

Possible reasons:

• temperature change, affecting the fuel volume and the tank deformation (this is especially true for flexible plastic tanks);
• a "vacuum" created due to the pressure difference (active intake of fuel into the engine);
• sedimentation of impurities in the fuel or dirt in the tank, happening after the end of the trip (shaking).

The solution in most cases is related to the hardware: using a fuel tank cap with a valve to equalize pressure, dirt/sediment removal in the tank or on the FLS. However, if the situation is related only to temperature changes, then using a sensor with the Temperature coefficient type can help you (you can find an example of its setting in the documentation).

Oleg Zharkovsky,Customer Service Engineer 2021-10-28

Fuel control is one of the strengths of Wialon. The system has long been able to calculate the actual and expected fuel consumption for groups and individual units, as well as track fuel fillings and drains in real time or for the past period. But Wialon has another important tool for fuel control, which may not be known to everyone, although it opens up a unique opportunity for accounting dispenses by refuelling trucks. We are talking about the Fuel Traffic table, and this is what is considered in this article.

Table features

The Fuel Traffic table is unusual for several reasons. In fact, it combines three tables: Fuel Fillings, Fuel Drains, and Counter Sensors. Despite the fact that it is not available for unit groups, when you run a report on a refuelling truck it can display data for other units that receive fuel (namely, customer units).

This table can be used in different ways:

1. For a refuelling truck to display fuel dispensing to customer units.

2. For any unit to display all its fuel fillings and drains in one list.

3. Combining the first and second methods to see both fuel fillings and dispensing of a refuelling truck.

Only the first method is considered further in the article since it requires more non-standard settings comparing with the second one.

Necessary sensors

The logic of the table

Let's take a step-by-step look at the operation logic of the Fuel Traffic table for the case when it is executed for a refuelling truck.

When running a report for the selected interval, the table searches the refuelling truck for Fillingies of various types: fuel fillings, drains, or counter performance. The search is carried out in the same way as in the tables of the same name — Fuel Fillings, Fuel Drains, and Counter Sensors. It is possible to filter the types of fuel actives to be displayed in the table settings. The logic of working with all three types of activities is the same. For simplicity, let's assume that only fuel dispensing is considered in the example.

Next, the system looks for potential customers, that is, other units that were close to the refuelling truck during its fuel activities. The distance to these units is compared with the radius of approximation, which is specified in the settings of the Fuel Traffic table. Let's assume that several such units are found.

The next step, the system starts searching for fuel fillings for the units found nearby. The search is carried out in the same way as in the Fuel Fillings table.

If the Include only units with tank fuelling option is enabled in the table settings, then units without fillings will be excluded from further analysis and display. And if this option is disabled, then the report will include even those units that were simply near the refuelling truck at the time of fuel activities, but did not have fillings. Let’s suppose that the option Include only units with tank fuelling is enabled in our example.

At the moment, the system has already calculated the refuelling truck activity intervals and the filling intervals of customer units. Now we need to adjoin them.

If the filling time of a potential customer falls within the fuel activity, then the filling and fuel activity are considered to be adjacent. If such a hit did not happen, then the algorithm looks for intersections of the filling interval with the interval of fuel activity. If there are several such intersections, then the filling will be adjacent to the first fuel activity in terms of time. If the filling interval does not intersects with any fuel activity, then the customer unit and its filling will not be displayed in the report.

In the example shown in the pictures, we get:

• The fuel activity 1 row will display the fuel filling of the potential customer 1.
  In this case, the filling time (maximum fuel level difference) of the customer unit falls within the dispensing interval.
• The fuel activity 2 row will display the fuel filling of the potential customer 2.
  The time of this filling does not fall within the dispensing intervals, however, the fuel filling has intersections with several dispensing activities and will be related to the very first one.
• No fuel fillings will be displayed in the fuel activity 3 row.
  The filling interval of the potential customer 3 does not overlap with any fuel dispensing.
• The potential customer 4 will not be displayed in the report.
  No fuel fillings were detected for it, and according to the condition of the example, the option Include only units with tank fuelling is enabled in the table settings.

The names of the customer units will be displayed in the Geofences/Units column, the Filled column will contain the volume of the customer unit fuel fillings, and the Deviation column will contain the difference between fuel filling and dispensing.

Example of settings for fuel dispensing control

Let's consider an example of setting up the Fuel Traffic table to control dispensing by a refuelling truck. By default, this table displays all types of fuel activities, so you must first hide the unnecessary ones, and then configure the remaining ones.

Please remember that the settings may vary depending on the equipment used and its accuracy, as well as the needs of the client. However, most of the steps in the instructions below are still the same for all users.

• To hide refuelling truck fillings, open the Fillings block in the interval filtration, enable the Fuel fillings filter in it, and select the option Without fillings in the drop-down menu.
  
  
  
• If the fuel dispenser does not have a fuel filling gun with flow meter installed, while other counter sensors are created for the unit, they may affect the displayed result.
  To hide the readings of these counters, open the Sensors block in the interval filtration, enable the Sensor masks filter in it, and specify a name that does not match the names of the counters.
  
  
  
• If a refuelling truck is equipped with a fuel filling gun with flow meter, it is recommended to work with its data and not with fuel drains detected by the FLS.
  To hide fuel drains from the fuel dispenser, open the Drains block in the interval filtration, enable the Fuel drains filter in it, and select the Without drains option in the drop-down menu.
  
  
  

• Depending on the previous steps, at this stage the report will only display the acts of fuel dispensing recorded by the FLS or by the counter.
  In both cases, to display customer units and their fillings, it is necessary to mark the necessary units or unit groups in the Geofences/Units filter and specify the radius of approximation. This filter is repeated in each of the blocks (Fillings, Drains, Sensors), so you need to configure it in the block that you plan to use.
  It is also recommended to enable the Include only units with tank fuelling option to hide the units that were just nearby but did not have fillings from the report results.
  
  

  If several units were found nearby, the report displays the name of the unit with the smallest radius of approximation. If the radii match, then all units are displayed in the report.

Solving possible issues

Below we consider common issues that arise when working with the Fuel Traffic table and methods for solving them.

Dispensing or filling volumes do not converge

If the volumes in the Fuel Traffic table do not converge, then you need to perform the same actions as if the incorrect results were in the Fuel Fillings, Fuel Drains, and Counter Sensors tables. You can verify:

• The availability of sensor parameters in messages from the truck and the customer unit.
  
• Calibration of the refuelling truck and customer unit tanks.
• Refuelling truck counter coefficient (if used).
• Additional settings for the fuel sensors of the refuelling truck and the customer unit.
  

You might find our other fuel-related articles in the Miscellaneous section helpful.

The customer unit is not displayed or is displayed incorrectly

This issue may be related to the inaccuracy in determining the location of the refuelling truck or customer units.

You can check location-related tracker configurations or increase the radius of approximation in the settings of the Fuel Traffic table.

Based on the logic of the table discussed above the issue may be related to how and when a dispensing of a refuelling truck or a filling of a customer unit are detected. Therefore, you can follow the recommendations from the previous paragraph about the inconsistency of the volumes of dispensing or filling.

The dispensing is divided into several parts

If the dispensing is determined by the counter, then you can set the merge intervals condition in the Sensors section in the settings of the Fuel Traffic table. For example, if you set the Timeout less than 30 seconds, then the counter intervals with less than 30 seconds in between will be merged.

If the dispensing is determined by the FLS, then you can increase the Timeout to separate consecutive drains in the FLS properties.

The acts of dispensing are not split

A possible cause of this issue is the low frequency of sending data, due to which it is not possible to receive a sufficient number of messages between the acts of dispensing from the tracker.

You can also apply the recommendations from the previous paragraph, but vice versa: reduce the Timeout less then in the merge intervals condition or reduce the Timeout to separate consecutive drains in the FLS properties.

Lots of little extra acts of dispensing

It is possible that the fuel filling gun through which the fuel is dispensed is leaking, that is, fuel is dripping through it even when closed.

It would be most correct to repair the equipment, however, from the Wialon side, you can set the minimum Counter sensor value range in the Fuel Traffic table settings which will allow you to ignore small dispensing.

Drivers are not displayed correctly

Drivers may not appear in the report, or the same driver may appear in all rows.

There is no single instruction for fixing such a issue, since the process of working with drivers depends on the equipment used.

Try to study the logic of automatic assignment and separation of drivers. You may need to verify:

• Availability of driver assignment sensor parameters in the messages from the refuelling truck.
  
• Driver assignment sensor settings including the separation code.
  
• Properties of drivers, namely, their codes.
  
• Settings of the automatic assignment list.
  

Oleg Zharkovsky,Customer Service Engineer 2023-01-25

Wialon not only receives data from trackers, but can also send commands to them. In this article, you will find conditions for executing commands, the description of peculiar properties of different channels for sending commands, as well as possible issues and their solutions.

Conditions for executing commands

To execute commands, you should consider several conditions at once related to the service, account, user, and unit. Let's look at these conditions one by one.

1. The Commands service is enabled in the account.

   
   
   

2. The user has the Send commands special right regarding the unit.

   
   
   

3. The command is created in the same-name Commands tab in the unit properties.

   
   To create commands, the user must have the Create, edit, and delete commands special right regarding the unit.
   
   
4. There are several additional conditions for executing commands over the SMS channel:
   

   • The SMS messages service is enabled in the account.
     
     

   • SMS must be available in the service, i.e., the counter on the top panel must be greater than zero.
     
     This counter is not displayed if the service uses a personal modem for sending SMS.
     
     

   • In the General tab in the unit properties, you must specify the Phone number in international format, to which the tracker will receive SMS.

     

Peculiarities of channels for sending commands

The channel (connection type) for sending the command is selected in its properties. Depending on the selected channel, you should consider the unit with the server connection state when executing the command.

The unit keeps an Internet connection with the server if messages with data or keep alive/heart beat packets come from it. To check the current connection status, you can use the Connection state column on the Monitoring panel.

Checking the command sending on the Wialon side

The fact of command execution is recorded in the unit Log. This information is also available for viewing:

• in the Messages tab when requesting Sent commands;
• in the Messages tab when requesting SMS messages;
• in the report with the Sent commands table.

An entry about command execution in the log means that the command was executed on the Wialon side. Then it is sent over a TCP/UDP channel or transferred to the modem/SMPP gateway for sending.

Possible issues and their solutions

If according to the Wialon log the command is executed, but there is no response from the tracker, the issue is most likely related to the operation of third-party systems. It’s possible that the tracker did not receive the command, the tracker did not perform the programmed actions on the command, or it did not send a response/file to the command to Wialon. The most common issues of this kind and possible actions to solve them are listed below.

Sergey Novikov,Customer Service Engineer 2022-06-20

The ability to send information to different channels is a big advantage. Standard options have their inconveniences: an email can get lost in spam, and an SMS is not free of charge and does not always reach the recipient. In such conditions, the Telegram messenger can become a convenient alternative.

Telegram is a third-party service for Wialon. You can freely find guidance for the necessary settings on the internet. However, to simplify the work of our partners, in one article, we have collected the key steps that will be required to send notifications to Telegram from Wialon for public and private groups or channels, individual and bulk messages.

Preliminary requirements

Create a bot following the instructions. Hereinafter we will assume that the Telegram app is installed on your computer or phone. You can configure it in both versions, but we recommend doing it on a computer as it is easier since you will have to copy the information to the notification settings in Wialon.

Categories of notifications

Notifications can be roughly divided into two categories:

• individual — notifications for one dedicated user (for example, a client with one personal car);
• bulk — sending messages for several users at once (for example, one group, team, department, or company).

There is only one setting for Telegram notifications in Wialon — you need to set the Bot token and Channel ID:

Usually questions arise with the Channel ID. The way you fill in this field determines whether the notifications will be individual or bulk.

Individual notifications

On a computer or on the phone with Telegram installed, open this link: https://telegram.me/userinfobot

Send a command to start. In response, you get your own ID:

Then, use this own ID in the notification settings:

When such a notification is triggered, the message will be sent to the chatbot and only you will see it:

What is even more remarkable about this method is the ability to use one token for different user IDs. Thus, we use one bot for many individual notifications but each client receives only their own notification.

To find out the ID of another user, simply forward this user's message to them (for example, if you already have a chat with them, you may forward this message from there):

Bulk notifications

Public channel

Setting up the bulk sending to several users at once seems easier. It is enough to create a public Telegram channel, add a bot there, and allow it to manage notifications.

Put the channel ID in the Channel ID field for configuring notifications in Wialon:

Take only the “pach_test” part (without the symbols “t.me/”), put the “@” prefix, and add it to the notification in Wialon like this:

Then, add all the relevant contacts to this channel (all of them will receive notifications on a centralized basis). Wait for the triggered processing with the result similar to the one below:

Private channel

First, create an public channel and add a bot there with the administrator role. Send a request on behalf of the bot to this channel:

https://api.telegram.org/bot/sendMessage?chat_id=@yourchannelname&text=ping

Then replace the existing token with the token of your bot:

Enter your Channel ID:

Paste the following link into the address bar of the browser and press Enter:

https://api.telegram.org/bot775ххххххх:AAH5Kp_cххххххххххххххххх/sendMessage?chat_id=@gurtamstudy&text=ping

In response you will get:

{"ok":true,"result":{"message_id":17,"chat":{"id":-1001xxxxxxxxx,"title":"Study","username":"gurtamstudy","type":"channel"},"date":1593066856,"text":"ping"}}

Delete the message and make the channel private. Use the value "id": -1001xxxxxxxxx instead of @yourchannelname in the notification settings.

Private group

Sending notifications to a group can be useful as it gives an opportunity to its members to discuss the messages straight away. The setup process is similar to the settings for notifications to a private channel.

Create a public group and add a bot there (with or without administrator rights). Send a request on behalf of the bot to this group:

https://api.telegram.org/bot/sendMessage?chat_id=@yourgroupname&text=ping

Replace the token with the token of your bot:

Enter the ID of your group:

Paste the following link into the address bar of the browser and press Enter:

https://api.telegram.org/bot775ххххххх:AAH5Kp_cххххххххххххххххх/sendMessage?chat_id=@gurtam_study&text=ping

In response you will get:

{"ok":true,"result":{"message_id":2,"from":{"id":775ххххххх,"is_bot":true,"first_name":"pach_test","username":"pach_bot"},"chat":{"id":-1001xxxxxxxxx,"title":"Study group","username":"gurtam_study","type":"supergroup"},"date":1593070025,"text":"ping"}}

Delete the message and make the group private. Use the value "id": -1001xxxxxxxxx instead of @yourgroupname in the notification settings.

Pavel Chebotarev,Customer Service Engineer 2023-05-05

A tachograph is a device that monitors compliance with the drivers' working hours (DWH) of drivers, as well as the speed of the vehicle, the distance it has traveled and the country of location. The use of such a device allows minimizing the risk of accidents due to driver fatigue and optimizing the fleet operation. The need to install a tachograph is determined by law.

This article will cover general issues related to tachography, as well as the options for calculating and displaying DWH that are implemented in Wialon.

Legal aspect

Generally speaking, the tachograph is a mandatory device for vehicles engaged in cargo-and-passenger transportation. However, different countries have different rules about the need to install tachographs and the DWH control.

Wialon only supports the European Agreement Concerning the Work of Crews of Vehicles Engaged in International Road Transportation, or AETR for short (from the French Accord Européen sur les Transports Routiers). This is a single agreement on the work of vehicle crews on the territory of European countries.

Each tachograph is configured to control the rules of a specific country/region. The readings of a digital tachograph are legally recognized data in court proceedings or traffic control on the roads, and a document issued by a digital tachograph is the basis for imposing penalties by law enforcement agencies, because this document is generated automatically, protected from falsification and recognized as being objective.

Operation modes

Instead of text notation, tachographs use standard symbols (pictograms) so that anyone, even without knowing the language, can understand the tachograph readings. The basic pictograms indicate the modes, i.e., the different driver activity:

Other pictograms are not used in Wialon, so they are not mentioned in this article. However, the driver must know them in order to properly interact with the device.

Examples of DWH rules

To get an idea of what criteria the tachograph uses when controlling DWH, you can look at some AETR rules:

• You can drive a maximum of 4.5 hours without stopping for a break. After that, a break of 45 minutes should be taken.

   Examples

  Example 1. The driver drove for 4.5 hours and then took a break for 45 minutes. In this case, there are no violations.
  

  

  Example 2. The driver drove for 4.5 hours and then took a break for 30 minutes. This is a violation, as the duration of the break is not enough.
  

  

• If within 4.5 hours of driving you take a break of more than 15 minutes but less than 45 minutes, then at the end of the 4.5-hour driving period, you can take a break of such duration that in total with the previous break will be equal to 45 minutes. If the break lasts less than 15 minutes, it will not be counted.

   Examples

  Example 1. The driver drove for 2 hours, took a break for 20 minutes, then drove for another 2.5 hours and took a break for 25 minutes. In this case, there are no violations, since in total there were 45 minutes of rest for the 4.5-hour driving period.
  

  

  Example 2. The driver drove for 2 hours, took a break for 10 minutes, then drove for another 2.5 hours and took a break for 35 minutes. This is a violation, since the first break lasted less than 15 minutes, and therefore was not counted. As a result, for the 4.5-hour driving period, there were no 45 minutes of rest.

  

• The maximum driving time within one working week is 56 hours, and within two consecutive weeks — 90 hours.
  

   Examples

  Example 1. The driving time in the first week was 50 hours, in the second — 40 hours, and in the third — again 50 hours. In this case, there are no violations, since in each individual week the limit of 56 hours was not exceeded, and in total for each two consecutive weeks the limit of 90 hours was met.
  

  

  Example 2. The driving time in the first week was 50 hours, in the second — 50 hours, and in the third — 40 hours. In this case, there is a violation: despite the fact that in each individual week the limit of 56 hours was not exceeded, in total, the limit of 90 hours for the first and second weeks was exceeded.
  

  

DWH control uses a lot of such rules with confusing conditions, and almost all of them focus on the duration of continuous driving, periodic breaks and daily/weekly rest, or their combinations. The tachograph automatically controls the rules, however, the driver must know them in order to correctly plan their route and not violate DWH.

The structure of tachographs

Usually, tachographs are divided into analog and digital.

Analog tachographs are of round shape and installed in the speedometer socket. There is a paper disk inside, on which information is recorded. Today, analog tachographs are considered obsolete.

Digital tachographs are of rectangular shape and installed in the socket of the car radio (head unit). The technical implementation of a digital tachograph is an encrypted system of permanent energy-independent data storage with limited access to data and a thermal printer for reporting. Further, in the article, we will talk only about this type of tachographs.

The main practical difference between analog and digital tachographs is the degree of data protection from hacking. This necessity arises because some drivers try to manipulate tachograph data to complete routes faster while neglecting rest and safety, or to artificially increase their mileage and steal fuel. Any mechanical interference or incorrect data entry will be registered in the digital tachograph's memory, which will be discovered during the official check. Identified manipulations with the tachograph entail a fine, which will depend on the seriousness of the violation and on the country where it’s discovered.

Access to the tachograph memory is provided by 4 types of plastic key cards:

1. Driver card — allows the driver to save data on operating modes for 28 days.
   
2. Company card — allows the transport company to read the trip data of its vehicles.
   
3. Workshop card — allows technical specialists to set up the tachograph.
   
4. Control card — allows law enforcement agencies to read driver violations and hardware failures.
   

The data in the tachograph memory is stored in files that may have different formats (extensions) depending on the tachograph model.

DWH control in Wialon

The previous paragraphs are a kind of introduction to the tachography and DWH control. Now, let's move on to the direct work within Wialon.

Tachographs are not connected to Wialon directly — they always work via the tracker. Note that some models of trackers have a built-in tachograph, i.e., one body contains two devices at once.

In Wialon, not only the tachograph can be the source of information on DWH. The following diagram will help you understand presented in the system sources and options for displaying DWH information.

Sources of DWH information

The information on DWH displayed in Wialon can be obtained from several sources.

Driver card file

Files with different data are stored in the tachograph memory. The information on DWH of a particular driver is stored on his card. There are different ways to upload a file from a driver card to Wialon, depending on the tracker model:

• Using commands — in the FAQ section, you can find instructions on how to do this. Such a method is available for trackers that are displayed in the list of supported devices by the Tachograph file download filter.
  
• Using third-party software, for example, by connecting the tracker to a computer. Next, you should upload the file to Wialon via the TachoManager web application, and when uploading, select to which driver it belongs.
  

As a result of each of the actions described above, Wialon will have a file from the driver card, which will be associated with the Driver element.

Assignments and trips

The tachograph determines the work mode by the speed of the vehicle, the ignition status and the presence of a card in the slot. Wialon contains this data without the tachograph as well: trips detector that can be calculated based on the ignition sensor and speed, and assigning/separating drivers. Therefore, driver activity can be determined by messages from the tracker, even if the tachograph is not installed on the unit.

Online data

The procedure of uploading files from the driver card to Wialon takes time, which is not always convenient. However, users may need real-time DWH information. To satisfy this demand, Wialon created an algorithm, the data source for which is selected on the Advanced tab:

• Parameters from tachograph, which the tracker determines according to the current tachograph mode. At the moment of this writing, such a capability is only implemented in trackers manufactured by Xirgo, Ruptela, Teltonika, and Navtelecom.
• Assignments and trips from Wialon.

The online data calculated from any of the sources is associated with the Driver element.

Displaying DWH information

There are several ways to display DWH information in Wialon.

TachoView

The TachoView web application visualizes DWH information in the form of color charts and reports on driver activity or labor routine violations.

The information source for displaying is selected in the application settings, and it can be a file from the driver card or online data.

Reports on drivers

The Driver activity table shows DWH information.

The Infringements table shows the information on the DWH violations.

In the settings of both tables, a file from the driver card, online data or assignments and trips can be selected as the source of information.

Additional information on the unit and the driver

To use this method, you should first enable the Driver activity by online data option in the general user settings.

When hovering over a driver, the information on DWH and violations will be displayed in a tooltip.

The same information will be displayed in the unit tooltip and extended unit information, if the display of drivers in the mentioned places is selected in the user settings and the driver is assigned to this unit.

The source of information for this way of displaying is always online data.

Oleg Zharkovsky,Customer Service Engineer 2022-09-19

Based on the title, it may seem that the Routes module should be suitable for any request related to vehicle route control. However, this module has specific features that make it ideal for solving certain tasks and completely unsuitable for others. Different options for route control were mentioned in the meetup 4 ways of routes control in Wialon and how to choose the right one. This article will discuss the key settings of the Routes module and examples of its application.

Overall Concept

Routes from the module of the same name are macro-objects and are not part of the resource, unlike report templates, notifications, etc. The thing is, a route itself is a multi-layered object that requires an understanding of check points, schedules, and rides for proper configuration.

The key feature of routes is their focus on the time of visiting check points rather than how the vehicle moves between these points.

The main questions that need to be answered when using the Routes module are as follows:

• How will check points be added?
• What type of schedule will be used?
• What order of passing check points will be chosen?
• How will a ride be created?
• How will the result be tracked?

Each of these questions has 3 possible answers. Let's consider each of them.

Adding Check Points

The first layer of routes consists of check points that are included in it. Check points are areas on the map that a unit must visit. They can be added using three methods:

1. Adding points from the map is similar to using the Address tool: you can double-click on the desired location on the map or enter the address in the corresponding field. The found point will be the center of the check point. By default, the radius is 100 meters, but it can be manually changed if necessary.

   Similarly, route check points can be added through the Routing tool and then saved as a route.

2. Adding points from geofences involves selecting the desired one from the list of available geofences. In this case, there is no need to specify a radius since the geofence already has a defined area.
   

3. Adding points from units is similar to the previous method: you simply need to select a unit from the list. Since a unit corresponds to a point, a radius must be set for it (by default, it is 100 meters).
   

   Using a unit as a check point may seem like a strange method, but there can be practical applications for this approach. For example, the unit that follows the route could be a truck, and the moving check points could be harvesters collecting crops. On the other hand, a unit point can also be stationary, such as a fuel station with a tracker installed on it, registered as a unit in Wialon.

An important step in creating check points is optimizing the order of visiting them. During optimization, the map displays the estimated shortest route between check points, but after saving the route, the check points will simply be connected by dashed lines since the Routes module does not track the unit's location between check points.

Types of Schedules

The second layer of routes consists of schedules, which represent the expected arrival time at check points and, optionally, the departure time from them. Multiple schedules can be added for a set of check points.

There are three types of schedules:

1. Absolute — this type of schedule can only be used once, after that it should be changed, copied, or deleted.
   This type of schedule takes into account not only the time but also the specific date.

   

2. Relative to day — this type of schedule can be used once a day.

   

3. Relative to activation — this type of schedule can be used multiple times a day.
   The activation time is the time specified when creating a ride, at which the movement of the unit to the check points begins to be tracked.
   Most often, when working with this schedule, the activation time coincides with the time of visiting the first point, so the schedule lists 00:00 as the time for it, and then the time is calculated based on the time it takes to travel from the first point to the second, from the first point to the third, and so on.

   

   However, there can be a different situation when the ride is activated before the unit enters the first point. In this case, the schedule adjusts the time based on how long it will take for the unit to move from the activation time to the first point, from the activation time to the second point, and so on.

   

The examples above show how to fill in the Arrival field for different types of schedules. In addition to that, the Departure field can be filled in for each check point, allowing you to record the time that the unit should spend at that point. Additionally, for each time, an acceptable Variation can be specified, which represents the allowed time corridor for a delay or being ahead of schedule that is not a violation.

Also, any type of schedule can have a Time limitation, which allows the schedule to be applied only during certain months, days of the month, week days, or hours.

Check Points Order

Initially, the check points order can be specified in the schedule, but later it can be changed to another when creating a ride. The available options are listed below:

1. Strict — all the check points must be passed in the established order without skipping.
2. Skipping possible — the check points are expected to be visited in the established order but can be skipped, at the same time it is mandatory to visit the last check point.
3. Arbitrary — the check points can be passed in any order.

Creating rides

Rides are the implementation of routes and they combine check points, schedules, and units. It is rides that allow tracking the movement of a unit through the check points according to the specified time.

A ride can be created in three ways:

1. Manually — this method can be used when there is a dispatcher who can create a ride at the right time. It is unlikely that this approach will be suitable when there are a large number of rides.
2. Automatically for schedules with the Relative to day type. This type of schedule clearly determines the time of creating a ride on any day, so it is enough to select units in the schedule and enable the option Create rides for this schedule automatically.
   

3. Automatically using notifications with the Create a ride action. This method logically combines with schedules of the Relative to activation type.
   

   For example, a notification can be created that will start a ride when the unit leaves any of the selected geofences.

   

   With such a setup, any departure of the unit from the Base geofence will lead to creating a ride. Therefore, if the unit leaves the base not only for a ride, additional properties must be used to distinguish these departures from each other. For example, the unit may only leave for a ride at a certain time, or only with an assigned driver, or only when the certain button in the cabin is pressed, etc.

Tracking methods

Different approaches can be used for tracking routes:

1. Reports allow gathering information about the route for a specific period. The Rides and Check points tables can be used for a unit or a unit group, and the Rides and Log tables can be used for route reports.
   
2. Notifications allow real-time tracking of rides. The only type of notification, Route progress, includes the following:
   
   • Ride status: started, finished, and aborted.
   • Activity at check points: arrival, departure, and skip.
   • Schedule control: delay, outrunning, and return to the schedule.
     
     

3. The timeline also allows you to track rides in real-time. It is a special panel available at the bottom of the Routes tab. Its main feature is that units are not visible on it but the schedule is displayed in the form of ranges from Arrival to Departure (when clicking on the icon , the range will be expanded considering the allowed Variation), and the vertical line corresponds to the current time.

   

   Since units are not displayed on the timeline, it is not possible to determine how far they are from a check point while using the timeline. This can only be done using a map.
   
   If the vertical line of the current time reaches a check point, it does not mean that the unit has visited the point. The visit can only be recorded by a change in the color of the check point: before the visit, it is indicated by an empty rectangle, and after the visit, the rectangle is filled with the color of the route (in this case, blue), and if the point is missed, the rectangle is filled and outlined in red.
   

Configuration examples

When using the Routes module, a number of settings need to be made, which were mentioned above. For convenience, they are collected in a cheat sheet table, where one option needs to be selected in each column.

The cell color in the table indicates the frequency of use based on our experience of working with partners: green means often, yellow means sometimes, and red means rarely.

* The Arrival field in the schedule must be always filled in, as it is the essence of schedules, and the Departure and Variation fields are optional. Time limitations can also be specified.

Below are examples of using the Routes module and suitable settings for them.

Bakery Delivery to Grocery Stores

Every morning, a truck must deliver fresh baked goods from the bakery to the same stores. Unloading and filling out invoices at each point takes a total of 10 minutes with an allowed delay time of 5 minutes.

Proposed settings:

• Check points can be added through the addresses or geofences.
• The ride is done once in the morning, so a relative to day schedule would be suitable.
  For each point, the Departure field will contain a time 10 minutes later than the Arrival field. The Variation field should be set to 5 minutes.
  No need to set time limitations.
  
• Since the optimal order of visiting can be calculated in advance and check points can not be skipped (usually, batches of baked goods are not large and are always sold within a day), the order of visiting points will be strict.
• The departure time is the same every day, so rides can be created automatically (relative to day).
• Let's assume that during the delivery process, there are no expected real-time problems that need to be solved, so a report on a unit with a Rides table will be suitable for tracking.

Schedule settings

Water Cooler Delivery

A van delivers 5-gallon water bottles for office coolers. The customers are regular and their information is stored in the system. However, not all customers finish their water by Wednesday (which is a standard delivery day), that’s why an additional delivery day is available — Thursday. The exact visiting time is not significant, we have only an approximate range: from 10:00 to 14:00. Due to the flexibility of the schedule, unloading and filling out invoices can be not taken into consideration.

Proposed settings:

• Check points can be added through the addresses or geofences. The warehouse can be specified as the last point, where the delivery starts and ends.
• The ride is done once in the middle of the day, so a relative to day schedule would be suitable.
  For all check points, the Arrival field can be set to 12:00. The Departure field can be left empty. The Variation field can be set to 2 hours.
  Time limitations: only Wednesday and Thursday.
  
• Since not all points need to be visited on the same day, the Skipping possible option should be selected as the order of visiting.
• The departure time is approximately the same every day, so rides can be created automatically (relative to day).
  An additional ride on Thursday can be launched manually if necessary, but in that case, the time limitations in the schedule should only include Wednesday, so that automatic ride creation happens only on that day.
• Customers occasionally contact the administrator to check the real-time delivery status, so notifications and a timeline can be used for tracking.

Schedule settings

Time limitations settings

Shuttle bus

On weekends, a shuttle bus waits at the station until there is a certain number of passengers inside. After that, it starts the ride and visits each check point. The same route is performed multiple times a day.

Proposed settings:

• Check points can be added through the addresses or geofences. The passenger waiting point at the beginning of the route is enclosed by a geofence. The first check point of the route is placed immediately after this geofence.
• The ride can be done multiple times a day, so a relative to activation schedule would be suitable.
  The Arrival field for the first point is set to 00:00, and for the other points, it is filled out relative to the first point. Since the shuttle bus spends little time at each stop, the Departure field can be left empty. The Variation field can be set to any value based on the usual situation on this route (e.g. 10 minutes).
  Time limitations: Saturday and Sunday.
  
• This case describes a specific public transportation route, so the order of visiting points will be strict.
• Since the unit starts moving only after enough people get inside, the exact start time of the ride is unknown. Rides must be created using a notification, and the criterion for starting will be leaving the geofence at the beginning of the route where the empty shuttle bus is waiting for passengers.
• Let's assume that during the delivery process, there are no expected real-time problems that need to be solved, so a report on a unit with a Rides table will be suitable for tracking.

Creating geofences for check points

Schedule settings

Time limitations settings

Choosing the type of notification to start a ride

Choosing the action in the notification

Oleg Zharkovsky,Customer Service Engineer 2023-09-04

Wialon provides a wide range of features within its standard functionality, but some tasks can only be solved with non-obvious methods. For example, using dynamic groups, which we are going to discuss in this article. This method allows sorting units into groups, controlling a chain of conditions using notifications, finding units that have not met certain conditions, and so on.

General logic of dynamic groups

The logic of this method is based on the following system features:

• notifications can monitor not only specific units but also groups of units;
  
  
  
  
• notifications allow adding or removing units from groups.
  
  
  

By combining these features, non-obvious behavior can be achieved:

• If you set up a notification to monitor an empty group, the notification will be enabled, but will not trigger because there are no units in the group.
  
• If you add units to this group, even without changing the notification settings, it will automatically start monitoring the added units.
  
• If you remove units from the group, the notification will automatically stop monitoring them.
  

With dynamic groups, it is possible to create unique logical schemes. Let's take a closer look at some of them.

Sorting by groups

The simplest approach when using dynamic groups is to sort units by groups. For example, all the vehicles in a fleet can be divided into those that are moving and idling, free and busy ones, those that are on the perimeter of the facility and outside of it, and so on. After sorting, the resulting groups can be used in Reports or Jobs, as well as displayed on the Monitoring tab.

To sort by one condition A, the following elements and settings will be required:

1. The Alpha group that contains units the condition A has not yet been met for.
2. The Beta group that contains units the condition A has been met for.
3. Notification 1 which is configured to monitor the Alpha group and control condition A. If this condition is met, the units will be removed from the Alpha group and added to the Beta group.
   
4. Notification 2 which is configured to monitor the Beta group and control the condition opposite to condition A. If this condition is met, the units will be removed from the Beta group and added back to the Alpha group.
   

Schematically, this approach can be represented as follows:

Let's consider a few examples.

Example 1. Report on units outside the country

Let's assume that a client's company has dispatchers who need to divide the vehicles into two groups. One group should include those vehicles that are currently inside the country, and the other one is for those vehicles that are outside the country. Such a division is necessary in order to be able to request a report on each group at any time.

To solve this problem, it is first necessary to create a geofence that corresponds to the borders of the country, as well as 2 unit groups, which can be named Inside the country and Outside the country. Then it is necessary to manually add units to the corresponding groups based on their current location.

Next, it is necessary to set up the first notification called Departure, which will monitor the Inside the country group. It will control the presence of units outside the geofence. As the action, you should select the Add or remove units from groups action, namely to remove units from the Inside the country group and add them to the Outside the country group.

The second notification will be called Return and monitor the Outside the country group. It will control the presence of units inside the geofence. As the action, you should select the Add or remove units from groups action, namely to remove units from the Outside the country group and add them to the Inside the country group. As can be easily noticed, settings of the second notification are opposite to the first.

Now the units will dynamically move to the correct groups. Dispatchers will be able to execute a report on either the Inside the country or Outside the country group at any time, depending on their needs.

Example 2. Distribution of access through the groups

Let’s suppose that a client's request is similar to example 1, but additionally, it is necessary to ensure that a specific dispatcher has access only to those units that are currently outside the country. The solution from the previous example will be taken as a basis, and only the missing settings will be considered below.

There are two ways to approach this solution. On the one hand, you can configure the notification so that it not only moves units between the groups but also changes access to these units. On the other hand, you can provide access to the units through the groups. Only the latter method is described below.

First, it is necessary to make sure that the dispatcher does not have access rights regarding the given units. Then it is necessary to provide the dispatcher with access rights only to access a specific group of units (in this example it is the Outside the country group).

Now, when leaving the geofence and triggering the notification, the units will be added to the Outside the country group, so the dispatcher will be able to see them. When entering the geofence, the opposite situation will occur: the notification will remove those units from the Outside the country group, so the dispatcher will not see them.

Controlling multiple conditions in notifications

In Wialon, there are 20 types of notifications that allow you to automatically perform different actions when a selected condition is met. There can be multiple actions (for example, you can simultaneously display an online notification in a pop-up window and change the icon of the unit), while formally only one condition can be controlled by one notification.

However, in 8 types of notifications, in addition to the main condition, you can include several additional conditions.

It turns out that not all types of notifications can simultaneously control multiple conditions. If a client needs to combine non-standard conditions, it is necessary to use dynamic groups. With this approach, for example, you can receive a notification fuel drain only while the vehicle is on the move.

To control two conditions — A and B, the following elements and settings will be required:

1. The Alpha group which contains units for which condition A has not yet been met.
2. The Beta group which contains units for which condition A has already been met.
3. Notification 1 which is configured to monitor the Alpha group and control condition A. If this condition is met, the units will be removed from the Alpha group and added to the Beta group.
4. Notification 2 which is configured to monitor the Beta group and control the condition opposite to condition A. If this condition is met, the units will be removed from the Beta group and added back to the Alpha group.
5. Key notification 3 which is configured to monitor the Beta group and control condition B. If this condition is met, the notification will perform the final action (for example, notify the client by email).

Schematically, this approach can be represented as follows:

If it is necessary to control more conditions, the number of groups and notifications can be increased, for example:

Example 3. Controlling units outside specific area

Let’s suppose a manager wants to receive information about violations of the temperature regime of refrigerator trucks that have left the base.

To solve this problem, it is first necessary to create a geofence that corresponds to the base, as well as two unit groups, which can be named At the base and On departure. Next, it is necessary to create two notifications to sort units by the created groups. You can do it similarly as the solution in the example 1. Below, only the settings for the last notification will be shown.

For temperature control, another notification called Abnormal temperature will be needed, which will monitor the On departure group. As an action, this notification will send emails to the manager.

As a result, the units will dynamically move into the appropriate groups, and temperature control will only occur outside the base.

Controlling conditions taking time into account

By combining the approaches described above, various logical schemes can be created. Of all the possible use cases, several are highlighted that takes time into account. Let's consider their settings using some examples.

Example 4. Notification triggering once a day

Let’s suppose a client wants to receive an SMS about the first press of the panic button for all vehicles in the fleet during the working day.

To solve this task for one unit, it is necessary to set the value 1 in the Max triggers field, and then specify a time limitation for this parameter from 00:00 to 23:59. If there are not a lot of units, you can create one notification for each of them. However, if there are quite many units, dynamic groups will have to be used, and we will be discussing it further in this example.

Schematically, the solution to this problem can be represented as follows:

Consequently, the following elements and settings will be required:

1. A group named No alarm (the Alpha group in the above diagram) which contains all units whose drivers have not pressed the panic button today. At midnight, all units should be in this group, so they need to be placed there initially.
2. A group named Alarm triggered (the Beta group in the diagram) which contains units whose drivers pressed the panic button today. This group should be empty at midnight.

3. A notification named Alarm! (notification 1 in the diagram) which is set to monitor the No alarm group and control the panic button press. If this condition is met, these units will be removed from the No alarm group and added to the Alarm triggered group, and the notification will send an SMS to the client.

   Loading the gallery...

   ---

   There are no pictures in the gallery

   ---

   Problem loading this gallery!

   Source page for this gallery is either deleted or does not exist

   ❮ ❯

4. A notification named Back to initial settings (notification 2 in the diagram) in this case will return all units from the Alarm triggered group to the No alarm group closer to midnight. For this, it must be set to monitor the Alarm triggered group, have a time limitation (for example, from 20:00 to 23:59), and control some conditions that will undoubtedly be met for all the units at the end of the working day. One such condition may be a speed of less than 300 km/h (in this case, the notification should trigger For all messages).
   

   Loading the gallery...

   ---

   There are no pictures in the gallery

   ---

   Problem loading this gallery!

   Source page for this gallery is either deleted or does not exist

   ❮ ❯

Now, all the units whose drivers pressed the panic button will move to the Alarm triggered group at the first trigger. The control of triggering the panic button is no longer carried out for this group. Consequently, the client will only receive an SMS about the first alarm for each unit. In the evening, all units will be returned to the initial group.

Example 5. Report on the units that have not started moving by a certain moment

Let’s assume an owner of a fleet wants to receive a daily list of vehicles that have not started moving by 8 am.

Schematically, the solution to this problem can be represented as follows:

Consequently, the following elements and settings will be required:

1. A group named Did not start working before 8 am (the Alpha group in the above diagram) which will contain all units that have not yet started moving. It is assumed that at midnight, all units in the fleet should be in this group, so they need to be initially placed there.
2. A group named Started working before 8 am (the Beta group in the diagram) which contains units that have already started moving. At midnight, this group should be empty.

3. A notification named Managed to start before 8 am (notification 1 in the diagram) which is set to monitor the Did not start working before 8 am group and control the appearance of speed (meaning, the start of work). If this condition is met, the units will be removed from the Did not start working before 8 am group and added to the Started working before 8 am group. Also, the time limitation of this notification should be set from 00:00 to 07:59.
   

   Loading the gallery...

   ---

   There are no pictures in the gallery

   ---

   Problem loading this gallery!

   Source page for this gallery is either deleted or does not exist

   ❮ ❯

4. A job named Latecomers list, which at 08:00 will send a report to the owner of the fleet about the units from the Did not start working before 8 am group. The group report may contain, for example, the Unit latest data table.
   

   Loading the gallery...

   ---

   There are no pictures in the gallery

   ---

   Problem loading this gallery!

   Source page for this gallery is either deleted or does not exist

   ❮ ❯

5. A notification named Back to initial settings (notification 2 in the diagram) in this case will return all the units from the Started working before 8 am group to the Did not start working before 8 am group closer to midnight. This is done by analogy with the similarly named notification from example 4 above.
   

Now, all the units that have not started moving by 08:00 will remain in the Did not start working before 8 am group, and then the job will send a report about them to the owner of the fleet. If any unit starts moving before 8 am, it will be moved to the Started working before 8 am group, so it will not be included in the report about violations. In the evening, all the units will be returned to the initial group.

Example 6. Controlling long-term conditions (more than a day)

Let’s suppose a manager needs to receive an email if a unit stays in the factory area for more than 3 days (72 hours).

Usually, the duration of the controlled alarm state (in this case, being in a geofence) is set through the Min duration of alarm state field on the last page of the notification settings. The maximum value for this field is 24 hours (1440 minutes, 86400 seconds). In other words, it is not possible to control an alarm state lasting 72 hours without using dynamic groups.

Schematically, the solution to this problem can be represented as follows:

Consequently, the following elements and settings will be required:

1. A geofence that corresponds to the factory area.
2. A group named Inside <24 hours or outside (the Alpha group in the above diagram), which initially contains all units.
3. A group named Inside >24 hours (the Beta group in the diagram) which will contain units that are inside the geofence for 24 hours or more.
4. A group named Inside >48 hours (the Gamma group in the diagram) which will contain units that are inside the geofence for 48 hours or more.

5. A notification named Entry for 1 day (notification 1 in the diagram), which is configured to monitor the Inside <24 hours or outside group and control a unit being inside the geofence for more than 24 hours. If this condition is met, the units will be removed from the Inside <24 hours or outside group and added to the Inside >24 hours group. The notification should trigger Only when the state changed, and the Min duration of alarm state should be equal to 24 hours (1440 minutes, 86400 seconds).
   

   Loading the gallery...

   ---

   There are no pictures in the gallery

   ---

   Problem loading this gallery!

   Source page for this gallery is either deleted or does not exist

   ❮ ❯

   
   

6. A notification named Entry for 2 days (notification 2 in the diagram) which is configured to monitor the Inside >24 hours group and control a unit being inside the geofence for more than 48 hours. If this condition is met, the units will be removed from the Inside >24 hours group and added to the Inside >48 hours group. The notification should trigger For all messages, and the Min duration of alarm state should be equal to 24 hours (1440 minutes, 86400 seconds).
   

   Loading the gallery...

   ---

   There are no pictures in the gallery

   ---

   Problem loading this gallery!

   Source page for this gallery is either deleted or does not exist

   ❮ ❯

7. A notification named Back to initial settings (notification 3 in the diagram) will return all the units from the Inside >24 hours and Inside >48 hours groups to the Inside <24 hours or outside group if a unit leaves the geofence. The notification should trigger Only when the state changed.

   Loading the gallery...

   ---

   There are no pictures in the gallery

   ---

   Problem loading this gallery!

   Source page for this gallery is either deleted or does not exist

   ❮ ❯

   In this case, all the notifications and groups are used to control one condition (being inside or outside the geofence), so unlike the previous section of this article, one notification is enough to move all the units to the first group.

8. A notification named Entry for 3 days (notification 4 in the diagram) which is configured to monitor the Inside >48 hours group and control a unit being inside the geofence for more than 72 hours. If this condition is met, the units will be removed from the Inside >48 hours group and added to the Inside <24 hours or outside group and an email will be sent to the manager. The notification should trigger For all messages, and the Min duration of alarm state should be set to 24 hours (1440 minutes, 86400 seconds).
   

   Loading the gallery...

   ---

   There are no pictures in the gallery

   ---

   Problem loading this gallery!

   Source page for this gallery is either deleted or does not exist

   ❮ ❯

   
   

Now, all the units that have been inside the geofence for one day will move from the Inside <24 hours or outside group to the Inside >24 hours group after one day, they will move to the Inside >48 hours group after another day, and after one more day, the notification will send an email to the manager and move the units back to the initial group. If at any point the units leave the geofence, they will return to the original Inside <24 hours or outside group.

Oleg Zharkovsky,Customer Service Engineer 2023-11-26

SDK (Software Development Kit) is a set of tools for developing custom applications. Wialon SDK includes several APIs. The most basic of them is the Remote API, and these articles are focused on studying this exact tool. Remote API allows access to data through HTTP requests and is relevant for 1C, PHP, C++/C#, and other programming languages. JS API and others are built on top of the Remote API.

This article will cover the basic knowledge necessary for beginners to use Remote API.

Viewing Requests in the Browser

When starting to explore the SDK, it is often necessary to understand which API request is being sent to the server when performing a certain action in the Wialon interface. This can be easily tracked using built-in browser tools for network request monitoring.

In Chrome browser, you can do it using the Network tab in the Developer Tools, which can be opened by pressing F12. In other browsers, this tool may open differently, as described in the browser's documentation.

When viewing network requests, you can see the sent request, its parameters, and the response from the API server in JSON format.

Request Format

HTTP requests are sent to the server in the following format:

https://host/wialon/ajax.html?svc=REQUEST_NAME¶ms={PARAMETERS}&sid=SESSION_IDENTIFIER

Obtaining a Token and Authorization

Wialon uses a token for authorization, which is a key used for encrypted user identification.

To create a token, you can use the oAuth form. After you log in successfully, the token will be displayed in the browser's address bar as the value of the access_token parameter. It is important here to consider additional parameters that regulate properties such as token duration (duration parameter), user name (user parameter), token flags (access_type parameter), and others.

Example of an extended form for obtaining a token:

https://hosting.wialon.com/login.html?client_id=APP_NAME&access_type=256&activation_time=0&duration=0&lang=en&flags=0&user=USER_NAME

Example of a response:

https://hosting.wialon.com/login.html?lang=en&user=USER_NAME&wialon_sdk_url=https%3A%2F%2Fhst%2Dapi%2Ewialon%2Ecom&access_token=TOKEN_VALUE&svc_error=0

After obtaining the token, you can use it for authorization. Here is the example of logging in with a token:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/login¶ms={"token":"TOKEN_VALUE"}

The response to the token login contains the eid parameter, and its value is the unique session identifier. It will be used in almost all API requests.

Setting the Time Zone

By default, when working with the Remote API, data is displayed according to the GMT+0 time zone. To change it to the desired time zone, the render/set_locale request is used. It is sufficient to execute this request within one active session.

When sending the render/set_locale request, you must use the tzOffset parameter. The standard method for calculating its value is described in the documentation.

You can also find out the required value of the tzOffset parameter by viewing network requests while changing the user's time zone in the web interface.

System ID

In the API, work with almost every item is done through system IDs, which are represented by unique numerical values.

System IDs are not displayed in web interfaces by default but they can be seen in three ways:

1. In the response to a request for search items by property (core/search_items). We will explain it in more detail in the next section of this article.
   
2. In the parameters of requests when viewing network requests in the browser.

3. In the avl_id column in the management system.

   To make the avl_id column shown, you need to log in to the CMS and add ?features=avl_id to the end of the link. An example of such a link is shown in the image below.
   
   

Search Items by Property

This request allows you to find items by certain properties.

The search is performed for the following types of items, which are specified in the itemsType field:

• avl_hw — hardware type;
  
• avl_resource — resource;
  
• avl_retranslator — retranslator;
  
• avl_unit — unit;
  
• avl_unit_group — unit group;
  
• user — user;
  
• avl_route — route.
  

One of the possible search properties can be subitems. In this case, the propType parameter is set to propitemname, and the propName parameter takes the following values:

• units:
  
  • unit_sensors — sensors;
  • unit_commands — commands;
  • service_intervals — service intervals;
    
    
• resources:
  
  • drivers — drivers;
  • driver_groups — driver groups;
  • jobs — jobs;
  • notifications — notifications;
  • trailers — trailers;
  • trailer_groups — trailer groups;
  • zones_library — geofences;
  • reporttemplates — report templates;
  • orders — orders;
    
    
• routes:
  
  • rounds — rounds;
  • route_schedules — schedules;
    
    
• retranslators:
  
  • retranslator_units — retranslator units;
    
    
• units, users, or resources:
  
  • custom_fields — custom fields;
  • admin_fields — administrative fields.

The information in the response depends on the flags specified in the search request in the flags parameter. Flags are specified in DEC format.

Let's consider several examples of using the request for searching items by property (other examples can be found in the documentation).

Search Items by a Specific Name

In case you need to get a list of all units available to the user with the word Tractor in their name, as well as information about the sensors created in these units, you can use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*Tractor*","sortType":"sys_name"},"force":1,"flags":4097,"from":0,"to":0}&sid=SESSION_IDENTIFIER

{
	"searchSpec":{
		"itemsType":"avl_unit",
		"propName":"sys_name",
		"propValueMask":"*Tractor*",
		"sortType":"sys_name",
		"propType":"",
		"or_logic":"0"
	},
	"dataFlags":4097,
	"totalItemsCount":1,
	"indexFrom":0,
	"indexTo":0,
	"items":[
		{
			"nm":"Tractor 1",
			"cls":2,
			"id":22353120,
			"mu":0,
			"sens":{
				"1":{
					"id":1,
					"n":"Ignition",
					"t":"engine operation",
					"d":"",
					"m":"On\/Off",
					"p":"in1",
					"f":0,
					"c":"{\"act\":1,\"appear_in_popup\":true,\"ci\":{},\"cm\":1,\"mu\":0,\"pos\":2,\"show_time\":false,\"timeout\":0}",
					"vt":0,
					"vs":0,
					"tbl":[]
				},
				"2":{
					"id":2,
					"n":"Fuel level",
					"t":"fuel level",
					"d":"",
					"m":"l",
					"p":"adc1",
					"f":0,
					"c":"{\"act\":1,\"appear_in_popup\":true,\"calc_fuel\":0,\"ci\":{},\"cm\":1,\"fuel_params\":{\"fillingsJoinInterval\":300,\"filterQuality\":0,\"flags\":0,\"ignoreStayTimeout\":10,\"minFillingVolume\":20,\"minTheftTimeout\":0,\"minTheftVolume\":10,\"theftsJoinInterval\":300},\"mu\":0,\"pos\":1,\"show_time\":false,\"timeout\":0}",
					"vt":0,
					"vs":0,
					"tbl":[]
				}
			},
			"sens_max":-1,
			"uacl":-1
		}
	]
}

Search Users Created after a Specific Date

Imagine you need to get a list of users created after February 23, 2021, 05:41:46 (GMT+0). The response should contain user's system IDs and email addresses.

In such a case use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"user","propName":"rel_creation_time","propValueMask":">=1614058906","sortType":"sys_name"},"force":1,"flags":3,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Search Units of a Specific Type

Let’s get a list of units with the Wialon Retranslator hardware type that have sent messages after February 12, 2023, 12:00:00 (GMT+0). The response must display information about the sensors on the units, the last message date, and the position. In this case, use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"rel_hw_type_name,rel_last_msg_date","propValueMask":"Wialon%20Retranslator,>1676203200","sortType":"rel_creation_time"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Search Units by Sensor Name

To get a list of units that have a sensor named Engine created, you can use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propType":"propitemname","propName":"unit_sensors","propValueMask":"Engine","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Search Unit Groups by Multiple Properties

To get a list of unit groups created by User and containing more than 5 units, the following request can be used:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit_group","propName":"rel_user_creator_name,rel_group_unit_count","propValueMask":"User,>5","sortType":"sys_name"},"force":1,"flags":133,"from":0,"to":0}&sid=SESSION_IDENTIFIER

List of Common Errors

An error is displayed when it is not possible to execute a request. A complete list of returned errors can be found in the documentation.

The most common errors are the following:

• {error: 1} — invalid session.
  This error is displayed when the unique session identifier has expired. To fix this error, simply log in with the token again and use the new session identifier (sid) for further requests.

  If within 5 minutes no request is made within the session, then it becomes inactive. To keep the session active, you can send an avl_evts request every 5 minutes.

• {error: 4} — invalid input.
  This error is displayed if there is a mistake in the request text, for example, not all required parameters are specified, text parameters are not enclosed in quotes, there is no opening or closing bracket, etc. To fix this error, correct the text of the executed request according to its description in the documentation.
  
  
• {error: 7} — access denied.
  This error is displayed if the user does not have sufficient access flags to execute the request. To fix this error, check if the token used to obtain the unique session identifier has sufficient access flags, as well as if the user the token was generated for has sufficient access rights regarding the used items.
  

Ekaterina Grib,Customer Service Engineer 2023-08-02

In this article, we will cover the creation of accounts and units using the Remote API. These objects are essential when working with Wialon, and their creation requires a chain of mandatory actions.

Creating an Account

Before performing this action, it is necessary to remember two important terms:

• Creator — this is the user of the system on whose behalf this object was created.
  
• Account — this is a macro-object of the system, which represents the unity of a resource, a user, and a billing plan.

Based on this, to create an account, you need to:

1. Find a suitable billing plan.
2. Find the system ID of the user-creator which will relate to the future account creator.
   
3. Create a new user on behalf of the found user-creator.
   
4. Create a resource on behalf of the new user.
5. Merge the new user, resource, and billing plan into an account.

Let's consider the requests that will be needed at each of these steps, using the following example: it is necessary to create an account with the name sdk_account, which will be located under the account of the user manager in the service hierarchy.

1. Searching a Billing Plan

Use the request core/get_account_data.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/get_account_data¶ms={"type":1}&sid=SESSION_IDENTIFIER

The names of assigned billing plans will be displayed in the response to the request in the subPlans parameter. Let's assume that we will use a billing plan with the name standard_client.

2. Searching the System ID of the User-creator

Use the request core/search_items.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"user","propName":"sys_name","propValueMask":"manager","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

The system ID of the user-creator will be displayed in the response to the request in the id parameter. Let's assume it has a value of 11111.

3. Creating a New User

Use the request core/create_user.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/create_user¶ms={"creatorId":11111,"name":"sdk_account","password":"Pa%24%24w0rd","dataFlags":1}&sid=SESSION_IDENTIFIER

The system ID of the new user will be displayed in the response to this request under the id parameter. Let's assume it has a value of 22222.

4. Creating a Resource

Use the request core/create_resource.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/create_resource¶ms={"creatorId":22222,"name":"sdk_account","dataFlags":1,"skipCreatorCheck":0}&sid=SESSION_IDENTIFIER

The system ID of the new resource will be displayed in the response to this request under the id parameter. Let's assume it has a value of 33333.

5. Account Merging

Use the request account/create_account.

https://hst-api.wialon.com/wialon/ajax.html?svc=account/create_account¶ms={"itemId":33333,"plan":"standard_client"}&sid=SESSION_IDENTIFIER

Creating a Unit

To create a unit using the Remote API, you need to:

1. Find the system ID of the hardware type.
2. Find the system ID of the user-creator, in whose account the future unit will be located.
   
3. Create a unit.
   
4. Assign a unique ID to the unit.

Let's consider the necessary requests using the following example: it is necessary to create a unit Delivery truck with the hardware type Wialon IPS and a unique ID 12345 in the account of the user sdk_account.

1. Searching the System ID of the Hardware Type

Use the request core/get_hw_types.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/get_hw_types¶ms={"filterType":"name","filterValue":["Wialon%20IPS"],"includeType":0,"ignoreRename":1}&sid=SESSION_IDENTIFIER

The system ID of the hardware type will be displayed in the response to the request in the id parameter. Let's assume it has a value of 44444.

2. Searching the System ID of the User-creator

Use the request core/search_items.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"user","propName":"sys_name","propValueMask":"sdk_account","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

The system ID of the user-creator will be displayed in the response to the request in the id parameter. Let's assume it has a value of 22222.

3. Creating a Unit

Use the request core/create_unit.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/create_unit¶ms={"creatorId":22222,"name":"Delivery%20truck","hwTypeId":"44444","dataFlags":1}&sid=SESSION_IDENTIFIER

The system ID of the unit will be displayed in the response to the request in the id parameter. Let's assume it has a value of 55555.

4. Assigning a Unique ID

Use the request unit/update_device_type.

https://hst-api.wialon.com/wialon/ajax.html?svc=unit/update_device_type¶ms={"itemId":55555,"deviceTypeId":"44444","uniqueId":"12345"}&sid=SESSION_IDENTIFIER

Ekaterina Grib,Customer Service Engineer 2023-08-20

In this article, we will cover working with report templates using the Remote API. Executing reports through the SDK implies a sequence of mandatory actions that are not visible when working in the web interface. To complete the picture, examples of working with reports with and without grouping will be given.

Creating Reports

In most cases, users create report templates in the web interface and then execute them using API requests. We will be considering such cases later in this article.

However, you can create a report template through the SDK by using the request report/update_report.

Sequence of Actions

To obtain report results using the Remote API, several consecutive requests need to be sent. The use of some of them depends on the presence of grouping in the report and the amount of analyzed data. Here is the general list of actions:

1. Authorization through the request token/login and setting localization through the request render/set_locale.
   
   

2. Obtaining the necessary system IDs for:
   

   • the object the report needs to be executed for;

     Since reports can be executed for drivers, trailers, passengers, geozones, and their groups, in some cases it will also be necessary to obtain system IDs for these subitems.

   • the resource that contains the report template;
     
   • the report template itself.
     
     

3. Executing the report through the request report/exec_report.

   In general, we recommend executing the report in the background mode on the server. Despite the increase in the number of steps, this can be useful if the report takes a long time to execute due to a large number of objects, report execution interval, number of tables and charts, etc. Later in this article, we will specifically consider executing the report in the background mode.
   
   If the report is not executed in the background mode on the server, then the response to this request will be similar to the response from step 5, so you can proceed directly to step 6.
   

4. Checking the report execution status through the request report/get_report_status.
   After confirming the report is ready, you can proceed with following the instructions.
   
   
5. Obtaining the report result through the request report/apply_report_result.
   The result of this request will provide the number of rows, columns, and levels of nesting if grouping is used.
   
   
6. Getting the table rows through the request report/get_result_rows for a report without grouping or through the request report/select_result_rows for a report with grouping.
   The selection of the table, nesting levels, and displayed rows is based on the data from the previous response.
   
   
7. Exporting to a file through the request report/export_result.
   This step is optional but quite simple and useful, so we will also consider it.
   
   
8. Deleting the result of the previous report through the request report/cleanup_result.
   This step is mandatory if multiple reports must be executed in one session.