A few weeks ago, we added the YHub class to the Java and TypeScript libraries. This week, we're adding this class to all the other programming libraries. As a reminder, this class is used to obtain the connection status between the programming library and any YoctoHubs or VirtualHubs that have been registered.
Note: This post assumes that you're already familiar with the Yoctopuce programming libraries and how our products work. If not, you can start with our tutorial series.
As a reminder, this class is declared in the same file as the YAPI class, so you don't need to modify your makefiles and/or projects to use it. If you already have a program that uses one of our libraries, simply update our lib to use this new class.
For languages that don't use dynamic allocation, such as C++, Objective-C, or Delphi, this new class follows the same rules as our other classes(YModule, YFunction, and so on): you don't need to allocate or deallocate objects. The Yoctopuce library is responsible for allocating and deallocating the objects corresponding to each hub. It keeps a reference to these objects throughout execution, and they are released only when YAPI.FreeAPI() is called at the end of the execution.
YHub class methods
All the methods we had in the Java and TypeScripts libraries are available:
- The get_registeredUrl() method returns the URL under which this hub was initially registered using the YAPI::RegisterHub or YAPI::PreregisterHub method, for example: 192.168.1.12
- The get_connectionUrl() method returns the URL currently used to communicate with this hub. Unlike get_registeredUrl(), which returns the value passed to the API, get_connectionUrl( ) returns a normalized URL with prototype, port, but not the authentication information, for example: ws://192.168.1.12:4444/
- The get_serialNumber() method returns the serial number of the YoctoHub or VirtualHub.
- The isOnline() method indicates whether communication with this hub is currently active and usable. For example, if the YoctoHub is switched off or offline, this method returns false.
- The isReadOnly() method indicates whether access to this hub is write-protected. This function enables you to test if the authentication parameters allow you to modify the attributes of the modules connected to the YoctoHub.
- The isInUse() method indicates whether this hub is currently registered in the API. This function enables you to test if a hub has been unregistered with YAPI::UnregisterHub().
- The set_networkTimeout() and get_networkTimeout() methods are used to configure the network connection timeout for the Hub. The default value is the value set by the YAPI::GetNetworkTimeout function at the time the hub was registered, but the timeout can be subsequently modified for each hub.
- The set_userData() and get_userData() methods are used to register a free context in order to retrieve it later. These methods do not trigger any communication.
- The get_errorType() and get_errorMessage() methods return the details corresponding to the latest error that occurred while using the hub. These methods are mainly useful when the Yoctopuce library is used with exception handling disabled.
We've also added a new get_knownUrls() method to all libraries, including Java and TypeScript. This method returns all URLs under which a hub has been registered.
This function can be used to detect and debug the special case where the application has registered two different URLs pointing to the same YoctoHub or VirtualHub. In this situation, the library detects that it's the same hub and merges the two connections, applying the parameters of the last call.
For example, on a machine running the VirtualHub, the latter is accessible via the localhost interface and the machine's public IP address.
The following code incorrectly uses these two addresses with different parameters.
...
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)
When executing the call to PreregisterHub("192.168.1.125"), the library detects that it's the same VirtualHub and merges the two calls. However, the parameters of the latter call are used. In this particular case, the program displays the following messages:
Alternate URL:
- http://localhost
- 192.168.1.125
In this situation, the library stops using this VirtualHub on the first call to UnregisterHub() using one of these two URLs. For example, the second call of the following code has no effect.
YAPI.UnregisterHub("http://localhost")
# next call is useless
YAPI.UnregisterHub("192.168.1.125")
Note that if we reverse the two calls to UnregisterHub, the situation is the same.
In short, the API merges URLs pointing to the same VirtualHub or YoctoHub. In this situation, the parameters of the last call are saved and used. In the case of UnregisterHub, the opposite is true: the connection is stopped as soon as the first call is made.
Special cases
As a reminder, the YHub class represents the connection with a YoctoHub or VirtualHub after a call to RegisterHub. However, there are two special cases: RegisterHub("usb") and RegisterHub("callback"). In these two cases, it's not the URL of the YoctoHub which is passed, but a keyword.
In both cases, a YHub object is created and the get_connectionUrl() and get_registeredUrl() methods return either "usb" or "callback".
Another particularity of the USB mode is that the get_serialNumber() method returns an empty string ("").
Conclusion
This new functionality can now be used in all our libraries. This new YHub class is very useful for applications where the user can configure URLs to connect to YoctoHub, such as the Yocto-Visualization application.