A propos de RegisterHub

A propos de RegisterHub

Si vous avez déjà écrit le moindre petit bout de programme pour gérer des modules Yoctopuce, vous connaissez la fonction RegisterHub. Mais connaissez-vous vraiment toutes ses particularités? Au fil des années, cette fonction s'est enrichie de fonctionnalités supplémentaires sans qu'on prenne vraiment le temps de les décrire en détail. Voyons donc à quoi sert cette fonction indispensable...


A l'exception de l'API en ligne de commande où elle n'a pas de sens, la fonction RegisterHub existe sous des formes variées dans tous les langages de programmation. Elle a plusieurs buts:

Initialisation de l'API

La fonction première de RegisterHub est d'initialiser l'API Yoctopuce. Par conséquent c'est le premier appel que vous devez faire avant de commencer à travailler avec des modules Yoctopuce. Typiquement, vous allez mettre cet appel dans la partie initialisation de votre application. Sauf cas particulier, il est inutile, voir contre-productif, d'appeler RegisterHub plusieurs fois pendant la vie de votre application.

Si l'initialisation s'est bien passée, RegisterHub va renvoyer la constante YAPI_SUCCESS, dans le cas contraire, le message d'erreur passé en paramètre contiendra une description du problème.

Mode de fonctionnement

En plus d'initialiser l'API Yoctopuce, RegisterHub permet de spécifier dans quel mode vous désirez travailler. Ces modes sont au nombre de trois et sont décrits par le premier paramètre de l'appel à RegisterHub.

USB

C'est le mode d'accès en USB natif, le plus simple. Vous l'utilisez si vous souhaiter accéder aux modules branchés par USB à la machine sur laquelle tourne votre programme. Pour utiliser ce mode, passez simplement la chaîne dans "usb" comme premier paramètre. Notez qu'il y a une limitation technique: sur la même machine, il ne peut y avoir qu'une seule application à la fois qui accède aux modules en mode natif. Attention : le VirtualHub compte comme une application native. Cependant cette limitation peut être contournée facilement grâce au mode network décrit plus bas.

Par ailleurs, ce mode n'est pas disponible en JavaScript, PHP et Java (sauf Android). En effet, ces langages de programmation interdisent d'accéder directement aux couches matérielles de la machine.

Réseau

Dans ce mode, vous spécifiez que vous souhaitez accéder à des modules Yoctopuce à travers le réseau. Au lieu de "usb" vous allez utiliser une adresse réseau. Cette adresse peut tout aussi bien être l'adresse d'une machine sur laquelle tourne un VirtualHub ou l'adresse d'un YoctoHub. Du point de vue de l'API, un VirtualHub tournant sur une machine ou un YoctoHub sont strictement équivalents. Vous pouvez utiliser une adresse IP ou directement l'adresse logique de la machine. Si vous souhaitez contacter un VirtualHub tournant sur votre machine locale, utilisez l'adresse 127.0.0.1. L'appel à RegisterHub est le seul point qui distingue un programme qui accède des modules à travers le réseau d'un programme qui accède à des modules en USB natif, tout le reste reste strictement identique. L'API gère les communications tant réseau qu'USB de manière totalement transparente.

RegisterHub: La seule différence entre accès USB natif et accès réseau
RegisterHub: La seule différence entre accès USB natif et accès réseau


Le VirtualHub et les YoctoHub peuvent être configurés afin que leur accès soit protégé à l'aide d'un nom d'utilisateur et un mot de passe. Dans ce cas, ces deux paramètres doivent alors être passés avec l'adresse réseau au format username:password@adresse.

Si vous souhaitez contacter plusieurs machines à la fois, faites un appel RegisterHub par machine à contacter. C'est le seul cas où vous devrez appeler RegisterHub plusieurs fois dans la vie de votre application. Bien sûr, vous pouvez aussi mixer les modes réseau et USB.

Si la machine que vous essayez de contacter ne répond pas, RegisterHub renverra un message d'erreur après un timeout. Il est possible d'obtenir un comportement différent avec la fonction Preregisterhub décrite plus bas.

HTTP callback

Le mode HTTP callback est un mode spécial disponible uniquement en PHP, Java et Node.js. Il s'agit d'une technique qui permet de passer les filtres NAT sans encombre. Typiquement lorsque vous souhaitez contrôler des modules Yoctopuce qui se trouvent chez vous depuis un serveur qui se trouve directement sur internet. Cette technique évite d'avoir à ouvrir un port sur votre routeur DSL, elle est idéale pour créer un service de cloud capable de gérer des produits Yoctopuce.

Dans ce mode, vous configurez un VirtualHub ou un YoctoHub pour appeler un script situé sur un serveur distant. Le VirtualHub/YoctoHub va alors envoyer automatiquement au script l'état des tous les modules connectés. Le script répondra éventuellement par la liste des actions à entreprendre. Le côté magique de la chose, c'est que la seule différence entre un script "callback" et un programme normal, c'est le premier paramètre de RegisterHub. Il suffit de spécifier "callback" et c'est tout: tous les autres appels restent identiques, ici aussi, les communications réseau entre le VirtualHub/YoctoHub et le script sont soigneusement cachées par l'API. Bon, évidement, c'est un peu moins réactif qu'une connexion directe.

PreregisterHub

PreregisterHub est une variante de RegisterHub qui ne ne renverra pas d'erreur si la machine que l'on cherche à contacter n'est pas disponible au moment de l'appel. En revanche, si la machine en question devient accessible plus tard dans la vie de votre application, les modules qui lui sont raccordés seront alors accessibles sans avoir à refaire un appel à RegisterHub. Vous pouvez facilement être prévenu de la mise en ligne d'une machine enregistrée à l'aide de PreregisterHub: il suffit de mettre en place un callback à l'aide de RegisterDeviceArrivalCallback, et dès que la machine sera en ligne, vous allez voir tous ses modules débarquer.

FreeAPI

Si vous être un puriste ou que vous souhaitez tracer un memory leak, vous pouvez appeler FreeAPI, à la fin de votre application pour libérer toutes les ressources utilisées par l'API. Mais dans la mesure où le système d'exploitation le fera de toutes manières, ce n'est pas obligatoire. Attention, après avoir appelé FreeAPI, vous ne pourrez plus à accéder aux autres fonctions de l'API sans faire crasher votre application.

Conclusion

RegisterHub sert à initialiser et à configurer le comportement de l'API Yoctopuce, et il n'est absolument pas nécessaire de l'appeler en boucle, qu'on se le dise ! :-)

Commenter aucun commentaire
Retour au blog












Yoctopuce, get your stuff connected.