usbtenkical Documentation

Calibrate your Dracal sensors with usbtenkical

You will find on this page how to use the calibration feature available with your Dracal sensors supporting calibration. These are identifiable by their product code, ending with the suffix "-CAL". This functionality is available via QTenki, but also by using our command line tool usbtenkical presented in this page. The calibration feature offered is a polynomial calibration supporting up to 3 calibration points per real channel. For more details about the theory behind the calibration, see the documentation of the 3-point user calibration mechanism.

1) Installation

Users with Windows or Mac OS X: How to install usbtenkical.exe

The command line tool usbtenkical comes with QTenki, in versions 2.1.21 and later. Under Windows or Mac OS X, you must first install QTenki. After installation, you will simply find usbtenkical.exe in the installation directory (usually it will be "c:program filesQTenki" or "c:program files (x86)QTenki")

Users under Linux: How to compile usbtenkical

Under Linux, the command line tool usbtenkical must be compiled from the source code. Follow the instructions from page Use of Dracal sensors under Linux.

2) Help command: -help or -h

To start, and as often as you like, read the complete and detailed list of available commands by running the command usbtenkical -help (short version: usbtenkical -h):

C:Program Files (x86)QTenki>  usbtenkical -help
Usage: ./usbtenkical [options] command [command arguments ...]

Valid options:
    -V          Display version information
    -v          Run in verbose mode
    -h          Displays help
    -s serial   Operate on the device matching the given serial number.
    -f          Operate on the first device found.
    -l          List calibration points for selected device, or all devices if none is selected.
    -T unit     Select the temperature unit to use. Default: Celsius
    -P unit     Select the pressure unit to use. Default: kPa
    -F unit     Select the frequency unit to use. Default: Hz
    -M unit     Select the length unit to use. Default: m
    -C unit     Select the concentration unit to use. Default: Sensor default
    -p          Enable pretty output
    -7          Use 7-bit ASCII output (no Unicode degree symbols)

To view the list of devices, channels, and points, use the '-l' option.

To operate on a device, select it with '-s serial' or '-f', and provide a command
along with its arguments, if applicable. Each command operates on a single device.

Commands and arguments:
    set chid pid sval tval      Set a calibration point on a device.
        chid    The channel ID
        pid     The point ID
        sval    The non-compensated source value returned by the device
        tval    The compensated target value
    clear chid [pid]            Clear calibration points of a single channel.
        chid    The channel ID
        pid     The point ID (optional; if absent, entire channel is cleared)
    clearall                    Clear calibration points of all channels.
        (no arguments)

Valid temperature units:
    Celsius, c, Fahrenheit, f, Kelvin, k

Valid pressure units:
    kPa, hPa, Pa, bar, at (98.0665 kPa), atm (101.325 kPa), Torr, psi, inHg

Valid frequency units:
    mHz, Hz, kHz, MHz, rpm

Valid length units:
    mm, cm, dm, m, mil, in, ft, yd

Valid concentration units:
    ppb, ppm, percent

We provide an overview of the available options through examples in the following sections.

3) Display calibratable channels: -l command

Let us first use the command usbtenkical -l to view the list of sensors recognized by usbtenkical and view the calibratable channels.

C:Program Files (x86)QTenki>  usbtenkical -l
E16198, 0, 0, ** none **
E16198, 0, 1, ** none **
E16198, 0, 2, ** none **
E16198, 1, 0, ** none **
E16198, 1, 1, ** none **
E16198, 1, 2, ** none **
E16198, 2, 0, ** none **
E16198, 2, 1, ** none **
E16198, 2, 2, ** none **
E16198, 3, 0, ** none **
E16198, 3, 1, ** none **
E16198, 3, 2, ** none **
E00001, This device does not support user calibration.

We see by the serial number that two Dracal sensors are detected, of which only the second one supports calibration.

3.1) Detail channels and calibration points: -p command

It is possible to detail the content of each channel by adding the command -p ("pretty output") in order to have a better overview of the connected Dracal sensors. If we take the example just above and add the option -p, we get:

C:Program Files (x86)QTenki>  usbtenkical -l -p
Device: 'USB-PTh300', Serial: 'E00004', Version 1.3, Channels: 3
    This device does not support user calibration.
Device: 'USB-PTh300-CAL', Serial: 'E16026', Version 1.4, Channels: 3
    Channel 0: MS5611 Pressure [Pressure]
        Point 0: ** none **
        Point 1: ** none **
        Point 2: ** none **
    Channel 1: SHT31 Temperature [Temperature]
        Point 0: ** none **
        Point 1: ** none **
        Point 2: ** none **
    Channel 2: SHT31 Relative Humidity [Relative Humidity]
        Point 0: ** none **
        Point 1: ** none **
        Point 2: ** none **

