Virtual sensors usage

In the world of IoT and telematics, understanding and interpreting data is crucial. This is where virtual sensors come into play. These powerful tools help users comprehend data from various device sensors in a more meaningful way, often translating it into text form for easier understanding. In this article, we'll delve into what virtual sensors are, how they work, and how to configure them.

What are virtual sensors

Virtual sensors interpret and translate raw data from the physical sensors of a device, making it comprehensible and actionable. For example, they can get data from state fields or even from a certain bit in a particular field.

One of the standout features of virtual sensors is their ability to monitor ignition, even on devices where no ignition input is provided or that input is already occupied by other needs. This allows users to read ignition from any desired source, be it motion, RPM, or voltage.

The information from virtual sensors can be viewed in several ways:

1. Current readings in widgets.

2. Historical readings in reports.

3. Alerts when certain values are received in rules.

Virtual sensors configuration

Virtual sensors are available on all devices that support reading sensor data or state fields. To set up these sensors, you first need to create a virtual sensor.

To do this, navigate to 'devices and settings' and select the 'sensors and buttons' portlet. Here, you can create a new sensor by pressing '+' and selecting 'virtual sensor'.

Every GPS tracker may have up to 100 virtual sensors.

Before setting up the sensor, it's important to decide what you intend to use the sensor for. This will determine the method, which is one of the fundamental options for outputting the result.

Let's break down the settings depending on the use case example. You can tailor any of these examples to your specific business case and select a calculation method based on that.

Value in range

A 'Value in Range' sensor is an effective tool for maintaining essential parameters, such as virtual ignition, temperature, humidity, and fuel level, within a specified range. It functions on a simple principle:

• if a sensor value falls within defined boundaries, it equates to 1 (your A value),

• if it's outside these boundaries, it corresponds to 0 (your B value).

To get virtual ignition

If your device is without an ignition input or all physical inputs are used on it, a virtual ignition can be utilized to detect the ignition state. This process works by detecting a significant increase in the car's onboard voltage when the engine is turned on. This change in voltage can then be used as a signal to determine whether the engine is running or not. Typically, if the board voltage exceeds 13.2 V, it's a clear indication that the engine is operational.

You can use different data like RPM or movement state.

Creating a virtual ignition sensor involves a few simple steps:

1. Start by giving your sensor a descriptive name that accurately represents its function.

2. Set the input to 'Board Voltage' or any other sensor as needed.

3. Enable the 'Considering as ignition state' option in the settings.

4. Select 'Value in range' as the calculation method.

5. Define a minimum range value (such as 13.2V). A maximum value isn't necessary as the Board Voltage can vary when the ignition is on.

6. Finally, set the 0 and 1 states, usually representing 'Off' and 'On' respectively.

With these settings in place, if the incoming onboard value falls within your specified range, the platform will switch the ignition state to "on". If it falls outside of this range, the state will switch to "off".

This Virtual Ignition method is also factored into reports and notifications based on its status. For instance, it can be used to generate engine hours reports or send alerts for excessive idling.

Moreover, this virtual ignition will help in detecting trips and parking instances with ignition consideration.

To get sensor values into understandable format

This example parallels the one we just discussed about setting up a virtual ignition, but in this case, instead of monitoring a vehicle's ignition, we're keeping tabs on temperature.

Let's say you have an analog sensor that gathers temperature data. For instance, it might output 1020 for -10°C, and 1900 for 0°C. It's important to note that the information from these analog sensors comes uncalibrated, which means you'll need to specify it in this raw form when setting up your virtual sensor.

Now, let's establish our range. If the sensor reading falls anywhere between 1020 and 1900, we'll classify that as "cold" (1). On the other hand, any reading above 1900, we'll deem as "hot" (0).

So, by following this method, you can translate complex sensor values into a simplified, more understandable format.

Source Value

With virtual sensors, you have the flexibility to assign your own definitions to any values received. This feature is particularly handy when dealing with predefined sets of values or strings, allowing you to work with static values without the need to specify different ranges. Plus, it's adaptable to any data you require. For instance:

• 0/1

• true/false

• on/off

• open/close

• armed/disarmed

• state 1/state 2/state 3

• key 1/key 2/key 3, etc.

The mode operates in the following way:

