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 gurtam.com in the Hardware section. To do this, enter the desired device model in the Search hardware line. You can also select one of the categories of hardware types and find the desired model on the list. Then, on the hardware page, go to the Parameters tab (an example of such a page for WiaTag).

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

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

Engine ignition sensor

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

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

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

Practical method for selecting and checking a parameter

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

Mileage sensors

Currently, Wialon has two sensors for tracking mileage:

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

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

Practical method for selecting and checking a parameter

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

You can use the parameter in the Mileage sensor if

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

You can use the parameter in the Relative odometer if

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

Fuel sensors

Currently, Wialon has several types of fuel sensors:

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

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

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

AbsFCS

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

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

InsFCS and ImpFCS

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

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

FLS

You can use the parameter in the Fuel level sensor if

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

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

Ekaterina Grib,Customer Service Engineer 2022-03-16

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

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

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

Displaying digital inputs/outputs

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

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

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

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

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

I/O=4D/A5

The obvious conciseness of the entry is a key advantage.

Defining the number of an activated digital input/output

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

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

Selection

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

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

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

Mathematical approach

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

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

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

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

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

13. Determine the bit numbers for a given number:
    

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

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

Using digital inputs/outputs

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

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

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

Oleg Zharkovsky,Customer Service Engineer 2022-02-03

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

General principle of sensors operation

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

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

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

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

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

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

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

When to use a calculation table

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

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

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

Calculation table settings

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

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

XY pairs

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

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

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

X is an input value

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

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

Otherwise, this condition can be written as follows:

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

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

a is a slope coefficient of the line

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

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

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

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

An example of lines with different displacements

Lower and upper bounds

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

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

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

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

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

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

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

The principle of the calculation table operation

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

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

The chart of the Y=0.5⋅X² function

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

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

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

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

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

Rationale and use cases

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

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

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

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

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

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

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

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

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

The temperature chart where higher parameter values correspond to negative temperatures

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

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

The ignition status chart depending on voltage

Oleg Zharkovsky,Customer Service Engineer 2023-02-21

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

Challenge

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

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

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

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

Theoretical background

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

Numeral systems

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

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

The table below lists a few common numeral systems:

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

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

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

Bits and bytes

A bit is one digit of a binary code.

A byte is a group of 8 bits.

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

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

Floating-point numbers

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

Below are some examples of such numbers:

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

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

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

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

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

Practical application

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

A binary to an integer decimal number conversion

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

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

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

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

,

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

This formula can also be presented in the following way:

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

Let’s consider an example with the same number:

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

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

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

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

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

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

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

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

Extracting a part of a parameter

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

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

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

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

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

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

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

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

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

Considering the sign of a number

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

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

(DEC) 13 = (BIN) 1101

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

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

,

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

This formula can also be presented in the following way:

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

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

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

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

A binary to a decimal floating-point number conversion

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

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

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

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

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

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

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

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

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

The biased exponent E will be equal to:

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

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

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

After a simplification, we get:

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

When substituting the numbers, we get:

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

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

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

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

Oleg Zharkovsky,Customer Service Engineer 2023-05-16

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

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

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

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

1. GPS

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

a. Outliers of coordinates and incorrect message chronology

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

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

Possible solutions:

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

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

b. Using the mileage sensor

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

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

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

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

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

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

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

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

Possible solutions:

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

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

2. GPS + ignition sensor

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

Incorrect value of the ignition sensor

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

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

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

Possible solutions:

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

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

3. Mileage sensor

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

a. Resetting values of the mileage parameter

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

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

The reason is the reset of the mileage sensor parameter.

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

Possible solutions:

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

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

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

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

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

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

Possible solutions:

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

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

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

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

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

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

Possible solutions:

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

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

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

Pavel Chebotarev,Customer Service Engineer 2022-08-03

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

Theoretical background

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

Speed and acceleration

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

v = S / Δt,

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

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

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

a = Δv / Δt,

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

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

Units of measurement

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

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

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

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

Accelerometers

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

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

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

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

Implementation in Wialon

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

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

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

General setting approach

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

Here are some details on each of the approaches:

1. Tracker sends calculated eco driving parameters

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

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

2. Tracker sends calculated acceleration parameters in a custom format

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

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

3. Tracker sends raw values of acceleration along the axes

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

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

4. Tracker does not send any data of acceleration

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

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

Recommended criteria values

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

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

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

Criteria presets

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

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

Oleg Zharkovsky,Customer Service Engineer 2023-05-03