We can recognize the device supporting calibration by the presence of the suffix -CAL in its product code.

3.2) Specify the device to be calibrated: -s command

It is common to have several Dracal devices connected simultaneously in order to build a coherent and synchronized measurement system. Dracal Technologies' tools are developed with this in mind and allow the simultaneous management of an unlimited number of sensors. During calibration, it is however recommended to consider each sensor independently. Consequently, we will specify the device on which we want to apply calibration using the command -s. In this case, the sensor to be calibrated is the USB-PTh300-CAL whose unique serial number is E16026.

C:Program Files (x86)QTenki>  usbtenkical -l -p -s E16026
Device: 'USB-PTh300-CAL', Serial: 'E16026', Version 1.4, Channels: 3
    Channel 0: MS5611 Pressure [Pressure]
        Point 0: ** none **
        Point 1: ** none **
        Point 2: ** none **
    Channel 1: SHT31 Temperature [Temperature]
        Point 0: ** none **
        Point 1: ** none **
        Point 2: ** none **
    Channel 2: SHT31 Relative Humidity [Relative Humidity]
        Point 0: ** none **
        Point 1: ** none **
        Point 2: ** none **

4) Calibration point management

4.1) Add calibration points: set command

The addition of calibration points is done via the command set (without dash in front). To have the set command work, it is mandatory to specify in which one instrument the calibration points will be registered in. This is done via the -s command presented in the previous section. The set command itself takes as argument (separated by spaces) the 4 following information:

  • chid: The id number of the channel for which the point is entered (0,1,...)
  • pid: The id number of the entered point (0,1 or 2)
  • sval: Non-calibrated value measured by the device (raw)
  • tval: Calibrated value (target)

For example, to enter a first (pid = 0) pressure (chid = 0) calibration point for our USB-PTh300-CAL whose serial number is E16026, where the measured value is 101.26 while the calibration value is 101.3, we use the following command:

C:Program Files (x86)QTenki>  usbtenkical -s E16026 set 0 0 101.26 101.3
Device: 'USB-PTh300-CAL', Serial: 'E16026', Version 1.4, Channels: 3
E16026, 0, 0, 101.26, 101.3 [kPa]
E16026, 0, 1, ** none **
E16026, 0, 2, ** none **
Successfully set calibration point 0 of channel 0

The tool then confirms that the operation has been carried out successfully, while reminding us of the list of points entered to date. Note that usbtenkical has saved the points entered as being in kPa units, which are the default units for the pressure channel of a USB-PTh300. However, it is possible, and even strongly recommended, to specify the units in which the calibration points are entered.

How to specify the units, consistent with the similar functionality available in usbtenkiget, is presented in the next section.

4.2) Specify the display and/or input unit: -T, -P, -F, -M, -C, ... commands

As in usbtenkiget, it is possible to specify the display and input units using the commands provided for this purpose. Feel free to refresh your memory on the available units using the command usbtenkical -h. In the previous example, we entered a pressure calibration point in the default units which are kPa. To display the point in inHg, we can use the listing command -l by specifying that the pressure display unit must be in inHg via the option -P (Pressure):

C:Program Files (x86)QTenki>  usbtenkical -s E16026 -l -p -P inHg 
Parsing P option
Using pressure unit inHg
Device: 'USB-PTh300-CAL', Serial: 'E16026', Version 1.4, Channels: 3
    Channel 0: MS5611 Pressure [Pressure]
        Item 0: 29.9021, 29.9139 [inHg]
        Point 1: ** none **
        Point 2: ** none **
    Channel 1: SHT31 Temperature [Temperature]
        Point 0: ** none **
        Point 1: ** none **
        Point 2: ** none **
    Channel 2: SHT31 Relative Humidity
        Point 0: ** none **
        Point 1: ** none **
        Point 2: ** none **

As with the display of points already registered, the unit can be specified when entering calibration points. In the following example, we enter a second (pid = 1) pressure (chid = 0) calibration point in the units inHg:

C:Program Files (x86)QTenki>   usbtenkical -s E16026 -P inHg set 0 1 34.1 34
Parsing P option
Using pressure unit inHg
Device: 'USB-PTh300-CAL', Serial: 'E16026', Version 1.4, Channels: 3
E16026, 0, 0, 29.9021, 29.9139 [inHg]
E16026, 0, 1, 34.1, 34 [inHg]
E16026, 0, 2, ** none **
Successfully set calibration point 1 of channel 0

