Looking for a quote?

Documentation of dracal-usb-get

[Last update: 04-05-2023]

[Based on release: v3.2.1]

dracal-sensgate-get

Introduction

The command line tool dracal-usb-get has been developed specifically for you, allowing you to directly access the data generated by every of your Dracal sensors communicating via USB protocol. The advantages of using such a tool are numerous, the most notable of which is the integration of your data in the software of your choice. Go to the Resources section of the site to find out concrete examples of how to use dracal-usb-get in several programming languages or to view an example of integration in LabVIEW software. You will find on this page a documentation of the main features offered by our command line tool dracal-usb-get. If some features do not seem to be available on your local version, we invite you to download the latest version for free.

1. Installation

Windows and Mac OS X users: Where to get dracal-usb-get

The dracal-usb-get command-line tool is included in DracalView. Under Windows or Mac OS X, simply install DracalView. After installation, navigate to the installation directory (typically, this will be "C:\Program files\DracalView" or "C:\Program files (x86)\DracalView"). The file dracal-usb-get will be found in this location.

Linux users: Compile dracal-usb-get

The dracal-usb-get command-line tool must be compiled from sources. Follow the instructions found on the Using Dracal sensors under Linux page.

2. Help command: --help or -h

To begin, and as often as you like, access the complete and detailed list of available commands by running the command dracal-usb-get --help (short version: dracal-usb-get -h):

C:\Program Files (x86)\DracalView>  dracal-usb-get --help
Valid arguments:
    -V           Display version information
    -v           Verbose mode
    -h           Displays help
    -l           List and display info about available sensors
    -s serial    Use USB sensor with matching serial number. Default: Use first found
    -i id<,id,id...>  Use specific channel(s) id(s) or 'a' for all. Default: 0
    -x num       Set number of fractional digits [0-6]. Default: 2
    -R num       If a USB command fails, retry it num times before bailing out
    -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)
    -u           Print uncalibrated values, i.e. do not apply user calibration configured by usbtenkical
    -L logfile   Log to specified file (use - for console)
    -I interval  Log interval. In milliseconds. Default: 1000
    -r rows      Number of log rows. Default: 0, i.e. run continuously
    -S value     Set standard sea level pressure (Pascals) used to compute altitude. Default: 101325
    -o option    Enable specified option (see below). You may use -o multiple times.

Options:
    no_humidex_range     Calculate humidex even if input values are out of range.
    no_heat_index_range  Calculate heat index even if the input values are out of range.
    legacy_errors        Output channel errors in the old (unspecific) way.
                         For instance: The string 'err' instead of 'ProbeDisconnected'

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

Errors:

When an error occurs reading a channel, the value is replaced by an error string:
    Undefined            Unknown/undefined error.
    Saturated            Sensor (or resulting value) is saturated and unusable.
    SensorError          The physical sensor or interface circuitry is not working properly
    ProbeDisconnected    Indicates that the probe is disconnected or cable is cut/open
    OutOfRange           The reading falls outside the sensor possible or supported range
    InvalidData          The data received from the sensor did not make sense or was incomplete

Note: If pretty output is enabled (see -p) there will be spaces in the error messages. See also
the 'legacy_errors' option to restore the old behaviour of returning 'err', regarless
of what the specific error was.

Return value:
 - On success, dracal-usb-get returns 0.
 - If the requested serial number (see -s) was not found, or if no devices were found (-f and -l) a non-zero value is returned.

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

3. List of sensors: -l command

Execute the command dracal-usb-get -l to list and get the general characteristics of all Dracal sensors connected to your device whose communication protocol is USB. In the example below, two sensors are connected, a USB-DXC120 and a VCP-PTH450-CAL:

C:\Program Files (x86)\DracalView>  dracal-usb-get -l
Found: 'VCP-PTH450-CAL', Serial: 'E22196', Version 2.10, 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]
Found: 'USB-DXC120', Serial: 'E19857', Version 2.1, Channels: 1
    Channel 0: SCD30 CO2 GAS PPM [CO2 Gas PPM]

For each of the detected sensors, you will find the product code (Found: ), its serial number (Serial: ), the firmware version (Version), the number of available data channels (Channels:) and their description.

Note 1: A virtual channel is a channel whose data are calculated from the "real" channels. Real channels correspond to physical quantities directly measured by the sensor.

Note 2: Under Linux, if no sensors are found, a possible reason might be that the user you are running the tool as does not have the required access rights. Please consult the configuring access permissions section of the Using Dracal sensors under Linux page for more information.

From now on, we will focus on the data generated by the VCP-PTH450-CAL. In order to specify that we are interested in the data of this exact sensor, we will need its serial number: E22196.

