Personnalisation des callbacks HTTP

Personnalisation des callbacks HTTP

Les modules Yoctopuce sont des composants destinés à être intégrés dans des systèmes de mesure et d'automatisation. La méthode d'intégration la plus courante consiste à ajouter notre librairie au code de contrôle du système, mais nous offrons aussi la possibilité de les intégrer via des Callbacks HTTP vers des services tiers. Nous avons tout récemment élargi les possibilités de ce type d'intégration.



Techniquement, les callbacks HTTP fonctionnent selon le même principe que la plupart des objets connectés que l'on peut acheter en grande surface de nos jours: le module réseau Yoctopuce envoie une requête vers un serveur Web qui peut être n'importe où sur Internet pour lui transmettre ses dernières mesures.

La grande différence réside dans l'infrastructure utilisée: alors que les objets connectés les plus répandus utilisent un serveur Web propriétaire, qui sera arrêté un jour en rendra l'objet connecté inutilisable, les modules Yoctopuce sont configurables pour se connecter au serveur de votre choix, sur lequel vous avez un contrôle complet. C'est beaucoup plus fiable sur le long terme, mais cela exige:

  • de votre part de choisir et de configurer un service Web qui vous convienne
  • de la part de Yoctopuce d'offrir suffisamment de flexibilité pour les méthodes de transmission des données

Sur ce dernier point, nous avons récemment ajouté une nouvelle option qui permet de mieux personnaliser la manière dont les données sont transmises par callbacks HTTP.

Noms associés aux valeur postées


A l'exception des callbacks de type Yocto-API qui donnent accès à la totalité des informations sur les modules Yoctopuce, les callbacks HTTP sont conçus pour ne transmettre que les informations les plus importantes au serveur, en associant chaque valeur avec un nom qui permette facilement de le rattacher à son origine.

Le comportement standard est de transmettre la valeur de l'attribut advertisedValue pour chaque fonction présente sur les modules Yoctopuce. Le nom associé automatiquement à chaque valeur suit la logique suivante:

  1. Si un nom logique a été défini pour une fonction:

    NOM_LOGIQUE_DE_LA_FONCTION = VALEUR

  2. Si un nom logique a été défini pour le module, mais pas pour la fonction:

    NOM_DU_MODULE.NOM_HARDWARE = VALUE

  3. Si aucun nom logique n'a été attribué:

    NUMERO_DE_SERIE.NOM_HARDWARE = VALEUR


La manière la plus simple pour personnaliser les noms associés aux valeurs consiste donc à configurer le nom désiré comme nom logique de la fonction, ou sinon comme nom logique du module lui-même. Par exemple, pour un système comportant un Yocto-Watt où chaque fonction a reçu un nom logique explicite (par exemple VoltageDC) et un Yocto-Meteo-V2 où c'est au module lui-même qu'on a donné le nom logique Ambiant, le format de base utilisé pour InfluxDB a la forme ci-dessous:

yoctopuce,name=VIRTHUB0-12345678,ip=192.168.1.10
  CurrentAC=0,CurrentDC=0,VoltageAC=0,VoltageDC=0,Power=0,
  Ambiant_temperature=22.5,Ambiant_pressure=948.63,Ambiant_humidity=29.4
  1678281649


Ce format de base associe toutes les valeurs à une base de mesures yoctopuce et ajoute un tag name avec le nom réseau du hub et un tag ip avec son adresse IP. Ensuite, chaque valeur est postée dans un champ dont le nom suit la convention de base décrite précédemment. Les données sont transmises par un HTTP POST sur une seule ligne, mais elles ont été mises ici sur plusieurs lignes pour faciliter la lecture.

Personnalisation avancée par un fichier


Voici la nouveauté: si l'on désire une personnalisation plus poussée du format des données transmises, pour sélectionner spécifiquement quelle attribut de quel module doit être envoyé sous quel nom, ou pour y rajouter des informations contextuelles, c'est désormais possible... même si c'est un petit peu plus compliqué. Il faut à ce moment créer un fichier modèle définissant le format exact des données à envoyer. Le contenu et le nom de ce fichier est spécifique à chaque type de callback HTTP.

Le contenu du fichier de modèle sera envoyé tel quel au serveur, à l'exception des expressions englobées entre accents graves (le caractère `, code ASCII 96, appelé backquote ou backtick en anglais) qui seront évaluées par l'interface REST des modules Yoctopuce. Par exemple, si le fichier de modèle comporte le texte:

{ "origin": "`/api/module/productName`" }


et qu'il est utilisé sur un YoctoHub-Ethernet, alors le contenu effectivement posté sera

{ "origin": "YoctoHub-Ethernet" }



Si l'on reprend l'exemple précédent d'InfluxDB, pour personnaliser le format des données il faut créer sur le YoctoHub un fichier modèle de format portant le nom INFLUXDB_cb.fmt (pour InfluxDB v1.0), ou INFLUXDB_V2_cb.fmt (pour InfluxDB v2.0).

Ce fichier peut comporter plusieurs lignes si vous le désirez, ce qui vous permettre d'utiliser des tags différents pour différents mesures, ou même de ventiler des mesures sur plusieurs bases de données. Par exemple, pour poster l'humidité absolue et relative simultanément, mais avec des tags différents, vous pourriez utiliser le fichier de format suivant:

humidity,type=relative,location=Library relHum=`/byName/Ambiant/api/humidity/relHum`
humidity,type=absolute,location=Library absHum=`/byName/Ambiant/api/humidity/absHum`


Attention: le serveur InfluxDB n'accepte que les retours de chariot au format UNIX (caractère \n, aussi appelé LF). Si vous éditez le fichier sur une machine Windows, prenez soin d'utiliser un éditeur de texte capable de ne pas ajouter le retour de chariot Windows (\r\n, aussi appelé CR LF).

Quelques astuces

Si vous voulez vérifier le résultat produit par votre fichier modèle après substitution, vous pouvez demander au YoctoHub de montrer en direct le résultat à l'aide du server Web intégré. Pour cela, ouvrez avec un navigateur l'URL correspondant au nom du fichier modèle sur votre hub, précédé du fameux caractère `:

http://w.x.y.z:4444/`INFLUXDB_V2_cb.fmt



La possibilité d'utiliser un fichier modèle n'est pas limitée à l'utilisation d'un YoctoHub: vous pouvez aussi l'utiliser avec le logiciel VirtualHub sur un PC. Mais pour cela, il faut lancer VirtualHub avec l'option -F container.tar qui vous permettra d'uploader des fichiers sur VirtualHub comme vous pouvez le faire sur un YoctoHub.

Commenter aucun commentaire Retour au blog












Yoctopuce, get your stuff connected.