Note in this example that the echo of the command set confirms the registration of the new point while displaying the list of points entered so far for the channel in the input units specified when calling the command (inHg in this example). Thus, although in this case the first calibration point has been entered in kPa, it has been converted to inHg in the display in order to allow the user to have a consistent overview of the calibration points entered.

Although we have so far entered the calibration points in the display order, note that all calibration points are of equal importance and that the order in which the points are entered has no effect on the calibration calculation.

4.3) Detail channels with no special symbol:-7 command

Under Windows, some special characters such as the degree symbode (°C) are not displayed correctly on the screen. The use of option -7 eliminates special characters, and can be used with command -l as well as command set.

4.4) Modify a calibration point

Modifyng a calibration point is exactly the same as entering a new point with the command set. Simply overwrite the already saved point by entering a new calibration point.

4.5) Delete calibration points: clear and clearall commands

To illustrate the removal of calibration points, we have previously entered 3 calibration points for each of the 3 calibratable channels of our USB-PTh300, as shown below:

C:Program Files (x86)QTenki>  usbtenkical -s E16026 -l
E16026, 0, 0, 101.26, 101.3 [kPa]
E16026, 0, 1, 115.476, 115.137 [kPa]
E16026, 0, 2, 129.36, 135.456 [kPa]
E16026, 1, 0, 0.1, 0 [°C]
E16026, 1, 1, 25.13, 25 [°C]
E16026, 1, 2, 55.18, 55 [°C]
E16026, 2, 0, 0, 1 [%]
E16026, 2, 1, 5.13, 5 [%]
E16026, 2, 2, 20.2, 20 [%]

4.5.1) Delete a single calibration point

The deletion of a specific calibration point is done by the command clear (without dash) followed by the channel identifier (chid) and the identifier of the point to be deleted (pid). The following example illustrates the deletion of the first temperature calibration point of our USB-PTh300-CAL:

C:Program Files (x86)QTenki>   usbtenkical -s E16026 clear 1 0
Device: 'USB-PTh300-CAL', Serial: 'E16026', Version 1.4, Channels: 3
E16026, 1, 0, ** none **
E16026, 1, 1, 25.13, 25 [°C]
E16026, 1, 2, 55.18, 55 [°C]
Successfully cleared calibration point 0 of channel 1

4.5.2) Delete all the calibration points of a single channel

To remove all the points entered for a channel, invoke the clear command, specifying only the channel to act on. For example, to delete all calibration points for the relative humidity channel (chid = 2), we run the following command:

C:Program Files (x86)QTenki>   usbtenkical -s E16026 clear 2 
Device: 'USB-PTh300-CAL', Serial: 'E16026', Version 1.4, Channels
E16026, 2, 0, ** none **
E16026, 2, 1, ** none **
E16026, 2, 2, ** none **
Successfully cleared calibration points of channel 2

4.5.3) Delete all calibration points on all channels

To reset a calibratable Dracal instrument to its original state and delete all calibration points registered in it, one can invoke the clearall command. In order to illustrate the effect of the clearall command, we will display the result of the listing command before and after its application. The first listing also allows us to observe the effect of the two deletions already made in the 2 previous sub-sections:

Before deletion

C:Program Files (x86)QTenki>  usbtenkical -s E16026 -l
E16026, 0, 0, 101.26, 101.3 [kPa]
E16026, 0, 1, 115.476, 115.137 [kPa]
E16026, 0, 2, 129.36, 135.456 [kPa]
E16026, 1, 0, ** none **
E16026, 1, 1, 25.13, 25 [°C]
E16026, 1, 2, 55.18, 55 [°C]
E16026, 2, 0, ** none **
E16026, 2, 1, ** none **
E16026, 2, 2, ** none **

Deletion of all points

C:Program Files (x86)QTenki>   usbtenkical -s E16026 clearall
Device: 'USB-PTh300-CAL', Serial: 'E16026', Version 1.4, Channels: 3
Successfully cleared all calibration points

After deletion

C:Program Files (x86)QTenki>  usbtenkical -s E16026 -l
E16026, 0, 0, ** none **
E16026, 0, 1, ** none **
E16026, 0, 2, ** none **
E16026, 1, 0, ** none **
E16026, 1, 1, ** none **
E16026, 1, 2, ** none **
E16026, 2, 0, ** none **
E16026, 2, 1, ** none **
E16026, 2, 2, ** none **