4. Access data from different channels: -i and -s commands

We have previously discovered that the VCP-PTH450-CAL made 7 data channels available, 3 real and 4 virtual. Let's now see how to access the data generated by the sensor via the command -i . The command -i takes as a pre-argument the serial number of the sensor (via the command -s) and in parameters the channels to be displayed. In the following example, we access the data of the first three channels, i.e. channels 0,1 and 2.

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i 0,1,2
101.50, 22.64, 33.71

The order in which the data is displayed corresponds to the input order of the channels. For example, to list the first 3 channels in reverse order, just send the following command:

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i 2,1,0
33.66, 22.64, 101.49

Note that in case where only one sensor is connected, there is a short cut so that the serial number of the sensor does not have to be specified.

4.1 Access all channels without listing them: a parameter

To access the entire list of channels (here there are 7), simply replace the list of channels by the parameter a, like this:

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i a
101.50, 22.66, 33.66, 5.84, 22.24, 22.66, -14.14

4.2 Detail channels: -p command

It is possible to detail the content of each channel by adding the command -p ("pretty output"). If we take the example just above and add the command -p, we get:

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i a -p
MS5611 Pressure: 101.49 kPa
SHT31 Temperature: 22.67 ┬░C
SHT31 Relative Humidity: 33.60 %
Dew point: 5.83 ┬░C
Humidex: 22.25 ┬░C
Heat index: 22.67 ┬░C
Altitude: -14.06 m

4.3 Detail channels without special symbol: -7 command

You will have noticed in the previous example the "strange" appearance of the units for degrees Celsius (°C). Using the parameter -7 eliminates special characters, as shown in the following example:

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i a -p -7
MS5611 Pressure: 101.49 kPa
SHT31 Temperature: 22.63 C
SHT31 Relative Humidity: 33.63 %
Dew point: 5.80 C
Humidex: 22.20 C
Heat index: 22.63 C
Altitude: -13.98 m

Suppose we are only interested in pressure, temperature, relative humidity and height above sea level, then we could type the command:

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i 0,1,2,262 -p -7
MS5611 Pressure: 101.49 kPa
SHT31 Temperature: 22.70 C
SHT31 Relative Humidity: 33.47 %
Altitude: -13.81 m

4.4 Access the data of the first encountered sensor: -f command

You may not need to specify the serial number of a sensor to access its data if it corresponds exactly to the "first sensor encountered". This is the case, in particular, when only one Dracal sensor is connected and recognized; it is necessarily the first (and only!) sensor encountered. Note that the notion of "first encountered" has nothing to do with the order of appearance of sensors when using the command dracal-usb-get -l. Indeed, in the case illustrated in this documentation, the first sensor listed by the commanddracal-usb-get -l was the VCP-PTH450-CAL while the "first" sensor encountered when using the parameter -f is the USB-DXC120, as shown in the example below:

C:\Program Files (x86)\DracalView>  dracal-usb-get -f -i a -p -7
SCD30 CO2 GAS PPM: 420.34 ppm

We then recommend to use the -f command with caution in cases when several sensors are connected to your computer. Finally, note that there is a shortcut to the -f command which is simply to not write it at all. Indeed, the result of the above command is perfectly equivalent to this one:

C:\Program Files (x86)\DracalView>  dracal-usb-get -i a -p -7
SCD30 CO2 GAS PPM: 420.02 ppm

4.5 Choose the number of decimals to display: -x command

Control the output precision by specifying the number of decimal places to be displayed using the -x command. The following example illustrates the use of this command to output the sensor measurements with 6 decimal places:

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i 0,1,2,262 -p -7 -x 6
MS5611 Pressure: 101.491997 kPa
SHT31 Temperature: 22.687494 C
SHT31 Relative Humidity: 33.485924 %
Altitude: -13.892179 m

5. Specify units: -T,-P,-F,-M,... commands

Still using the data from our sensor VCP-PTH450-CAL whose serial number is E22196, let us see how to change its output units. Refer to the command -help to get the list of unit types (temperature, pressure, height, etc.) supported by your current version of DracalView as well as the list of units available for each type. In the following example, we convert the pressure units (in kPa by default) into bar by adding the command -P bar :

(Without conversion)

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i 0 -p
MS5611 Pressure: 101.49 kPa

(With conversion of pressure units)

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i 0 -p -P bar
MS5611 Pressure: 1.01  bar

In addition to this first conversion, we can display the temperature units in Fahrenheit by adding the command -T f:

(Without conversion)

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i a -p -7
MS5611 Pressure: 101.49 kPa
SHT31 Temperature: 22.72 C
SHT31 Relative Humidity: 33.44 %
Dew point: 5.80 C
Humidex: 22.28 C
Heat index: 22.72 C
Altitude: -13.64 m

