Une grande majorité des modules Yoctopuce sont des capteurs, ou servent à interfacer des capteurs externes. C'est pourquoi l'interface de programmation pour accéder aux capteurs et récupérer les mesures est parmi les plus développées, et continue de s'enrichir en fonction des demandes que nous recevons. Pour vous aider à trouver la méthode qui vous conviendra le mieux, nous vous proposons aujourd'hui une synthèse de tout ce qui est à votre disposition.
Les capteurs Yoctopuce servent à mesurer via USB -ou via le réseau- une ou plusieurs grandeurs physiques. Par exemple, le Yocto-Meteo mesure la température, l'humidité et la pression. Au niveau applicatif, ces trois fonctions peuvent être accédées et configurées indépendamment les unes des autres, comme nous l'avions expliqué dans un précédent article sur la structure logique des modules Yoctopuce. Pour la suite de cet article, lorsque nous parlons des différents paramètres d'un capteur, il s'agit naturellement de paramètres disponibles dans chacune des fonctions de mesure.
Chaque fonction de mesure est accédée à l'aide d'une classe qui lui est dédiée dans la librairie de programmation Yoctopuce. Par exemple, les capteurs de température sont interfacés par la classe YTemperature. Toutes ces classes héritent de la classe YSensor et partagent par conséquent un certain nombre d'attributs et de méthodes communes.
La valeur courante
L'attribut currentValue contient la valeur de la dernière mesure effectuée par le capteur. La manière la plus simple de lire un capteur Yoctopuce est donc d'appeler la méthode get_currentValue(). Par exemple:
// récupère la valeur du capteur de lumière de la salle à manger
sensor = YLightSensor.FindLightSensor('diningRoom');
double luxCount = sensor.get_currentValue();
La fréquence de rafraîchissement de la valeur courante dépend de la technologie utilisée par le capteur, et change donc selon les modules. Vous trouvez en général ce paramètre listé dans les spécifications du produit. Par exemple, dans les spécifications du Yocto-Light-V3 on trouve une fréquence de rafraîchissement de 4 Hz, ce qui signifie que la valeur est mise à jour 4 fois par seconde. Rien ne sert donc d'aller la lire plus souvent...
Les valeurs minimales et maximales
En plus de donner la dernière mesure, chaque capteur garde dans les attributs lowestValue et highestValue les valeurs minimale et maximale rencontrées. Cela peut être utile par exemple si votre programme n'interroge pas constamment le capteur, mais désire connaître les valeurs extrêmes. Ces valeurs peuvent être réinitialisées manuellement lorsque vous le désirez:
double luxMin = sensor.get_lowestValue();
double luxMax = sensor.get_highestValue();
// réinitialise les min/max à la valeur courante
sensor.set_lowestValue(luxCount);
sensor.set_highestValue(luxCount);
Notez que les valeurs min/max ne sont pas préservées lorsque le module est mis hors tension.
L'unité
Pour faciliter l'interprétation des mesures, tous les capteurs sont dotés d'un attribut unit indiquant l'unité physique qu'ils mesurent. Souvent, cet attribut n'est pas modifiable: un Yocto-Volt retourne toujours des mesures en Volt, etc. Mais parfois vous pouvez changer l'unité. Par exemple, pour tous les capteurs de température, vous pouvez choisir entre degrés Celsius, degrés Fahrenheit ou Kelvins :
YTemperature tempSensor = FirstTemperature();
while(tempSensor != null) {
tempSensor.set_unit('K');
tempSensor = tempSensor.nextTemperature();
}
Par savoir si un changement d'unité est possible pour un capteur donnée, consultez simplement la référence de la classe correspondante. Vous y verrez par exemple que la classe YVoltage ne propose pas de méthode set_unit(), contrairement à la classe YTemperature.
La résolution
Chaque capteur Yoctopuce comporte aussi un attribut resolution qui indique la résolution significative pour l'affichage des mesures. En effet, les mesures sont retournées à l'aide de nombres à virgule flottante de grande précision, mais en général seules quelques décimales sont significatives. Cet attribut permet donc de faire en sorte que l'interface utilisateur cache les décimales non significatives. Voilà un exemple de code qui arrondi une valeur à la résolution du capteur:
double prettyValue = Math.round(temperature / resol) * resol;
Ceci dit, vous n'avez pas à faire ce calcul vous-même pour lire la valeur du capteur: les méthodes get_currentValue(), get_lowestValue() et get_highestValue() filtrent automatiquement les décimales en fonction de la résolution configurée.
Attention, ne confondez pas précision, sensibilité et résolution. Par exemple, si l'on prend le cas concret du Yocto-Meteo:
- La précision absolue de la mesure de température est typiquement de 0.2°C, ce qui signifie qu'il faut s'attendre à ce que la valeur mesurée s'écarter de 0.2°C de la véritable température ambiante (l'erreur absolue est quantifiée encore plus précisément dans le datasheet du chip effectuant la mesure, le SHT25).
- La sensibilité relative de la mesure de température est de 0.01°C, ce qui signifie qu'il est capable de détecter des variations relatives de cet ordre de grandeur.
- La résolution configurée dans le module est un choix arbitraire, lié à votre applications.
A la sortie d'usine, la résolution des capteurs Yoctopuce est en général configurée quelque part entre le niveau de précision et le niveau de sensibilité du capteur. Mais vous pouvez changer la résolution si vous voulez soit afficher plus de décimales de sensibilité, soit au contraire cacher des décimales qui ne sont pas correctes dans l'absolu. Bien entendu, ce changement n'aura pas d'effet réel sur la véritable précision du capteur, qu'on ne peut pas changer ainsi.
Valeur brute et calibration
Il existe une technique permettant parfois d'augmenter - dans une certaine mesure - la précision d'un capteur Yoctopuce: effectuer une calibration à l'aide d'un instrument de référence ou de valeurs étalon. En effet, les capteurs Yoctopuce sont fabriqués en série, et leur précision découle de la précision des composants utilisés, sans calibration individuelle. En effectuant une calibration du module par rapport à des mesures de référence, on peut compenser les variations individuelles d'un capteur et ainsi améliorer la précision absolue des mesures. Vous trouverez des explications sur la marche à suivre dans notre article intitulé Calibrer un senseur Yoctopuce.
Les attributs relatifs à cette calibration sont calibrationParam, qui stocke les paramètres de calibration, et rawValue, qui permet d'obtenir la valeur brute, avant application de la calibration et avant l'arrondi à la résolution spécifiée. Les réglages de calibrations sont sauvés dans la mémoire flash du module.
Notez encore que cette procédure de calibration générique, commune à tous les capteurs Yoctopuce, est indépendante de la procédure de calibration spécifique dont disposent certains capteurs, comme le Yocto-CO2 et le Yocto-3D-V2.
Etat du capteur, valeur du signal
Parfois, un capteur Yoctopuce peut ne pas être en état de retourner une mesure. Cela peut être le cas par exemple lorsqu'un Yocto-4-20mA-Rx ne reçoit pas un signal entre 4 et 20mA. Il est possible de détecter cette signification en testant l'attribut sensorState, qui vaut zéro lorsqu'une valeur actuelle est disponible, et contient sinon un code d'erreur positif dépendant du capteur.
Pour les capteurs dont la mesure vient à l'origine d'un signal électrique, comme par exemple les Yocto-Thermocouple, Yocto-MaxiThermistor, Yocto-PT100, il est aussi possible d'obtenir à de fins de diagnostique la valeur de signal électrique mesuré. Elle est disponible dans l'attribut signalValue.
L'enregistreur de données
Tous les capteurs disposent d'un réglage individuel permettant de configurer si leurs mesures doivent enregistrées sur la mémoire flash du module, et à quelle fréquence. C'est l'attribut logFrequency qui contrôle cela. La valeur d'usine est "1/s", qui correspond à une valeur enregistrée par seconde, mais elle peut être changée librement:
tempSensor.set_logFrequency("OFF");
// active l'enregistrement par périodes de 5 secondes
tempSensor.set_logFrequency("12/m");
La chaîne décrivant la fréquence peut avoir la forme suivante:
- 1/h ... 60/h pour stocker les valeurs minimale, moyenne et maximale pour chaque période de quelques minutes définie par la fréquence choisie.
- 1/m ... 60/m pour stocker les valeurs minimale, moyenne et maximale pour chaque période de quelques secondes définie par la fréquence choisie. Les valeurs minimales, moyennes et maximales sont calculées par échantillonnage 16 fois par seconde.
- 1/s ... 100/s pour stocker très rapidement des mesures instantanées uniquement, jusqu'à 100 par seconde. Notez qu'il est complètement inutile de stocker des mesures plus rapidement que la fréquence d'échantillonnage dont nous avons parlé précédemment.
Vous pourrez trouver des instructions sur la récupération des données depuis l'enregistreur dans ce précédent article.
Les mesures périodiques
De même qu'il est possible au capteur de stocker des mesures à intervalle fixe dans l'enregistreur de données, il est possible de les obtenir en temps réel. L'attribut reportFrequency permet de contrôler l'envoi de ces mesures transmises en temps réel et à intervalle fixe. Il utilise la même syntaxe décrite précédemment pour l'attribut logFrequency. Les deux sont d'ailleurs intimement liés: ils ne peuvent pas être configurés pour une fréquence différente. Par contre, il est possible de désactiver l'un ou l'autre à volonté.
Comme les mesures périodiques sont produites spontanément à intervalle fixe par le module, elles ne sont pas obtenue par une méthode get_..., comme c'était le cas pour la valeur instantanée par exemple. A la place, elles doivent être obtenues que par la méthode des callbacks dont nous parlerons plus bas.
La valeur propagée
En plus de tout cela, chaque capteur Yoctopuce définit une valeur essentielle qui le représente, et qui est spontanément propagée au hub auquel il est connecté, et de là au programme qui l'utilise: c'est l'advertisedValue. En temps normal, la valeur propagée d'un capteur est sa valeur courante, la même que vous pouvez obtenir avec la méthode get_currentValue. Grâce à cela,
- lorsque vous ouvrez l'interface Web du VirtualHub (ou du YoctoHub), si vous cliquez sur le bouton Show device function vous obtenez une vue d'ensemble des valeurs de tous les capteurs.
- lorsque vous définissez dans le VirtualHub (ou sur un YoctoHub) un callback HTTP vers un script PHP ou un service tel que ThinkSpeak ou EmonCMS, la dernière mesure est automatiquement transmise au serveur.
Depuis peu, il est possible de configurer la nature de la valeur propagée sur les capteurs, à l'aide de l'attribut advMode. Vous pouvez choisir entre ADVMODE_IMMEDIATE, le comportement standard qui propage la valeur immédiate du capteur, ou trois modes basés sur les mesures périodiques: ADVMODE_PERIOD_AVG, ADVMODE_PERIOD_MIN et ADVMODE_PERIOD_MAX. Voici un exemple :
tempSensor.set_advMode(YTemperature.ADVMODE_PERIOD_AVG);
Bien entendu, l'envoi de la valeur moyenne n'est possible que lorsque la fréquence d'envoi définie dans reportFrequency est définie de sorte à calculer cette moyenne (fréquence comprise entre 1/h et 60/m).
Si nécessaire, par exemple pour réduire le trafic réseau, il est aussi possible de couper complètement la propagation spontanée des mesures pour un capteur:
tempSensor.muteValueCallbacks();
Programmation réactive (par callback)
En plus de la méthode élémentaire décrite en début de cet article, qui consiste à interroger activement un capteur pour lire sa mesure, il est aussi possible de lire la valeur des capteurs Yoctopuce par une méthode réactive, c'est-à-dire par une fonction de callback qui est appelée spontanément par la librairie, soit lorsque le capteur change de valeur, soit à intervalle fixe.
Le principal avantage de la méthode réactive est son efficacité: il suffit en effet de quelques octets pour transférer spontanément un valeur, alors que l'interrogation du capteur est un mécanisme plus lourd. C'est pourquoi cette méthode est chaudement recommandée pour les mesures à haute fréquence.
Vous trouverez des explications détaillées sur l'utilisation des callbacks dans notre article intitulé Comment lire efficacement un capteur.
Voilà, vous connaissez maintenant l'essentiel pour utiliser au mieux les capteurs Yoctopuce. Il vous restera encore à découvrir les spécificités de capteurs particuliers, que vous trouverez décrites dans les manuels correspondants, mais ces principes de base resteront les même pour tous.