Il y a quelques semaines, nous avons ajouté la classe YHub aux librairies Java et TypeScript. Cette semaine nous ajoutons cette classe dans toutes les autres librairies de programmation. Pour rappel, cette classe permet d'obtenir l'état de la connexion entre la librairie de programmation et les YoctoHubs ou VirtualHubs qui ont été enregistrés.
Note: Cet article part du principe que vous êtes déjà familier avec les librairies de programmation Yoctopuce ainsi qu'avec le fonctionnement de nos produits. Si ce n'est pas le cas, vous pouvez commencer par notre série de tutoriels.
Pour rappel cette classe est déclarée dans le même fichier que la classe YAPI, vous n'avez donc pas besoin de modifier vos makefiles et/ou projets pour l'utiliser. Si vous avez déjà un programme qui utilise une de nos librairies, il suffit de mettre à jour notre lib pour utiliser cette nouvelle classe.
Pour les langages qui n'utilisent pas d'allocation dynamique, comme C++, Objective-C ou Delphi, cette nouvelle classe suit les mêmes règles que nos autres classes (YModule, YFunction, etc): vous n'avez pas besoin d'allouer ou de désallouer les objets. La librairie Yoctopuce est responsable de l'allocation et la désallocation des objets qui correspondent à chaque hub. Elle garde une référence sur ces objets tout le long de l'exécution et ils sont libérés uniquement lors de l'appel à YAPI.FreeAPI() à la fin de l’exécution.
Les méthodes de la classe YHub
Toutes les méthodes que nous avions dans les librairies Java et TypeScripts sont disponibles:
- La méthode get_registeredUrl() retourne l'URL sous laquelle ce hub a été initialement enregistré à l'aide de la méthode YAPI::RegisterHub ou YAPI::PreregisterHub. Ex: 192.168.1.12
- La méthode get_connectionUrl() retourne L'URL actuellement utilisée pour communiquer avec ce hub. Contrairement get_registeredUrl() qui retourne la valeur qui a été passée à l'API, get_connectionUrl() retourne une URL normalisée avec le prototype, le port, mais pas les informations d'authentification. Ex: ws://192.168.1.12:4444/
- La méthode get_serialNumber() retourne le numéro de série du YoctoHub ou de VirtualHub.
- La méthode isOnline() indique si la communication avec ce hub est actuellement active et utilisable. Par exemple, si le YoctoHub est éteint ou offline cette méthode retournera false.
- La méthode isReadOnly() indique si l'accès à ce hub est protégé contre l'écriture. Cette fonction permet de tester si les paramètres d'authentifications permettent de modifier les attributs des modules connectés au YoctoHub.
- La méthode isInUse() indique si ce hub est actuellement enregistré dans l'API. Cette fonction permet de tester si un hub a été désenregistré avec YAPI::UnregisterHub().
- Les méthodes set_networkTimeout() et get_networkTimeout() permettent de configurer le délai de connexion réseau pour le Hub. La valeur par défaut est la valeur configurée par la fonction YAPI::GetNetworkTimeout au moment où le hub a été enregistré, mais le délai peut être modifié ultérieurement pour chaque hub.
- Les méthodes set_userData() et get_userData() permettent d'enregistrer un contexte libre afin de le retrouver plus tard. Ces méthodes ne déclenchent aucune communication.
- Les méthodes get_errorType() et get_errorMessage() retournent le détail correspondant à la dernière erreur survenue lors de l'utilisation du hub. Ces méthodes sont principalement utiles lorsque la librairie Yoctopuce est utilisée en désactivant la gestion des exceptions.
Nous avons aussi ajouté, une nouvelle méthode get_knownUrls() dans toutes les librairies, y compris Java et TypeScript. Cette méthode retourne toutes les URLs sous lesquelles un hub a été enregistré.
Cette fonction permet de détecter et débugger le cas particulier où l'application a enregistré deux URL différentes qui pointent vers le même YoctoHub ou VirtualHub. Dans cette situation la librairie détecte qu'il s’agit du même Hub et fusionne les deux connexions en appliquant les paramètres du dernier appel.
Par exemple, sur une machine qui exécute le VirtualHub, ce dernier est accessible par l'interface localhost et adresses IP publique de la machine.
Le code suivant utilise, à tort, ces deux adresses avec des paramètres différents.
...
YAPI.PreregisterHub("192.168.1.125")
...
hub = YHub.FirstHubInUse()
print("URL: %s" % hub.get_connectionUrl())
print("Alternate URL:")
knownUrls = hub.get_knownUrls()
for url in knownUrls:
print("- " + url)
Lors de l’exécution de l’appel à PreregisterHub("192.168.1.125"), la librairie va détecter qu'il s’agit du même VirtualHub et fusionnera les deux appels. Mais les paramètres du dernier appel seront utilisés. Dans ce cas particulier, le programme affichera les messages suivants:
Alternate URL:
- http://localhost
- 192.168.1.125
Dans cette situation, la librairie va stopper l'utilisation de ce VirtualHub dès le premier appel à UnregisterHub() utilisant une de ces deux URL. Par exemple le deuxième appel du code suivant n'a aucun effet.
YAPI.UnregisterHub("http://localhost")
# next call is useless
YAPI.UnregisterHub("192.168.1.125")
Notez que si l'on inverse les deux appels à UnregisterHub, la situation est la même.
En résumé, l'API fusionne les URL qui pointent vers le même VirtualHub ou YoctoHub. Dans cette situation, les paramètres du dernier appel sont sauvés et utilisés. Pour UnregisterHub, c'est l'inverse, dès le premier appel la connexion est stoppée.
Les cas particuliers
Pour rappel, la classe YHub représente la connexion avec un YoctoHub ou VirtualHub après un appel à RegisterHub. Il y a cependant deux cas particuliers: RegisterHub("usb") et RegisterHub("callback"). Dans ces deux cas, on ne passe pas l'URL du YoctoHub à utiliser, mais un mot-clef.
Dans les deux cas, un objet YHub est créé et les méthodes get_connectionUrl() et get_registeredUrl() retourneront soit "usb" soit "callback".
Autre particularité du mode USB, la méthode get_serialNumber() retourne une chaîne de caractère vide ("").
Conclusion
Cette nouvelle fonctionnalité est désormais utilisable dans toutes nos librairies. Cette nouvelle classe YHub est très utile dans une application où l'utilisateur peut configurer les URLs pour se connecter YoctoHub, comme l'application Yocto-Visualization.