Everything you wanted to know on Yoctopuce sensors

Everything you wanted to know on Yoctopuce sensors

A large majority of Yoctopuce modules are sensors, or are used to interface external sensors. Therefore the programming interface to access the sensors and retrieve their measures is among the most developed and continues to be enriched following the requests that we receive. To help you find the method that suits you best, today we offer a synthesis of everything at your disposal.



Yoctopuce sensors can provide via USB -or via the network- measurements of one or more physical quantities. For instance, the Yocto-Meteo measures the temperature, humidity and atmospheric pressure. From the user perspective, these three functions can be used and configured individually, as explained in previous article on the logical structure of Yoctopuce devices. In the following text, where we explain the parameters of a sensor, we actually explain the parameters available in each of these measuring functions.

Each measuring function is accessed using a dedicated class in the Yoctopuce programming library. For instance, you would use the YTemperature class to read a temperature sensor. But all these classes inherit from the YSensor class and thus share a large number of common attributes and methods.

Current value

The currentValue attribute contains the value of the latest measure retrieved from the sensor. The simplest way to read a Yoctopuce sensor is therefore to call the get_currentValue() method. For example:

YLightSensor sensor;
// retrieves the value of the dining room light sensor
sensor = YLightSensor.FindLightSensor('diningRoom');
double luxCount = sensor.get_currentValue();


The current value refresh rate depends on the sensor technology and thus changes depending on the module. Usually, you can find this parameter in the specifications of the product. For example, you can find in the Yocto-Light-V3 specifications a 4Hz refresh rate, which means that the value is updated 4 times per second. So, no need to read it more often...

Minimal and maximal values

On top of providing the latest measure, each sensor keeps in the lowestValue and highestValue attributes, the minimal and maximal values measured. This can be useful for example if your program doesn't constantly question the sensor, but needs to know extreme values. You can manually initialize these values again when you want:

// retrieves the min/max values since the latest initialization
double luxMin = sensor.get_lowestValue();
double luxMax = sensor.get_highestValue();
// initializes min/max to the current value
sensor.set_lowestValue(luxCount);
sensor.set_highestValue(luxCount);


Note that the min/max values are not preserved when the module is powered off.

Unit

To ease measure interpretation, all the sensors have a unit attribute indicating the physical unit they measure. Often, you can't modify this attribute: a Yocto-Volt always returns measures in Volts, and so on. But sometimes, you can change the unit. For example, with all the temperatures sensors you can choose between degrees Celsius, degrees Fahrenheit, or Kelvins:

// Configuring all the temperature sensors in kelvins
YTemperature tempSensor = FirstTemperature();
while(tempSensor != null) {
  tempSensor.set_unit('K');
  tempSensor = tempSensor.nextTemperature();
}


To know if you can change the unit for a given sensor, simply read the reference of the corresponding class. You can see for example that the YVoltage class doesn't have a set_unit() method, in the opposite to the YTemperature class.

Resolution

Each Yoctopuce sensor also has a resolution attribute indicating the significative resolution for measure display. Indeed, the measures are returned with high accuracy floating point numbers, but usually only a few decimals are significative. This attributes enables you to hide non-significative decimals in the user interface. Here is a code example rounding a value to the sensor resolution:

double resol = tempSensor.get_resolution();
double prettyValue = Math.round(temperature / resol) * resol;


This being said, you don't have to compute this yourself to read a sensor value: the get_currentValue(), get_lowestValue(), and get_highestValue() methods automatically filter the decimals depending on the configured resolution.

Note, do not confuse accuracy, sensitivity, and resolution. For example, if you take the concrete case of the Yocto-Meteo:

  • The absolute accuracy of the temperature measure is typically of 0.2°C, which means that you should expect that the measured values can vary of 0.2°C from the actual ambient temperature (the absolute error is quantified even more accurately in the datasheet of the chip performing the measure, the SHT25).
  • The relative sensitivity of the temperature measure is typically of 0.01°C, which means that the sensor can detect relative variations of this order of magnitude.
  • The resolution configured in the module is an arbitrary choice, linked to your applications.

Coming out of the factory, the resolution of Yoctopuce sensors is usually configured somewhere between the accuracy level and the precision level of the sensor. But you can change the resolution if you want either to display more sensitivity decimals, or in the opposite to hide decimals that are not correct in the absolute. Naturally, this modification has no real impact on the true accuracy of the sensor, which you can't change like this.

Raw value and calibration

There is a technique enabling us to sometimes increase - up to a certain point - the accuracy of a Yoctopuce sensor: performing a calibration with a reference instrument or with standard values. Indeed, Yoctopuce sensors are manufactured in series, and their accuracy reflects the accuracy of their components, without individual calibration. By performing a module calibration with reference values, you can compensate individual variations of a sensor and thus increase the absolute accuracy of the measures. You can find instructions on how to do so in our post titled Calibrating a Yoctopuce sensor.

