Fleetrun
Hecterra
NimBus
Other apps
Wialon for Android/iOS
Logistics
Wialon Local
Wialon Hosting
WiaTag
Configurator
LeaseControl
en
Contents
By date
Issues When Changing Access Rights to Units
  • technical_consulting
  • access_rights

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.

A unit can belong to several groups at once, and in this case, it is recommended to check the user's rights towards all these groups. The list of groups that a unit belongs to is displayed on the Groups tab in the unit properties.

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 them. 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).

You can check the service structure using the Service Hierarchy tool in the management interface (CMS).

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 their 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.

Changes to unit rights are logged in the Log (on the Messages tab or in a report using the same-name table). The Host column will contain the username if the changes were made manually or via an API request, or "job" or "notification" if the changes were made using this functionality.

Log entries can be deleted. In this case, information about changing rights will not be displayed. If you suspect that you’ve faced such a situation, please contact Wialon technical support via email support@wialon.com.

Ekaterina Grib,Customer Service Engineer

Transferring Objects within the Same Service
  • technical_consulting
  • hierarchy
  • service_structure
  • transferring_units

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@wialon.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.

If the account you are planning to transfer to does not appear in the list when using the unit transfer tool, check if the following conditions are met:

  • the creator of the account to which the transfer is planned has the View object and its basic properties access right for transferred units;
  • the services Units and Create units are activated for the account to which the transfer is planned;
  • the account to which the transfer is planned must not be blocked;
  • other conditions specified in the user manual.

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 fileComplete 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.

In case of difficulties, check the following issues:

  • To allow the creation of subordinate accounts, make sure an account matches these requirements:
    • the Create users, Create resources, and Management system (CMS Manager) services are enabled;
    • the dealer rights are activated, and billing plans are assigned.

  • Enable the Import/Export service for the account you are exporting the user settings from.
  • To export all the user settings, you must have full access rights to them. Export as the main user to avoid checking for full rights since such a user has full access to all the service objects.

  • When you export the user settings, select the Complete copy option to include all the hidden settings (for example, operational settings for applications) in the copy.

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.

Drivers’, trailers’, and passengers’ assignments are unavailable for transfer.

If the settings of the exported report templates, notifications, and jobs use any geofences, units, users, report templates, etc., you will need to re-set these settings. It is necessary because when creating objects, they will be assigned a new internal ID, and the old settings will be invalid.

Users

  1. Export the settings of the original user to a WLP file (Export to fileComplete 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.

The user-creator of the account you want to transfer a unit group to must have rights to all the units in this group.

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.

Difficulties with transferring the objects

If you have any questions about transferring the objects, please, contact our technical support via email at support@wialon.com. In the request, describe the issue in detail, and also indicate:

  • the name of the object you are transferring;
  • the name of the account you want to transfer the object from (if you are not transferring an account itself);
  • the name of the account you are transferring the object to (if you are transferring the account itself, mention the name of the planned parent account).

Kristina Malakhovskaya,Customer Service Engineer

Transferring Objects between Services
  • technical_consulting
  • hierarchy
  • service_structure

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.

Users may experience access issues during the transfer due to a temporary username change. Also, during the transfer, it is not recommended to make changes to the transferred objects (try not to create new units in the account, change the groups or notification settings, etc.).

After the transfer, we recommend that you check the transferred objects.

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 fileComplete 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, they 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.

In case of difficulties, check the following issues:

  • To allow the possibility of subordinate accounts creating, make sure that:
    • the Create users, Create resources, and Management system (CMS Manager) services are enabled;
    • the dealer rights are activated, and billing plans are assigned.

  • Enable the Import/Export service for the account you are exporting the user settings from.
  • to export all the user settings, you must have full access rights to them. Export as the main user to avoid checking for full rights since such a user has full access to all the service objects.

  • When you export the user settings, select the Complete copy option to include all the hidden settings (for example, operational settings for applications) in the copy.

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.

In case of difficulties, check the following issues:

  • To export all the unit settings, you must have full access rights to them. Export as the main user to avoid checking for full rights since such a user has full access to all the service objects.

  • 64 MB is the size limit for an imported file or archive. If the exported file is larger than 64 MB, it is necessary to divide the time interval for messages during export and, thus, obtain several files.
  • In the original service, the user must have the Export messages access right for the units with the messages to transfer. And in the destination service, the user must have the Import messages access right for the units to receive those messages.
  • The Messages service must be enabled in the account both in the original and destination services.
  • When transferring units, you may need to change the configuration of trackers. You can find the required IP and port numbers in the unit settings in the General section.
  • Messages received between the change of the original ID and the creation of a new unit from the WLP file may be lost if the device does not have a black box.

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.

In case of difficulties, check the following issues:

  • If retranslation is not available, check if the Retranslators service is enabled for the current and parent accounts.
    If retranslation is not available and there is no access to the parent account, you need to contact the monitoring service provider.
  • To add units to the retranslators, the user must have the Use unit in jobs, notifications, routes, retranslators access right for these units.
  • When retranslating from Wialon Hosting to Wialon Hosting, a special address is used that is different for each data center:
    • hosting.wialon.com — hw.sig;
    • hosting.wialon.eu — hw.tig;
    • hosting.wialon.us — hw.usa;
    • hosting.wialon.ru, hosting.wialon.org — hw.tms.
      If you need to clarify in which data center your service is located, please contact our technical support at support@wialon.com.

  • When transferring units, you may need to change the configuration of trackers. You can find the required IP and port numbers in the unit settings in the General tab.
  • Messages received between the change of the original ID and the creation of a new unit from the WLP file may be lost if the device does not have a black box.

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.

Drivers’, trailers’, and passengers’ assignments are unavailable for transfer.

If the settings of the exported report templates, notifications, and jobs use any geofences, units, users, report templates, etc., you will need to re-set these settings. It is necessary because when creating new objects, they will be assigned a new internal ID, and the old settings will become invalid.

Users

  1. Export the settings of the original user to a WLP file (Export to fileComplete 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, they 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.

Post-transfer check

After the transfer, we recommend performing the following steps:

  • check user rights to objects created as a result of the transfer (units, resources, etc.);
  • make sure that the messages from the units are transferred correctly;
  • check if the billing plans are assigned to the created accounts;
  • check the relationships between micro-objects (for example, geofences in the report templates and notifications).

It is worth deleting elements from the original service only after checking the correctness of the transfer of all the objects, their settings, and relationships.

Kristina Malakhovskaya,Customer Service Engineer

How to Choose a Parameter for a Sensor
  • technical_consulting
  • sensor_parameters
  • sensor_types

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@wialon.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.

Engine ignition sensor does not indicate the ACC position of the ignition key, in which the engine is not running, but additional hardware is already available for use.

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.
 Example

Messages with the following parameters are received from the unit:


Speedparam1param2param3
15526.00301000
25626.00401020
35726.00511015
4026.00611004
5026.0071476
6026.0080489
71026.00901001
81126.01011004

Let's assume that the unit ignition was off in the 5th and 6th messages (highlighted in red). In other messages, the ignition is on (highlighted in green).

param1 — the value was constantly increasing at all intervals, there are no abrupt changes, there is no connection with the speed or its absence. Hence, this parameter can’t be used for the ignition sensor.

param2 — changed at all three intervals, took on a zero value when there was speed in the messages, although the ignition should have been turned on at that moment. Hence, this parameter can’t be used for the ignition sensor.

param3 — at intervals when the ignition is supposed to be on, the parameter takes on a value of more than 1000, and at intervals when the ignition is off, the value abruptly drops to a level of less than 500. Hence, you can try to use this parameter in the ignition sensor by applying the calculation table.

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.

If the device sends parameters for both mentioned types of sensors at once, the odometer readings do not have to completely coincide with the difference that you get by subtracting the mileage sensor readings in two adjacent messages. This is due to the fact that the calculation algorithm for sensors may differ on the device side. In that case, it is advised to choose the sensor that shows more reliable results.

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.
 Example

Messages with the following parameters are received from the unit:

Create a Mileage sensor based on the mileage parameter, as it constantly increases while moving and does not drop to zero during a stop.

Create a Relative odometer based on the odo parameter, as it has different values while moving and drops to zero during a stop. However, its value seems too high, so try using the odo/const1000 formula.

Measure the unit mileage between several pairs of messages using the Distance tool by placing the measured segments on top of the track.

Compare the obtained results:

Mileage sensorDifference with the previous by the mileage sensorRelative odometerThe Distance tool
16801.54 km1.00 km
26802.52 km6802.52 - 6801.54 = 0.98 km1.00 km1.000 km
36803.51 km6803.51 - 6802.52 = 0.99 km1.00 km1.020 km
46804.00 km6804.00 - 6803.51 = 0.49 km0.50 km0.500 km
56804.20 km6804.20 - 6804.00 = 0.20 km0.50 km0.160 km
66804.20 km6804.20 - 6804.20 = 0.00 km0.00 km-

The values are approximately equal, therefore, we can assume that the parameters for both sensors are selected correctly.
Please note that different sensors may have different accuracy. In this case, in the Mileage counter and Trip Detector, it’s recommended to use the sensor that sends readings closest to the expected ones.

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.
  • Impulse fuel level 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.

If the device sends parameters for several of the mentioned types of sensors at once, their readings, as well as the calculation results for them, may differ. This is due to the difference in measuring methods, and the peculiarities of working with fuel. In that case, it is advised to choose the sensor that shows more reliable results.

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.

In contrast to fuel consumption sensors, the parameter from FLS may behave not the way described above, because fuel drain may happen during a stop or movement, the unit may move at an angle, the temperature may change significantly during the day, fuel may contain impurities, etc. Find more information about fuel control issues and their solutions in the MiscellaneousFuel section.

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

In some cases, the FLS parameter behaves in the opposite way: when the engine is running, its value increases, and when filling, it decreases. This difference will be neutralized after the tank is calibrated and its results are entered into the Calculation table.

Ekaterina Grib,Customer Service Engineer

How to Choose the Number of Digital Input/Output (I/O)
  • technical_consulting
  • sensor_parameters

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):

    Number121110987654321
    Value000100000010
  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:

    Number121110987654321
    Value000100001010
  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

Sensors: Calculation Table Explained
  • technical_consulting
  • calculation_table

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.

The article contains information of varying complexity. The main part is helpful for understanding the logic of the calculation table. However, you can find more detailed mathematical formulations in the highlighted special blocks called It’s Math Time. For a general understanding of this article, you can skip these blocks.

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).
 It’s Math Time

In other words, the calculation table should be used if:

  • the formula Y=f(X) is unknown, but in practice, correspondences between some X and Y have been established;
  • the formula Y=f(X) is too complex (for example, it contains such functions as sin, cos, log, etc., which are not supported in Wialon);
  • the chart of the formula Y=f(X) has different shapes at different intervals and cannot be described by a single function;
  • it is necessary to separate the range of correct and erroneous values.

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.

To see a chart that corresponds to the completed calculation table, you need to click on the icon  at the top of the tab.

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.

We recommend using XY pairs only for fuel level sensors to add the calibration table. In other cases, you should independently calculate and enter the values of X, a, and b.

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.

Pairs with the same X value are not allowed to enter. This is technically impossible since two or more Y values cannot correspond to one X value. However, you can enter the same Y values.

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.

The last row affects all further values up to +∞, and the first row affects values even up to the first specified X, i.e., starting from −∞. Therefore, writing several consecutive rows with the same values of a and b does not make sense.

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

Determining the coefficient of the line slope is quite simple: its value equals the ratio of the change in Y to the change in X.

As an example, consider the green line in the chart above. It shows that Y increases from 0 to 1 when X grows from 0 to 3, which means that the coefficient for this line is a=(1-0)/(3-0)=1/3=0.33.

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

When using XY pairs, the value of b is automatically calculated so that the next line segment smoothly continues the previous one.

Calculating the value of b is not as simple as the slope coefficient since usually it has no clear analogy outside of mathematics other than the displacement of the line up or down.

The only exception is when a digital sensor is set up using the calculation table. In this case, a=0, and the formula becomes Y=b. Therefore, the value of b will be equal to what you expect to see as Y.

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:

Since the lower bound is within the allowed range, we can specify the values from the condition — 3 or 0. But the upper limit is not included in the allowed range, so in this field you need to specify a value slightly higher than in the condition — 250.1 or 100.1.

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⋅X2 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⋅X2 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⋅X2 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⋅X2 by lines built on six points

From the considered example, we can draw the following conclusion: the relationship between X and Y can be described by a formula, but also it can be simplistically described with the help of several straight lines. This is the essence of using the calculation table.

 It’s Math Time

The calculation table uses point approximation and linear interpolation.

Point approximation is finding a function that is close to the original one, based on a set of pre-known values. In Wialon, it is used to roughly reproduce a function based on XY pairs.

Linear interpolation is the calculation of values in the areas between initially known points along straight lines that pass through these points. In Wialon, it is used to calculate the values at the points that are between the previously entered XY pairs.

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

In digital sensors, the slope coefficient always equals 0.

The ignition status chart depending on voltage

 It’s Math Time

The article has already mentioned several times that the sensor ideally needs a formula for the relationship between X and Y, and we use the calculation table due to the lack of this formula. In fact, you can try to calculate such a formula, but to do this, you need to have an idea about numerical methods of analysis and the corresponding software. Unfortunately the result is likely to be intricate and hard to adjust in the future. To demonstrate this, we calculated an interpolation polynomial for the following 7 points: (0; 5), (400; 8), (1000; 22), (1850; 78), (2800; 160), (3600; 195), ( 4096; 200).

The result of polynomial interpolation, in this case, is as follows:

Y=1.78962834270398⋅10-19⋅X6-7.99064624017665⋅10-16⋅X5-4.83816855045549⋅10-12⋅X4+
+2.62803612257704⋅10
-8⋅X3-1.24091655860425⋅10-5⋅X2+8.58707470047479⋅10-3⋅X+5

This formula can be entered in the Parameter field in the sensor properties taking into account the Wialon syntax, and it will work. The chart of such a function in the range from 0 to 4096 looks like this:

However, if the described dependence has a more complex form than shown in the chart above, you will have to take more points or use a different interpolation method. It might lead to the result that is even harder to understand. Therefore, linear interpolation, which is used in the calculation table in Wialon, looks very advantageous against this background since it is quite accurate and easy to use.

Oleg Zharkovsky,Customer Service Engineer

Sensors: Logic and Alternatives to Validation
  • technical_consulting
  • sensors
  • validation

One of the first and crucial stages of working with Wialon is setting up sensors in the unit. This article will provide a detailed explanation of sensor validation, as it has some non-obvious use cases and allows users to perform unique actions with 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. 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.

In some cases, the same result can be achieved using different methods. For example, summing the values of two sensors can be done using both an expression in the Parameter field and validation. Similar cases will be considered further.

When to use validation

Validation is used in cases where it is necessary to link the value of one sensor to another. In terms of practical applications, the following cases can be distinguished for using validation:

  • one sensor affects another at the physical level (for example, a fuel level sensor shows the wrong value when there is a jump in the voltage sensor readings);

  • it is necessary to link several sensors into a logical scheme (for example, it is necessary to create a sensor for opening the front doors of a car, which will be activated when either the left door opening sensor or the right door opening sensor is on);

  • it is necessary to display a report for a time interval, where an old sensor with one parameter was used at the beginning and a new sensor with another parameter was used at the end (for example, a less accurate fuel level sensor with one calibration table was previously used on a truck and then it was replaced with a more accurate fuel level sensor with another calibration table);

  • several sensors are measuring the same parameter and it is necessary to display the value of one or the other sensor (for example, a more accurate fuel level sensor was installed on a vehicle in addition to a less accurate factory-installed fuel level sensor, and usually the readings of the more accurate one are used, but if they have an error, it is better to read the values of the factory-installed sensor, even though they are less accurate);

  • the parameter contains information about different systems of a unit, and only a certain part needs to be extracted from it (for example, the first 5 bits of the parameter indicate voltage, while the subsequent bits have a different purpose, and only those bits related to voltage are to be extracted from the parameter);

  • some arithmetic calculations need to be performed that involve values from several sensors (for example, it is necessary to see the real-time fuel consumption in km/l, which is calculated by dividing the reading from the relative odometer by the reading from the instant fuel consumption sensor).

Types of validation

There are 12 types of validation in Wialon. You won't see such a division in the monitoring system interface, but for simplicity, all types can be roughly divided into 3 groups.

GroupValidation typesCommentAlternatives
Arithmetic
  • Sum up
  • Subtract validator from sensor
  • Subtract sensor from validator
  • Multiply
  • Divide sensor by validator
  • Divide validator by sensor

You can easily work without these types.

Alternatives exist and are simple.

