This week, we are going to clarify the use of two methods of our API: YAPI.RegisterHub() and YAPI.PreregisterHub(). These two functions enable you to adapt the library behavior to your needs, more particularly managing network disconnection when you use a YoctoHub or a VirtualHub.
First of all, let 's specify that the topic of this post is rather advanced, and that if you have never used our modules or one of our programming libraries, you may not understand much. Before you immerse yourself in the reading of this post, we recommend that you read (again) the following posts:
What doesn't change
The basic aim of these two methods is the same: to configure the library to use modules accessible with the URL given as a parameter. This URL can be the "usb" keyword for the native USB access mode, the "callback" keyword for the callback HTTP mode, or the network address of a YoctoHub.
In native USB mode or in callback HTTP mode, there is no difference between these two methods. Indeed, as we are going to see, the difference between these two methods concerns only the network connection management between the library and a YoctoHub or a VirtualHub.
YAPI.RegisterHub()
The YAPI.RegisterHub() method adds the URL to the list of the YoctoHubs to be used and marks this YoctoHub as "required". That is, issues of connection to this YoctoHub are considered as serious and an error is returned.
For example, if the YoctoHub is not turned on at the time of the call to YAPI.RegisterHub(), the library actively tries to connect to this URL, and if it doesn't succeed within the time limit, it returns an error. It's a rather classic and natural behavior, but using this method also has an impact on the behavior of YAPI.UpdateDeviceList().
What happens if the YoctoHub is connected during the call to YAPI.RegisterHub(), but is later disconnected? As the YoctoHub is marked as "required", the YAPI.UpdateDeviceList() method has the same behavior as YAPI.RegisterHub(). That is, the YAPI.UpdateDeviceList() method tries to reconnect within the time limit and returns an error if it doesn't succeed.
The idea behind this behavior is that the YoctoHub is required for the system and that, if it is not available, there's no point in continuing because it's a fatal error.
This behavior works well for an application using only one YoctoHub on a cabled network, but in some cases we would rather appreciate for the library to signal the disconnection of the YoctoHub and of the modules connected to it, without blocking the application. This is what YAPI.PreregisterHub() does.
YAPI.PreregisterHub()
The YAPI.PreregisterHub() method adds the URL to the list of YoctoHubs to be used, but marks the later as "optional". That is, if this YoctoHub is not available, no error is returned and the modules are simply marked as "offline".
When calling YAPI.PreregisterHub(), the library adds the URL to the list of YoctoHubs to be used and returns YAPI.SUCCESS. The library manages the connection with the YoctoHub as a background task.
Later, when calling YAPI.UpdateDeviceList(), the library checks the connections with the YoctoHub and updates the inventory. If the YoctoHub answers, the modules are kept or added in the list of available modules. If, on the opposite, the YoctoHub is not responding, the modules which were present on this YoctoHub are taken out of the inventory. In both cases, YAPI.UpdateDeviceList() returns YAPI.SUCCESS.
Note also that in this mode, YAPI.UpdateDeviceList() returns control very quickly as the library performs connection management as a background task. Indeed, in this mode, this function only checks the state of the connection with the YoctoHub and updates the inventory accordingly.
A few comments
YAPI.SetNetworkTimeout()
We added a YAPI.SetNetworkTimeout() method which allows you to change the delay during which YAPI.RegisterHub() et YAPI.UpdateDeviceList() try to connect to the YoctoHub. By default, this delay is of 20 seconds, but depending on your network, you may want to modify this delay, for example if your network infrastructure uses a GSM connection.
YoctoHub on battery
Using YAPI.PreregisterHub() is very useful in scenarios where a YoctoHub works on a battery and is turned on only from time to time. Using YAPI.PreregisterHub() allows you to avoid timeouts when calling YAPI.UpdateDeviceList() while being able to detect when the YoctoHub is on or not. We used this technique for our WiFi mailbox.
Arrival/removal callbacks
Using the YAPI.PreregisterHub() method is almost inseparable from arrival/removal callbacks. Indeed, in this mode the YAPI.UpdateDeviceList() function doesn't return errors, therefore the best way to detect the state of the connection is to register arrival and removal callbacks to monitor the arrival of the YoctoHub.
PreregisterHub() AND RegisterHub()
It's quite possible to use both methods in the same application. Let's imagine a scenario in which a YoctoHub contains required modules, such as a relay driving a valve, and another YoctoHub working on a battery and which would be turned on only from time to time.
However, in this scenario, if the required YoctoHub is not online, the YAPI.UpdateDeviceList() method returns an error and there is no guarantee that the arrival and removal callbacks of the other YoctoHubs are called.
Conclusion
We hope that this post will have clarified the difference between YAPI.RegisterHub() and YAPI.PreregisterHub(). As usual, if you have questions, don't hesitate to contact support.