The attributes needed for this calibration are calibrationParam, storing the calibration parameters, and rawValue, enabling you to obtain the raw value before calibration and before rounding to the specified resolution. Calibration settings are saved in the flash memory.

Note that this generic calibration process, shared by all the Yoctopuce sensors, is independent from the specific calibration process that some sensors are equipped with, such as the Yocto-CO2 and the Yocto-3D-V2.

Sensor state, signal value

Sometimes, a Yoctopuce sensor is in a state where a measure cannot be returned. This can be the case for example when a Yocto-4-20mA-Rx doesn't receive a signal between 4 and 20mA. You can detect this case by testing the sensorState attribute, which is at zero when a current value is available, and otherwise contains a positive error code depending on the sensor.

For sensors with a measure coming originally from an electric signal, such as for example the Yocto-Thermocouple, the Yocto-MaxiThermistor, and the Yocto-PT100, you can also obtain for diagnosis purposes the value of the measured electric signal. It is available in the signalValue attribute.

The data logger

All the sensors have an individual setting enabling you to configure whether their measures must be stored in the module flash memory, and at which frequency. The logFrequency attribute controls this. The factory value is "1/s", corresponding to one value stored each second, but you can freely change it:

// disables temperature logging
tempSensor.set_logFrequency("OFF");
// enables logging by periods of 5 seconds
tempSensor.set_logFrequency("12/m");


The string describing the frequency follows this syntax:

  • 1/h ... 60/h to store the minimal, maximal and average values for each period of a few minutes defined by the selected frequency.
  • 1/m ... 60/m to store the minimal, maximal and average values for each period of a few seconds defined by the selected frequency. Minimal, maximal and average values are computed by sampling 16 times per second.
  • 1/s ... 100/s to quickly store instant values, up to 100 per second. Note that it's completely useless to store measures faster that the refresh rate we spoke about earlier


You can find instructions on how to retrieve data from the data logger in this previous post.

Periodic measures

As the sensor can store measures at fixed intervals in the data logger, you can also obtain them in real time. The reportFrequency attribute allows you to control the transmission of these measures in real time and at a fixed interval. The attribute uses the same syntax as logFrequency, described above. Both are intimately linked: they cannot be configured for a different frequency. However, you can disable one or the other at will.

As periodic measures are produced spontaneously at a fixed interval, they are not obtained with a get_... method, as it was the case for the current value for example. Instead, you must obtain them through callbacks, of which we talk below.

Advertised value

On top of all this, each Yoctopuce sensor defines an essential value representing it and which is spontaneously propagated to the hub to which it is connected and from there to the program using it: it's the advertisedValue. Usually, the advertised value of a sensor is its current value, the same that you obtain with the get_currentValue method. Thanks to this,

  • when you open the web interface of the VirtualHub (or of the YoctoHub), if you click on Show device function, you obtain a summary view of the values of all the sensors
  • when you define in the VirtualHub (or on a YoctoHub) an HTTP callback to a PHP script of a service such as ThinkSpeak or EmonCMS, the latest measure is automatically transmitted to the server.

As of recently, you can configure the nature of the advertised value on the sensors, with the advMod attribute. You can select between ADVMODE_IMMEDIATE, the standard behavior which propagates the current value of the sensor, or three modes based on periodic measures: ADVMODE_PERIOD_AVG, ADVMODE_PERIOD_MIN, and ADVMODE_PERIOD_MAX. Here is an example:

// propagates the average value on the period rather than the current value
tempSensor.set_advMode(YTemperature.ADVMODE_PERIOD_AVG);


Naturally, sending the average value is possible only when reportFrequency is defined in a way to compute this average (frequency between 1/h and 60/m).

If necessary, for example to reduce network traffic, you can also completely switch off spontaneous propagation of measures for a given sensor.

// completely disables value propagation
tempSensor.muteValueCallbacks();



Reactive programming (with callbacks)

On top of the elementary method described at the beginning of the post, consisting in actively questioning a sensor to read its measures, you can read the value of Yoctopuce sensors with a reactive method, that is with a callback function that the library calls spontaneously, either when the sensor changes its value or at fixed intervals.

The main advantage of the reactive method is its efficiency. You only need a few bytes to spontaneously transfer a value, while questioning the sensor is a heavier mechanism. Therefore, we highly recommend this method for high frequency measures.

You can find detailed explanations on how to use callbacks in our post titled Polling vs. callback.

There you are. You now know the essential to best use Yoctopuce sensors. You still need to discover the specificities of each particular sensor, for which you'll find descriptions in the corresponding user's guides, but these basic principles stay the same for all.

Add a comment No comment yet Back to blog












Yoctopuce, get your stuff connected.