Algorithmic
  • Not-null check
  • Replace sensor with validator in case of error

Both types are used frequently.

There is a simple alternative for the second type.

Logical
  • Logical AND
  • Logical OR
  • Math AND
  • Math OR

The least clear types, usually only the first two are used.

Alternatives exist, but they are not simple.

Let's consider each group in more detail.

Arithmetic validation

This group includes basic arithmetic operations: addition, subtraction, multiplication, and division.

You can easily work without these types of validation, as similar results can be achieved using an expression in the Parameter field. To refer to the value of another sensor in the expression, you need to specify the name of this sensor in the square brackets (for example, [Fuel Level]).

The following example illustrates a small difference between these approaches.

 Example

Let's suppose messages are received from a unit with the following parameters:

  • odometer, which displays the distance in kilometers traveled between the last two messages;
  • fuel_consumption, which displays the fuel in liters spent between the last two messages.

The client needs a sensor that will show real-time consumption in km/l.

Here is the solution using validation:

  1. Create an Instant fuel consumption sensor named InsFCS based on the fuel_consumption parameter.
  2. Create a Custom sensor named Consumption with km/l as a unit of measurement. Specify the odometer as a parameter. In the properties of the Consumption sensor, specify the InsFCS sensor as a validator and choose the Divide sensor by validator validation type.

The solution using an expression:

  1. Create a sensor with the Relative odometer type named Relative mileage based on the odometer parameter.
  2. Create an Instant fuel consumption sensor named InsFCS based on the fuel_consumption parameter.
  3. Create a Custom sensor named Consumption with km/l as a unit of measurement. Use a formula with the names of the previously created sensors in square brackets: [Relative mileage]/[InsFCS].

As you can see, when using validation, it is enough to create 2 sensors, not 3. In this case, however, none of the sensors will show the mileage value between messages. Nevertheless, if you need to create a sensor with the Relative odometer type for solving other tasks, then the solution using an expression will be more convenient.

Algorithmic validation

This group includes only 2 types of validation, and we will consider each of them.

Not-null check

This type of validation is one of the most commonly used. It allows ignoring incorrect readings of the validated sensor, while their availability is determined by the zero value of the validating sensor (the validator).

The most common situation of application is as follows: a sensor connected to the tracker may show incorrect data when the voltage is insufficient.

 Example

Let's suppose the following sensors are created in the unit:

  • Fuel level sensor named FLS, which is based on the parameter fuel_lvl;
  • The Voltage sensor named Voltage, which is based on the parameter pwr_ext.

When the voltage value drops below 9 volts, an analog fuel level sensor shows incorrect values. To control fuel properly, it is necessary to get rid of false readings.

In this case, it is necessary to follow the next steps:

  1. Create a Custom digital sensor named Sufficient voltage based on the [Voltage] expression.
  2. Add a calculation table with the following rows:
    X=0; a=0; b=0
    X=9; a=0; b=1
  3. In the properties of FLS, specify the Sufficient voltage sensor as a validator and select Not-null check as the type of validation.

Now, when the voltage drops below 9 volts, the Sufficient voltage sensor will have a value of 0 (Off), therefore, the not-null check will not be passed, so the FLS readings will be replaced with a dash (N/A). This will exclude incorrect data from the analysis.

The use of the Not-null check validation is possible not only in situations where sensors are physically linked to each other (in the example above, the operation of the sensor is affected by insufficient voltage), but also in cases where there is a correlation between sensor values. For example, if you notice that for some reason FLS shows false values when the temperature sensor shows a value of 255, this is enough to use this type of validation.

Replacing the sensor with a validator in case of an error

This type of validation is also quite popular. Its logic is simple: if the validated sensor has an erroneous value, it is replaced with the value of the validator.

This is the only type of validation that can react to erroneous sensor values, which are displayed as a dash or N/A. All the other types of validation will display an error both on input and output.

This type is suitable for situations where it is necessary to display the value of two sensors as if they were one sensor. There are usually two reasons for this: either an old sensor has been replaced with a new one, and reports should contain information for both the old and new sensor intervals, or there are two sensors on the unit at the same time, but one of them occasionally displays an error, and at this moment it is necessary to display the value of the other sensor. Let's consider both cases with examples.

 Example 1

Let's suppose that messages with the following parameters were received from the unit within the reporting interval:

  • adc1, which displays the fuel level in volts according to the previously installed fuel level sensor (the parameter is missing in new messages);
  • param4, which displays the fuel level in volts according to the new fuel level sensor (the parameter is missing in old messages).

It is necessary to set up the sensors so that the report can display data on fuel from both old and new sensors.

In such a case, follow these steps:

  1. Create a Fuel level sensor named FLS (old) based on the adc1 parameter. It is necessary to enter the old calibration table into the FLS (old) calculation table to convert volts to liters.

  2. Create a Fuel level sensor named FLS based on the param4 parameter. It is necessary to enter the new calibration table into its calculation table to convert volts to liters. In the properties of FLS, specify the FLS (old) sensor as a validator and select the Replace sensor with validator in case of error as a type of validation.

This task can be solved using an expression in the Parameter field, namely using the Value availability check operation. To do this:

  1. Create a Fuel level sensor named FLS (old) based on the adc1 parameter. It is necessary to enter the old calibration table into its calculation table to convert volts to liters.
  2. Create a Fuel level sensor named FLS based on the param4|[FLS (old)]. It is necessary to enter the new calibration table into its calculation table to convert volts to liters.
 Example 2

Let's suppose that messages are received from the unit containing the following parameters:

  • fls_rs485, which displays the fuel level in volts according to the installed fuel level sensor;
  • fuel_lvl, which displays the fuel level in liters according to the factory-installed fuel level sensor.

The installed FLS is more accurate, but sometimes it displays an error, and once it happens, the client wants to see the readings of the factory-installed FLS.

In this case, it is necessary to follow the next steps:

  1. Create a Custom sensor named Factory-installed FLS based on the fuel_lvl parameter.
  2. Create a Fuel level sensor named FLS based on the fls_rs485 parameter. It is necessary to enter a calibration table into the FLS calculation table to convert volts to liters. In the properties of FLS, specify the Factory-installed FLS sensor as a validator and select Replace sensor with validator in case of error as the type of validation.

Logical validation

This group includes 4 types of validation:

  • Logical AND and Logical OR, which work with logical values (in Wialon they are called digital, that is, On/Off or 1/0);
  • Math AND and Math OR, which work separately with each bit of numbers.

Let's consider these types with examples.

Logical AND/OR

For simplicity, the Logical AND operation gives a value of 1 as a result only when both input values are equal to 1, and the Logical OR gives a value of 1 if at least one of the input values is equal to 1.

If we assume that two sensors are linked by validation, and one of them is based on parameter a, and the other is based on parameter b, then all possible results can be described using one table:

Truth table
aba AND ba OR b

0

000
0101

1

001

1

111

After performing logical AND/OR operations, the value of the validated sensor will always be equal to 0 or 1 (in this case, an error is not considered, i.e., it's going to be a dash or N/A).

Only values of 0 or 1 are also expected at the input. However, in Wialon, there may be a situation where other numerical values are input for validation. In this case, the system will operate as follows:

  • Only 0 is perceived as 0 (Off).
  • Any other numerical value (for example, 0.01, -0.01, 100500, -777, etc.) will be perceived as 1 (On).

Ideally, it is worth avoiding such situations and using a calculation table to convert all incoming values to only 0 or 1.

 Example 1

Let's suppose that messages are coming from a unit containing the following parameters:

  • in3, which equals 0 when the attachment equipment is turned off, or 1 when it is turned on;
  • in4, which equals 0 when the rear door is closed, or 1 when it is open.

It is necessary to create a sensor that will be activated when the attachment equipment is on and the rear door is open.

In this case, it is necessary to do the following steps:

  1. Create a Custom digital sensor named Attachment equipment, based on parameter in3.

  2. Create a Custom digital sensor named Rear door is open when the equipment is on based on parameter in4. Then select the Attachment equipment sensor as the validator and choose the Logical AND validation type.

This problem can also be solved using an expression in the Parameter field. To do this, it is enough to create a Custom digital sensor named Rear door is open when the equipment is on based on the expression in3*in4.

This approach will work if the parameters can only have values of 0 or 1.

 Example 2

Let's suppose that messages are coming from a unit containing the following parameters:

  • door11, which equals 0 when the left front door is closed, or 1 when this door is open;
  • door12, which equals 0 when the right front door is closed, or 1 when this door is open.

It is necessary to create a sensor that will be activated when at least one of the front doors of the car is open.

In this case, follow these steps:

  1. Create a Custom digital sensor named Left front door is open, based on parameter door11.

  2. Create a Custom digital sensor named Front doors are open, based on parameter door12. Then specify the Left front door is open sensor as the validator and choose the Logical OR validation type.

This task can also be solved using an expression in the Parameter field and a calculation table:

  1. Create a Custom digital sensor named Front doors are open based on the expression door11+door12.
  2. Add a calculation table to the sensor with the following rows:
    X=0; a=0; b=0
    X=1; a=0; b=1

This approach will work if the parameters can only have values of 0 or 1.

Math AND

This validation is useful for extracting a specific part of the bits from a parameter. It involves bitwise execution of the Logical AND operation, as demonstrated below.

First, convert the considered number must be from decimal (DEC) to binary (BIN) numeral system using the Calculator application in programmer mode or similar online tools.

For example, the result of the math AND between the numbers 122 and 15 will look like this:


DECBIN
number 112201111010
number 21500001111

result of math AND

1000001010

If the bit in the second number is equal to 0 (highlighted in red), then the final value of this bit will also be 0. If the bit in the second number is equal to 1 (highlighted in green), then the final value of this bit will be equal to the value of the bit in the first number. We can say that using the binary representation of the number 15, the number 122 was filtered in such a way as to leave only the 4 least significant bits in it.

 Example 1

Let's suppose that we receive messages from the unit with a 16-bit parameter can_a1 that contains information about different systems of the unit. Based on the tracker documentation, information about the fuel level is contained in the 8 least significant bits of the parameter. It is necessary to verify this and extract part of the parameter from the 8 least significant bits to create a fuel level sensor based on them.

For example, when a 100-liter tank is filled up to 40%, the value of the parameter can_a1 may have the following values:

DECBIN
169980100001001100110
267260110100001100110
408061001111101100110
390141001100001100110

As you can see, the value of the parameter can_a1 can change in decimal representation. But at the same time, the 8 least significant bits of the parameter remain unchanged (they are highlighted in blue), as the amount of fuel in the tank does not change. If we convert the values of the 8 least significant bits into decimal, we get:

(BIN) 0110 0110 = (DEC) 102

The maximum value that can be stored in 8 bits is:

(BIN) 1111 1111 = (DEC) 255

Using simple arithmetic operations, we verify that 102/255 = 40/100 = 0.4. This brings us to the conclusion that the 8 least significant bits of the parameter indeed correspond to a tank filled up to 40%.

To extract the first part of the parameter, you need to follow these steps:

  1. Create a Custom sensor named 8 least significant bits based on the const255 parameter.
  2. Create a Fuel level sensor named FLS based on the can_a1 parameter. Then select the 8 least significant bits sensor as a validator and choose Math AND validation type. Also, it is necessary to enter a calibration table into the sensor calculation table to convert the result into liters.

Since each bit can have different values in different messages, let's label the least significant bits as b and the most significant ones as B:


DECBIN
can_a1
BBBBBBBBbbbbbbbb
number 22550000000011111111
result of math AND
00000000bbbbbbbb

As a result, using the binary representation of the number 255, the can_a1 parameter was filtered in such a way as to leave only the 8 least significant bits in it.

This task can be solved using an expression in the Parameter field.

To do this, create a Fuel level sensor named FLS based on the following expression:

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

More details about such a solution can be found in the article about working with bits.

 Example 2

Let's suppose that we receive messages from the unit with a 16-bit parameter can_b2 that contains information about different systems of the unit. Based to the tracker documentation, information about the fuel level is contained in the 8 most significant bits of the parameter. It is necessary to verify this and extract part of the parameter from the 8 most significant bits to create a fuel level sensor based on them.

For example, when a 200-liter tank is filled up to 60%, the value of the parameter can_b2 may have the following values:

DECBIN
392821001100101110010
392621001100101011110
393621001100111000010
392861001100101110110

As you can see, the value of the parameter can_b2 can change in decimal representation. But at the same time, the 8 most significant bits of the parameter remain unchanged (they are highlighted in blue), as the amount of fuel in the tank does not change. If we convert the values of the 8 most significant bits into decimal, we get:

(BIN) 1001 1001 = (DEC) 153

The maximum value that can be stored in 8 bits is:

(BIN) 1111 1111 = (DEC) 255

Using simple arithmetic operations, we verify that 153/255 = 120/200 = 0.6. This brings us to the conclusion that the 8 most significant bits of the parameter indeed correspond to a tank filled up to 60%.

To extract the second part of the parameter, it is necessary to do the following:

  1. Create a Custom sensor named 8 most significant bits based on the parameter const65280.
  2. Create a Custom sensor named Filtered bits based on the parameter can_b2. Then select the 8 most significant bits sensor as a validator and select the Math AND validation type.

  3. Create a Fuel level sensor named FLS based on the expression [Filtered bits]/const256. It is necessary to enter a calibration table into its calculation table to convert the result into liters.

Since each bit can have different values in different messages, let's label the least significant bits as b and the most significant ones as B:


DECBIN
can_b2
BBBBBBBBbbbbbbbb
number 2652801111111100000000
result of math AND
BBBBBBBB00000000
result after division by 256
00000000BBBBBBBB

Shifting bits down by several digits occurs through division by 2 to the power, which is equal to the number of digits to shift. In this case, we need an offset by 8 digits, so division is carried out by 28 = 256.

As a result, using the binary representation of the number 65280, the can_b2 parameter was filtered in such a way as to leave only the 8 most significant bits in it, and then they were converted into the least significant bits using the offset.

This task can be solved using an expression in the Parameter field.

To do this, create a Fuel level sensor named FLS based on the following expression:

const128*can_b2:16+const64*can_b2:15+const32*can_b2:14+const16*can_b2:13+const8*can_b2:12+
const4*can_b2:11+const2*can_b2:10+const1*can_b2:9

More details about such a solution can be found in the article about working with bits.

Math OR

This validation implies bitwise execution of the Logical OR operation, as demonstrated below.

First, convert the considered number must be from decimal (DEC) to binary (BIN) numeral system using the Calculator application in programmer mode or similar online tools.

For example, the result of the math OR between the numbers 122 and 210 will look like this:


DECBIN
number 112201111010
number 221011010010
result of math OR25011111010

If at least one of the bits in the first two numbers is equal to 1, then the final value of this bit will be equal to 1 (highlighted in green). If both bits in the first two numbers are equal to 0, then the final value of this bit will be equal to 0 (highlighted in red).

Oleg Zharkovsky,Customer Service Engineer

Sensors: Working with Bits
  • technical_consulting
  • sensor_parameters

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×1021 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:

Name

Symbol

Base

Application field

Characters used

Binary

BIN2

Discrete mathematics, computer science, programming

0, 1

Decimal

DEC10

Everywhere

0, 1, 2, 3, 4, 5, 6, 7, 8, 9

Hexadecimal

HEX16

Computer science, programming

0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F

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).

Numbers in Wialon are displayed in a decimal numeral system. The exceptions are text parameters, where numbers can be used (for example, a driver's unique identification hexadecimal code), and digital inputs and outputs in I/O format.

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

Binary numeral system and binary code are different terms. The first term relates to mathematics (theory), and the second one relates mainly to digital technologies (practical application). These terms intersect in many ways, so further in the article, we will jump between them, but it should not affect the understanding of the topic at the level of immersion we need.

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.

Bit numbering in Wialon starts from 1. Usually, bit numbering starts from 0, so the formulas that you will see below may differ slightly from those found on the Internet or other sources.

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 × 105 — here, the mantissa is 1.25 and the exponent is 5.

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

125000000000000 = 1.25 × 1014 — 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.

Examples of their use can be found in the instructions.

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 × 103−1 + 2 × 102−1 + 5 × 101−1 = 1 × 1022 × 101 + 5 × 100

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 bi is the value of the i-th bit.

This formula can also be presented in the following way:

d = bN × 2N−1 + ... + bi × 2i−1 + ... + b2 × 22−1 + b1 × 21−1

Let’s consider an example with the same number:

(BIN) 0111 1101 = (DEC) 0 × 28−1 + 1 × 27−1 + 1 × 26−1 + 1 × 25−1 + 1 × 24−1 + 1 × 23−1 + 0 × 22−1 + 1 × 21−1 =

= (DEC) 0 × 27 + 1 × 26 + 1 × 25 + 1 × 24 + 1 × 23 + 1 × 22 + 0 × 21 + 1 × 20 = (DEC) 26 + 25 + 24 + 23 + 22 + 20 =

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

This formula is the key to working with bits in Wialon. All other conversions are performed on this basis.

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 223 = 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.

Parameter

user_value

Original value bit number

16151413121110987654321

Bit value

0111110111001000

Desired value bit number

8765432187654321

Sensor

Counter #2

Counter #1

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 bi is the value of the i-th bit.

This formula can also be presented in the following way:

d = (−1)bN × (bN-1 × 2(N−1)−1 + ... + bi × 2i−1 + ... + b2 × 22−1 + b1 × 21−1)

This formula works because (−1)0 = 1 and (−1)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/223),

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.

 Additional information

