Preview of the new 2.0 C++ library

Preview of the new 2.0 C++ library

A few months ago, we presented the beta version of the VirtualHub 2.0 with SSL/TLS support. This week, we present version 2.0 of the C++ library which adds the same feature: SSL/TLS support. As with the VirtualHub 2.0, this new version is available in Beta/preview.





The main improvement of this new version of the C++ library is the addition of the SSL/TLS support, but to do so we had to somewhat change the compilation of this library. As usual, we tried to maintained backward compatibility as much as possible, but some of the choices we made may break the build scripts. For this reason, we publish this library in Beta/preview in parallel with the official version.

However, the C++ API of the library remains the same. Classes and functions stay the same and we didn't remove any feature. Code intended for use with API 1.0 works as well with this new version.

Internally, this new version of the C++ library uses the mbed TLS library. As we explain it below, this library is included with the sources of our library and is compiled at the same time as the code of our library. This library uses the Apache-2.0 license and therefore authorizes the use of our library in a commercial product.

SSL/TLS support

The main novelty is the addition of the SSL/TLS support enabling you to connect to the VirtualHub v2.0 in a secure and encrypted manner. To use a secure connection, you only need to add the "WSS://" prefix to the VirtualHub address when calling YAPI::RegisterHub. The WSS prefix means "WebSocket Secure" and configures the library to communicate with the WebSocket protocol over an SSL/TLS encrypted connection.

Here is the code to initialize a connection with a VirtualHub v2.0 with a secure WebSocket:

...
if (YAPI::RegisterHub("wss://vhub.example.com", errmsg) != YAPI_SUCCESS) {
    cerr << "YAPI::RegisterHub failed: " << errmsg << endl;
}
...



Note that you can also force the use of the old HTTP protocol, but using an encrypted connection, with the "https://" prefix:

...
if (YAPI::RegisterHub("https://vhub.example.com", errmsg) != YAPI_SUCCESS) {
    cerr << "YAPI::RegisterHub failed: " << errmsg << endl;
}
...



In both cases, the Yoctopuce library takes care to encrypt the transmitted data.

The other features of the library are available and the use of the C++ API remains unchanged. To sum up, you only need to change the first parameter of the YAPI::RegisterHub method to use an encrypted protocol.

Download


The v2.0 C++ library is available on our web site and we also created a new repository on GitHub: https://github.com/yoctopuce/yoctolib_cpp_v2

Compiling the library

As explained above, the use of the library hasn't changed, but the compilation is different. The first modification is that there are more files to compile.
To compile the library, you must compile the following files:

  • all the .cpp files of the Sources directory
  • all the .c files of the Sources/yapi directory
  • all the .c files of the Sources/yapi/mbedtls/library directory


You must also add the Sources and Sources/yapi/mbedtls/include directories to the include path of the compiler.

There is a GNU makefile in the Binaries subdirectory which enables you to recompile the library. To compile the C++ library, you must simply run the make command in the Binaries subdirectory.

$ make



For Linux and macOS, nothing changes, as we already used a GNU makefile. For Windows it's new, as we used nmake before. You must therefore install a GNU make, for example with Chocolatey to recompile the C++ library. But you don't need to install GCC, because the makefile still uses the Microsoft cl compiler. However, under Windows, it's usually much simpler to use Visual Studio and to drop all the files mentioned above in your project.

Examples


You can find all the examples of use of the different Yoctopuce modules as well as several examples of the use of the features of the API in the Examples directory. Each example contains a GNU makefile, a Visual Studio project, and an XCode project.

Under Windows, you can compile and test the examples with Visual Studio 2017 or 2019.

The Visual Studio project for the Doc-Inventory example
The Visual Studio project for the Doc-Inventory example



And under macOS, you can use XCode, version 9.3 or higher.

The XCode project for the Doc-Inventory example
The XCode project for the Doc-Inventory example



Under Linux, the simplest way is to use the GNU makefile. To compile the example, you only need to run the make command in the example directory.

yocto@linux-build:~/cpp/Examples/Doc-Inventory$ make



Limitations


Currently, SSL support is not available for mips and mipsel platforms.

For the library to be able to use an encrypted connection, both parts must support SSL/TLS. At the time of writing, only the VirtualHub 2.0 supports this feature. You can't therefore use this feature to communicate with YoctoHubs yet.

Finally, if we publish this new version of the library with the "Preview" mention, it's because we reserve the right to make changes which may break upward compatibility. It is very unlikely that we would decide to change the API, but we could decide to change the location of source files or of the compilation scripts.

Feedback


Don't hesitate to contact support if you have trouble using this new version of the library or if you want to pass suggestions along.

Add a comment No comment yet Back to blog












Yoctopuce, get your stuff connected.