# 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 (<mark style="color:red;">if the</mark> [<mark style="color:red;">firmware upgrade</mark>](https://udexreal.gitbook.io/udexreal-docs/software-instruction/channel-and-firmware#firmware-upgrade-1) <mark style="color:red;">is required, it is recommended to</mark> [<mark style="color:red;">download the Windows version</mark>](https://udexreal.gitbook.io/udexreal-docs/software-instruction/software-instruction/download-and-installation)<mark style="color:red;">. Note: always upgrade the DataGlove first, then upgrade the receiver.</mark>)

### 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：**

{% file src="<https://2082502898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8s1Ia6TfFovgyJ5JsDJZ%2Fuploads%2FNRjS8FcX8w5v4tT8zsAX%2FHDService-Regular_V2.2.2_202601191623_Ubuntu22%2B_arm_64.zip?alt=media&token=f209077f-3423-4d06-af00-4f1eb7b5995b>" %}

{% file src="<https://2082502898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8s1Ia6TfFovgyJ5JsDJZ%2Fuploads%2FIKU4nLuiVZHiSxGxkgit%2FHDService-Regular_V2.2.2_202601191450_Ubuntu22%2B_x86_64.zip?alt=media&token=4ae853d4-e015-472d-b25f-e0972b7041c0>" %}

**Ubuntu 20:**

{% file src="<https://2082502898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8s1Ia6TfFovgyJ5JsDJZ%2Fuploads%2F0x80awOdz1n1aiMIh3x2%2FHDService-Regular_V2.2.2_202601191741_Ubuntu20_x86_64.zip?alt=media&token=3707bb86-4e55-4bc6-9035-f883482a125a>" %}

{% file src="<https://2082502898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8s1Ia6TfFovgyJ5JsDJZ%2Fuploads%2FRisPcEtHvSIzk2qnlXm7%2FHDService-Regular_V2.2.1_202512311725_Ubuntu20_x86_64.zip?alt=media&token=7cfc04f1-24b2-4617-8705-ed2580cdc2b3>" %}

**Windows:**

{% file src="<https://2082502898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8s1Ia6TfFovgyJ5JsDJZ%2Fuploads%2FwaFSbArE9UWd0S20Imre%2FHDService-Regular_V2.2.2_202601231450_Win_x86_64.zip?alt=media&token=0efebe9e-5bbe-4898-89e2-8b9050b85dcd>" %}

**Web client installation package (supports Windows/Ubuntu, supports x86/arm architectures):**

{% file src="<https://2082502898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8s1Ia6TfFovgyJ5JsDJZ%2Fuploads%2FBAuv7XE481ogJxNHI1JY%2FHDWebClient_V2.2.2_202601201729.zip?alt=media&token=4be4839d-a2bf-4701-901b-3301e3ff928f>" %}

## 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

<mark style="color:red;">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</mark> [<mark style="color:red;">License Key</mark>](https://udexreal.gitbook.io/udexreal-docs/software-instruction/settings-help-and-about#id-3.-about) <mark style="color:red;">instructions).</mark>

#### 3.1.2. Paxini Dexterous Hands Authorized Version

{% hint style="warning" %}
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. For specific inquiries, please contact UDEXREAL sales.

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

* 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.

{% code lineNumbers="true" %}

```
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
```

{% endcode %}

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. **Ubuntu Version**

{% stepper %}
{% step %}
**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)

{% code overflow="wrap" %}

```
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 
```

{% endcode %}

* 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
```

{% endstep %}

{% step %}
**Operations for Different Ubuntu Versions**

**a. Ubuntu20**

Perform the following operations in any directory.

{% code overflow="wrap" lineNumbers="true" %}

```
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
```

{% endcode %}

**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
```

{% endstep %}

{% step %}
**Server Startup**

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

{% code lineNumbers="true" %}

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

{% endcode %}

* 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
```

{% endstep %}
{% endstepper %}

2. **Windows Version**

For the Windows version of the server, after extraction, it can be placed in any directory. Double-click HDService.exe to run it.

### 3.2. Web Client Deployment and Operation

#### 3.2.1. Ubuntu Environment Setup

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.

{% stepper %}
{% step %}

#### Environment Preparation

* Update the system and install the Nginx:

{% code lineNumbers="true" %}

```
sudo apt update
sudo apt install -y nginx
```

{% endcode %}

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

<figure><img src="https://2082502898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8s1Ia6TfFovgyJ5JsDJZ%2Fuploads%2FinvetWknPWgl50OwvKy0%2Fimage.png?alt=media&#x26;token=a9b36b2e-a33c-4b20-b0e9-4eaea20910d6" alt="" width="350"><figcaption></figcaption></figure>

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

{% code overflow="wrap" %}

```json
{
  "serverUrl": "ws://192.168.5.215:7789" //This IP address is the server address. Port 7789 must not be changed.
}
```

{% endcode %}

* If using UFW or other firewalls, open the port 80 (or 443): `sudo ufw allow 'Nginx Full'`
  {% endstep %}

{% step %}

#### 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 (<mark style="color:red;">Please pay special attention to ensuring that the configurations for</mark> <mark style="color:red;"></mark>*<mark style="color:red;">listen</mark>*<mark style="color:red;">,</mark> <mark style="color:red;"></mark>*<mark style="color:red;">server\_name</mark>*<mark style="color:red;">, and</mark> <mark style="color:red;"></mark>*<mark style="color:red;">root</mark>* <mark style="color:red;"></mark><mark style="color:red;">in the configuration file are correctly set</mark>):

<pre class="language-nginx"><code class="lang-nginx">server {
<strong>    listen 8088; # This listening port can be set according to your actual situation.
</strong><strong>    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.
</strong>
<strong>    root /var/www/handdriver; # Actual Web client deployment directory.
</strong>    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;
}
</code></pre>

2. 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`

3. Enable the site and verify the configuration

```
sudo nginx -t
```

4. Apply the new configuration

```
sudo systemctl reload nginx
```

{% endstep %}

{% step %}

#### 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.
{% endstep %}

{% step %}

#### 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/`**](http://192.168.5.215:8080/) **(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.
  {% endstep %}
  {% endstepper %}

#### 3.2.2. Windows Environment Setup

Please refer to the [Windows IIS local deployment guide for HandDriver WebClient](https://udexreal.gitbook.io/udexreal-docs/software-instruction/windows-iis-local-deployment-guide-for-handdriver-webclient).&#x20;

## 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.