The above formula does not use the exponent, which can be negative (for example, 1.25×10−7), but the biased exponent E, which is always positive. The reverse bias is achieved by subtracting 127 from the biased exponent at the stage of calculating the result that allows you to get negative values.

The normalized binary mantissa lies in the range [1; 2), that is, its first bit is always equal to 1. Therefore, in the IEEE 754 standard, this 1 is not sent (because it is already known), but is added to the formula at the stage of calculating the result. This allows you to save one bit and get more precision of the transmitted value. In the above formula, M is not the mantissa, but its remainder.

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

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

Sign bit (S)

Biased exponent (E)

Remainder of normalized mantissa (M)

3231302928272625242322212019181716151413121110987654321
10011101110000101101111000101101

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)1 × 2(59−127) × (1 + 4382253/223) = −0.00000000000000000000515811 = −5.15811×10−21

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

The formula for converting a binary normalized number to a 32-bit IEEE 754 format is the same for all trackers since we are talking about a specific standard. If you see in the tracker documentation that a user parameter can be sent according to the IEEE 754 standard, and you choose this sending format, then for interpretation in Wialon you can copy the expression for the sensor directly from this article, replacing only the user_value parameter name in it, but without changing the bit numbers.

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

Incorrect Mileage
  • technical_consulting
  • trips

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.

Wialon has a limitation: no more than 1 message should come from a unit per 1 second. If the terminal transmits more than 1 message per 1 second, the chronology of messages may be disrupted and the track will look the same. The reason is incorrect arrangement of messages with positional data (coordinates) in the Wialon database. In such cases, you should reduce the frequency of sending messages with data in the terminal settings.

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.
 Explanation

Let's agree that the unit actually traveled 2 km, and messages came in the following order:

  1. 10 km
  2. -- km
  3. -- km
  4. 15 km

In the Mileage column, we get 2 km (the total distance between coordinates without considering the mileage sensor); in the Initial mileage column, we get 10 km (as in the message); in the Final mileage column, we get 15 km (as in the message).

A similar example, but the value of the mileage sensor is available only in the last message:

  1. -- km
  2. -- km
  3. -- km
  4. 15 km

In the Mileage column, we get 2 km (the total distance between coordinates without considering the mileage sensor); in the Final mileage column, we get 15 km (as in the message).

And one more example, where the mileage sensor value is only available in the first message:

  1. 10 km
  2. -- km
  3. -- km
  4. -- km

In the Mileage column, we get 2 km (the total distance between coordinates without considering the mileage sensor); in the Initial mileage column, we get 10 km (as in the message).

  • 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.
 Explanation

Let's agree that the unit actually traveled 2 km, and messages came in the following order:

  1. -- km
  2. -- km
  3. -- km
  4. 15 km

In the Mileage column, we get 2 km (the total distance between coordinates without considering the mileage sensor); in the Initial mileage column, we get 15 km — the value calculated from GPS coordinates or 15 km - 2 km = 13 km; in the Final mileage column, we get 15 km (as in the message).

  • 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.
 Explanation

Let's agree that the unit actually traveled 2 km, and messages came in the following order:

  1. 10 km
  2. -- km
  3. -- km
  4. -- km

In the Mileage column, we get 2 km (the total distance between coordinates without considering the mileage sensor); in the Initial mileage column, we get 10 km (as in the message); in the Final mileage column, we get 10 km + the value calculated from GPS coordinates or 10 km + 2 km = 12 km.

  • 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.
 Explanation

Let's agree that the unit actually traveled 2 km, and messages came in the following order:

  1. -- km
  2. 10 km
  3. 15 km
  4. -- km

In the Mileage column, we get 2 km (the total distance between coordinates without considering the mileage sensor); in the Initial mileage column, we get 10 km — the value calculated from GPS coordinates before the first message of the interval; in the Final mileage column, we get 10 km + the value calculated from GPS coordinates before the last message of the interval.

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.

If you have any questions on specific practical cases, you can contact technical support via email support@wialon.com. Make sure to indicate in your email a brief description of the situation with screenshots, the exact unit name, the report template name for verification, the minimum time interval for verification (for example, not a month, but one day), and other essential details.

Pavel Chebotarev,Customer Service Engineer

Eco Driving Control
  • technical_consulting
  • eco_driving

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/s2), 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/s2 (the approximation g ≈ 10 m/s2 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).

An acceleration of 1 g corresponds to an acceleration from 0 to 100 km/h in 2.83 seconds.

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

Movement type

Average acceleration
m/s2kmph/sg

Passenger lift

0.9—1.63.2—5.60.09—0.16

Subway train

13.50.1

Short distance runner

1.55.30.15

Cyclist

1.760.17

Passenger car

2.5—38.8—10.60.25—0.3

Motorbike

3—610.6—21.20.3—0.6

Racing car

8—928—320.8—0.9

Emergency vehicle braking

up to 20up to 70up to 2

Spacecraft launch and landing

40—60140—2104—6

Jet aircraft maneuver

up to 100up to 350up to 10
 Example of calculation of speed and acceleration

Using the formulas above, let's calculate the speed and acceleration based on the unit’s coordinates received from the tracker.

As part of the example, we will count the time from 0 seconds. For simplicity, we will assume that the vehicle always moved in a straight line, and it's speed changed uniformly between messages.

Message number

12345678

Time, s

0510204070100103

Distance, m

002515040090014001430

Speed, km/h

0018454560600

Acceleration, g

0.0000.0000.1020.0770.0000.0140.000-0.567

Based on the table and chart, we come to the following conclusions:

  • The speed is 0 when the vehicle does not change position.
  • Acceleration is 0 when the vehicle does not change speed (stands still or moves at the same speed).
  • A positive acceleration value corresponds to an increase in speed and a negative value to a deceleration.
  • The amount of acceleration indicates how quickly and how much the speed has changed between messages.

This example allows us to evaluate the relationship between position, velocity, and acceleration. The data coming from a real vehicle may differ from those given in the example as it contains simplifications.

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.

A tracker with an accelerometer or a separate accelerometer sensor may have axes drawn on the body, it must be placed on the vehicle according to them.

There is no single rule for the direction or naming of axes. That is, the Z axis can be directed not up but down, or instead of the X axis, the Y axis can be directed forward. This information can found in the device documentation.

When installing the device on a vehicle, make sure it is firmly fixed.

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.

Types of trackers

Accuracy

Difficulty of settings

Calculate acceleration by

Message frequency

Sensors creation

Criteria for acceleration control

1. Tracker sends calculated eco driving parameters

HighEasyEco driving parametersAnyNot requiredAcceleration,
Braking, Turn,
Reckless driving

2. Tracker sends calculated acceleration parameters in a custom format

HighAverageNo matterAnyRequiredCustom

3. Tracker sends raw values of acceleration along the axes

AverageHighNo matter1 per 2 secondsRequiredCustom

4. Tracker does not send any data of acceleration

LowEasyGPS1 per 2 secondsNot requiredAcceleration,
Braking, Turn,
Reckless driving

Here are some details on each of the approaches:

1. Tracker sends calculated eco driving parameters

This approach applies only to certain types of devices that use special algorithms for processing data from the accelerometer. You can find the list of them on the wialon.com website in the Hardware section using the ECO driving filter.

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.

This type of device may not have a calibration procedure, which requires individual settings for each axis to obtain accurate acceleration readings.

It is worth repeating that there is no single rule for the direction or name of the axes. You can find out the directions of the axes of your device from its documentation.

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.

If the tracker does not send information about the direction of movement (the course parameter), then the system will not be able to detect violations according to the criteria with the Turn type.

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.

If you use standard criteria presets for different units, then even if you are not sure about the correctness of the values in the criteria, you will be able to see the relative score obtained by the same rules. This should be enough for comparison within the same fleet.

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

Math Consumption
  • technical_consulting
  • fuel
  • fuel_consumption
  • math_consumption

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 Calculate drains by time 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 ⋅ ( CI 1 + CI 2 + ... + CI N ) ⋅ (KEES 1 + (KEES 2 - 1) + (KEES 3 - 1) + ... + (KEES M - 1)),

where Δt — the time between messages; CI 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; KEES 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.

We should note that the given formula applies only to bound sensors. If there is no EES in the unit or they are not bounded with engine operation sensors, then a short formula is used:

Δt ⋅ ( CI 1 + CI 2 + ... + CI N )

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.

The more data you enter, the more accurately the mathematical model will work, but the minimum information you should provide is urban cycle consumption.

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 Calculate drains by time 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.


If you have any questions on specific practical cases, you should contact technical support via support@wialon.com. Make sure to indicate in your email a brief description of the situation with screenshots, the exact unit name, the report template name for verification, the minimum time interval for verification (for example, not a month, but one day), and other essential details.



Oleg Zharkovsky,Customer Service Engineer



Differences in Fuel Algorithms
  • technical_consulting
  • fuel

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:
    • Calculate fuel consumption by time
    • Calculate fillings by time
    • Calculate drains by time – 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.

If you have any questions on specific practical cases, you should contact technical support via support@wialon.com. Make sure to indicate in your email a brief description of the situation with screenshots, the exact unit name, the report template name for verification, the minimum time interval for verification (for example, not a month, but one day), and other essential details.

Oleg Zharkovsky,Customer Service Engineer




Fuel Filling is Not Detected
  • technical_consulting
  • fuel
  • fuel_fillings

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.

 Explanation

The fuel level in the tank fluctuates due to engine operation, acceleration, braking, turning, road bumps, vehicle tilt, and so on.

The higher the filtration level, the stronger is the smoothing used to compensate for FLS readings fluctuations. The stronger the smoothing, the easier it is to analyze the processed data, but the more distorted the input information is. Thus, to obtain the needed accuracy, you should set the filtration level to the minimum required. If the filtration level is too high, the processed data may no longer contain the fuel level difference corresponding to the filling. In most cases, it’s not recommended to use a filtration level higher than 10.

Often, test fuel fillings are not displayed for this very reason: they are performed immediately after or before fuel draining, that’s why a short-term fuel level change is ignored due to smoothing. Actual fillings don’t imply the return of the fuel level to the previous state, so they will not be missed for the indicated reason.

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.

 Explanation

This option acts as a kind of coarse filter separating fillings and normal fuel level fluctuations, which will remain even despite the use of filtration. Consequently, you should choose the Minimum fuel filling volume in proportion to the value of these fluctuations that in some cases can even reach 20 liters or more.

If you set a too high Minimum fuel filling volume, the actual filling may disappear from the report results.

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.

 Explanation

Speed determined by the tracker and displayed in the monitoring system doesn’t always clearly indicate that the unit is moving. This happens due to the inaccuracy of satellite navigation systems (GPS, GLONASS, and so on). To determine the fact of driving, the Min moving speed is used, which defines the minimum threshold of the speed value recognized by the system as a movement.

In rare cases, speed value inaccuracy reaches large values, which can be associated with both the tracker quality and the environment (terrain, being in a building, the presence of large metal structures nearby, and so on). Some trackers can independently mark messages with inaccurate speed as invalid. However, using Messages validity filtration, you can find and filter out such invalid messages already in Wialon. This filtration applies only to messages that arrive on the server after enabling the appropriate settings, that’s why you’ll have to delete previous invalid messages manually.

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.

 Explanation

Fuel level sensors may be inert, i.e., send data with time delays. For some FLS, this is a consequence of built-in filtration; in other cases, the delayed data arrival points at the need of FLS maintenance (for example, cleaning the drain hole).

4. Filling is marked as false and then hidden

Try to enable the Show false events option in the report template settings. Then execute the report again and unmark the filling so that it isn't regarded as a false one.

 Explanation

There is a possibility to mark fillings as false in the reports. It is done when current settings of the fuel level sensor are regarded as optimal for the unit, but the system still display incorrect fillings according to the incoming messages.

Fillings marked as false are shown in the report only when the corresponding option is enabled.

None of the variants work

You are probably faced with a more complicated situation than those discussed above, and you should contact technical support via support@wialon.com. Make sure to indicate in your email the exact unit name, the report template name for verification, the minimum time interval for verification (for example, not a month, but several days), and other essential details.

Oleg Zharkovsky,Customer Service Engineer

Fuel Drain is Not Detected
  • technical_consulting
  • fuel
  • fuel_thefts

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.

 Explanation

The fuel level in the tank fluctuates due to engine operation, acceleration, braking, turning, road bumps, vehicle tilt, and so on.

The higher the filtration level, the stronger is the smoothing used to compensate for FLS readings fluctuations. The stronger the smoothing, the easier it is to analyze the processed data, but the more distorted is the input information. Thus, to obtain the needed accuracy, you should set the filtration level to the minimum required. If the filtration level is too high, the processed data may no longer contain the fuel level difference corresponding to the drain. In most cases, it’s not recommended to use a filtration level higher than 10.

Often, test fuel drains are not displayed for this very reason: they are performed immediately after or before the filling, that’s why a short-term fuel level change is ignored due to smoothing. Actual drains don’t assume the return of the fuel level to the previous state, so they will not be missed for the indicated reason.

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.

 Explanation

The 1% FLS accuracy declared by some manufacturers often doesn’t allow detecting small drains in real conditions due to the fuel fluctuations in the tank mentioned above. That’s why it would be quite optimistic to set, for example, a 1-liter Minimum fuel drain volume right away. This option acts as a kind of coarse filter separating drain and normal fuel level fluctuations, which will remain even despite the use of filtration. Consequently, you should choose the Minimum fuel drain volume in proportion to the value of these fluctuations that in some cases can even reach 20 liters or more.

If you set a too high Minimum fuel drain volume, the actual drain may disappear from the report results.

3. Drain takes place during short stops

Try to reduce the Minimum stop duration to detect a fuel drain in the fuel level sensor settings.

 Explanation

During a short stop, the fuel level can change significantly, therefore the analysis of short stops will result in detecting wrong drains. Using the Minimum stop duration to detect a fuel drain option, you can configure the system to monitor drains only during long stops and idle time.

If you set a too long Minimum stop duration to detect a fuel drain, then a long stop or idle time can be excluded from the analysis, and drain will not be registered.

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 Calculate drains by time.

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.

 Explanation

Speed determined by the tracker and displayed in the monitoring system doesn’t always clearly indicate that the unit is moving. This happens due to the inaccuracy of satellite navigation systems (GPS, GLONASS, and so on). To determine the fact of driving, the Min moving speed is used, which defines the minimum threshold of the speed value recognized by the system as a movement.

In rare cases, speed value inaccuracy reaches large values, which can be associated with both the tracker quality and the environment (terrain, being in a building, the presence of large metal structures nearby, and so on). Some trackers can independently mark messages with inaccurate speed as invalid. However, using Messages validity filtration, you can find and filter out such invalid messages already in Wialon. This filtration applies only to messages that arrive on the server after enabling the appropriate settings, that’s why you’ll have to delete previous invalid messages manually.


5. Drain is marked as false and then hidden

Try to enable the Show false events option in the report template settings. Then execute the report again and unmark the drain so that it isn't regarded as a false one.

 Explanation

There is a possibility to mark drains as false in the reports. It is done when current settings of the fuel level sensor are regarded as optimal for the unit, but the system still display incorrect drains according to the incoming messages.

Drains marked as false are shown in the report only when the corresponding option is enabled.

None of the variants work

You are probably faced with a more complicated situation than those discussed above, and you should contact technical support via support@wialon.com. Make sure to indicate in your email the exact unit name, the report template name for verification, the minimum time interval for verification (for example, not a month, but several days), and other essential details.

Oleg Zharkovsky,Customer Service Engineer



How to Get Rid of False Fuel Drains
  • technical_consulting
  • fuel
  • fuel_thefts

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.

There is a possibility to mark drains as false and then hide them from the report result (the Show false events option in the report template settings should be disabled). Such an approach is used when current settings of the fuel level sensor are regarded as optimal for the unit, but sometimes the system still display incorrect drains according to the incoming messages.

Marking drains as false is a manual action, while this article is mainly focused on changing sensor properties that can hide all false drains automatically.

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).

 How filtration works (smoothing of sensor values)