• When value 1 is received, that's designated as your value A.

• When value 2 arrives, that becomes your value B.

• When value 3 is transmitted, that's identified as your value C, and so forth.

The best way to get historical readings on this calculation method sensors is to use it with state field value alert with report on all events.

Let's clarify this functionality with a practical example.

When you need to define every sensor value to understand the readings

Certain sensors might supply different numerical values to a platform. For example, let's say we have a truck equipped with a PTO drive engagement sensor that only outputs the following values:

• 0 - No PTO drive is engaged

• 1 - At least one PTO drive is engaged

• 2 - Error

• 3 - Not available

To set up such a sensor, follow these steps:

1. Begin by assigning its name.

2. Choose the appropriate input.

3. Ensure "Consider as ignition" is switched off.

4. Select "Source Value" as the calculation method.

5. Populate the table with your own values on the left side and their corresponding sensor values on the right. You can add more rows by clicking the "+" symbol, and remove them using the trash can icon.

By following these steps, you can easily customize how your sensor values are displayed and understood.

Hardware key readings for drivers, equipment and trailers

Certain devices have the ability to recognize drivers and their iButtons, RFID keys, or equipment linked via Bluetooth sensors. The platform can identify the closest equipment or driver to the device, and a Virtual Sensor can display these names.

The simplest method of identification is through the use of tags. Each unit that's connected to heavy equipment has its own sensor with an attached tag. This tag serves as a hardware key that's recognizable by the platform. When the unit is connected to the machine, this key is transmitted to the platform.

Just like the way we named values for PTO, the associated name of this key can be displayed in an easily understandable format. This ensures that you always know which unit is communicating with your machine.

Event code readings

Navixy platform has the capability to provide you with the most recent event code received from your device. In this scenario, you can select the event code input and define the appropriate event codes to be displayed in widgets. For instance, if you're using a Jimi JC400, you can access Driver Monitoring System (DMS) events.

Bit index

Certain devices might transmit complex data in their packets, sometimes consolidating several parameters into a single value. The Virtual Sensors feature gives you the ability to interact with segments of telematics values, helping you decode the data sent by the GPS hardware.

For instance, let's say a value of 011 is transmitted. We must first interpret this information in little endian (from he right to the left) according to the protocol:

• 1 - Indicates the status of the driver's seat belt: 0 signifies it's fastened, 1 means it's unfastened. (Bit 0)

• 1 - Displays the status of the driver's door: 0 means it's closed, 1 indicates it's open. (Bit 1)

• 0 - Represents the condition of the hood: 0 means it's closed, 1 indicates it's open. (Bit 2)

Each position in the parameter reflects the status of different vehicle systems. To configure and display these, you'll need to create a separate sensor for each parameter.

For a sensor that shows the condition of the car hood in our example, you would need to:

1. Assign a name to the sensor.

2. Choose the input based on the device's documentation.

3. Select "Bit Index" as the calculation method.

4. Choose bit 2 for this field.

Here's an example for a sensor that displays the condition of the car hood. Once a virtual sensor is set up and its associated device sensor has provided data, you can view it in the "Sensor Readings" widget on the device's Information tab, notifications with alerts and historical values in reports.

Getting data in reports to analyze

To analyze historical readings, you have five available options:

1. The Equipment working time report reveals the operational times of any unit linked to discrete or virtual inputs with a calculation method value in the range or bit index. It allows you to learn about the operating time of the equipment both while moving and stationary, obtain daily activity data, and pinpoint when and where the equipment was activated.

2. The Engine Hours Report provides the working duration for ignition-based sensors. It offers valuable insights into the operation time of your ignition-based equipment, whether it's on the move or idle. The report also delivers daily activity data, enabling you to identify precisely when and where the ignition was on.

3. The measuring sensors report displays data from any configured measurement sensors or virtual sensors with a calculation method source value for a selected period. It enables you to view both graphical and statistical information from your device's sensors.

4. The vehicle readings report showcases data gathered from your vehicle's instruments via the CAN/OBD or virtual sensors for any chosen time frame. This includes information such as mileage, engine RPMs, speed, fuel consumption, coolant temperature, and more.

5. Reports on all events is handy for obtaining information about specific states received by the sensor with the aid of rules.

