How to efficiently read a sensor with the command line API

How to efficiently read a sensor with the command line API

Our command line library enables you to use all our modules from a terminal or in a shell script.
We have used this library several times to configure a module or perform a one-time task, but we noticed that we never yet spoke of another type of use: monitoring the values measured in a shell script.




If you want to monitor the value of a sensor, you can use the traditional commands get_XXX in a loop with a shell scrip or the UNIX watch tool.

$ watch -n5 YSensor all get_currentValue



However, this technique is not efficient. First, each time you call the YSensor tool it must initialize a connection with the module, which can take some time. Second, this technique enables you to obtain only a measure at a given time every X seconds. The measures between each call to YSensor are ignored.

In our programming libraries, the correct solution to monitor the value of a sensor is to use callbacks: Polling vs. callback.

For the command line library, there is no callback, strictly speaking, but two functions enable you to read the values of a sensor, efficiently and on a continuous basis.

get_valueChange


The get_valueChange command is the equivalent of value callbacks in programming libraries. This means that this function enables you to obtain the advertised value efficiently.

As soon as the sensor of the module detects a modification of the measured signal, it sends the new value to the command line library which displays it immediately. The command doesn't give back control and goes on to display on the standard output the new values it receives from the sensors. There is no latency dependent on an external delay and the measures are not lost.

Here is an example on a computer with a Yocto-Meteo connected by USB:

yocto@linux-laptop:~$ YSensor all get_valueChange OK: METEOMK2-120582.temperature.valueChange = 23.52.
OK: METEOMK2-120582.pressure.valueChange = 972.02.
OK: METEOMK2-120582.humidity.valueChange = 46.7.
OK: METEOMK2-120582.humidity.valueChange = 46.6.



Note that you can configure the command to give back control after the first value change with the two following optional parameters:

  • minWait: the minimum time to wait for a value, zero to wait at least until the first value.
  • maxWait: the maximum time to wait for a value, zero to wait no longer than the first value.


get_timedReport


The get_timedReport command is the equivalent of periodic callbacks in Yoctopuce programming libraries. This means that this function enables you to obtain at fixed interval the minimal, average, and maximal value of a sensor. Like with get_valueChange, the values are immediately displayed on the standard output.

To use this feature, the reportFrequency attribute of the module must have been configured beforehand. As it is the module which internally computes the minimal, average, and maximal values and transmits these data periodically to the library, if the reportFrequency attribute is not configured, the module never sends periodic notifications. You can configure this attribute with the VirtualHub or, as we'll see below, directly with the command line library.

Here is an example of a machine with a Yocto-Meteo connected by USB:

yocto@linux-laptop:~$ YSensor all get_timedReport
OK: METEOMK2-120582.humidity.timedReport = 1572482454;46.590;46.647;46.670.
OK: METEOMK2-120582.pressure.timedReport = 1572482454;971.840;971.845;971.851.
OK: METEOMK2-120582.temperature.timedReport = 1572482454;23.513;23.522;23.534.
OK: METEOMK2-120582.humidity.timedReport = 1572482456;46.590;46.6470;46.6700.
OK: METEOMK2-120582.pressure.timedReport = 1572482456;971.839;971.845;971.853.
OK: METEOMK2-120582.temperature.timedReport = 1572482456;23.520;23.523;23.534.
OK: METEOMK2-120582.humidity.timedReport = 1572482458;46.630;46.655;46.680.
OK: METEOMK2-120582.pressure.timedReport = 1572482458;971.839;971.844;971.849.
OK: METEOMK2-120582.temperature.timedReport = 1572482458;23.517;23.519;23.523.
OK: METEOMK2-120582.humidity.timedReport = 1572482460;46.600;46.626;46.670.
OK: METEOMK2-120582.pressure.timedReport = 1572482460;971.837;971.845;971.850.
OK: METEOMK2-120582.temperature.timedReport = 1572482460;23.510;23.517;23.523.



As with the get_valueChange command, you can specify a minWait and a maxWait to give back control after the first measure.

Concrete example

To illustrate how to use these commands, here is how to write a micro script made of only one line which retrieves the temperature of a Yocto-Meteo and, if the temperature is above 25° during the last 5 minutes, adds an entry on the Linux system logs.

Installing the library


You must first install the latest version of our command line library with apt-get.

If it is not done already, you must add our APT repository to the system with the following commands:

wget -qO - https://www.yoctopuce.com/apt/KEY.gpg | sudo apt-key add - echo "deb https://www.yoctopuce.com/ apt/stable/" | sudo tee /etc/apt/sources.list.d/yoctopuce.list



You can then install the library with a apt-get tool

sudo apt-get update sudo apt-get install yoctolib-cmdlines



Configuring the module


Then, you must configure the periodic notification frequency of the temperature sensor of the Yocto-Meteo. For this example, use a frequency of 12 times per hours, which means a 5 minutes interval. Note the -s option which saves this parameters in the flash memory of the Yocto-Meteo. In this way, even if the module is disconnected and reconnected, it still sends a notification every 5 minutes.

yocto@linux-laptop:~$ YTemperature -s all set_reportFrequency 12/h OK: METEOMK2-120582.temperature.set_reportFrequency = 12/h. OK: METEOMK2-120582.module.saveToFlash executed.



Reading the temperature on a continuous basis


Then to retrieve these notifications efficiently, use the get_timedReport command. To simplify parsing the displayed data, you can use the --csv option which formats the results in a CSV format.

Concretely, the YTemperature tool displays the following pieces of information, separated by ";" on a single line every 5 minutes:

  • the sensor hardware ID
  • the time stamp of the measure
  • the minimal value during the 5 minutes
  • the average value during the 5 minutes
  • the maximal value during the 5 minutes


Before you go on, you can check that everything works as planned.

yocto@linux-laptop:~$ YTemperature --csv all get_timedReport METEOMK2-120582.temperature;2019-10-31 00:45:00.00;23.579;23.593;23.608 METEOMK2-120582.temperature;2019-10-31 00:50:00.00;23.568;23.598;23.632 METEOMK2-120582.temperature;2019-10-31 00:55:00.00;23.582;23.606;23.632 METEOMK2-120582.temperature;2019-10-31 01:00:00.00;23.542;23.572;23.600 METEOMK2-120582.temperature;2019-10-31 01:05:00.00;23.546;23.570;23.596



The last step consists in redirecting the YTemperature output on the awk tool to parse each line and make it something interesting. In this case, you want to call the logger command if the temperature goes above 25° C.

The awk command allowing you to parse the output is the following:

awk -F\; '$4>25 {system("logger -s \"High temperature : \""$1"="$4 "°")}'



The -F\; option tells awk that each field is separated by a ";".
In the script, the $1, $2, $3, $4, and $5 variables correspond respectively to the hardware ID, the time stamp of the measure, the min temperature, the average temperature, and the max temperature.
The "$4>25" tells awk to execute the remainder only if the average temperature ($4) goes above 25. The remainder is by design a call to the logger tool which adds an entry in the system logs.

The full command is therefore:

yocto@linux-laptop:~$ YTemperature --csv all get_timedReport | awk -F\; '$4>25 {system("logger -s \"High temperature : \""$1"="$4 "°")}' <13>Oct 31 17:58:12 yocto: High temperature : METEOMK2-120582.temperature=25.3190°



Conclusion

As we just saw it, you can efficiently monitor a Yoctopuce sensor with our command line API. This feature will certainly appeal to shell script gurus. However, in our opinion, it is simpler in 99% of the cases to write a short program in a language such as Python.

Add a comment No comment yet Back to blog












Yoctopuce, get your stuff connected.