Wialon uses median filtering. For each message, several messages before and after it are taken; altogether, they form a filter window, and then, taking these messages into account, a smoothed value in the center of the window is calculated.

Filtration levelWindow widthNumber of messages before/after the window center
031


N

N — odd5×N(5×N-1)/2
N — even5×N-1(5×N-2)/2

Example

The filtration level is set to 3. The window width will be 5×3 = 15. Consequently, 7 messages are taken before the message concerned and 7 messages after to smooth the fuel level values.

For example, messages 54 through 68 will be used to calculate the value in message 61.

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 stop duration to detect a 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: Calculate fillings by time, Calculate drains by time, and Calculate fuel consumption by time. We should clarify that in this very case, it would be possible to do only with the Calculate drains by time 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).

None of the variants work

This article discusses only false fuel drains, so if you couldn't get rid of drains using the suggested instructions, this may mean one of three variants:

  1. The FLS accuracy is insufficient for a given tank shape, type of vehicle, mode of motion, terrain, etc. The only thing that can help is increasing the Minimum fuel drain volume value in the fuel level sensor settings. In fact, this is not a problem solution, but simply the recognition of the FLS low accuracy and the unit adjustment according to this accuracy.
  2. You are faced with a more complicated situation than those discussed above, and you should contact technical support via support@wialon.com. Make sure to indicate in your email a brief description of the situation with screenshots, the exact unit name, the report template name for verification, the minimum time interval for verification (for example, not a month, but one day) and other essential details.
  3. Probably, the fuel drain actually took place.

Oleg Zharkovsky,Customer Service Engineer

Fuel Traffic
  • technical_consulting
  • fuel
  • fuel_traffic
  • tables

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

Unit type

Sensor type

Opportunities

Refuelling truck

Fuel level sensor (FLS)

Allows displaying fuel dispensing (as drains) and refuelling (filling the tank with fuel).

Refuelling truck

Counter sensor

Allows displaying the amount of fuel dispensed through the fuel filling gun with flow meter.

The use of a counter gives a more accurate result compared to the FLS.

Customer unit

FLS

Allows displaying the volume of filling when receiving fuel from the refuelling truck.

Refuelling truck

Driver assignment

To display a driver's name, a card reader must be installed on the refuelling truck. It is assumed that the driver of the customer unit swipes their card to the refuelling truck's card reader to start dispensing, and for this time they are assigned to the refuelling truck. After the dispensing is completed, the driver must be separated from the unit.

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.

Fuel fillings for potential customers are calculated for the entire report interval, and not only for the time when they were near the refuelling truck at the time of fuel dispensing. This is explained as follows:

  • FLS can be inertial, i.e. display the change of the level not immediately, but with some delay.
  • Wialon uses smoothing by neighboring messages in order to compensate for inaccuracies in the FLS. Thus, for the correct calculation of the filling, it is necessary to take into account the messages before it starts and after it ends.

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.

Wialon uses several timestamps when working with fuel fillings:

  • Beginning of the filling — time from the first message of the filling interval.
  • End of the filling — the time from the last message of the filling interval.
  • Filling time — the time indicated in the message after which the maximum increase in fuel occurred in the filling interval. It is this value that is displayed in the Time column in the Fuel Fillings table.

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.

None of the variants work

Probably, you are faced with a more complex situation than those discussed above, feel free to contact technical support via support@wialon.com. Be sure to indicate in your email the exact name of the unit, the name of the report template to be checked, the minimum time interval for checking (not a month, but several days, for example), as well as other important details.

Oleg Zharkovsky,Customer Service Engineer

Command Does Not Work
  • technical_consulting
  • commands
  • sms

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.

Channel

Peculiarities

GPRS (TCP/UDP)

The unit must keep an Internet connection with the server.

Virtual

This channel is similar to TCP/UDP judging by the principle of sending, but the virtual command can be executed even when the unit is not connected to the server. At the moment of execution, the command is queued, and its actual sending will be done at the moment the unit goes online.

For each type of device, Wialon imposes a limit on the number of virtual commands in the queue, and when the queue is full, a new virtual command will push the oldest command out of the queue (it will not be sent).
SMSThe unit may not keep an Internet connection with the server.
AutoWhen sending, the program will choose the channel that is currently available. If more than one type is available, the channel that is higher in this table will be used.
If the communication channel selected for commands is currently available, the button for command execution opposite the unit on the Monitoring panel will become active.

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.

If the command was not executed when pressing the corresponding button, you should check the compliance with the above-mentioned requirements. If all the requirements were met and the unit did not lose connection at the moment of command execution, you can send a detailed description of the problem (username, unit, command name and execution time) to support@wialon.com for analysis by Wialon technical support specialists.

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.

IssuePossible causesOptions for action
SMS command is not delivered to the unit

Problems with the delivery of SMS messages and TCP/UDP commands are usually associated with problems at the level of telecom operator/Internet provider networks. Together with your provider, you should check the message delivery route, troubleshoot the network, or search for other delivery routes.

If you use the 500 SMS package, write to Wialon technical support at support@wialon.com.
If you use your own SMPP gateway or modem, please contact your SMPP provider or GSM operator to analyze the situation.

The command is delivered but with incorrect text

Typically, this problem is related to the telecom operator encoding and is relevant mainly for SMS messages. Wialon uses the standard A5 (CCITT T.50)/ASCII (ANSI X3.4) encoding. The recipient's operator may use a different protocol and, as a result, decode the message incorrectly.

The user should contact the recipient's operator to correct the situation.

An alternative is to use your own SMPP gateway with the required encoding.
The command is delivered with the correct text, but the tracker did not execute/rejected the command

An incorrect command format is specified in SMS. You should double-check the syntax according to the device manual or contact the hardware manufacturer.

If standard Wialon commands are used (except Custom message), make sure that the correct parameters are specified in the command (for example, the number of the tracker input for activation). You can also contact Wialon technical support at support@wialon.com, providing the detailed problem description.

An SMS command is received from a sender's number that is not added to the allowed list.

Add the allowed number in the tracker settings.

The command is received from an IP not allowed to the tracker.

Add the allowed IP in the tracker settings. IP in Wialon Hosting depends on the service data center, and you can see it in the General tab in the properties of any unit.

The Password for executing commands is not entered in the unit settings (or it does not match the password in the tracker).

Double-check the password for executing commands. It is recommended to use the Latin alphabet for the password, because the tracker may decode other languages incorrectly.

The tracker is defective.

A hardware or software failure at the tracker level should be analyzed with the engineer maintaining this tracker.

The command is delivered, executed by the tracker, but the Wialon system receives no response

For some types of devices, there is an additional hardware protocol setting, where you should activate the corresponding flag or configure settings for receiving and displaying messages from the tracker.

When configuring the device, find and activate the corresponding option in the General tab. The configuration button is located to the right of the device type entry field and is active if the device itself provides the configuration option.

The command came from a virtual number that cannot act as an SMS recipient.

Wialon Hosting uses a virtual number 79037676122. You can contact Wialon technical support at support@wialon.com and clarify whether it’s possible to switch your service to another available sender phone number in order to receive SMS responses from trackers to this number.
If, due to the peculiarities of SMS delivery routes to a certain country, you cannot set a different sender’s number for sending SMS, the most convenient solution would be to connect your own SMPP gateway for your Hosting service with the ability to receive SMS from trackers. To connect your SMPP gateway to the Hosting service, contact your manager (or Wialon technical support for technical advice).


Sergey Novikov,Customer Service Engineer

Telegram notifications
  • technical_consulting
  • notifications_to_telegram

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.

Part of the information (tokens and IDs) in the instructions are hidden, since this is private data. It does not affect the understanding of the guidance.

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

Tachographs and Wialon
  • technical_consulting

A tachograph is a device that monitors compliance with the drivers' working hours (DWH), 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.

 Rules of other countries

The rules listed below are not supported in Wialon, but it may be useful to know about them:

  • In the United States, the function of tachographs is performed by electronic logging devices (ELD), and the rules that determine the work-rest schedule of drivers are called Hours of Service (HOS). For HOS accounting, the Apollo ELD solution was created on the Wialon basis. You can find it on the following website: eld.wialon.com
  • In Australia, the tachograph law is called the Heavy Vehicle National Law and Regulations (NHVL).
  • In the Russian Federation, the rules of use of tachographs are determined by orders of the Ministry of Transport of the Russian Federation (in particular, Order No. 36 of February 13, 2013, Moscow).

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.

The tachograph information displayed in Wialon has no legal force, despite the fact that it may be based on data received from the tachograph.

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:

PictogramNameAlternative namesDescription

Driving

Steering wheel

Used to register the duration of the actual vehicle driving.

Turns on automatically when the driver card is inserted into the first slot, the engine is on, and the vehicle speed is not zero.

Work

Other work,
hammers

Used to register work that is not driving (paperwork, loading and unloading, etc.).

Turns on manually or automatically when the driver card is inserted into the first slot, the engine is on, and the vehicle speed is zero.

Rest

Break,
bed,
chair

Used to register rest time.

Turns on manually or automatically when the ignition is off.

Availability

Valid interruption,
square

Used if there is a second driver in the vehicle crew.

Turns on automatically when a driver card is inserted in the second slot, and for the first driver the Driving or Work mode is displayed.

The use of the modes may differ from the above description (for example, depending on the requirements for loading or the recommendations of the transport company). And the logic of automatic/manual mode switching may depend on the tachograph model.

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.

Wialon can display only data from the driver card. It’s possible to work with the DDD format and other formats with similar structure (for example, TGD, V1B, C1B).

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.

Since the tachograph-tracker-Wialon combination is involved in obtaining information, it is not always possible to solve potential issues on the Wialon side.

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 their 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.

A file from the driver card is the only reliable source for displaying tachograph information in Wialon. The controller sees data from the same source when checking the tachograph readings on the road.

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.

Assignments and trips can only be used as a rough estimate of the DWH compliance. Unlike the tachograph, which determines the current work mode in real time, drivers' assignments/separations and trips in Wialon are determined by messages from the tracker recorded at a certain frequency, which is less than that of the tachograph.

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 Sensata INSIGHTS (ex-BCE), RuptelaTeltonika, and Navtelecom.
  • Assignments and trips from Wialon.

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

Online data can only be used as a rough estimate of the DWH compliance. Unlike the tachograph, which has an algorithm for recalculating previous intervals, Wialon saves online data without further recalculation.

Displaying DWH information

There are several ways to display DWH information in Wialon.

Tacho View

The Tacho View 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.

If assignments and trips are selected as the source, the result of the repeated report execution will change after changing the unit's trip detector settings or when editing the assignment history and registering driver shifts.

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

Working with the Routes Module
  • technical_consulting
  • routes

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

The word route is often used in everyday speech, but in Wialon it is a term. To avoid confusion, let's agree that within the framework of this article, the word route will be used only as a term.

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.

If schedules have not been created for the route yet, you can make changes to the list of check points. If schedules have been created, the route cannot be edited, but it can be copied for future modifications.

Please, keep in mind that routes cannot be transferred from one account to another.


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.

None of the schedule types prohibit entering overlapping ranges of arrival and departure times with variation taken into account. The use of this approach depends on the order of passing the check points.

For example, if the Strict or Skipping possible orders of passing points are chosen, the unit must visit them in a fixed sequence but in case of applying significant variation the visiting time can be almost any. As a result, there is control over the sequence, but not over the visiting time.

If the Arbitrary check points order is chosen, then with significant variation there is control only over the fact of visiting but not over the time and sequence.

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.

Check points

Schedule*

Check points order

Creating a ride

Tracking

Addresses

Absolute

Strict

Manually

Reports

Geofences

Relative to day

Skipping possible

Automatically (Relative to day)

Notifications

Units

Relative to activation

Arbitrary

Automatically (Notifications)

Timeline

* 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

How to Choose a Way to Control Routes
  • technical_consulting
  • routes
  • geofences

Wialon allows you to meet customer needs in various ways. For example, the system offers at least four route control options, each of which has its advantages and disadvantages. This article will help you to compare them to choose the option that best suits your customer's needs.

Considered options

During our comparison, we will focus on the following four options for route control:

  • Routes module — despite its name, this module is suitable only for cases where there is a specific time for visiting check points and there is no need to track the path between them.

  • Combination of geofences, reports, and notifications (this option will be referred to as Geofences) is the most flexible option suitable for most situations but requires configuring several separate elements.

  • Logistics web application is a niche solution for organizing operations of courier services, which can also be used for other business tasks.

  • NimBus web application is a niche solution for public transport operations, which can also be used for other business tasks.

The terminology used in these options differs from each other:


RoutesGeofencesLogisticsNimBus
Point to visitcheck pointgeofenceorderstop
Group of points within one triproute

planned route or templateroute
Time for visiting check pointsscheduletime limitationtime of the estimated arrivalschedule
Movement of a unit through the group of check points

ride

active routeride

It is important to take this difference into account when comparing the considered options.

Comparison by criteria

Now, let’s summarize the considered options in the table, which will indicate how well they meet different criteria, meaning, the customer's requirements. We have tried to make these criteria as practical as possible, based on our experience of communicating with our partners.

Criteria

RoutesGeofencesLogisticsNimBus

Basic
1The same check points every dayyesyesyesyes
2

New check points every day

nopartiallyyesno
3Tracking the path between check pointsnoyesyesyes
4Optimizing the sequence of check pointsyespartiallyyesno
5Optimizing the path between check pointsnopartiallyyesyes
6

Automatic start of tracking the ride

yesyesnoyes

Specific
7Additional conditions for visiting check pointsnopartiallyyesno
8Schedule relative to departure
yesnopartiallyyes
9Transport replacement during the ride executionnopartiallyyesyes
10Long route (more than 2 days)yesyesyesno
11Moving check pointsyesyesnono
12Sending routes to the driverpartiallypartiallyyesno

Displaying information
13Online controlyesyesyesyes
14Reports for the previous periodyesyesyesyes
15Displaying in the monitoring interfaceyesyespartiallyno
16Mobile applicationnoyesyespartially

Now let's consider each of the criteria separately.

1. The same check points every day

Routesyes

Routes allow you to start rides with the same check points every day if the schedules Relative to day or Relative to activation are used.

Geofencesyes

Geofences are not deleted immediately after visiting them, so they can easily be used on other days.

Logisticsyes

Orders correspond to check points. They can be permanent, meaning they are not deleted immediately after visiting.
You can also turn the route into a template to quickly repeat it on other days.

NimBusyes

Public transport stops rarely change their location, so the application is initially designed to work with the same check points every day.

2. New check points every day

Routesno

New checkpoints cannot be added to an already saved route. To add new check points, you need to create a brand-new route, reconfigure schedules, and create rides. It is pretty time-consuming.

Geofencespartially

Creating a new geofence, as well as adding it to reports and notifications, is not a problem. Setting up may take a relatively long time only if there is a need to control the time for visiting check points (via Time limitation in reports and notifications).

Logisticsyes

A new route with new orders can be created very quickly. Adding check points to an already created route is also available.

NimBusno

Since the application is designed to control public transport, and the public transport stops change quite rarely, adding new check points will require changing several settings at once (creating a stop, adding it to the route, changing the schedule), which is time-consuming.

3. Tracking the path between check points

Routesno

The module doesn't track movement between check points. It is assumed that it’s the driver who should choose the route from one address to another in order to stay on schedule.

Geofencesyes

To track the path between check points, you can create a line geofence on the roads that the unit should follow. Notifications with the Geofence type can be used to control leaving or entering to the geofence line.

Logisticsyes

The application has a notification type called Deviation from a route. This notification triggers if the unit moves away from the route line exceeding the distance indicated in the notification.
You can also display the planned and actual route of the unit on the map when completing the route.

NimBusyes

The application has a notification type called Unit left the route path. It is triggered after receiving a message from the unit that is geographically remote from the route path by more than 50 meters.

4. Optimizing the sequence of check points

Routesyes

There is an option to optimize the order of check points when creating a route.
Also, in the monitoring interface, you will find the Routing tool. Among other things, this tool allows you to optimize the sequence of check points and save the result as a route.

Geofencespartially

In the monitoring interface, you will find the Routing tool. Among other things, this tool allows you to optimize the sequence of check points and save the result as a geofence.

Logisticsyes

When creating a route, the application automatically optimizes the order of check points considering multiple criteria and also allows changing the order of check points manually.

NimBusno

The order of check points in the application is to be fixed manually when creating a route.

5. Optimizing the path between check points

Routesno

The module doesn't track the path between check points. The path is only displayed during the optimization of the order of check points.

Geofencespartially

In the monitoring interface, you will find the Routing tool. Among other things, this tool allows you to optimize the path between the check points and save the result as a geofence.

