Documentation de usbtenkical

Calibrez vos capteurs Dracal avec usbtenkical

Vous trouverez sur cette page comment utiliser la fonctionnalité de calibration disponible avec vos capteurs Dracal supportant la calibration. Ceux-ci sont identifiables par leur code de produit, se terminant par le suffixe "-CAL". Cette foncionnalité est disponibles via QTenki, mais aussi par l'utilisation de notre outil en ligne de commande usbtenkical présenté dans cette page. La calibration offerte est une calibration polynômiale supportant jusqu'à 3 points de calibration par canal réel. Pour plus de détails concernant la théorie derrière la calibration, consultez la documentation technique du mécanisme de calibration par l'usager en 3 points.

Vous trouverez ci-aprés la documentation des principales fonctionnalité offertes par notre outil en ligne de commande usbtenkical. Si vous avez des questions spécifiques, n'hésitez pas à naviguer directement à la section qui vous intéresse:

1) Installation

Utilisateurs sous Windows ou Mac OS X: Comment obtenir usbtenkical.exe

L'outil en ligne de commande usbtenkical est fourni avec QTenki, dans les versions 2.1.21 et suivantes. Sous Windows ou Mac OS X, installez d'abord QTenki. Après l'installation, vous trouverez usbtenkical.exe dans le répertoire d'installation (généralement, il s'agira de "c:program filesQTenki" ou "c:program files (x86)QTenki").

Utilisateurs sous Linux: Comment compiler usbtenkical

Sous Linux, l'outil en ligne de commande usbtenkical doit être compilé à partir du code source. Suivez les instructions de la page Utilisation des capteurs Dracal sous Linux.

2) Commande d'aide: -help ou -h

Pour commencer, et aussi souvent que vous le souhaitez, prenez connaissance de la liste complète et détaillée des commandes disponibles en exécutant la commande usbtenkical -help ( version courte: 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

Nous faisons un survol des options disponibles par le biais d'examples dans les prochaines sections.

3) Afficher les canaux calibrables: commande -l

Utilisons tout d'abord la commande usbtenkical -l pour visualiser la liste des capteurs reconnus par usbtenkical, ainsi que visualiser les canaux calibrables.

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.

Nous voyons par le numéro de série que deux capteurs Dracal sont détectés, dont seul le second supporte la calibration.

3.1) Détailler les canaux et points de calibrations enregistrés: commande -p

Il est possible de détailler le contenu de chaque canal en ajoutant la commande -p ("pretty output") de manière à avoir une meilleure vue d'ensembles des capteurs Dracal connectés. Si nous reprenons l'exemple juste au-dessus et ajoutons l'option -p, nous obtenons:

C:Program Files (x86)QTenki>  usbtenkical -l -p
Device: 'USB-PTH200', Serial: 'E00004', Version 1.3, Channels: 3
    This device does not support user calibration.
Device: 'USB-PTH200-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 **

Nous pouvons reconnaitre l'appareil supportant la calibration par la présence du suffixe -CAL dans son code de produit.

3.2) Préciser l'appareil à calibrer: commande -s

Il est fréquent d'avoir plusieurs appareils Dracal branchés simultanément afin de construire un système de mesure cohérent et synchronisé. Les outils de Dracal Technologies sont développés dans cette optique et permettent la gestion simultanée d'un nombre illimité de capteurs. Lors de la calibration, il est cependant recommandé de considérer chaque capteur indépendamment. Conséquemment, nous allons préciser l'appareil sur laquelle nous désirons appliquer de la calibration en utilisant la commande -s. Dans le cas présent, le capteur à calibrer est le USB-PTH200-CAL dont le numéro de série unique est E16026.

C:Program Files (x86)QTenki>  usbtenkical -l -p -s E16026
Device: 'USB-PTH200-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) Gestion des points de calibration

4.1) Ajouter des points de calibration: commande set

L'ajout de points de calibration se fait via la commande set (sans tiret devant). La précision de l'appareil Dracal sur lequel la calibration est appliquée est obligatoire, et est effectuée via la commande -s présentée dans la section précédente. La commande set elle-même prends en argument (séparés par des espaces)les 4 informations suivantes:

  • chid: Le numéro (id) du canal pour lequel le point est entré (0,1,...)
  • pid: Le numéro (id) du point saisi (0,1 ou 2)
  • sval: Valeur non-calibrée mesurée par l'appareil (brute)
  • tval: Valeur calibrée (cible)