(With conversion of pressure and temperature units)

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i a -p -7 -P bar -T f
MS5611 Pressure: 1.01  bar 
SHT31 Temperature: 72.86  F 
SHT31 Relative Humidity: 33.46 %
Dew point: 42.42  F 
Humidex: 72.08  F 
Heat index: 72.86  F 
Altitude: -13.64 m

You will have deduced that it is possible to concatenate as many conversion command as there are unit types.

6. Height calculation: -S command

The virtual "Altitude" channel is a channel whose calculation is based on the measured atmospheric pressure as well as the "reference" atmospheric pressure, which is by default the one at sea level. The latter is set at 101325 Pa. However, it is possible to change the value of the reference atmospheric pressure with the command -S. This allows to calculate a height from a reference point, if we know the value of the atmospheric pressure at this point. For example, if we want to establish the current height as our zero height, we will first measure the atmospheric pressure:

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i 0,262 -7 -p -P Pa
MS5611 Pressure: 101489.00 Pa
Altitude: -13.64 m

We will therefore establish the value of the reference pressure at the value of the pressure we have just measured, that is 101489 Pa:

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i 0,262 -7 -p -P Pa -S 101489
MS5611 Pressure: 101489.00 Pa
Altitude: -0.00 0.00 m

As expected, with the current pressure as the reference pressure, the measured value of the height is 0. Now, if we place the sensor on the floor (it was on a table) and run the same command again, we get:

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i 0,262 -7 -p -P Pa -S 101167
MS5611 Pressure: 101491.00 Pa
Altitude: -0.17 m

which is actually the height of the table on which the sensor was placed.

7. Management of calibrated data: command -u

Some Dracal products have Dracal 3-point calibration feature. In calibratable products, the addition of calibration points takes effect immediately upon registration. Thus, when a calibration point is set, the data displayed by DracalView and dracal-usb-get becomes 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 dracal-usb-get, the option -u (uncalibrated) allows 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 VCP-PTH450-CAL:

C:\Program Files (x86)\DracalView>  dracal-usb-cal -s E22196 -l -p
Device: 'VCP-PTH450-CAL', Serial: 'E22196', Version 2.10, 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
        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 dracal-usb-get without and with calibration, as follows:

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i0 -p -P kPa -u && dracal-usb-get -s E22196 -i0 -p -P kPa
Pressure: 101.49 kPa
Pressure: 101.59 kPa

As expected, an offset of +0.1 kPa has indeed been applied to the readings. Note that the -u command applies to all channels without exception. Thus, the following command compares the calibrated and uncalibrated data of all channels of our VCP-PTH450-CAL:

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -ia -u && dracal-usb-get -s E22196 -ia 
101.49 , 22.26, 34.06, 5.66, 21.78, 22.26, -14.06 
101.59 , 22.26, 34.06, 5.66, 21.78, 22.26, -22.37

where the definition of the different channels is as follows:

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -l
Found: 'VCP-PTH450-CAL', Serial: 'E22196', Version 2.10, Channels: 7
    Channel 0: MS5611 Pressure [Pressure]
    Channel 1: SHT31 Temperature [Temperature]
    Channel 2: SHT31 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]

This example illustrates the fact 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.

8. Save data to a file: -L command

Use the -L command to save the data to a file in .csv format. If the specified file does not exist, it will be created when the command is sent. If it already exists, the data will be concatenated to the already existing content of the file ("append mode"). For example, to save the data in a file named test.csv located at C:\Users\Public\Documents, we type the following command:

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i a -L C:\Users\Public\Documents\test.csv
Log mode on.
Opened file 'C:\Users\Public\Documents\test.csv' for logging. Append mode.
101.59, 22.18, 34.09, 5.60, 21.67, 22.18, -22.04
101.59, 22.18, 34.04, 5.58, 21.67, 22.18, -22.04
101.59, 22.15, 34.05, 5.56, 21.63, 22.15, -22.12
101.59, 22.15, 34.07, 5.57, 21.64, 22.15, -22.12
^C

Note that the data is displayed on the screen in the terminal while the file is being written. To stop logging, enter the command CTRL+C (^C). Here is the content of the file test.csv:

C:\Program Files (x86)\DracalView> type C:\Users\Public\Documents\test.csv
2023-05-04 13:41:27.240, 101.59, 22.18, 34.09, 5.60, 21.67, 22.18, -22.04
2023-05-04 13:41:28.268, 101.59, 22.18, 34.04, 5.58, 21.67, 22.18, -22.04
2023-05-04 13:41:29.279, 101.59, 22.15, 34.05, 5.56, 21.63, 22.15, -22.12
2023-05-04 13:41:30.309, 101.59, 22.15, 34.07, 5.57, 21.64, 22.15, -22.12

