Cette semaine, nous allons vous parler d'une nouvelle fonctionnalité pour les callbacks HTTP. Nous avons ajouté une nouvelle méthode qui permet l'utilisation des fichiers présents sur les YoctoHubs dans le script du callback HTTP.
Note: cet article parle de fonctionnalités avancées des callbacks HTTP Yoctopuce. Si vous n'avez jamais utilisé cette fonctionnalité, nous vous conseillons de commencer par l'article suivant Les callback HTTP.
Le callback HTTP est un mode de fonctionnement particulier dans lequel c'est le YoctoHub ou le VirtualHub qui établit la connexion à la librairie Yoctopuce. Une fois la communication établie, toutes les données de toutes les fonctions des modules sont envoyées en un bloc. Le script qui utilise la librairie Yoctopuce travaille sur ces données et retourne les commandes que les modules doivent exécuter (par exemple commuter un relais, car la température est trop basse).
La limitation de ce mode de fonctionnement est que le script a accès uniquement aux données que le YoctoHub a envoyé lors de l'établissement de la connexion. C'est-à-dire, l'état courant de toutes les fonctions des modules Yoctopuce connectés. Cependant, les fichiers stockés dans la mémoire interne des modules ne sont pas transmis.
Pour accéder à ces fichiers, il faut utiliser la méthode addFileToHTTPCallback de l'objet YModule. Cette méthode envoie un message au YoctoHub pour qu'il ajoute un fichier à la liste des données qui seront envoyées lors du prochain callback.
Par exemple, le code suivant est un script PHP d'un callback HTTP qui utilise le contenu du fichier myconfig.txt qui se trouve sur la mémoire flash du YoctoHub. Avant d'appeler la méthode download, il faut appeler la méthode addFileToHTTPCallback pour que le YoctoHub transmette aussi ce fichier.
$module = YModule::FindModule("hub_logical_name");
$module->addFileToHTTPCallback("myconfig.txt");
$filecontent = $module->download("myconfig.txt");
...
Attention, la méthode addFileToHTTPCallback impacte uniquement la prochaine exécution du callback. Cette modification n'est pas permanente. Cela veut dire que lors de la toute première exécution du callback, le fichier ne n'est pas présent et que par conséquent l'accès à ce fichier retourne une erreur. Pour reprendre l'exemple précédent, l'appel $module->download("myconfig.txt") retournerait une erreur lors de la toute première exécution. Mais tous les callbacks suivants fonctionneront, car l'exécution précédente aura appelé addFileToHTTPCallback("myconfig.txt").
Notez que si nous avions inversé les deux dernières lignes, le code ne fonctionnerait jamais, car le script planterait avant qu'il ait exécuté l'appel à addFileToHTTPCallback.
Il est important de prendre en compte cette particularité dans son application, de concevoir son code afin qu'il gère correctement les cas où l'appel à download ne fonctionnera pas.
Par exemple, le code suivant gère correctement l'erreur de la méthode download. En cas d'erreur, le script relance immédiatement un callback avec la méthode triggerCallback et termine l'exécution.
$module = YModule::FindModule("hub_logical_name");
$module->addFileToHTTPCallback("myconfig.txt");
try {
$filecontent = $module->download("myconfig.txt");
} catch(YAPIException $e){
print("file is not yet uploaded by the YoctoHub");
$network->triggerCallback();
die();
}
...
Quelques remarques
Ce que l'on vient de vous expliquer n'est pas complètement exact. Si vous appelez la méthode download("myconfig.txt") sans utiliser addFileToHTTPCallback, votre callback risque de fonctionner, mais pas systématiquement.
Voilà pourquoi: quand la librairie essaie d'accéder à une ressource ou un fichier qui n'a pas été envoyé par le YoctoHub, elle appelle implicitement la fonction addFileToHTTPCallback pour ajouter le fichier à la liste de ressources à uploader, et ensuite retourne une erreur. Au prochain callback, le fichier est transmis par le YoctoHub et l'appel à download fonctionne, mais la méthode addFileToHTTPCallback n'est pas appelée.
Bref, sans appeler explicitement addFileToHTTPCallback, un callback sur deux va générer une erreur. Pire, en fonction de la manière dont vous avez codé votre callback et du nombre de fichiers dont vous avez besoin, votre callback risque de ne jamais fonctionner.
C'est pour cette raison que nous avons décidé d'ajouter la méthode addFileToHTTPCallback qui permet de contrôler explicitement quand un fichier doit être uploadé.
Enfin, cette nouvelle fonctionnalité est disponible dans les libraires Yoctopuce depuis la version v1.10.51266 et est compatible avec toutes les versions des YoctoHubs et du VirtualHub. Toutefois, les firmwares des YoctoHubs antérieurs à la version v51218 avaient un bug qui empêchait l'utilisation de cette fonctionnalité sur les fichiers binaires (par exemple les fichiers .gif ou .png).
Comme d'habitude, tout est disponible sur notre site web et sur GitHub.