Par exemple, pour entrer un premier point (pid = 0) de calibration en pression (chid = 0) pour notre USB-PTH200-CAL dont le numéro de série est le E16026, où la valeur mesurée est 101.26 alors que la valeur d'étalonnage est 101.3, nous utilisons la commande suivante:

C:Program Files (x86)QTenki>  usbtenkical -s E16026 set 0 0 101.26 101.3
Device: 'USB-PTH200-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

L'outil nous confirme alors que l'opération s'est effectuée avec succès, tout en nous rappelant la liste des points saisis à ce jour. Notez qu'usbtenkical a enregistré les points saisis comme étant dans les unités kPa, qui sont les unités par défaut du canal de pression d'un USB-PTH200. Il est cependant possible, et même fortement recommandé, de préciser les unités de saisie des points de calibration.

La manière de préciser les unités, cohérente avec la fonctionnalité similaire disponible dans usbtenkiget, est présentée dans la section suivante.

4.2) Préciser l'unité d'affichage et/ou de saisie: commandes -T, -P, -F, -M, -C, ...

Tout comme dans usbtenkiget, il est possible de préciser les unités d'affichage et de saisie via les commandes prévues à cet effet. N'hésitez-pas à vous rafraîchir la mémoire sur les unités disponibles en utilisant la commande usbtenkical -h. Dans l'exemple précédent, nous avons saisi un point de calibration en pression dans les unités par défaut qui sont le kPa. Pour visualiser le point en inHg, nous pouvons utiliser la commande de listage -l en spécifiant que l'unité d'affichage en pression doit être en inHg via l'option -P (Pressure):

C:Program Files (x86)QTenki>  usbtenkical -s E16026 -l -p -P inHg 
Parsing P option
Using pressure unit inHg
Device: 'USB-PTH200-CAL', Serial: 'E16026', Version 1.4, Channels: 3
    Channel 0: MS5611 Pressure [Pressure]
        Point 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 [Relative Humidity]
        Point 0: ** none **
        Point 1: ** none **
        Point 2: ** none **

De même que pour l'affichage des points déjà enregistrés, l'unité peut être précisée au moment de la saisie des points de calibration. Dans l'exemple suivant, nous saisissons un second (pid = 1) point de calibration en pression (chid = 0) dans les unités 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-PTH200-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

Remarquez dans cet exemple que l'écho de la commande set confirme l'enregistrement du nouveau point tout en affichant la liste des points saisis jusqu'à présent pour le canal, et ce dans les unités de saisie précisée lors de l'appel de la commande (soit en inHg dans cet exemple). Ainsi, bien que dans le présent cas le premier point de calibration ait été saisi en kPa, celui-ci a été converti en inHg à l'affichage afin de permettre à l'usilisateur d'avoir une vue d'ensemble cohérente des points de calibration saisis.

Bien que nous ayons entrés jusqu'à présent les points de calibration dans l'ordre d'affichage, notez que tous les points de calibration sont d'importance égale et que l'ordre d'entrée des points n'a aucun effet sur le calcul de la calibration.

4.3) Détailler les canaux sans symbole spécial: commande -7

Sous Windows, certains caractères spéciaux tel le symbode de degré (°C) ne s'affichent pas correctement à l'écran. L'utilisation du paramètre -7 élimine les caractères spéciaux, et peut être employé au besoins comme option avec la commande -l comme la commande set.

4.4) Modifier un point de calibration

La modification d'un point de calibration s'effectue exactement comme la saisie d'un nouveau point via la commande set. Il suffit tout simplement d'écraser le point déjà enregistrer en saisissant un nouveau point de calibration.

4.5) Supprimer des points de calibration: commandes clear et clearall

Afin d'illustrer la suppression de points de calibration, nous avons préalablement saisis 3 points de calibration pour chacun des 3 canaux calibrables de notre USB-PTH200, tel qu'illustré ci-après:

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) Supprimer un seul point de calibration