Note that no rollback is possible after deleting calibration points.

5) Visualize the effect of calibration with usbtenkiget: -u command

The addition of calibration points in a Dracal sensor takes effect immediately upon its registration. Thus, when a calibration point is added, the data displayed by QTenki and usbtenkiget become immediately calibrated by default. It is however possible to ask these tools to access and display the uncalibrated data in order to visualize and validate the effect of the calibration set up.

In usbtenkiget, the option -u (uncalibrated) has been added to allow the user to access the uncalibrated data of his Dracal device. For example, suppose that only one pressure calibration point has been entered for our PTh300:

C:Program Files (x86)QTenki>  usbtenkical -s E16026 -l -p
Device: 'USB-PTh300-CAL', Serial: 'E16026', Version 1.4, Channels: 3
    Channel 0: MS5611 Pressure [Pressure]
        Point 0: 101.2, 101.3 [kPa]
        Point 1: ** none **
        Point 2: ** none **
    Channel 1: SHT31 Temperature [Temperature]
        Point 0: ** none **
        Point 1: ** none **
        Point 2: ** none **
    Channel 2: SHT31 Relative Humidity [Relative Humidity]
        Point 0: ** none **
        Point 1: ** none **
        Point 2: ** none **

The effect of this calibration is to introduce a constant offset of +0.1 kPa at all pressure readings. We can validate this assertion by subsequently using usbtenkiget without and with calibration, as follows:

C:Program Files (x86)QTenki>  usbtenkiget -s E16026 -i0 -p -P kPa -u ; usbtenkiget -s E16026 -i0 -p -P kPa
Pressure: 102.25 kPa
Pressure: 102.35 kPa

As expected, an offset of +0.1 kPa has indeed been introduced. In the following example, we compare all the data returned by our USB-PTh300-CAL without and with calibration:

C:Program Files (x86)QTenki>  usbtenkiget -s E16026 -ia -u ; usbtenkiget -s E16026 -ia 
102.25, 22.17, 60.45, 14.15, 25.62, 22.17, -76.88
102.35, 22.17, 60.45, 14.15, 25.62, 22.17, -85.31

where the definition of the different channels is as follows:

C:Program Files (x86)QTenki>  usbtenkiget -s E16026 -l
Found: 'USB-PTh300-CAL', Serial: 'E16026', Version 1.4, Channels: 7
    Channel 0: MS5611 Pressure [Pressure]
    Channel 1: SHT31 Temperature [Temperature]
    Channel 2: SHT31 Relative Humidity [Relative Humidity]
    Virtual Channel 256: Dew point [Dew point]
    Virtual Channel 257: Humidex [Humidex]
    Virtual Channel 258: Heat index [Heat index]
    Virtual Channel 262: Altitude [Height]

By this example, we want to highlight that not only the pressure channel was affected by the pressure calibration, but also the altitude channel. The latter, being a virtual channel calculated from the pressure measurement, is not directly calibratable but is indirectly affected by the applied pressure calibration. The same principle applies to every virtual channels following the registration of calibration points on the real channels they are calculated from.

6) Calibration error: presence of nan

The presence of nan in the reading of a calibrated channel is the symptom of an error in the association of the calibration points. Indeed, it is not possible to associate two distinct calibration values to the same measured value. In the following example, the pressure value measured of 101.2 kPa is associated with two different calibration values, that is 101.3 kPa and 101.4 kPa:

C:Program Files (x86)QTenki>  usbtenkical -s E16026 -l -p
Device: 'USB-PTh300-CAL', Serial: 'E16026', Version 1.4, Channels: 3
    Channel 0: MS5611 Pressure [Pressure]
        Point 0: 101.2, 101.3 [kPa]
        Point 1: 101.2, 101.4 [kPa]
        Point 2: ** none **
    Channel 1: SHT31 Temperature [Temperature]
        Point 0: ** none **
        Point 1: ** none **
        Point 2: ** none **
    Channel 2: SHT31 Relative Humidity [Relative Humidity]
        Point 0: ** none **
        Point 1: ** none **
        Point 2: ** none **

The calibrated values then read

C:Program Files (x86)QTenki>  usbtenkiget -s E16026 -ia -p
Pressure: -nan kPa
Temperature: 22.34 °C
Relative Humidity: 42.45 %
Dew point: 8.95 °C
Humidex: 23.15 °C
Heat index: 22.34 °C
Height: -nan m

To remedy the situation, simply remove or modify the calibration points involved.