Logisticsyes

When creating a route, the application automatically optimizes the path between the check points considering multiple criteria.

NimBusyes

When creating a route, the path between check points is automatically optimized, after which it can be edited manually.

6. Automatic start of tracking the ride

Routesyes

Automatic creation of rides is available when using a schedule with the Relative to day type or when using notifications with the Create a ride action type.

Geofencesyes

In this option, there is no concept of a ride, so tracking a ride doesn't start at a specific time. You can start tracking the visits to the check points at any time after adding geofences to reports or notifications.

Logisticsno

The application assumes that the route is started manually by the operator. However, the operator can create routes that are meant to start in the future depending on the delivery interval in the properties of orders.

NimBusyes

If schedules are created for the route and it is switched on, then a ride related to this route is created automatically. Two types of ride activation are available in the application:

  • According to schedule, meaning, the ride is created a certain number of minutes before the planned visit to the first stop; the number of minutes is specified in the settings.
  • When visiting a stop — this type of activation is only available for routes where the automatic assignment of units is enabled.

7. Additional conditions for visiting check points

Routesno

There are no additional conditions for visiting check points. Any message with coordinates in the check point area is considered as visiting a check point.

Geofencespartially

Using notification settings or interval filtration, you can hide visited geofences from the results. For example, you can use a filter by speed and sensor value for a notification with the Geofence type. However, this cannot be called total control of visits, as there is no additional confirmation of visits received from the driver's side.

Logisticsyes

With the help of a mobile application, the courier can send confirmation of the order by leaving a comment, taking a photo, or attaching a client’s signature.

NimBusno

There are no additional conditions for visiting a stop. Any message with coordinates in the stop area is considered as visiting a stop.

8. Schedule relative to departure

Routesyes

The schedule can have the activation type called Relative to activation so that one schedule can be used multiple times a day.

Geofencesno

In this option, there is no concept of a schedule. It is substituted by Time limitation in reports and notifications, where only the beginning of the day is specified.

Logisticspartially

When creating a route, the time of the estimated arrival can vary depending on the current time. For example, if orders can be visited from 10:00 to 20:00, and it is currently 12:00, the time of the estimated arrival for the requests will be counted from 12:00. This can only be partly called a schedule relative to departure.

NimBusyes

For such a case, there is a type of schedule called Relative in the application.

9. Transport replacement during the ride execution

Routesno

It is impossible to replace a unit during the execution of a ride. For example, if the first unit breaks down, a new ride (or even route) will have to be created for another unit that is going to replace the first one.

Geofencespartially

In this option, there is no concept of a ride. However, technically, the operator can contact drivers and direct them to the unvisited geofences.

Logisticsyes

The application offers the possibility to change a unit for an active route.

NimBusyes

It is possible to replace the unit that is in the process of executing the ride.

10. Long route (more than 2 days)

Routesyes

There are no restrictions on the duration of the route for the Absolute schedule type. However, each such schedule can only be used once, and then it becomes useless. For the Relative to day and Relative to activation schedule types, a duration of up to 99 hours (which is slightly over 4 days) can be achieved.

Geofencesyes

In this option, there are no concepts of a ride or schedule. Therefore, nothing prevents a unit from moving between geofences for several days, weeks, and even longer.

Logisticsyes

It is possible to set a restriction on the maximum duration in the application, but as long as it is not enabled, the route can take any number of days.

NimBusno

The route schedule can include only one running past midnight, as sometimes transport may execute the last ride after 00:00 (this is done using the Past midnight function).

11. Moving check points

Routesyes

Moving units can be used as check points. This can be useful, for example, for organizing harvesting when a truck needs to approach moving harvesters collecting crops.

Geofencesyes

Units can be used as moving geofences in the Geofences and Trips Between Geofences tables.

Logisticsno

Orders in the application have a fixed location.

NimBusno

Stops in the application have a fixed location.

12. Sending routes to the driver

Routespartially

There is a possibility to send routes to a unit using commands. The tracker must support such a command, also, a navigator must be connected to the tracker. This means that this feature is not available for all the units.

Geofencespartially

There is a possibility to send geofences to a unit using commands, but they won't be combined into a common route. The tracker must support this feature.

Logisticsyes

There is a mobile application created specifically for couriers where they can see their planned routes.

NimBusno

NimBus doesn't have such functionality.

13. Online control

Routesyes

It is possible to track the route's execution on the map in the monitoring interface, using notifications such as Route progress, and on the Timeline with rides. Unfortunately, working with the timeline is not very convenient, as the position of the unit is not displayed on it.

Geofencesyes

It is possible to track the route's execution on the map in the monitoring interface or using notifications with the Geofence type.

Logisticsyes

Currently active routes and order statuses can be displayed as a table. The dispatcher will also find notifications useful. Real-time statistics are displayed on the Dashboard tab.

NimBusyes

The Online tab is suitable for monitoring ride execution online. Notifications will also be useful for the dispatcher. Real-time statistics are displayed on the Dashboard tab.

14. Reports for the previous period

Routesyes

You can use the Rides and Check Points tables for a unit and a group of units, and the Rides and Log tables for the route report.

Geofencesyes

The Geofences and Trips Between Geofences tables are the most convenient and available for a unit and a group of units.

Logisticsyes

There is a special Reports tab in the application.

NimBusyes

There is a special Reports tab in the application.

15. Displaying in the monitoring interface

Routesyes

The module is a part of the monitoring interface.

Geofencesyes

Geofences, reports, and notifications are the parts of the monitoring interface.

Logisticspartially

It is possible to create the Orders table based on the Logistics data, but it only displays part of the information available in the application.

NimBusno

The units’ movement is displayed in the monitoring interface, but the application's data (stops, routes, schedules, rides, etc.) is not displayed.

16. Mobile application

Routesno

Routes are not displayed in the Wialon mobile application.

Geofencesyes

Geofences, notifications, and reports are displayed in the mobile application.
Clients can track location using the Locator link, which can be added to a notification text using the %LOCATOR_LINK% tag. It is convenient to open this link in a browser on a smartphone.

Logisticsyes

A mobile application has been created specifically for couriers. Using it, the courier sees all the routes they must complete.
The client can track the delivery of their order after receiving a notification with the %LOCATOR_LINK% tag. After sending the notification, the tag turns into the Locator link, which is convenient to open in a browser on a smartphone.

NimBuspartially

Passengers can track the movement of transport using the Locator link, which is convenient to open in a browser on a smartphone. However, this mobile application is not suitable for dispatchers or drivers.


Oleg Zharkovsky,Customer Service Engineer

Controlling Non-standard Conditions with Dynamic Groups
  • technical_consulting
  • notifications
  • unit_groups

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.

To solve specific tasks, you can use a system of multiple notifications that automatically move units between groups, and then apply other notifications, tasks, and reports to these groups as needed. For brevity, this solution is called the method of dynamic groups (or simply dynamic groups). In this case, the word dynamic means that the units are automatically added and removed from groups in real time.

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.

If initially all units are placed in one of the groups, then after setting up the dynamic groups, units will be automatically move to the correct groups after some time. The duration of such a sorting will depend on how often the controlled condition changes (in this example, it is entering and leaving the geofence).

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.

There are no pictures in the gallery


❮ ❯

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.

There are no pictures in the gallery


❮ ❯

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.

Such division into groups is only relevant at the current moment. That is, if you generate a report on a group of units for last week, it will display results for those units that are currently in the group, not for those that were in it during the last week.

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).

There are no pictures in the gallery


❮ ❯

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.

Notification type

Additional conditions

Sensor value

Geofence

Speed

Driver absence

Speed



Geofence



Interposition of units



Address



Off time



Connection loss




Fuel filling




Fuel drain




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:

In this scheme, it is possible to manage without the Alpha group, however, based on practice, the presence of this group simplifies configuration and scalability in the future. E.g. if the number of monitored units is increased, you just need to add them to the Alpha group.

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

The distinctive feature of this approach is the sequential control of conditions. For example, the Speed type notification with an additional Sensor value filter controls the fulfillment of both conditions simultaneously (one message is required for the notification to trigger). A notification system with dynamic groups configured for these same conditions first controls the speed and only then the sensor value (i.e., two messages is required for it to trigger). At the same time, increasing the number of elements in the scheme will also increase the number of messages required for triggering.

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.

There are no pictures in the gallery


❮ ❯

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.

    There are no pictures in the gallery


    ❮ ❯

  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).

    There are no pictures in the gallery


    ❮ ❯

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.

    There are no pictures in the gallery


    ❮ ❯

  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.

    There are no pictures in the gallery


    ❮ ❯

  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.

There are two exceptions: Off time notification has a maximum duration of 30 days, and Connection loss notification has a maximum duration of 999,999 minutes (or approximately 694 days).

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).

    There are no pictures in the gallery


    ❮ ❯


  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).

    There are no pictures in the gallery


    ❮ ❯

  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.

    There are no pictures in the gallery


    ❮ ❯

    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).

    There are no pictures in the gallery


    ❮ ❯


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

How to Get an SSL Certificate
  • technical_consulting
  • sites

You may need an SSL certificate if you log into Wialon using a site with an address other than hosting.wialon.com/eu/us/org (i.e., you use an extra-site). SSL certificate allows the use of HTTPS connection to secure the personal user's data. If an SSL certificate is not used, an HTTP connection is used, and your site is marked as not secure in the browser.

SSL certificates are issued by special certification authorities. These certification authorities are trusted parties that authenticate the website owner's identity and issue digital certificates confirming that the connection to the site is secure. You should contact an SSL provider who will work with the certification authorities.

In this article, we list the requirements for adding SSL certificates, and also describe the sequence of steps to obtain certificates.

What Files Need to be Sent to Us

In case you would like to enable HTTPS for your site, please, send an email to support@wialon.com. Your email must contain the following information:

  1. the site name for which the SSL certificate should be applied;
  2. signed (issued) by a third-party SSL certificate (signed by Comodo, GlobalSign, etc.);
  3. private key along with the passphrase if it has been specified.

Before sending the files to us, please ensure that the files contain the corresponding data. You can open files with the help of a text editor to check the content.

  • A file with the certificate usually has one of these extensions: CRT, PEM, or TXT. The files should have the following content:

    -----BEGIN CERTIFICATE-----
    <>
    -----END CERTIFICATE-----



  • The file with the certificate should NOT contain a certificate request that looks as follows:

    -----BEGIN CERTIFICATE REQUEST-----
    <> 
    -----END CERTIFICATE REQUEST-----


    If you see this information in the file, it is not a certificate file but a certificate request. We do not need it when adding the SSL certificate.

  • A file with the private key usually has one of these extensions: CRT, PEM, or TXT. The files should have the following content:

    -----BEGIN RSA PRIVATE KEY-----
    <>
    -----END RSA PRIVATE KEY-----

Requirements

  1. From our side, only commercial certificates valid for a year or more are accepted.
  2. Self-signed and short-term certificates are not accepted.
  3. Let's Encrypt certificates are not accepted.
  4. The SSL certificate and private key must correspond to each other.
  5. We do not host third-party files to confirm ownership of the domain.

    To get the SSL certificate, you need to confirm domain ownership. There are different ways to do it. Please note that we don't host third-party files for this purpose, so please select an alternative method of domain ownership confirmation when selecting the confirmation type. For example, you can use email. With this option, an email containing a unique code and a confirmation link will be sent to the email address of the domain's administrative contact.

    You can get more details about alternative validation methods from your SSL service provider.

SSL Certificate Generation

The easiest way to get an SSL certificate is to ask your SSL provider to generate the SSL certificate for you, and they will create all the required files on their side. In this case, you don't need to use the following instructions.

The following files must be generated to get an SSL certificate: a CSR request and a private key.

If you need to create the mentioned files on your side, please follow the brief instructions below. The steps depend on your operating system (Linux, macOS, or Windows).

Before generating a CSR request and private key, we recommend contacting the SSL service provider to learn some nuances. For example, some companies ask not to enter an email address, challenge password, or an optional company name when generating the CSR.

How to Get an SSL Certificate on Linux/macOS

  1. Make sure that OpenSSL is installed. For that purpose, open the terminal and run 'openssl version'. If OpenSSL is installed, the version will be displayed. If OpenSSL is not installed, please, do it by the corresponding commands that depend on your operating system. You can find out the required command in the documentation available on the Internet.
  2. Use OpenSSL to generate a CSR and match the private key. For that purpose, execute the command below to generate a 2048-bit RSA private key and CSR. When executing the command, it will be necessary to enter data such as a passphrase, country, domain for which the CSR request will be generated, and others.
    To skip a field, press Enter on the keyboard.

    Remember the passphrase because it is used to encrypt the private key. You will need it to access the generated private key.
    openssl req -newkey rsa:2048 -keyout PRIVATE_KEY.key -out CSR_REQUEST.csr
    • The Country Name (optional) — a two-letter country code.
    • State or Province Name (optional) — your state or province name, or use the Locality name if you have none.
    • The Locality Name field (optional) — your city or town.
    • The Organization Name field (optional) — the name of your company or organization. If the company or department has an '&', '@', or any other symbol using the shift key in its name, the symbol must be spelled out or omitted to enroll.
    • The Common Name field (required) — the Fully Qualified Domain Name of the website the certificate will protect. It should be set the same way the client will address it. In most cases, this will be the entire domain name.
    • Email Address (optional) — your email address. The email used for CSR generation will not be used for domain control validation or delivery of the issued certificate.
    • The Challenge Password field (optional) — might be needed for certificate revocation.
  3. You will get 2 files: CSR request and private key. Please save the private key somewhere where the risk of its being deleted will be minimized.
  4. Send two files from the previous step to the certificate provider. The provider will send you a signed certificate and the private key.
  5. Send us a signed certificate, private key, and information on which site they should be added to.
  6. We will recheck, add them, and inform you about the results.

In case you face issues using OpenSSL, you can replace step 2 by using Digicert OpenSSL CSR Wizard. This service helps to create a CSR request. Just fill in the form and press Generate. As a result, the service will create a console command with all required options. Copy this command and execute it in the terminal. Please note that this approach still requires OpenSSL to be installed.

How to Get an SSL Certificate on Windows

OpenSSL

  1. Download and install Win32 OpenSSL or Win64 OpenSSL.
  2. Press Win on the keyboard and type 'cmd'.

  3. Click the right button on the Command prompt and select Run as administrator.
  4. Move to the folder where you've installed OpenSSL. For example, it can be:

    cd C:\Program Files\OpenSSL-Win64\bin
  5. Run the following command:

    set OPENSSL_CONF=*OpenSSL base folder*\bin\openssl.cfg
  6. Restart your computer to apply the changes.
  7. Press Win on the keyboard and type 'cmd' to find the Command prompt.
  8. Click the right button on the Command prompt and select Run as administrator.

  9. Go to the subfolder \bin of your OpenSSL folder. If you've installed by default settings, it might look like:

    cd C:\Program Files\OpenSSL-Win64\bin
  10. Enter the following command to generate a private key file with the name 'PRIVATE_KEY' and a certificate request file with the name 'CSR_REQUEST'.

    openssl req -newkey rsa:2048 -keyout PRIVATE_KEY.key -out CSR_REQUEST.csr
  11. Enter the PEM pass phrase. It is used to output an encrypted private key.

  12. Enter the following information that will be incorporated into your certificate request:
    • Country Name (optional) — a two-letter country code.
    • State or Province Name (optional) — your state or province name, or use the Locality name if you have none.
    • Locality Name field (optional) — your city or town.
    • Organization Name field (optional) — the name of your company or organization. If the company or department has an '&', '@', or any other symbol using the shift key in its name, the symbol must be spelled out or omitted to enroll.
    • Organizational Unit Name (optional) — your unit or department name.
    • Common Name field (required) — the Fully Qualified Domain Name of the website the certificate will protect. It should be set the same way the client will address it. In most cases, this will be the entire domain name.
    • Email Address (optional) — your email address.

      The email used for CSR generation will not be used for domain control validation or delivery of the issued certificate.

  13. Enter the following extra attributes to be sent with your certificate request:
    • A challenge password (optional) — a password by which an entity may request certificate revocation.
    • An optional company name (optional).
  14. The files with the required private key and certificate request will be generated and saved in the folder C:\Program Files\OpenSSL-Win64\bin
  15. Send two files to the certificate provider. The provider will send you a signed certificate and the private key.
  16. Send us a signed certificate, private key, and information on which site they should be added to.
  17. We will recheck, add them, and inform you about the results.