La suppression d'un point spécifique de calibration se fait par la commande clear (sans tiret) suivie de l'identifiant du canal (chid) et de l'identifiant du point à supprimer (pid). L'exemple suivant illustre la suppression du premier point de calibration en température de notre USB-PTH200-CAL:

C:Program Files (x86)QTenki>   usbtenkical -s E16026 clear 1 0
Device: 'USB-PTH200-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) Supprimer tous les points d'un seul et même canal

Pour supprimer tous les points saisis pour un même canal, il suffit d'invoquer la commande clear en précisant uniquement le canal sur lequel agir. Par exemple, pour supprimer tous les points de calibration pour le canal d'humidité relative (chid = 2), nous lançons la commande suivante:

C:Program Files (x86)QTenki>   usbtenkical -s E16026 clear 2 
Device: 'USB-PTH200-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) Supprimer tous les points de calibration sur tous les canaux

Pour effectuer une remise à l'état d'origine d'un appareil Dracal calibrable et supprimer tous les points de calibration saisis sur celui-ci, il suffit d'invoquer la commande clearall. Afin d'illustrer l'effet de la commande clearall, nous allons l'encâdrer de la commande de listage avant et après son application. Le premier listage nous permet aussi d'observer l'effet des deux suppressisons déjà effectuées dans les 2 sous-sections précédentes:

Avant suppression

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 **

Suppression de tous les points

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

Après suppression

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 **

Notez qu'aucun retour en arrière n'est possible suite à la suppression de points de calibration.

5) Visualiser l'effet de la calibration avec usbtenkiget: commande -u

L'ajout de points de calibration dans un capteur Dracal prend effet immédiatement au moment de son enregistrement. Ainsi, au moment de l'ajout d'un point de calibration, les données affichées par QTenki et usbtenkiget deviennent immédiatement calibrées par défaut. Il est cependant possible de demander à ces outils d'accéder et afficher les données non-calibrées afin de visualiser et valider l'effet de la calibration mise en place.

Dans usbtenkiget, l'option -u (uncalibrated) a été ajoutée afin de permettre à l'usager d'accéder aux données non-calibrées de son appareil Dracal. Par exemple, supposons qu'un seul point de calibration en pression ait été saisi pour notre PTH200:

C:Program Files (x86)QTenki>  usbtenkical -s E16026 -l -p
Device: 'USB-PTH200-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 **

L'effet de cette calibration est d'introduire un décalage constant de +0.1 kPa à toutes les lectures de pression. Nous pouvons valider cette affirmation en utilisant subséquemment usbtenkiget sans et avec calibration, de la manière suivante:

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

Tel qu'attendu, un décalage de +0.1 kPa a bel et bien été introduit. Dans l'exemple ci-après, nous comparons l'ensemble des données retournées par le PTH200 sans et avec 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

où la définition des différents canaux est la suivante:

C:Program Files (x86)QTenki>  usbtenkiget -s E16026 -l
Found: 'USB-PTH200-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]

Par cet exemple, nous voulons mettre en évidence que non seulement le canal de pression a été affecté par la calibration en pression, mais également le canal d'altitude. Ce dernier, étant un canal virtuel calculé à partir de la mesure de pression, est non-calibrable directement mais est indirectement affecté par la calibration appliquée en pression. Il en sera de même pour tous les autres canaux virtuels à l'ajout de points de calibration sur les canaux réels à partir desquels ils sont calculés.

6) Erreur de calibration: présence de nan

La présence de NaN dans la lecture d'un canal calibré est le symptôme d'une erreur d'association des points de calibration. En effet, il n'est pas possible d'associer à une même valeur mesurée deux valeurs de calibration distinctes. Dans l'exemple suivant, la valeur 101.2 kPa mesurée est associée à deux valeurs de calibration différentes, soit 101.3 kPa et 101.4 kPa:

C:Program Files (x86)QTenki>  usbtenkical -s E16026 -l -p
Device: 'USB-PTH200-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 **

Les valeurs calibrées deviennent alors

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

Pour remédier à la situation, il suffit de supprimer ou modifier les points de calibration qui sont en cause.