New features in Yoctopuce API

New features in Yoctopuce API

After several months of development (much more than what we originally planned...), we are eventually ready to submit a grand new version of the Yoctopuce programming library and new firmwares for the modules. And this time, it is not only fixes, but new features of which you can take advantage after a software update. Here is a summary of what will change and what will stay the same in the new release 1.10…

Let's start by having a look at new features, and then let's see the impact these changes have on your existing software.

1. The new data logger

It was certainly the most awaited change and the trigger of this great make over of the firmware and library. Here are the main characteristics of this new version, first at the level of the sensors themselves:

  • You can configure the frequency of data logging.
  • The data logger can save either instant measures, or average/min/max values per period:

    • The instant measure frequency can range from 1Hz to 100Hz.
    • Averaged measure frequency can go from 60 per minute to 1 per hour; samples taken to compute the average, minimal, and maximal values are taken 16 times per second.

  • The new data logger automatically sets itself to the "real" time, using its host clock (based on the network for the YoctoHub-Ethernet, RTC and the network for the YoctoHub-Wireless, and on the system clock for the VirtualHub).
  • To facilitate data use, the beginning and end of measure intervals are automatically aligned to a multiple of the logging period.
  • For modules with more than one sensor:

    • Data logging can be activated or deactivated individually for each sensor;
    • Logging frequency can be set individually for each sensor.

Access to recorded measures is also greatly improved:

  • API objects representing a sensor now have a get_recordedData() method enabling you to directly receive a DataSet, that is a set of measures corresponding to a given time range. The following methods are available in the DataSet:

    • loadMore() which iteratively loads all the data from the module, and provides a progress indicator;
    • get_preview() which provides almost instantaneously a summary of the whole data in the DataSet, in the shape of a measure array about 200 times smaller than the detailed measures;
    • get_measures()
    • which provides the array of detailed measures which were loaded.

  • For users who do not use the high level programming libraries:

    • The command line library provides the same functions, returning data in a character separated format (CSV)
    • It is also much simpler to retrieve the data from the data logger using simple HTTP requests.

Screenshot of the new Javascript live graph example
Screenshot of the new Javascript live graph example

2. The YSensor generic class

The programming interface of most of our sensors share a core of identical methods, enabling you to read the current value, the measuring unit, etc. As this family of sensors is growing fast, we found important to provide a generic class, parent to all the sensors, enabling you to read the measures of any sensor. You can thus implement software able to read the measures of any Yoctopuce sensor, even those that do not yet exist when you compile your code...

Sensors supported by the YSensor class are those containing a data logger. By the way, the YSensor class also has a get_recordedData() method enabling you to retrieve the data of the new data logger.

Like the high level libraries, the command line library now also has a YSensor executable, able to access all the sensors.

The new YSensor utility can access any Yoctopuce sensor
The new YSensor utility can access any Yoctopuce sensor

3. Timed report notifications (periodic callback)

Up to now, we offered you two methods to read the values of sensors: direct access with the get_currentValue() method, and event-based callback when any sensor value changes. This latter method is usually the most efficient to obtain real time measures. However, for some applications, it sometimes transmits too many events (when the measures changes a lot) or sometimes not enough (when the measure does not change).

You can now configure each sensor to send timed reports via callbacks at a preset interval. As for the data logger, these notifications can be either instant measures or averaged/min/max values per period. Only one constraint: if the data logger is activated for a given sensor, set interval value notifications are performed at the same frequency as the data logging.

Combined use of the data logger and of timed report callbacks enables you to very easily build a graph of the measures for the latest few hours, for example, which is then automatically updated as new data are available. New data are automatically sent with a frequency corresponding to the frequency of the data previously logged.

def sensorTimedReportCallback(sensor,measure):
    info = sensor.get_userData()
    print(info['name']+": "+str(measure.get_averageValue())+" "+info['unit'])

# enable timed reports on all sensors
sensor = YSensor.FirstSensor()
while sensor:
    sensor.set_userData({ 'name' : sensor.get_friendlyName(),
                          'unit' : sensor.get_unit() })
    sensor = sensor.nextSensor()

# Event-based processing, nothing to do :-)
while True:
    YAPI.Sleep(500, errmsg)

Typical use of timed report callbacks

4. Other miscellaneous enhancements

The command line library has been improved to include all most important features available in the other libraries. It is now possible to apply calibration parameters from the command line, to retrieve measures from the data logger in CSV format, to test a YoctoHub network connectivity, etc. It is now also possible to customize the output format of the command line tools.

For all programming languages, the documentation and the in-line comments have been improved. New examples have been added. We have also taken the opportunity of the release to re-publish an up-to-date documentation for all devices.

Compatibility and migration

As for any library and firmware update, we tried to make the transition as transparent and seamless as possible. Here is what you should expect during the transitional phase:

The new firmware usually work without trouble with the old library (with your existing software). We must mention some particular cases:

  • In order to install a new firmware, you must use a Virtualhub at least as recent as the firmware.
  • It is not possible to update calibration parameters for new firmware using the old library.
  • The old library is not able to decode data saved by the new datalogger. If you want to continue using the old datalogger API, you should either keep the old firmware, or upgrade the library as well (the new library includes most of the old API functions, in order to maintain backward-compatibility with existing code).

The new library usually works without trouble with old firmware (with your current modules, without updating them). It is however recommended to upgrade the firmwares if when upgrade your library. We must mention some particular cases:

  • The new features of the new library (the new data logger, the timed reports, the YSensor class) only works with devices running the new firmware.
  • Updating calibration parameters is only possible for devices using the new firmware.

Given the number of changes in this release (and hence the risk of early bugs), we will not immediately push the switch to the new version. For now, we recommend to use the new library for new developments only, and to keep the old firmwares and old library for systems in production. The new library will definitely replace the old one as soon as we have received enough good feedback from the field. In between, don't hesitate to try it and to let us know about any issue you may hit. We will do our best to provide fixes as quickly as possible.

Here are the links to download the new VirtualHub:

Operating SystemDownloadDocumentation
Mac OS X

Here are the links to download the new programming library:

LanguageSource codeDocumentation
Command line
VisualBasic .Net

Here are the links to download the new firmwares:

Sensors with dataloggerFirmwareDocumentation

Other devicesFirmwareDocumentation

Network extensionsFirmwareDocumentation

Add a comment No comment yet Back to blog

Yoctopuce, get your stuff connected.