Let's see the contents of this file after executing the same command a second time:

C:\Program Files (x86)\DracalView> type C:\Users\Public\Documents\test.csv
2023-05-04 13:41:27.240, 101.59, 22.18, 34.09, 5.60, 21.67, 22.18, -22.04
2023-05-04 13:41:28.268, 101.59, 22.18, 34.04, 5.58, 21.67, 22.18, -22.04
2023-05-04 13:41:29.279, 101.59, 22.15, 34.05, 5.56, 21.63, 22.15, -22.12
2023-05-04 13:41:30.309, 101.59, 22.15, 34.07, 5.57, 21.64, 22.15, -22.12
2023-05-04 13:48:54.581, 101.58, 22.06, 34.12, 5.51, 21.53, 22.06, -21.54
2023-05-04 13:48:55.596, 101.58, 22.08, 34.15, 5.54, 21.55, 22.08, -21.54
2023-05-04 13:48:56.628, 101.58, 22.08, 34.12, 5.53, 21.55, 22.08, -21.62
2023-05-04 13:48:57.645, 101.58, 22.08, 34.09, 5.52, 21.55, 22.08, -21.45
2023-05-04 13:48:58.658, 101.58, 22.08, 34.14, 5.53, 21.55, 22.08, -21.62

As expected, the new data was recorded right after the existing one.

8.1 New! Specify the number of measurements to save: -r command

In conjunction with the -Lcommand, the -r command allows you to specify an exact number of measurements to record in a file. For example, in the example below, the number of measurements taken has been limited to 3:

C:\Program Files (x86)\DracalView> dracal-usb-get -s E22196 -i a -L C:\Users\Public\Documents\test2.csv -r 3
Opened file 'C:\Users\Public\Documents\test2.csv' for logging. Append mode.
101.58, 22.08, 34.12, 5.53, 21.55, 22.08, -21.37
101.58, 22.12, 34.11, 5.56, 21.60, 22.12, -21.37
101.58, 22.09, 34.10, 5.53, 21.57, 22.09, -21.45
Closing log file.

C:\Program Files (x86)\DracalView>

8.2 Change the recording frequency: -I command

Use the -I command to specify the data recording frequency in milliseconds (ms). The default recording frequency (when not specified) is 1000 ms. To illustrate our point, we will create a new file, "test2.csv", in which we will write by executing the following two commands in succession:

C:\Program Files (x86)\DracalView> dracal-usb-get -s E22196 -i a -L C:\Users\Public\Documents\test2.csv -r 3 -I 100

followed by

C:\Program Files (x86)\DracalView> dracal-usb-get -s E22196 -i a -L C:\Users\Public\Documents\test2.csv -r 3 -I 2000

We can see from the timestamp in the .csv file that the recording frequency corresponds to the parameter specified when executing the corresponding command:

C:\Program Files (x86)\DracalView> type C:\Users\Public\Documents\test2.csv
2023-05-04 13:52:42.149, 101.58, 22.12, 34.10, 5.56, 21.60, 22.12, -21.21
2023-05-04 13:52:42.274, 101.58, 22.12, 34.10, 5.56, 21.60, 22.12, -21.37
2023-05-04 13:52:42.400, 101.58, 22.12, 34.10, 5.56, 21.60, 22.12, -21.29
2023-05-04 13:52:50.629, 101.58, 22.12, 34.04, 5.53, 21.59, 22.12, -21.21
2023-05-04 13:52:52.647, 101.58, 22.12, 34.07, 5.54, 21.60, 22.12, -21.21
2023-05-04 13:52:54.666, 101.58, 22.13, 34.07, 5.56, 21.62, 22.13, -21.45

9. Redirect the output to another program

If, instead of saving the data in a .csv file, you want to use the output as input of another program, give the command -L the argument - instead of a file name. This will save the data into the variable stdout (standard output):

C:\Program Files (x86)\DracalView>  dracal-usb-get -s E22196 -i a -L - 
Log mode on.
Logging to stdout
101.58, 22.16, 34.03, 5.56, 21.65, 22.16, -21.29
101.58, 22.13, 34.00, 5.53, 21.61, 22.13, -21.54
101.58, 22.16, 34.01, 5.55, 21.64, 22.16, -21.45
101.58, 22.16, 34.02, 5.56, 21.65, 22.16, -21.37
101.58, 22.16, 33.97, 5.54, 21.64, 22.16, -21.45
^C