For each of these reports, you can find detailed articles explaining how they work, how to read them, and in what scenarios they are most useful.

Getting notifications on virtual sensors

There are a couple of rules you can implement to receive alerts based on virtual sensor values:

1. Parameter in range rule is associated with the use of measurement sensors. Its function is to generate a notification whenever the sensor data received by the platform falls within or outside a specified range.

2. State field value is used to monitor any virtual sensor states that you define in the state column when configuring the virtual sensor. As soon as that state is received, you'll be notified.

Virtual sensors with APIs

For integrators, the ability to create or read virtual sensors in their applications could be beneficial. In these instances, our APIs can be utilized. To get more information about the virtual sensors usage with APIs, follow our how-to article.

The virtual sensor object consists of the following parameters:

{
  "type": "virtual",
  "id": 1700049,
  "sensor_type": "virtual_ignition",
  "name": "Virtual Ignition",
  "input_name": "board_voltage",
  "parameters": {
    "calc_method": "in_range",
    "range_from": 13.4,
    "value_titles": [{
        "value": "0",
        "title": "Off"
    }, {
        "value": "1",
        "title": "On"
    }]
  }
}

type - string. This should be set as "virtual" for virtual sensors.

id- int. This is the sensor's ID.

sensor_type - enum. Must be "virtual_ignition" for virtual ignition sensor or "state" for others.

name - string. Your name of a sensor. May contain up to 100 characters.

input_name - string. A source input field (identifier). It indicates from which sensor the information is received by the platform.

parameters - an object with additional parameters.

calc_method - enum. This defines the method of sensor value calculation. It must be one of the following: "in_range", "identity", "bit_index".

range_from - double. Lower boundary of the range and is only used with the "in_range" calculation method.

range_to - double. Upper boundary of the range and is only used with the "in_range" calculation method.

bit_index - int, [1..N]. A bit index in the input field source value and is only used with the "bit_index" calculation method.

value_titles - a mapping for assigning special titles for sensor values, if required.

value - string. Sensor value - raw value that comes from a device. Max size 64 chars.

title - string. Your title for the sensor value. Max size 64 chars.

• There can only be one virtual sensor of type "virtual_ignition" for each tracker.

• For the "in_range" calculation method, one or both fields "range_from" and "range_to" must be specified.

• The "bit_index" field is mandatory for the "bit_index" calculation method.

• All values within "value_titles" must be unique.

Create

You can create such sensor with tracker/sensor/create request. For example, we need to track the virtual ignition on a device by the board voltage. In this case, we should use call:

curl -X POST 'https://api.navixy.com/v2/tracker/sensor/create' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "tracker_id": 123456, "sensor": {"type": "virtual", "sensor_type": "virtual_ignition", "name": "Virtual Ignition", "input_name": "board_voltage", "parameters": {"calc_method": "in_range", "range_from": 13.4, "value_titles": [{"value": "0", "title": "Off"}, {"value": "1", "title": "On"}]}}}'

Don’t use sensor_id parameter in the sensor object since there is no sensor with any ID before it is created.

The platform will notify you about the result with the assigned ID to this newly created sensor.

Reconfigure

In case you want to change something in the virtual sensor settings, you can use tracker/sensor/update API call. For instance, we should change the range from which the virtual ignition must be calculated.

curl -X POST 'https://api.navixy.com/v2/tracker/sensor/update' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "tracker_id": 123456, "sensor": {"type": "virtual", "sensor_id": 965837, "sensor_type": "virtual_ignition", "name": "Virtual Ignition", "input_name": "board_voltage", "parameters": {"calc_method": "in_range", "range_from": 13.7, "value_titles": [{"value": "0", "title": "Off"}, {"value": "1", "title": "On"}]}}}'

Get values per period

When you want to show sensor readings or probably generate your own report it will be useful to get information in form value - time. In this case, the API call tracker/sensor/data/read will help you.

curl -X POST 'https://api.navixy.com/v2/tracker/sensor/data/read' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "tracker_id": 123456, "sensor_id": 965837, "from": "2023-07-24 00:00:00", "to": "2023-07-24 23:59:00", "raw_data": false}'

Use raw_data: true in case, you need to get the raw sensor values per period.

Now you know everything about the work with virtual sensors and you can get all information you need from your devices in the necessary format.