If you ever wrote the tiniest bit of code to manage Yoctopuce modules, you know the RegisterHub function. But do you really know all of its features? As years went by, this function benefited from additional features without anyone taking care to describe them in details. So, let's see how to use this function...
Apart from the command line API where it doesn't make sense, the RegisterHub function exists in all programming languages in various forms. It fulfills several goals:
The main function of RegisterHub is to initialize the Yoctopuce API. Therefore, it's the first call you must make before you start working with Yoctopuce modules. Typically, you are going to put this call in the initialization section of your application. Except in particular cases, it is not needed, not to say counterproductive, to call RegisterHub several times during the life of you application.
If initializing went well, RegisterHub returns the YAPI_SUCCESS constant. Otherwise, an error message passed as a parameter contains a description of the problem.
On top of initializing the Yoctopuce API, RegisterHub enables you to specify the working mode in which you want to work. There are three distinct modes. The mode is given in the first parameter to the call to RegisterHub.
This is the simplest mode, to provide native USB access. You use it if you want to access modules connected by USB on the machine on which your application is running. To use this mode, simply pass the "usb" string as the first parameter. Note that there is a technical limitation: on the same machine, there can be only one application at a time accessing modules natively. Beware: the VirtualHub counts as a native application. However, you can easily work around this limitation thanks to the network mode described below.
In this mode, you specify that you want to access Yoctopuce modules through the network. Instead of "usb", you are going to provide a network address. This address can be the address of a machine on which a VirtualHub is running of the address or a YoctoHub. From the API standpoint, a VirtualHub running on a machine or a YoctoHub are strictly equivalent. You can use an IP address or directly the logical address of the machine. If you want to contact a VirtualHub running on your local machine, use the 127.0.0.1 address. The call to RegisterHub is the only point distinguishing a program accessing USB modules natively. Everything else remains completely identical. The API manages both network and USB communications in a transparent manner.
RegisterHub: the only difference between native USB access and network access
You can configure the VirtualHub or YoctoHubs to protect their access with a username and a password. In this case, you must pass these two parameters as username:password@address.
If you wish to contact several machines at the same time, call RegisterHub once for each machine you need to contact. This is the only case in which you must call RegisterHub several times in the life of your application. Naturally, you can also mix network and USB modes.
If the machine that you are trying to contact doesn't answer, RegisterHub returns an error message after a timeout. You can obtain a different behavior with the PreregisterHub function described below.
The HTTP callback mode is a special mode available only in PHP, Java, and Node.js. It's a technique allowing you to go through NAT filters without trouble. Typically, you use it when you want to control Yoctopuce modules located at home from a server located on the Internet. This technique avoids opening a port on you DSL router. It is ideal to create a cloud service able to manage Yoctopuce products.
In this mode, you configure a VirtualHub or a YoctoHub to call a script located on a remote server. The VirtualHub/YoctoHub then automatically sends to the script the state of all connected modules. The script may answer with the list of actions to be performed. What's magic is that the only difference between a "callback" script and a regular program is the first parameter of RegisterHub. You only need to specify "callback" and that's it: all the other calls remain the same. Here too, network communications between the VirtualHub/YoctoHub and the script are carefully hidden by the API. Well, obviously, it's somewhat less reactive than a direct connection.
PreregisterHub is a variant of RegisterHub. It doesn't return an error if the machine that you try to contact is not available when the call is performed. However, if the said machine becomes available later in the life of your application, modules that are connected to it are then made available without needing to call RegisterHub again. With PreregisterHub, you can easily be warned when a registered machine becomes online: simply set up a callback with RegisterDeviceArrivalCallback. As soon as the machine is online, you are going to see all of its modules.
If you are a purist or if you want to track of memory leak, you can call FreeAPI at the end of you application to free all the resources that the API used. But as the operating system does it anyway, it's not compulsory. Beware: after a call to FreeAPI, you cannot access other API functions without crashing your application.
You should use RegisterHub to initialize and configure the behavior of the Yoctopuce API. It is absolutely not necessary to call it in a loop, let it be known! :-)