HandDriver Web Deployment and Usage Guide

1. Overview

1.1. Function Overview

1. HandDriver Web adopts B/S architecture, supporting access to the graphical interface through a browser on a PC. The browser can be closed once the DataGlove is properly connected. It is suitable for applications in the robotic field (the interface language currently only supports English).

2. During use, the receiver is connected to the PC where the server is located. The distance between the DataGlove and the receiver should not be too far, ideally kept within 2-3 meters, with a maximum range of approximately 5 meters.

3. Only supports 1-To-2 receiver DataGlove.

4. Compared to the HandDriver, the following features have been removed:

   • FBX/BVH recording and its related configuration options;

   • Thumb root joint adjustment;

   • Firmware upgrades (if the firmware upgrade is required, it is recommended to download the Windows version. Note: always upgrade the DataGlove first, then upgrade the receiver.)

1.2. Environmental Requirements

• Google Chrome is recommended.

• Only supported in Ubuntu currently. Please pay special attention to the Ubuntu version requirements for different software versions.

2. Software Download

Server installation package:

Ubuntu 22 and above：

6MB

HDService-Regular_V2.2.1_202512311727_Ubuntu22+_arm_64.zip

archive

Open

2MB

HDService-Regular_V2.2.1_202512311721_Ubuntu22+_x86_64.zip

archive

Open

Ubuntu 20:

2MB

HDService-Regular_V2.2.1_202512311725_Ubuntu20_x86_64.zip

archive

Open

Web client installation package (both x86 and ARM are supported):

65MB

HDWebClient_V2.2.1_202512311341.zip

archive

Open

3. Software Environment Deployment and Execution

It is recommended to deploy and start the server first, then deploy and run the web client.

3.1. Server Deployment and Startup

3.1.1. Important Notes

When deploying the server, follow the operations described in the "Regular Version" section of this document. However, if using an authorized version related to dexterous hands, be sure to first review the operation instructions for the relevant dexterous hand version (including the License Key instructions).

3.1.2. Paxini Dexterous Hands Authorized Version

The Paxini authorized version only supports operation in Ubuntu 22. The Paxini authorized version requires an License Key and corresponding software package provided by Udexreal to be used.

If using the version that supports Paxini dexterous hand, the following steps must be performed first.

• Save the server installation package HDService.zip in any directory of your system, extract it, then navigate to the HDService directory, open a terminal, and enter the following commands in sequence.

sudo dpkg -i DexHandSDK-1.2.1-Linux.deb
sudo tar -xzf gsl.tar.gz
# Enter the gsl directory
cd gsl
sudo ./configure CFLAGS="-g -O0"
sudo make -j4
sudo make install
# Back to the HDService directory
cd ..
sudo tar -xzf eigen-3.3.7.tar.gz
# Enter the eigen-3.3.7 directory
cd eigen-3.3.7
sudo mkdir build
# Enter the build directory
cd build
sudo cmake ..
sudo make install

At this point, the operations required to support the Paxini dexterous hand are completed. Please proceed to refer to the Regular Version deployment instructions.

3.1.3. Regular Version (the Regular, Non-dexterous Hand Authorized Version) Deployment and Startup

1

Install Dependencies

Save the server installation package HDService.zip in any directory of your system, extract it, then navigate to the HDService directory, open a terminal, and enter the following commands in sequence.

• Install dependencies (if batch installation is not possible, they can also be installed individually)

sudo apt update && sudo apt install -y build-essential libboost-all-dev libopencv-dev libspdlog-dev libfmt-dev libgoogle-glog-dev libopenblas-dev libdlib-dev libjsoncpp-dev libfltk1.3-dev libyaml-cpp-dev python3-pip python3-dev cmake vim git 

• If error occurs during the process, execute the following command, then run the dependency installation again. Repeat this cycle until all the above dependencies are installed.

sudo apt --fix-broken install

2

Operations for Different Ubuntu Versions

a. Ubuntu20

Perform the following operations in any directory.

wget https://github.com/protocolbuffers/protobuf/releases/download/v3.12.4/protobuf-all-3.12.4.tar.gz
tar -xzf protobuf-all-3.12.4.tar.gz
# Enter the protobuf-3.12.4 directory.
cd protobuf-3.12.4
./configure
make -j$(nproc)
sudo make install
sudo ldconfig

