• ❓ What is it ?
• ✨ What can it do ?
• 🔧 How to build ?
  • 🟦 Windows
    • 📦 vcpkg instructions
  • 🐧 Linux
    • 🐳 docker instructions
  • 🍎 MacOS
• 🏁 How to use ?
• 📝 Authors & Contributors

With the release of Ultraleap Gemini V5 hand tracking, the websocket feature present in Leap Motion Orion V4 was removed. This meant that LeapJS experiences would no longer work with the newer tracking software.

This Ultraleap Tracking WebSocket repository aims to maintain some form of retro-compatibility with LeapJS and enable web developers to receive tracking data in their browser with the latest generation of Ultraleap hand tracking.

For now the goal is to be 100% compatible with what was called protocol v6 in LeapJS which includes LeapJS version 0.6.0 through to 1.1.1. Here is a quick list of the features of v6 and which ones has been implemented so far:

• Connection on v6.json endpoint ✔️
• Stream tracking data ✔️
• Focus and background messages ✔️
• Switch to HMD mode ✔️
• Switch to Screentop mode ✔️ (NEW - use latest LeapJS master branch)
• Device events ❌
• Gestures ❌
• Secure WebSocket ❌

You'll need Ultraleap Gemini V5 or above hand tracking to be installed, and OpenSSL too. You also have to add libwebsockets. If you have vcpkg, there is specific instructions that might make things easier for you.

Pull the content of this repository and use CMake to build the solution:

# Pull repository
git clone https://github.com/ultraleap/UltraleapTrackingWebSocket.git
cd ultraleap-tracking-websocket

# Prepare build
mkdir build
cd build

# Build solution
cmake ..

Then in the build folder you should be able to find your solution and build the executable with Visual Studio.

Start by installing and setting vcpkg. Then install libwebsockets with vcpkg install libwebsockets --triplet x64-windows. From then, you can follow these instructions:

# Pull repository
git clone https://github.com/ultraleap/UltraleapTrackingWebSocket.git
cd ultraleap-tracking-websocket

# Prepare build
mkdir build
cd build

# Build solution
cmake -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake ..
cmake --build .

To build on Linux, you'll need to have a couple of dependencies installed on your system:

• CMake (package cmake on Ubuntu/Debian)
• Ultraleap's tracking service and SDK (Ultraleap's website has instructions on how to add the repository and install the packages
• libwebsockets (package libwebsockets-dev on Ubuntu/Debian)

If you satisfy those dependencies, you can go ahead, pull the repository and build the executable:

# Pull repository
git clone https://github.com/ultraleap/UltraleapTrackingWebSocket.git
cd ultraleap-tracking-websocket

# Prepare build
mkdir build
cd build

# Build solution
cmake ..

Very useful if you want to cross-build for Linux, or avoid having to build and add libwebsockets to your system. Run the following on a Linux-based system:

# Build Docker image
docker build -t leapws-builder:latest .

# Run the container (also mounts the result folder)
docker run -v "$(pwd)/output":/code/build/output --rm -it leapws-builder:latest

The resulting build should be found in the output folder.

Ensure you have Xcode or at least the XCode Command Line Tools installed, and that homebrew is installed and set up. Make sure you also have installed Ultraleap Gemini V5 or above hand tracking service for Mac.

Install libwebsockets with brew install libwebsockets. From there, you can follow the instructions:

# Pull repository
git clone https://github.com/ultraleap/UltraleapTrackingWebSocket.git
cd ultraleap-tracking-websocket

# Prepare build folder
mkdir build
cd build

# Build solution and executable
cmake ..
cmake --build .

Once built, run the executable to start the websocket server.

Download the LeapJS repository and run one of the webpages from the examples folder such as dumper.html to see the hand data coming through.

• Author: Rodolphe Houdas
• Contributors:
  • James Provan