IIS Manager

  1. Press Win on the keyboard and type 'Control Panel'. Then click it in the search results.
  2. Select Programs.
  3. At Programs and Features, click Turn Windows features on or off.

  4. In the new window, click the checkbox next to Internet Information Services and press OK.
  5. When installation is complete, press Close.
  6. Press Win on the keyboard and type 'Internet Information Services (IIS) Manager' in the search bar. Then click it from the search results to launch.
  7. In the new window, in the left column Connections, select the server.

  8. Double-click the Server Certificates icon in the center panel of the window.

  9. Click the Create Certificate Request link in the Actions column on the right side of the window.

  10. Enter the required information and press Next:
    • Common Name field — the Fully Qualified Domain Name of the website the certificate will protect. It should be set the same way the client will address it. In most cases, this will be the entire domain name. You can also set a wildcard, like *.mydomain.com.
    • Organization — the name of your company or organization.
    • Organizational Unit — your unit or department name.
    • City / Locality — city or town where your company is located.
    • State / Province — your state or Province name, or use the Locality name if you have none.
    • Country/ Region Name (optional) — select from the drop-down list.
  11. Set Cryptographic Service Provider Properties. In the drop-down menu, select Microsoft RSA SChannel Cryptographic Provider as the cryptographic service provider, 2048 as the Bit length and press Next.

  12. Click the button with three dots to select where the CSR request should be placed and add its name. Press Finish.



  13. Close Internet Information Services (IIS) Manager.
  14. Press Win on the keyboard and type 'Microsoft Management Console' or 'mmc' in the search bar. Then click it from the search results to launch.
  15. In the new window, press File > Add/Remove Snap-in...

  16. In the new window, in the left column, select Certificates and press Add > button.

  17. This snap-in will always manage certificates for Computer account and press Next.

  18. This snap-in will always manage Local computer (the computer this console is running on) and press Finish.

  19. Press OK to save the changes.
  20. In the left column, select Certificate Enrollment Requests and click Certificates below it.

  21. In the center panel of the window, find the required certificate request and right-click it. Select All Tasks > Export...

  22. Select the answer Yes, export the private key.

  23. Select the format Personal Information Exchange - PKCS #12 (.PFX).

  24. On the next step, mark the Password option. Enter the desired password in the Password and Confirm password fields and press Next.

  25. Click the Browse... button to select where the files should be saved and set the filename. Press Next.



  26. Check the displayed data and press Finish.
  27. Send two files to the certificate provider. The provider will send you a signed certificate and the private key.
  28. Send us a signed certificate, private key, and information on which site they should be added to.
  29. We will recheck, add them, and inform you about the results.

Common questions

Is it possible to set up the site to use only HTTPS?

Yes, it's possible. If you already have an SSL certificate added for your site or request to add your certificate, please let us know if you would like your site to be accessible via HTTPS only.

By default, the website will be available via HTTP and HTTPS. If you want to switch to HTTPS-only mode, just let us know. We will enable force HTTPS redirection, so when you log in to HTTP://your.site.com, you'll be forcibly redirected to HTTPS://your.site.com.

Which type of SSL certificate to choose?

We don't restrict the certificate type, and it's possible to apply different types of certificates.

Depending on the number of websites and domain names you use, you can send us the following types of certificates:

Single Domain CertificateConfigured for a particular domain name and can secure only it.
Multi-Domain TLS/SSL Certificate

Can be configured to allow multi-domain. For example, one certificate can secure the following sites: www.your_domain1.com, www.your_domain2.com, mail.your_domain.com, test.your_domain2.com, etc.

The list of sites for which the certificate can be applied is pre-defined. If another site subsequently appears, you will need to issue an additional certificate for that site.

Wildcard TLS/SSL Certificate

Configured with a wildcard character (*) in the domain name field, so it can secure multiple subdomain names on the same base domain. For example, a certificate generated for '*.your_domain.com', can be used for www.your_domain.com, mail.your_domain.com, monitoring.your_domain.com, etc.

You do not need to add any changes to the certificate or issue additional certificates if you have an additional site on the same base domain. Additional subdomains can be added or removed at any time.

Keep in mind that a wildcard certificate is used only for subdomains at the same level where the asterisk is set. So a certificate generated for *.your.site can be used for monitoring.your.site, but it can't be used for www.monitoring.your.site.

Currently, there are three types of TLS/SSL certificates. They differ in the vetting and verification processes needed to obtain the certificate.
Domain Validation (DV)

It has the lowest level of validation. These certificates only verify the ownership of the domain name.

Organization Validation (OV)

It offers higher assurance than DV. These certificates require validation of the organization's identity in addition to domain ownership.

Extended Validation (EV)

It provides the maximum amount of trust to visitors. EV certificates undergo the most rigorous validation process, including verification of legal identity, physical address, and operational existence of the organization.

For what server should I issue the certificate?

It would be preferable if the certificate was generated for the Nginx server.

What should I do if the private key doesn't match the certificate?

Find the private key to generate the SSL certificate and send both files to us.

If you have issues finding the required file, contact your SSL provider.

How can I know when the certificate expires?

The easiest way is to visit your site by following the instructions:

  1. Open your site in the browser.
  2. Click on the icon near the address bar of the browser.
  3. In the pop-up window, click on the Connection is secure.
  4. Then click on the Certificate is valid.
  5. Check the field Expires On in the new window.

The example is provided for Chrome. The instructions for other browsers should be similar.


Ekaterina Grib,Customer Service Engineer



Intro to SDK: Basic Requests
  • technical_consulting

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.

You may also find the following sources useful:

  • Portal designed for developers with documentation and detailed description of each request.
  • Examples of ready-made solutions using the SDK from the Marketplace section.
  • Wialon API and SDK: how-to videos webinar series.
  • Collection of examples in the Postman application for testing API requests.
  • Custom SDK development forum section.

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.

 Example

As an example, let's create a circle geofence. Open the Network tab and fill in the Name, Description, Type, Radius, and Coordinates fields.

After clicking the Save button, the geofence will be created and the corresponding request will immediately appear in the right panel. To get information about the request, click on it.

This panel has three convenient tabs:

  • Headers — this tab allows you to see the full URL of the request, the method used for sending (POST or GET), the status of the request execution, and other useful information.
    Among other things, you can find the name of the API request. In this case, it is resource/update_zone.



  • Payload — this tab displays the request parameters, you can read about each of them in the documentation.
    For example, the parameters that were filled when creating a geofence: where n — name, d — description, t — type (circle), w — circle radius, x and y — coordinates of the center.



  • Response — this tab displays the response from the API server in JSON format (or its code in case of an error).


Some requests are executed in batches. In this case, when viewing network requests, you need to find the core/batch request and study its parameters.

Not all functionality of the monitoring interface is based on Wialon API (an example of an exception is the Distance tool).

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
ParameterDescription
host

For Wialon Hosting, this is usually hst-api.wialon.com, and for Wialon Local, it is the site of Wialon Web or CMS Manager type.

svc

The name of the request (e. g., resource/update_zone).

params

The parameters for executing the request in JSON format. They are listed in the documentation, and some of them may be optional. In some cases, the system sends an empty value params={}.

sid

A unique session identifier which is used in almost all requests. The server returns it after authorization request.

You can send requests to test the functionality of the API through the address bar in your browser. In this case, the characters must be encoded for transmission in the URL. For example, the code for the % symbol is actually %25, which can be checked using publicly available online tools. If special characters are not encoded, the server will return an error with code 4.

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.

We recommend setting the time zone immediately after authorization, thus, before performing any main actions (such as requesting messages, building tracks, etc.).

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.

 Example

As an example, let's calculate the value of the tzOffset parameter for a client in Sydney, Australia.

The necessary values for time settings (daylight saving time and time zone) can be found in the documentation. In this case, the time zone value is 36000 (in DEC format), and daylight saving time is 0x0A270000 (in HEX format).

Next, two actions need to be performed:

  1. Apply a bitwise AND operation to the time zone using the mask f000ffff (HEX).
    Since the used operation is performed for each pair of bits, the values need to be converted to the binary numeral system:

    Time zone

    00000000000000001000110010100000 (BIN)

    36000 (DEC)

    Mask

    11110000000000001111111111111111 (BIN)

    f000ffff (HEX)

    Result of the operation

    00000000000000001000110010100000 (BIN)

    36000 (DEC)

    In this case, the operation did not change the value of the time zone.

  2. Apply a bitwise OR operation to the result from the previous step using the daylight saving time mask.

    Previous result

    00000000000000001000110010100000 (BIN)

    36000 (DEC)

    Mask

    00001010001001110000000000000000 (BIN)

    0x0A270000 (HEX)

    Result of the operation

    00001010001001111000110010100000 (BIN)

    170364064 (DEC)

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.

Do not confuse the system ID of a unit with its Unique ID, which is specified in the properties on the General tab.

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 searching 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.

System IDs of items have unique numeric values and are assigned by the server.

System IDs of subitems are numbered in the order of creation and start from 1.

If several subitems were previously created (e. g., with system IDs 1, 2, and 3), and then one of them was deleted (assuming subitems with IDs 1 and 3 were left), then the next created subitem will get the smallest free ID (in this example, it is ID 2).

The search request cannot display data for a specific subitem. The response to the search request contains information about the items themselves (device type, resource, retranslator, unit, unit group, user, and route). In other words, subitems are the properties for the search.

For example, you can search Engine sensor by its name but the response to the request will return not only information about the sensors, but specifically about the units where a sensor with the required name is created.

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

Flags can be added up together to get multiple types of data simultaneously, rather than performing multiple separate requests.

