Dolphin

Setup Guide

Dolphin setup on Linux systems The current guide covers the setup of Dolphin's Stimulus Designer and Reader tools on Windows systems. Dolphin was built based on the Qt Framework with cross-platform compatibility in mind, however some additional steps are required to get it to run on Linux. I will update the present guide with details on that as soon as I can find the time to do so!

Step 1: Get the Dolphin sources

Dolphin currently needs to be built from the source files available for download on https://gitlab.com/h-reality/dolphin. Download or clone the contents of the master branch to the desired location on your machine.
(to clone with https: https://gitlab.com/h-reality/dolphin.git ; to clone with ssh: git@gitlab.com:h-reality/dolphin.git)

Dolphin installer An automatic installer for Dolphin is in the works to simplify the process described on this page, and will be made available as soon as it is ready.

Step 2: Ultraleap haptics SDK

Dolphin is currently designed to function with Ultraleap hardware and thus requires the Ultrahaptics SDK v2.6 to be installed* (*) Currently, the data structures used within Dolphin to represent different aspects of the stimuli are directly reused from the Ultraleap haptics SDK C++ libraries. We plan on reworking this to make the bulk of the software hardware agnostic in the near future, so that users interested in applying Dolphin to other hardware may simply reuse the stimulus designer as is, while only needing to rewrite the stimulus reader component for their specific hardware.

Access to the haptics SDK can be requested from Ultraleap over here: https://developer.ultrahaptics.com/downloads/sdk/

Ultraleap SDK v3.x compatibility With the upcoming possible release of the Ultraleap haptics SDK v3, an updated version of Dolphin is being prepared and will be made available as soon as possible.

Step 3: Set up Qt

Dolphin is built using the Qt framework and MSVC compiler. The MSVC compilers are automatically installed if you have Microsoft Visual Studio installed with all C++ components on your machine, or can be manually obtained from : https://visualstudio.microsoft.com/fr/downloads/#build-tools-for-visual-studio-2019

Download Qt and Qt Creator via the Qt online installer: https://www.qt.io/download-open-source
(If for some reason the previous page’s links appear broken, you can also access the installer directly here: https://www.qt.io/download-qt-installer , however we strongly recommend you take note of the terms of use of Qt for open-source development).

When running the Qt installation manager, select “Add or remove components” and make sure to install Qt 5.x (as of writing, the most up-to-date is 5.15.2) as building the applications will fail if using prior or subsequent versions of Qt.

During the installation, install support for the MSVC compiler you previously installed (add the appropriate MSVC kit to your installation).

Qt 6.x compatibility Due to significant changes in the Qt framework libraries between versions 5.x and 6.x, the Dolphin designer and reader tools will not compile as is when using Qt 6.x. We hope to be able to port Dolphin to Qt 6.x in the near future.

Step 4: Open and configure the Dolphin Qt project(s)

Once everything is installed, open the Dolphin project in Qt Creator using File > Open File or Project… and select the appropriate .pro file:

If you want to build the stimulus design tool: “./tools/design_tool/src/dolphin_design_tool.pro"
If you want to build the stimulus reader tool: “./tools/reader/src/dolphin_reader.pro"

Upon loading the selected project, Qt will display a configuration window allowing you to select the adequate compiler from the list of avaiable kits (Qt lingo for compiler and associated build tools). Select the previously installed MSVC kit if it appears in the list.

Qt missing MSVC compiler kit If for some reason, the MSVC compiler does not appear in the list, check the "Manage Kits" button in the top left corner of the project configuration window - also accessible via the Tools > Options > Kits menu - to see if Qt autodetects an installed MSVC kit. If it does not, this menu cannot allow you to manually add an MSVC kit to your Qt installation, so use the Qt installer to modify your installation and make sure an adequate MSVC kit is selected for installation.

Edit the .pro file to correctly set the path of the Ultrahaptics library to your installation path
(the three lines under #ULTRAHAPTICS DEPENDENCIES).

On the left of the Qt Creator window, click Projects and select your MSVC compiler. In the Build Settings section, choose the Debug configuration and uncheck the Shadow build checkbox, then do the same for the Release configuration.

Select whichever build configuration fits your purpose (Debug or Release) and click the Run button (green triangle at the bottom left corner of the Qt Creator Window) to build and run the design tool.

Step 5: Launching the tools from within Qt Creator

Once the loaded project is correctly configured and loaded, you should be able to directly build and run the tool from within Qt Creator by clicking the “Build & Run” button (green triangle at the bottom left corner of the Qt Creator Window).

Beforehand, select whichever build configuration fits your purpose (Debug or Release) by clicking the computer icon above the “Build & Run” button.

The selected tool can then be used normally (see Designing Stimuli for a tutorial on the stimulus designer tool, and Sensation Playback for a tutorial on the reader tool).

Dealing with common build issues

Cleaning and rebuilding the project If building the application fails for some reason, you can begin by cleaning the project, re-running qmake and re-building the project. For this, right-click on the project in the Qt Creator project pane and select "Clean", repeat and select "Execute qmake", then repeat and select "Recompile".

Incorrect Qt version If build errors persist and the compiler is throwing errors related to function calls in the code or included Qt libraries which cannot be found, you likely have an incompatible version of Qt installed. In this case, run the Qt installation manager and make sure your Qt installation is for Qt 5.15.x with MSVC compiler kit. Make sure to clean and rebuild the project as described above after making modifications to your Qt installation.

Incorrect path to Ultrahaptics libraries If compilation runs smoothly but the build process throws a linker error (usually LNK1181) the most likely culprit is the path to the Ultrahaptics dependencies set in the ".pro" file. Make sure this is correct and clean and rebuild the project as described above after any modifications to the ".pro" project file.

If you encounter any other build issues which you cannot easily resolve, do not hesitate to get in touch (see contact e-mails on the gitlab page).

Step 6: Building and independently launching the executables

Unless you configured it otherwise in the Qt Creator project settings, building or building and running one of the projects will generate a folder containing an executable file for the given tool which can be run independently from Qt Creator. Some additional steps are however necessary to ensure the required software libraries are correctly found by the tools.

By default, the path to the folder with the executables will be:

“./tools/design_tool/src/release" or "./tools/design_tool/src/debug" for the stimulus design tool, depending on whether you built it in Release or Debug configuration.
“./tools/reader/src/release" or "./tools/reader/src/debug" for the reader tool, depending on whether you built it in Release or Debug configuration.

To launch the executable contained in any of these folders, start by copying the Ultrahaptics DLLs (Ultrahaptics.dll and libusb.dll) which are found in the “./Ultrahaptics/bin” folder of your Ultrahaptics SDK installation. Paste these in the folder with the Dolphin tool executable.

Then, copy the required Qt DLLs (QT5Core.dll, QT5Gui.dll and QT5Widgets.dll if built in “Release” configuration, QT5Cored.dll, QT5Guid.dll, QT5PrintSupportd and QT5Widgetsd.dll if built in “Debug” configuration) from your Qt installation folder (e.g. “C:\Qt\5.15.2\msvc2019_64\bin“). Also paste these into the folder with the Dolphin tool executable.

Finally, copy the “platforms” folder from the “plugins” folder of your Qt installation (e.g. “C:\Qt\5.15.2\msvc2019_64\plugins“) to the folder with the Dolphin tool executable.

Once all these elements are placed in the folder with the tool’s executable file, you should be able to launch the executable directly without running Qt Creator in the background. The folder with the executable then also acts as a self-contained portable installation of the Dolphin tool.

Common execution issues

Below is a (non exhaustive) list of quick fixes for common issues when running the Dolphin tools. If you encounter an issue not listed here, please get in touch to tell us about the issue, your fix for it, or to request assistance (see contact e-mails on the gitlab page, or use the contact form).

No stimulus emission - incorrect device firmware Dolphin requires your Ultraleap device to be running Firmware version 1.1.0 to correctly interface with the SDK version used. You can check your device's Firmware version by connecting it and running the Ultraleap Haptics Control Panel. If you are running an incompatible firmware version, refer to the Ultraleap documentation to flash your device to the correct version.

No stimulus emission - Ultrahaptics service not running and/or Ultraleap Haptics Control Panel running concurrently If both the device and software are configured correctly but you are unable to emit any of the designed stimuli, first double check that the Ultrahaptics service is running in the background and restart it if necessary. We have also encountered issues in emission when the Ultraleap Haptics Control Panel application was running simultaneously with Dolphin, so make sure this is not the case.