The new YHub class

The new YHub class

While developing an internal application that used many YoctoHubs, we realized that our API was missing a way to easily get the list of Hubs that had already been registered. In order to fill this gap, we have just now added a new YHub class.





Note: This article assumes that you are already familiar with the Yoctopuce programming libraries and the way our products work. If not, you can start with our tutorial series.


As we said in the introduction, our API was missing a way to describe the state of the YoctoHubs or VirtualHub with which the API communicates. To do this, we added a new YHub class which represents the state of the connection between the library and a YoctoHub.

This class is implemented in the yocto_api file and is therefore by necessity already included in all your projects because it is in the same file that the YAPI class is implemented.

Like the YModule, YFunction, an so on classes, you do not need to allocate or deallocate the objects of this class. The Yoctopuce library automatically instantiates an object for each hub and keeps a reference to these objects throughout the execution. These objects are freed only when calling YAPI.FreeAPI() at the end of the execution.


The YHub class


The YHub class enables you to get and configure the state of the connection between the Hub and the library. Here is the list of methods that are currently implemented:

  • 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 that was passed to the API, get_connectionUrl() returns a normalized URL with the prototype, the 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 if 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 if 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 if 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 configured by the YAPI::GetNetworkTimeout function at the time the hub was registered, but you can change the timeout later 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. This method is mainly useful when the Yoctopuce library is used with exception handling disabled.


Listing the Hubs


Enumerating YHub objects is very similar to enumerating other objects in the Yoctopuce programming libraries. The FirstHubInUse() class method returns the first object or NULL if no hub is registered. To obtain the following hubs, you must then use the nextHubInUse() method on the object that has been returned.

For example, the following Java code lists all the URLs that have been registered.

YHub hub = YHub.FirstHubInUse();
while (hub !=null) {
    System.out.println("URL: "+hub.get_registeredUrl());
    hub = hub.nextHubInUse();
}



Special cases


The YHub class represents the connection with a YoctoHub or VirtualHub after a call to RegisterHub. There are however 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 methods get_connectionUrl() and get_registeredUrl() return either "usb" or "callback".

Another particularity of the USB mode is that the get_serialNumber() method returns an empty string ("").

Availability


This new class is currently only available in TypeScript and Java, but this new feature will be available on all our other libraries in the next few weeks.

Add a comment No comment yet Back to blog












Yoctopuce, get your stuff connected.