Cette semaine, nous allons clarifier l'utilisation de deux méthodes de notre API : YAPI.RegisterHub() et YAPI.PreregisterHub(). Ces deux fonctions permettent d'adapter le comportement de la librairie à ses besoins, plus particulièrement la gestion des déconnexions réseau lorsqu'on utilise un YoctoHub ou un VirtualHub.
Avant toute chose, précisons que cet article est un sujet assez avancé, et que si vous n'avez pas encore utilisé nos modules ou une de nos librairies de programmation, vous risquez de ne rien comprendre. Avant de vous plonger dans la lecture de cet article, nous vous recommandons de lire ou relire les articles suivants:
Ce qui est identique
La fonction de base de ces deux méthodes est la même: Configurer la librairie pour utiliser les modules accessibles avec l'URL passée en paramètre. Cette URL peut être le mot-clé "usb" pour mode d'accès en USB natif, le mot-clé "callback" pour le mode callback HTTP ou encore l’adresse réseau d'un YoctoHub.
En mode USB natif ou callback HTTP, il n'y a pas de différence entre ces deux méthodes. En effet, comme nous allons le voir, la différence entre ces deux méthodes concerne uniquement la gestion de la connexion réseau entre la librairie et un YoctoHub ou VirtualHub.
YAPI.RegisterHub()
La méthode YAPI.RegisterHub() ajoute l'URL à la liste des YoctoHubs à utiliser et marque ce YoctoHub comme "indispensable". C'est-à-dire que les problèmes de connexion à ce YoctoHub sont considérés comme grave et une erreur est retournée.
Par exemple, si le YoctoHub n'est pas allumé au moment de l'appel à YAPI.RegisterHub(), la librairie essaye activement de se connecter à cette URL, et si elle n'y arrive pas dans le délai prévu, elle retourne une erreur. C'est un comportement assez classique et naturel, mais l'utilisation de cette méthode a aussi un impact sur le comportement de YAPI.UpdateDeviceList().
Que se passe-t-il si le YoctoHub est connecté lors de l'appel à YAPI.RegisterHub() mais est débranché par la suite? Comme le YoctoHub est enregistré comme "indispensable", la méthode YAPI.UpdateDeviceList() va avoir le même comportement que YAPI.RegisterHub(). C'est-à-dire que la méthode YAPI.UpdateDeviceList() va essayer de se reconnecter pendant le délai impartit et retourner une erreur si elle n'y arrive pas.
L'idée derrière ce comportement est que le YoctoHub est nécessaire au système et que, s'il n'est pas disponible, cela ne sert à rien de continuer car il s'agit d'une erreur fatale.
Ce comportement fonctionne bien pour une application qui utilise un seul YoctoHub sur réseau filaire, mais dans certains cas on aimerait plutôt que la librairie signal la déconnexion du YoctoHub et des modules branchés sur ce dernier, sans bloquer l'application. C'est ce que fait YAPI.PreregisterHub().
YAPI.PreregisterHub()
La méthode YAPI.PreregiserHub() ajoute l'URL à la liste des YoctoHubs à utiliser mais marque ce dernier comme "optionnel". C'est-à-dire que si ce YoctoHub n'est pas disponible aucune erreur n'est retournée et les modules sont simplement marqués comme "offline".
Lors de l'appel à YAPI.PreregisterHub(), la librairie ajoute l'URL à la liste des YoctoHubs à utiliser et retourne YAPI.SUCCESS. L'établissement la connexion avec le YoctoHub est gérée en tâche de fond par la librairie.
Par la suite, lors de l'appel à YAPI.UpdateDeviceList(), la librairie vérifie la connexion avec le YoctoHub et met à jour l'inventaire. Si le YoctoHub répond, les modules sont maintenus ou ajoutés dans la liste des modules disponibles. Si, au contraire, le YoctoHub est inaccessible, les modules qui étaient présents sur ce YoctoHub sont enlevés de l'inventaire. Dans les deux cas, YAPI.UpdateDeviceList() retourne YAPI.SUCCESS.
Il faut aussi noter que dans ce mode, YAPI.UpdateDeviceList() rend la main très vite car la gestion de la connexion est gérée en tâche de fond par la librairie. En effet, dans ce mode, cette fonction ne fait que vérifier l'état de la connexion avec le YoctoHub et mettre à jour l'inventaire en conséquence.
Quelques remarques
YAPI.SetNetworkTimeout()
Nous avons ajouté une méthode YAPI.SetNetworkTimeout() qui permet de changer le délai durant lequel YAPI.RegisterHub() et YAPI.UpdateDeviceList() essaient de se connecter au YoctoHub. Par défaut, ce délai est de 20 secondes, mais en fonction de votre réseau il peut être souhaitable de changer ce délai, par exemple si votre infrastructure réseau utilise une connexion GSM.
YoctoHub sur batterie
L'utilisation de YAPI.PreregisterHub() est très utile pour les scénarios où un YoctoHub fonctionne sur batterie et n'est allumé que de temps en temps. L'utilisation de YAPI.PreregisterHub() permet de ne pas avoir de timeout lors des appels à YAPI.UpdateDeviceList() tout en étant capable de détecter quand le YoctoHub est allumé ou non. C'est la technique que nous avons utilisée pour notre Boîte aux lettres WiFi.
Les callbacks arrival/removal
L'utilisation de la méthode YAPI.PreregisterHub() est presque indissociable des callbacks arrival/removal. En effet, dans ce mode la fonction YAPI.UpdateDeviceList() ne retourne plus d'erreur, par conséquent la meilleur façon de détecter l'état de la connexion est d'enregistrer des callbacks d'arrival et de removal pour de surveiller l'arrivée du YoctoHub.
PreregisterHub() ET RegisterHub()
Il est tout à fait possible d'utiliser les deux méthodes dans la même application. On peut imaginer un scénario où un YoctoHub contient des modules indispensables, comme par exemple un relais qui contrôle une vanne, et un autre YoctoHub qui fonctionne sur batterie et qui ne serait allumé qu'une fois de temps en temps.
Par contre, dans ce scénario, si le YoctoHub "indispensable" n'est pas online, la méthode YAPI.UpdateDeviceList() retournera une erreur et il n'est pas garanti que les callbacks d'arrival et de removal des autres YoctoHubs soient appelés.
Conclusion
Nous espérons que cet article aura clarifié la différence entre YAPI.RegisterHub() et YAPI.PreregisterHub(). Comme d'habitude, si vous avez des questions, n'hésitez pas à contacter le support.