For example, if you need to display the general properties of a unit (“flag":1), the commands created in it ("flag":524288), and its last position ("flag":4194304), it is enough to search for units with the “flag":4718593 flag, since 1 + 524288 + 4194304 = 4718593.

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
Parameter and its valueDescription
"itemsType":"avl_unit"

The search will be performed on units.

If the value is left empty ("itemsType":""), the search will be performed on all types of items.

"propName":"sys_name"

The search will be performed on the name of the item.

"propValueMask":"*Tractor*"

The response will display a list of units containing the word Tractor in their names with any number of characters before and after it.

If the value for this parameter is set to *, then the response to the request will include items with any name value, i.e., all items available to the user.

"sortType":"sys_name"

The sorting will be performed based on the name of the item.

"force":1

Previous search results will not be taken into account.

"flags":4097

The response will include information about the general properties, as the names of the units and the created sensors are required.

1 + 4096 = 4097

"from":0;"to":0

There will be no restrictions on the number of found items.

 Response
{
	"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
Parameter and its valueDescription
"itemsType":"user"

The search will be performed on users.

"propName":"rel_creation_time"

The search will be performed on the creation date.

"propValueMask":">=1614058906"

The response will display a list of items with the creation time greater than or equal to February 23, 2021, 05:41:46 (GMT+0).

Requests use Unix time. You can use publicly available online tools to convert date and time to Unix time.

"sortType":"sys_name"

The sorting will be performed based on the name of the item.

"force":1

Previous search results will not be taken into account.

"flags":3

The response will include information about the general properties to get the system IDs of the users and the custom properties to get the email addresses of the users.

1 + 2 = 3

"from":0;"to":0

There will be no restrictions on the number of found items.

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
Parameter and its valueDescription
"itemsType":"avl_unit"

The search will be performed on units.

"propName":"rel_hw_type_name,rel_last_msg_date"

The search will be performed on the hardware type and last message date.

"propValueMask":"Wialon%20Retranslator,>1676203200"

The response will display a list of items with the Wialon Retranslator hardware type that have sent messages after February 12, 2023, 12:00:00 (GMT+0).

"sortType":"rel_creation_time"

The sorting will be performed based on the creation date of the items.

"force":1

Previous search results will not be taken into account.

"flags":1

The response will include information about the general properties of the units.

"from":0;"to":0

There will be no restrictions on the number of found items.

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
Parameter and its valueDescription
"itemsType":"avl_unit"

The search will be performed on units.

"propType":"propitemname"

The search will be performed on the subitem name.

"propName":"unit_sensors"

The search will be performed on the sensor name.

"propValueMask":"engine"

The response will display a list of units that have a sensor named Engine in their properties.

"sortType":"sys_name"

The sorting will be performed based on the name of the items.

"force":1

Previous search results will not be taken into account.

"flags":1

The response will include information about the general properties of the units.

"from":0;"to":0

There will be no restrictions on the number of found items.

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
Parameter and its valueDescription
"itemsType":"avl_unit_group"

The search will be performed on unit groups.

"propName":"rel_user_creator_name,rel_group_unit_count"

The search will be performed on the creator name and the number of items in the group.

"propValueMask":"User,>5"

The response will display a list of unit groups created by User and containing more than 5 units.

"sortType":"sys_name"

The sorting will be performed based on the name of the units.

"force":1

Previous search results will not be taken into account.

"flags":133

The response will include information about the general properties, billing properties, and administrative fields.

1 + 4 + 128 = 133

"from":0;"to":0

There will be no restrictions on the number of found items.

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

Intro to SDK: Creation of Accounts and Units
  • technical_consulting

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.

You may also find the following sources useful:

  • The article Intro to SDK: Basic Requests.
  • Portal designed for developers with documentation and detailed description of each request.
  • Examples of ready-made solutions using the SDK from the Marketplace section.
  • Wialon API and SDK: how-to videos webinar series.
  • Collection of examples in the Postman application for testing API requests.
  • Custom SDK development forum section.

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

Unlike other objects, a billing plan does not have a system ID. If it is necessary to refer to it, use its name as the unique parameter.

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.

If no billing plans are displayed in the response, it is necessary to check if the account has dealer rights and if billing plans are assigned to it.

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

Parameter and its value

Description

"itemsType":"user"

The search will be performed on users.

"propName":"sys_name"

The search will be performed on the name of the item.

"propValueMask":"manager"

The response will display the user whose name exactly matches the expression manager.

"sortType":"sys_name"

The sorting will be performed based on the name of the item.

"force":1

Previous search results will not be taken into account.

"flags":1

The response will only contain information about the general properties.

"from":0;"to":0

There will be no restrictions on the number of found items.

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
Parameter and its valueDescription
"creatorId":11111

The new user will be created by the user with the system ID 11111.

"name":"sdk_account"

The new user will have the name sdk_account.

"password":"Pa%24%24w0rd"

The new user will have the password Pa$$w0rd.

In accordance with the security requirements, the password must contain special characters, and they must be encoded for transmission in the URL.

"dataFlags":1

Only the general properties of the new user will be displayed in the response.

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
Parameter and its valueDescription
"creatorId":22222

The new resource will be created by the user with the system ID 22222.

"name":"sdk_account"

The new resource will have the name sdk_account.

"dataFlags":1

Only the general properties of the new resource will be displayed in the response.

"skipCreatorCheck":0

Check if the user is currently the creator of any system items.

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
Parameter and its valueDescription
"itemId":33333

The new account will contain the resource with the system ID 33333.

"plan":"standard_client"

The new account will use the standard_client billing plan.

Above, we considered only the minimum necessary steps for the creation of an account in the system. To perform other settings, additional requests from the list in the documentation should be used.


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
Parameter and its valueDescription
"filterType":"name"

Filtering will be done by the name of the hardware type.

"filterValue":["Wialon%20IPS"]

The search will be performed by the expression Wialon IPS.

"includeType":0

The response will not show any additional information about the hardware type.

"ignoreRename":1

Renaming of the hardware types will be ignored in the response.

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.


The system ID of one hardware type may vary for different Wialon Hosting and Wialon Local services.


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
Parameter and its valueDescription
"itemsType":"user"

The search will be performed on users.

"propName":"sys_name"

The search will be performed on the name of the item.

"propValueMask":"sdk_account"

The response will display the user whose name exactly matches the expression sdk_account.

"sortType":"sys_name"

The sorting will be performed based on the name of the item.

"force":1

Previous search results will not be taken into account.

"flags":1

The response will only contain information about the general properties.

"from":0;"to":0

There will be no restrictions on the number of found items.

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
Parameter and its valueDescription
"creatorId":22222

The user-creator of the new unit will have the system ID 22222.

"name":"Delivery%20truck"

The new unit will have the name Delivery truck.

"hwTypeId":"44444"

The system ID of the hardware type for the new unit will have a value of 44444.

"dataFlags":1

Only the general properties of the new unit will be displayed in the response.

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
Parameter and its valueDescription
"itemId":55555

The settings will be changed for the unit with the system ID 55555.

"deviceTypeId":"44444"

The system ID of the hardware type will have a value of 44444.

Using this parameter, you can change the hardware type of the unit.

"uniqueId":"12345"

The unique ID of the unit will have a value of 12345.

Above, we considered only the minimum necessary steps for the creation of a unit in the system. To perform other settings, additional requests from the list in the documentation should be used.


Ekaterina Grib,Customer Service Engineer

Intro to SDK: Reports Execution
  • technical_consulting

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.

You may also find the following sources useful:

  • The article Intro to SDK: Basic Requests.
  • Portal designed for developers with documentation and detailed description of each request.
  • Code samples for working with reports.
  • Examples of ready-made solutions using the SDK from the Marketplace section.
  • Wialon API and SDK: how-to videos webinar series.
  • Collection of examples in the Postman application for testing API requests.
  • Custom SDK development forum section.

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.

The following requests cannot be executed simultaneously:

  • report/exec_report
  • report/export_result
  • report/get_result_chart
  • report/get_result_map
  • report/get_result_chart
  • resource/get_driver_bindings
  • resource/get_trailer_bindings
  • resource/get_tag_bindings
  • exchange/import_zones_save
  • exchange/import_json
  • exchange/import_messages
  • exchange/import_pois_read
  • exchange/import_zones_read
  • unit/get_trips
  • render/create_messages_layer
  • messages/load_interval
  • exchange/export_zones
  • exchange/export_json
  • exchange/export_messages
  • exchange/export_pois
  • account/get_account_history

Next, we will consider two examples of working with reports (without grouping and with grouping).

Working with a Report without Grouping

Let’s imagine, it we need to obtain the results of the the report List of trips, available to the user authorized by a token, for the unit Truck 0769 (system ID 55555) for the time interval from 2023 June 30 20:00 to 2023 July 01 03:59 (GMT+0) and export it to a PDF file using API requests.

In the web interface, the result looks as follows:

1. Authorization and Localization

Use the request token/login.

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

Authorization details are described in one of the previous articles.

Localization settings include setting the time zone (which has also been discussed earlier), date format, and other parameters.

If the time zone setting is done within the session, then when executing the report, the time is set in GMT+0.

Use the request render/set_locale.

https://hst-api.wialon.com/wialon/ajax.html?svc=render/set_locale¶ms={"tzOffset":134217728,"language":"en","formatDate":"%25E.%25m.%25Y%20%25H:%25M:%25S"}&sid=SESSION_IDENTIFIER
Parameter and its valueDescription
"tzOffset":134217728

GMT+0 time zone will be applied (without daylight saving time).

"language":"en"

English language will be used.

"formatDate":"%25Y.%25m.%25E%20%25H:%25M:%25S"

Date format will be yyyy-MM-dd and time format will be HH:mm:ss.

If localization settings aren't done, this can lead to different results when executing the report through Remote API and the web interface.

2. Obtaining System IDs

In one of the previous articles, we have already described how to search items by property, so now we will focus only on searching a resource and report template.

Let’s get a list of all resources that have a report template named List of trips available to the user authorized by a token. Use the request core/search_items:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_resource","propType":"propitemname","propName":"reporttemplates","propValueMask":"List%20of%20trips","sortType":"sys_name"},"force":1,"flags":8193,"from":0,"to":0}&sid=SESSION_IDENTIFIER
Parameter and its valueDescription
"itemsType":"avl_resource"

The search will be performed for resources.

"propType":"propitemname"

The search will be performed based on the subitem name.

"propName":"reporttemplates"

The search will be performed based on the report template name.

"propValueMask":"List%20of%20trips"

The response will display a list of resources that have a report template named List of trips.

"sortType":"sys_name"

The sorting will be performed based on the name of the item.

"force":1

Previous search results will not be taken into account.

"flags":8193

The response will contain information about the general properties and created report templates.

1 + 8192 = 8193

"from":0;"to":0

There will be no restrictions on the number of found items.

 Response
{
	"searchSpec":{
		"itemsType":"avl_resource",
		"propName":"reporttemplates",
		"propValueMask":"List of trips",
		"sortType":"sys_name",
		propType:"propitemname",
		or_logic:"0"
		},
	"dataFlags":8193,
	"totalItemsCount":1,
	"indexFrom":0,
	"indexTo":0,
	"items":[
		{
			"nm":"sdk_account",
			"cls":3,
			"id":12345678,
			"mu":0,
			"rep":{
				1:{
					"id":1,
					"n":"List of trips",
					"ct":"avl_unit",
					"c":59352
				},
				2:{
					"id":2,
					"n":"Grouped trips",
					"ct":"avl_unit",
					"c":6883
				}
			},
			"repmax":-1,
			"uacl":-1
		}
	]
}

Pay attention to the following parameters in the response:

  • nm — resource name;
  • rep — an array of report templates created in the resource;

    If this parameter is displayed as empty, it means that there are no report templates created in the resource.

  • n — subitem name;
  • id — system ID.

In this case, the user has access to the sdk_account resource with system ID 12345678, which contains the report template List of trips with system ID 1.

3. Executing the Report

Use the request report/exec_report.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/exec_report¶ms={"reportResourceId":12345678,"reportTemplateId":1,"reportObjectId":55555,"reportObjectSecId":0,"interval":{"flags":0,"from":1688144400,"to":1688173199},"remoteExec":1}&sid=SESSION_IDENTIFIER
Parameter and its valueDescription
"reportResourceId":12345678

The report template will be selected from the resource with system ID 12345678.

"reportTemplateId":1

The report template with system ID 1 will be executed.

"reportObjectId":55555

The report will be executed for the object with system ID 55555.

"reportObjectSecId":0

The report will not be executed for a subitem.

"flags":0

The report will be executed for the specified interval.

"from":1688144400

The interval will start on 2023 June 30 at 20:00 (GMT+0).

Requests use Unix time. You can use publicly available online tools to convert date and time to Unix time.

"to":1688173199

The interval will end on 2023 July 1 at 03:59 (GMT+0).

"remoteExec":1

The report will be executed in the background on the server.

 Response
{
	"remoteExec":1
}

4. Checking the Execution Status

Since the report is being executed in the background on the server, we will check its execution status using the request report/get_report_status.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/get_report_status¶ms={}&sid=SESSION_IDENTIFIER
 Response
{
	"status":4
}

A status code 4 means that the report has been executed successfully. The interpretation of other values can be found on the page with a request description.

5. Obtaining the Report Result

Use the request report/apply_report_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/apply_report_result¶ms={}&sid=SESSION_IDENTIFIER
 Response
{
	"reportResult":{
		"msgsRendered":0,
		"stats":[],
		"tables":[
			{
				"name":"unit_trips",
				"label":"Trips",
				"grouping":{},
				"flags":4224,
				"rows":4,
				"level":1,
				"columns":5,
				"header":[
					"№",
					"Beginning",
					"End",
					"Duration",
					"Mileage"
				],
				"header_type":[
					"",
					"time_begin",
					"time_end",
					"duration",
					"mileage"
				]
			}
		],
		"attachments":[]
	}
}

Three key parameters from the response that are important for us here are as follows:

  • tables — shows the number of tables in the report as an array. In this case, only one table (Trips) is mentioned, therefore its index will be 0.
  • rows — the number of rows in the table, which is 4 in this case. Therefore, their indexes range from 0 to 3.
  • level — the number of levels of nesting, which is 1 in this case, as there is no grouping in the report.

Indexes of tables, rows, columns, and nesting levels are counted from 0. This should be taken into account when referring to them.

Other parameters from the response can also be briefly listed. The columns parameter indicates the number of columns, and their names are described in the header parameter. A value of 0 for the msgsRendered parameter indicates that the report template doesn't display tracks on the map. Empty stats and attachments parameters indicate that there are no Statistics nor attachments (e.g., charts) in the report template.

6. Getting Table Rows

Knowing the index of the table content, let's display it using the request report/get_result_rows.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/get_result_rows¶ms={"tableIndex":0,"indexFrom":0,"indexTo":3}&sid=SESSION_IDENTIFIER
Parameter and its valueDescription
"tableIndex":0

The content of the table with index 0 will be displayed.

"indexFrom":0

The first displayed row will have index 0.

"indexTo":3

The last displayed row will have index 3.

 Response
[
	{
		"n":0,
		"i1":0,
		"i2":790,
		"t1":1688144420,
		"t2":1688154878,
		"d":0,
		"c":[
			"1",
			{
				"t":"2023-06-30 20:00:20",
				"v":1688144420,
				"y":47.2941741943,
				"x":26.4906959534,
				"u":55555
			},
			{
				"t":"2023-06-30 22:54:38",
				"v":1688154878,
				"y":43.8697662354,
				"x":26.0177116394,
				"u":55555
			},
			"2:54:18",
			"469.54 km"
		]
	},
	{
		"n":1,
		"i1":936,
		"i2":2171,
		"t1":1688155181,
		"t2":1688169690,
		"d":0,
		"c":[
			"2",
			{
				"t":"2023-06-30 22:59:41",
				"v":1688155181,
				"y":43.8698196411,
				"x":26.0177154541,
				"u":55555
			},
			{
				"t":"2023-07-01 03:01:30",
				"v":1688169690,
				"y":41.7139854431,
				"x":26.3660545349,
				"u":55555
			},
			"4:01:49",
			"343.84 km"
		]
	},
	{
		"n":2,
		"i1":2340,
		"i2":2486,
		"t1":1688170034,
		"t2":1688170841,
		"d":0,
		"c":[
			"3",
			{
				"t":"2023-07-01 03:07:14",
				"v":1688170034,
				"y":41.7140579224,
				"x":26.365901947,
				"u":55555
			},
			{
				"t":"2023-05-01 09:23:10",
				"v":1688170841,
				"y":41.7122383118,
				"x":26.3712425232,
				"u":55555
			},
			"0:13:27",
			"1.39 km"
		]
	},
	{
		"n":3,
		"i1":2833,
		"i2":2910,
		"t1":1688171565,
		"t2":1688173175,
		"d":0,
		"c":[
			"4",
			{
				"t":"2023-07-01 03:32:45",
				"v":1688171565,
				"y":41.7120819092,
				"x":26.3711204529,
				"u":55555
			},
			{
				"t":"2023-07-01 03:59:35",
				"v":1688173175,
				"y":41.5760040283,
				"x":26.9871864319,
				"u":55555
			},
			"0:26:50",
			"57.84 km"
		]
	}
]

7. Export to File

Let’s export the result to a PDF file using the request report/export_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result¶ms={"format":2,"compress":0,"outputFileName":"List%20of%20trips"}&sid=SESSION_IDENTIFIER
Parameter and its valueDescription
"format":2

The report result will be exported in PDF format.

"compress":0

The exported file will not be compressed (added to an archive).

"outputFileName":"List%20of%20trips"

The exported file will have the name List of trips.

There is no response displayed for this API request, instead, the file download starts automatically.

8. Deleting the Result of the Previous Report

Use the request report/cleanup_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/cleanup_result¶ms={}&sid=SESSION_IDENTIFIER
 Response
{
	"error":0
}

A zero value indicates successful deletion.

Working with a Report with Grouping

Now we need to obtain the results of the report Grouped trips, available to the user authorized by a token, for the unit Truck 0769 (system ID 55555) for the time interval from 2023 June 30 20:00 to 2023 July 01 03:59 (GMT+0) and export it to a PDF file using API requests.

In the web interface, the result looks as follows:

Based on the result in the web interface, you can see that the Trips table has grouping by months and dates, meaning the report has 3 levels of nesting:

  • The first level contains rows with months.
    The second level contains rows with dates within the month.
  • The third level contains rows with trips within the date.

1. Authorization and Localization

Use the request token/login.

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

Authorization details are described in one of the previous articles.

Localization settings include setting the time zone (which has also been discussed earlier), date format, and other parameters.

If the time zone setting is done within the session, then when executing the report, the time is set in GMT+0.

Use the request render/set_locale.

https://hst-api.wialon.com/wialon/ajax.html?svc=render/set_locale¶ms={"tzOffset":134217728,"language":"en","formatDate":"%25E.%25m.%25Y%20%25H:%25M:%25S"}&sid=SESSION_IDENTIFIER
Parameter and its valueDescription
"tzOffset":134217728

GMT+0 time zone will be applied (without daylight saving time).

"language":"en"

English language will be used.

"formatDate":"%25Y.%25m.%25E%20%25H:%25M:%25S"

Date format will be yyyy-MM-dd and time format will be HH:mm:ss.

If localization settings aren't done, this can lead to different results when executing the report through Remote API and the web interface.

2. Obtaining System IDs

In one of the previous articles, we have already described how to search items by property, so now we will focus only on searching a resource and report template.

Let’s get a list of all resources that have a report template named Grouped trips available to the user authorized by a token. Use the request core/search_items:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_resource","propType":"propitemname","propName":"reporttemplates","propValueMask":"Grouped%20trips","sortType":"sys_name"},"force":1,"flags":8193,"from":0,"to":0}&sid=SESSION_IDENTIFIER
Parameter and its valueDescription
"itemsType":"avl_resource"

The search will be performed on resources.

"propType":"propitemname"

The search will be performed based on the subitem name.

"propName":"reporttemplates"

The search will be performed based on the report template name.

"propValueMask":"Grouped%20trips"

The response will display a list of resources where a report template named Grouped trips is created.

"sortType":"sys_name"

The sorting will be performed based on the name of the item.

"force":1

Previous search results will not be taken into account.

"flags":8193

The response will contain information about the general properties and created report templates.

1 + 8192 = 8193

"from":0;"to":0

There will be no restrictions on the number of found items.

 Response
{
	"searchSpec":{
		"itemsType":"avl_resource",
		"propName":"reporttemplates",
		"propValueMask":"Grouped trips",
		"sortType":"sys_name",
		propType:"propitemname",
		or_logic:"0"
		},
	"dataFlags":8193,
	"totalItemsCount":1,
	"indexFrom":0,
	"indexTo":0,
	"items":[
		{
			"nm":"sdk_account",
			"cls":3,
			"id":12345678,
			"mu":0,
			"rep":{
				1:{
					"id":1,
					"n":"List of trips",
					"ct":"avl_unit",
					"c":59352
				},
				2:{
					"id":2,
					"n":"Grouped trips",
					"ct":"avl_unit",
					"c":6883
				}
			},
			"repmax":-1,
			"uacl":-1
		}
	]
}

Pay attention to the following parameters from the response:

  • nm — resource name;
  • rep — an array of report templates created in the resource;

    If this parameter is displayed as empty, it means that no report templates are created in the resource.

  • n — subitem name;
  • id — system ID.

In this case, the user has access to the sdk_account resource with system ID 12345678, which contains the report template Grouped trips with system ID 2.

3. Executing the Report

Use the request report/exec_report.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/exec_report¶ms={"reportResourceId":12345678,"reportTemplateId":2,"reportObjectId":55555,"reportObjectSecId":0,"interval":{"flags":0,"from":1688144400,"to":1688173199},"remoteExec":1}&sid=SESSION_IDENTIFIER
Parameter and its valueDescription
"reportResourceId":12345678

The report template will be selected from the resource with system ID 12345678.

"reportTemplateId":2

The report template with system ID 2 will be executed.

"reportObjectId":55555

The report will be executed for the object with system ID 55555.

"reportObjectSecId":0

The report will not be executed for a subitem.

"flags":0

The report will be executed for the specified interval.

"from":1688144400

The interval will start on 2023 June 30 at 20:00 (GMT+0).

Requests use Unix time. You can use publicly available online tools to convert date and time to Unix time.

"to":1688173199

The interval will end on 2023 July 1 at 03:59 (GMT+0).

"remoteExec":1

The report will be executed in the background on the server.

 Response
{
	"remoteExec":1
}

4. Checking the Execution Status

Since the report is being executed in the background on the server, let’s check the status of its execution using the request report/get_report_status.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/get_report_status¶ms={}&sid=SESSION_IDENTIFIER
 Response
{
	"status":4
}

Status code 4 indicates that the report has been executed successfully. The interpretation of other values can be found on the page with a request description.

5. Obtaining the Report Result

Use the request report/apply_report_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/apply_report_result¶ms={}&sid=SESSION_IDENTIFIER
 Response
{
	"reportResult":{
		"msgsRendered":0,
		"stats":[],
		"tables":[
			{
				"name":"unit_trips",
				"label":"Trips",
				"grouping":{
					"nested":{
						"type":"day"
					},
					"type":"month"
				},
				"flags":4491,
				"rows":2,
				"level":3,
				"columns":6,
				"header":[
					"№",
					"Grouping",
					"Beginning",
					"End",
					"Duration",
					"Mileage"
				],
				"header_type":[
					"",
					"",
					"time_begin",
					"time_end",
					"duration",
					"mileage"
				]
			}
		],
		"attachments":[]
	}
}

Three key parameters from the response that are important for us here are as follows:

  • tables — shows the number of tables in the report as an array. In this case, only one table (Trips) is mentioned, therefore its index will be 0.
  • rows — the number of rows in the table, which is 2 in this case. Therefore, their indexes range from 0 to 1. This refers only to the rows at the top level of nesting, there may be more inside.
  • level — the number of levels of nesting, which is 3 in this case, as there is grouping in the report. Therefore, there are levels with indexes from 0 to 2 in the table.

Indexes of tables, rows, columns, and nesting levels are counted from 0. This should be taken into account when referring to them.

Other parameters from the response can also be briefly listed. The columns parameter indicates the number of columns, and their names are described in the header parameter. A value of 0 for the msgsRendered parameter indicates that the report template doesn't display tracks on the map. Empty stats and attachments parameters indicate that there are no Statistics nor attachments (e.g., charts) in the report template.

6. Selecting Rows in a Multi-Level Table

Knowing the index of the table content, let’s display it using the request report/select_result_rows.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/select_result_rows¶ms={"tableIndex":0,"config":{"type":"range","data":{"from":0,"to":1,"level":2}}}&sid=SESSION_IDENTIFIER
Parameter and its valueDescription
"tableIndex":0

The content of the table with index 0 will be displayed.

"type":"range"

A sequence of rows will be requested.

"from":0

The first displayed row will have index 0.

"to":1

The last displayed row will have index 1.

"level":2

The result will display nesting levels up to index 2.

 Response
[
	{
		"n":0,
		"i1":0,
		"i2":1188,
		"t1":1688144420,
		"t2":1688158739,
		"d":1,
		"c":[
			"1",
			"June",
			{
				"t":"20:00:20",
				"v":1688144420,
				"y":47.2941741943,
				"x":26.4906959534,
				"u":55555
			},
			{
				"t":"23:58:59",
				"v":1688158739,
				"y":43.1049079895,
				"x":25.6173667908,
				"u":55555
			},
			"3:53:36",
			"576.60 km"
		],
		"r":[
			{
				"n":0,
				"i1":0,
				"i2":1188,
				"t1":1688144420,
				"t2":1688158739,
				"d":2,
				"c":[
					"1.1",
					"2023-06-30",
					{
						"t":"20:00:20",
						"v":1688144420,
						"y":47.2941741943,
						"x":26.4906959534,
						"u":55555
					},
					{
						"t":"23:58:59",
						"v":1688158739,
						"y":43.1049079895,
						"x":25.6173667908,
						"u":55555
					},
					"3:53:36",
					"576.60 km"
				],
				"r":[
					{
						"n":0,
						"i1":0,
						"i2":790,
						"t1":1688144420,
						"t2":1688154878,
						"d":0,
						"c":[
							"1.1.1",
							"2023-06-30 20:00:20",
							{
								"t":"20:00:20",
								"v":1688144420,
								"y":47.2941741943,
								"x":26.4906959534,
								"u":55555
							},
							{
								"t":"22:54:38",
								"v":1688154878,
								"y":43.8697662354,
								"x":26.0177116394,
								"u":55555
							},
							"2:54:18",
							"469.54 km"
						]
					},
					{
						"n":1,
						"i1":936,
						"i2":1188,
						"t1":1688155181,
						"t2":1688158739,
						"d":0,
						"c":[
							"1.1.2",
							"2023-06-30 22:59:41",
							{
								"t":"22:59:41",
								"v":1688155181,
								"y":43.8698196411,
								"x":26.0177154541,
								"u":55555
							},
							{
								"t":"23:58:59",
								"v":1688158739,
								"y":43.1049079895,
								"x":25.6173667908,
								"u":55555
							},
							"0:59:18",
							"107.06 km"
						]
					}
				]
			}
		]
	},
	{
		"n":1,
		"i1":1193,
		"i2":2910,
		"t1":1688158805,
		"t2":1688173175,
		"d":1,
		"c":[
			"2",
			"July",
				{
					"t":"00:00:05",
					"v":1688158805,
					"y":43.0983314514,
					"x":25.6316585541,
					"u":55555
				},
				{
					"t":"03:59:35",
					"v":1688173175,
					"y":41.5760040283,
					"x":26.9871864319,
					"u":55555
				},
				"3:41:42",
				"294.55 km"
		],
		"r":[
			{
				"n":0,
				"i1":1193,
				"i2":2910,
				"t1":1688158805,
				"t2":1688173175,
				"d":3,
				"c":[
					"2.1",
					"2023-07-01",
					{
						"t":"00:00:05",
						"v":1688158805,
						"y":43.0983314514,
						"x":25.6316585541,
						"u":55555
					},
					{
						"t":"03:59:35",
						"v":1688173175,
						"y":41.5760040283,
						"x":26.9871864319,
						"u":55555
					},
					"3:41:42",
					"294.55 km"
				],
				"r":[
					{
						"n":0,
						"i1":1193,
						"i2":2171,
						"t1":1688158805,
						"t2":1688169690,
						"d":0,
						"c":[
							"2.1.1",
							"2023-07-01 00:00:05",
							{
								"t":"00:00:05",
								"v":1688158805,
								"y":43.0983314514,
								"x":25.6316585541,
								"u":55555
							},
							{
								"t":"03:01:30",
								"v":1688169690,
								"y":41.7139854431,
								"x":26.3660545349,
								"u":55555
							},
							"3:01:25",
							"235.31 km"
						]
					},
					{
						"n":1,
						"i1":2340,
						"i2":2486,
						"t1":1688170034,
						"t2":1688170841,
						"d":0,
						"c":[
							"2.1.2",
							"2023-07-01 03:07:14",
							{
								"t":"03:07:14",
								"v":1688170034,
								"y":41.7140579224,
								"x":26.365901947,
								"u":55555
							},
							{
								"t":"03:20:41",
								"v":1688170841,
								"y":41.7122383118,
								"x":26.3712425232,
								"u":55555
							},
							"0:13:27",
							"1.39 km"
						]
					},
					{
						"n":2,
						"i1":2833,
						"i2":2910,
						"t1":1688171565,
						"t2":1688173175,
						"d":0,
						"c":[
							"2.1.3",
							"2023-07-01 03:32:45",
							{
								"t":"03:32:45",
								"v":1688171565,
								"y":41.7120819092,
								"x":26.3711204529,
								"u":55555
							},
							{
								"t":"03:59:35",
								"v":1688173175,
								"y":41.5760040283,
								"x":26.9871864319,
								"u":55555
							},
							"0:26:50",
							"57.84 km"
						]
					}
				]
			}
		]
	}
]

7. Export to File

Let’s export the result to a PDF file using the request report/export_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result¶ms={"format":2,"compress":0,"outputFileName":"Grouped%20trips"}&sid=SESSION_IDENTIFIER
Parameter and its valueDescription
"format":2

The report result will be exported in PDF format.

"compress":0

The exported file will not be compressed (added to an archive).

"outputFileName":"Grouped%20trips"

The exported file will have the name Grouped trips.

There is no response displayed for this API request, instead, the file download starts automatically.

8. Deleting the Result of the Previous Report

Use the request report/cleanup_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/cleanup_result¶ms={}&sid=SESSION_IDENTIFIER
 Response
{
	"error":0
}

A zero value indicates successful deletion.

Peculiarities of Obtaining Results

Obtaining data from tables can be performed using the requests report/get_result_rows or report/select_result_rows, which use the parameter tableIndex to access a table with a specific index. At the same time, it is necessary to take into account that when executing a report for different intervals, the index of the same table may change due to the presence or absence of other tables.

To better understand the situation, let's consider an example. Let’s suppose the report template includes tables for Trips, Fuel Fillings, and Geofences. When executing the report for the interval from July 1st to 3rd, the result will contain all tables, and therefore their indexes will have the following values:

0 — Trips
1 — Fuel Drains
2 — Geofences

At the same time, when executing the report for the interval from July 4th to 6th, the indexes of some tables will change due to the absence of registered fuel fillings and will take other values:

0 — Trips
1 — Geofences

In this example, it is clear that when executing the report for different intervals, the index of the Geofences table changes. Therefore, accessing the table with index 2 will not always display information about visiting geofences. To fix such situations, it is recommended to apply additional checks, for example, based on the table name or the names of its columns.

When using a report for a group of units, additional checks can be avoided by disabling the Skip empty rows option in the report template settings. In this case, the tables will be displayed even if they have no data and will contain empty rows.

Ekaterina Grib,Customer Service Engineer

Intro to SDK: FAQ
  • technical_consulting

This article contains answers to the most frequently asked questions about the Remote API.

You may also find the following sources useful:

  • The article Intro to SDK: Basic Requests.
  • The article Intro to SDK: Creation of Accounts and Units.
  • The article Intro to SDK: Reports Execution.
  • Portal designed for developers with documentation and detailed description of each request.
  • Code samples for working with reports.
  • Examples of ready-made solutions using the SDK from the Marketplace section.
  • Wialon API and SDK: how-to videos webinar series.
  • Collection of examples in the Postman application for testing API requests.
  • Custom SDK development forum section.

Are there any limitations on API usage?

Global limitations are described in the documentation. Typically, reaching these limitations indicates that the developed application is not optimized for working with the API. For example, it makes multiple authorization requests instead of maintaining one active session.

There are also limitations on some requests, which are mentioned in the request description in the documentation. For example, only one report can be executed during a session at a time. If the session contains the results of the previous report execution, they should be deleted using the request report/cleanup_result before executing the next report. Additionally, the request to execute reports cannot be performed simultaneously with some other requests.

Is it possible to organize real-time data transfer from Wialon using the API?

No. API requests work on the request-response method. This means that data on the receiving side will not be updated without sending a request.

If it is necessary to receive data from hardware as soon as new messages arrive, retranslators can be used.

How to create a locator using the API?

Let's consider an example: it is necessary to create a locator with infinite lifespan, which will display units with system IDs 11111111 and 22222222, as well as geofences from a resource with system ID 12345678, but will not display units’ tracks.

To do this, you need to use the request token/update:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/update¶ms=
{"callMode":"create","app":"locator","at":0,"dur":0,"fl":256,"p":"{\"note\":\"Bus\",\"zones\":1,\"tracks\":0}","items":[11111111,22222222,12345678]}&sid=SESSION_IDENTIFIER

Parameter and its value

Description
"callMode":"create"

The action chosen is creation (editing and deletion are also available).

"app":"locator"

The value locator is necessary for display in the list of links in the web interface.

"at":0

Token activation time in UNIX-time is set to 0, which means the locator will start working immediately after creation.

"dur":0

Token lifespan after activation is set to 0, which means its lifespan will be infinite.

"fl":256

This access flag value will only allow tracking units in online mode.

"p":"{\"note\":\"Bus\",\"zones\":1,\"tracks\":0}"

The word Bus will be used as a note to distinguish this locator from others in the general list. The locator will display geofences but will not display units’ tracks.

"items":[11111111,22222222,12345678]

The locator will display units with system IDs 11111111 and 22222222, as well as geofences from a resource with system ID 12345678.

The response to the request will include the parameter h containing the token value. To obtain the desired link, the token value should be inserted into the following link: https://hosting.wialon.com/locator/index.html?t=TOKEN_VALUE

How to obtain a token with maximum access and infinite lifespan?

If token creation is done through an extended form, it is necessary to use the parameters access_type=-1 and duration=0. For example:

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

If token creation is done through the request token/update, it is necessary to use the parameters fl=-1 and dur=0. For example:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/update¶ms=
{"callMode":"create","app":"Wialon Hosting","at":0,"dur":0,"fl":-1,"p":"{}"}&sid=SESSION_IDENTIFIER

The token is automatically deleted if it is not used within 100 days, even if its lifespan is unlimited (parameter duration or dur equals 0).

Why can an error with code 1 be returned when using an unlimited token?

An error with code 1 indicates that the current session is invalid. The token's lifespan is not directly related to the session.

To fix the situation, it is necessary to perform authorization again. The response to the token login contains the parameter eid, and its value is the unique session identifier. It will be used in almost all API requests.

If no requests are made within 5 minutes of the session, it becomes inactive. To maintain the session, you can send the request avl_evts every 5 minutes.

How to fix an error with code 4?

An error with code 4 corresponds to invalid input, which can mean:

  • incorrect data type (numeric, text, etc.);

  • incorrect parameter names;
  • incorrect separators (commas, quotes, spaces, brackets, etc.);
  • absence of encoding for transmission in the URL.

Let's consider an example of a request with all the mentioned errors:

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result¶ms={"format":"2";"compres":0;"outputFileName":"List of trips"}&sid=SESSION_IDENTIFIER

In this example, the following errors were made:

  1. The parameter format should contain a number, but since its value is enclosed in quotes, it is interpreted as text.
  2. Instead of the parameter with the name compress, a parameter with the name compres was used.
  3. A semicolon was used instead of a comma to separate the parameters.
  4. The space character was not encoded for transmission in the URL.

To check the encoding in the URL, you can use publicly available online tools.

The correct request will look like this:

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result¶ms={"format":2,"compress":0,"outputFileName":"List%20of%20trips"}&sid=SESSION_IDENTIFIER

Why does an error with code 7 occur when using unique unit IDs?

API requests use internal system IDs of items, not unique unit IDs from the General tab. By default, these IDs are not displayed in web interfaces.

You can use the search items by property request (core/search_items) to obtain the system IDs of items. The desired value will be found in the parameter id of the response to this request.

Other methods of displaying system IDs are described in the article Intro to SDK: Basic Requests.

Why is access to the unit restricted even though the user has full access rights?

The problem is likely due to insufficient rights of the token being used.

To check the rights of the token, perform the token login:

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

The response will contain the parameter fl, which displays the current rights of the token. To change them, edit the current token or create a new one.

To provide different rights, the flags need to be summed together.

For example, if you need to provide the right to online tracking ("fl":256) and view access to most data ("fl":512), you should use the value "fl":768, since 256 + 512 = 768.

How to get the last coordinates of units?

To obtain the last coordinates of multiple units, you can use the search items by property request (core/search_items). In this case, you need to specify access flags according to which the response will display unit names ("flag":1") and information about the last position of units ("flag":1024). Flags can be summed together, so the request will use the value 1 + 1024 = 1025.

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

How to get a list of all units available to the user?

To display all units available to the user, you can use the search items by property request (core/search_items) with the value "propValueMask":"*".

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

The response will return a list of units that are accessible to the user whose session identifier was used in the request.

How to get the names of groups to which a certain unit is added?

To get the names of groups that include a unit with the system ID 11112222, you need to use the search items by property request (core/search_items) with the values "itemsType":"avl_unit_group", "propName":"sys_units", and "propType":"list".

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

How to get the names of units from a certain group?

To get the names of units that are included in a group named Group, you need to use two search items by property requests (core/search_items): the first one will search for the unit group (avl_unit_group), and the second one will search for the unit (avl_unit).

  1. First, you need to get a list of system IDs of units that belong to the group (specify its name in the parameter propValueMask):

    https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit_group","propName":"sys_name","propValueMask":"Group","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER
     Response
    {
    	"searchSpec":{
    		"itemsType":"avl_unit_group",
    		"propName":"sys_name",
    		"propValueMask":"Group",
    		"sortType":"sys_name",
    		"propType":"",
    		"or_logic":"0"
    	},
    	"dataFlags":1,
    	"totalItemsCount":1,
    	"indexFrom":0,
    	"indexTo":0,
    	"items":[
    		{
    			"nm":"Group",
    			"cls":5,
    			"id":10000000,
    			"mu":0,
    			"u":[
    				20000001,
    				20000002,
    				20000003
    			],
    			"uacl":-1
    		}
    	]
    }
    
  2. In the response to the previous request, you need to find the parameter u with the system IDs of units. You should substitute them in the parameter propValueMask for the next search request:

    https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"sys_id","propValueMask":"20000001,20000002,20000003","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER
     Response
    {
    	searchSpec:{
    		itemsType:"avl_unit",
    		propName:"sys_id",
    		propValueMask:"20000001,20000002,20000003",
    		sortType:"sys_name",
    		propType:"",
    		or_logic:"0"
    	},
    	dataFlags:1,
    	totalItemsCount:3,
    	indexFrom:0,
    	indexTo:0,
    	items:[
    		{
    			nm:"Unit_1",
    			cls:2,
    			id:20000001,
    			mu:0,
    			uacl:-1
    		},
    		{
    			nm:"Unit_2",
    			cls:2,
    			id:20000002,
    			mu:0,
    			uacl:-1
    		},
    		{
    			nm:"Unit_3",
    			cls:2,
    			id:20000003,
    			mu:0,
    			uacl:-1
    		}
    	]
    }
    

    The names of units will be displayed in the parameters nm.

Why do the results of the report differ between the interface and the response to the API request?

When executing reports through API requests, it is important not to forget to set the time zone for the current session. To do this, immediately after authorization, you should apply the user's localization settings once.

When working with reports through the API, you need to consider the peculiarities of obtaining results by table index.

Ekaterina Grib,Customer Service Engineer

10
  • 10
  • 25
  • 30
Thank you for your feedback!
Report a mistake
Text with the mistake Comment
Maximum 500 characters