b. Ubuntu22

There are no other special operations. Proceed directly to to the step 3 described below.

c. Ubuntu24

Perform the following operations in the HDService directory.

sudo dpkg -i libprotobuf23_3.12.4-1ubuntu7_amd64.deb

3

Server Startup

• Enter the HDService directory, open a terminal, and enter the following commands in sequence.

sudo cp 80-usb-serial.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

• Update local dependency libraries

sudo ldconfig

• Since HDService needs to create a log directory and may also save human-side motion data, it is necessary to ensure that the directory where HDService is located on the server has sufficient read and write permissions. It is recommended to check the permissions first. If unsure, you can execute "sudo chmod -R 777 <server directory>" to grant full read, write, and execute permissions to the directory and its subdirectories.

• Finally, execute the following commands in the HDService directory to complete the server deployment and service startup (If the permissions are insufficient, first execute sudo chmod +x HDService).

./HDService

3.2. Web Client Deployment and Operation

Web client deployment refers to Unity WebGL + Nginx (Ubuntu) deployment. It is recommended to place the Web client on the same computer as the server, so the deployment only needs to be done once.

3.2.1. Environment Preparation

• Update the system and install the Nginx:

sudo apt update
sudo apt install -y nginx

• Create the Web client deployment directory, such as /var/www/handdriver , and copy all files from the unzipped HDWebClient.zip to this directory.

• Ensure the server-config.json content is correct, for example:

{
  "serverUrl": "ws://192.168.5.215:7789" //This ip is the address where the server is located.
}

• If using UFW or other firewalls, open the port 80 (or 443): sudo ufw allow 'Nginx Full'

3.2.2. Nginx Configuration

1. Create a new site configuration: Use the command sudo vim /etc/nginx/conf.d/handdriver.conf (if vim is not available, use nano for writing) to create a configuration file, and write the following content into it (Please pay special attention to ensuring that the configurations for listen, server_name, and root in the configuration file are correctly set):

server {
    listen 8088; # This listening port can be set according to your actual situation.
    server_name 192.168.5.215; # The actual IP or domain name where the server is located, same as the address where the Web client resides.

    root /var/www/handdriver; # Actual Web client deployment directory.
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location = /server-config.json {
        default_type application/json;
        add_header Cache-Control "no-cache, must-revalidate";
        add_header Access-Control-Allow-Origin "*" always;
        add_header Access-Control-Allow-Methods "GET, OPTIONS" always;
        add_header Access-Control-Allow-Headers "Content-Type" always;
        try_files /server-config.json =404;
    }

    location /Build/ {
        add_header Cache-Control "no-store";
        try_files $uri =404;
    }

    location /TemplateData/ {
        try_files $uri =404;
    }

    access_log /var/log/nginx/handdriver_access.log;
    error_log  /var/log/nginx/handdriver_error.log;
}

1. Modify the nginx.conf file

sudo vim /etc/nginx/nginx.conf (use nano for writing if vim is not available)

Change the first line user www:data to user root

1. Enable the site and verify the configuration

sudo nginx -t

1. Apply the new configuration

sudo systemctl reload nginx

3.2.3. Permissions and Deployment

When updating the version, simply replace the files in the Web client deployment directory (e.g., /var/www/handdriver) and execute sudo systemctl reload nginx again.

3.2.4. Verification and Operation

• (This step is optional) Use curl http://192.168.5.215:8088/server-config.json (replace with the actual IP/domain and port) to check if the JSON is accessible and if the response headers meet expectations.

• Open a browser and visit http://192.168.5.215:8088/ (replace with the actual IP/ domain and port) to confirm that the WebGL page loads properly. Once verified, the HandDriver Web is ready to run.

• If HTTPS is required, configure the certificate (e.g., using Let's Encrypt) as needed and replace the listening port listen 8088 with the corresponding listen 443 ssl settings.

4. Precautions

1. When multiple Web clients are connected to the same server, operations performed on one client (such as Calibration or Data Trans setting) will be synchronized to all other clients.

2. Data transmission: Data generated by each character is packaged independently and send seperately.

3. If the server crashes, the indicator light on the previously connected DataGlove will remain solid green. The server must be restarted before reconnecting the DataGlove.

4. The Old Plugin option in the Data Trans function is currently non-functional when selected.