HandDriver Web软件部署使用指南

1. 概述

1.1. 功能综述

1. 本HandDriver Web软件采用B/S架构，支持在PC环境中通过浏览器访问图形界面，可在手套正常连接后关闭浏览器界面，适用于机器人领域（界面语言目前仅支持英文版）。

2. 使用时，接收器连接在服务器端所在PC，手套与接收器之间不宜过远，控制在2-3米范围内，最远大约为5米。

3. 仅支持一对二接收器手套。

4. 相较于独立的HandDriver软件，对以下功能进行了减除：

   • FBX/BVH录制功能及其相关配置项；

   • 拇指根关节调节；

   • 固件升级（若要进行固件升级，建议下载Windows版本，注意务必先升级手套，再升级接收器）。

1.2. 系统环境要求

• 推荐使用谷歌浏览器。

• 目前仅支持在Ubuntu中使用，请特别注意软件不同版本对Ubuntu版本的要求。

2. 软件安装包下载

服务器端安装包：

• Ubuntu22及以上：

2MB

HDService-Regular_V2.2.0_202512161624_Ubuntu22+_arm_64.zip

archive

Open

2MB

HDService-Regular_V2.2.0_202512161624_Ubuntu22+_x86_64.zip

archive

Open

• Ubuntu20：

2MB

HDService-Regular_V2.2.0_202512161624_Ubuntu20_x86_64.zip

archive

Open

Web客户端安装包（x86/arm均支持）：

65MB

HDWebClient_V2.2.0_202512161624.zip

archive

Open

3. 软件环境部署和运行

建议先部署服务器端并启动，再部署Web客户端并运行。

3.1. 服务器端部署和启动

3.1.1. 重要说明

服务器端部署时，运行本文“普通版”的操作，但如果使用与灵巧手有关的授权版本，务必先查看相关灵巧手版本的操作说明（授权码使用说明）。

3.1.2. 帕西尼灵巧手授权版

帕西尼授权版仅支持在Ubuntu 22中运行。帕西尼授权版须经宇叠提供授权码和对应软件包方可使用。

若使用支持帕西尼灵巧手的版本，需要先执行以下步骤，否则可忽略本小节，直接进入“普通版”章节执行相关操作。

• 将服务器端安装包HDService.zip保存于系统某个目录下（任意目录均可），对其进行解压缩，然后进入HDService目录，打开终端依次输入以下命令

sudo dpkg -i DexHandSDK-1.2.1-Linux.deb
sudo tar -xzf gsl.tar.gz
# 进入gsl目录
cd gsl
sudo ./configure CFLAGS="-g -O0"
sudo make -j4
sudo make install
# 回到HDService目录
cd ..
sudo tar -xzf eigen-3.3.7.tar.gz
# 进入eigen-3.3.7目录
cd eigen-3.3.7
sudo mkdir build
# 进入build目录
cd build
sudo cmake ..
sudo make install

至此，支持帕西尼灵巧手所需操作完成，请继续参阅“普通版”部署说明。

3.1.3. 普通版（即Regular非灵巧手授权版本）部署与启动

1

安装依赖项

将服务器端安装包HDService.zip保存于系统某个目录下（任意目录均可），对其进行解压缩，然后进入HDService目录，打开终端依次执行以下步骤（如果之前执行了其他灵巧手相关的操作，请退回到HDService目录下依次执行以下步骤）：

• 安装依赖项（如无法一次性进行安装，也可逐个安装）

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 

• 若中途报错则执行以下命令，然后再次执行上面的依赖项安装，如此反复循环，直到安装完上述所有依赖项

sudo apt --fix-broken install

2

针对Ubuntu不同版本的操作

Ubuntu20

在任意目录下执行以下操作。

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
# 进入protobuf-3.12.4目录
cd protobuf-3.12.4
./configure
make -j$(nproc)
sudo make install
sudo ldconfig

Ubuntu22

暂无其他特别操作，直接执行下文第三步。

Ubuntu24

在HDService目录下执行以下操作。

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

3

服务启动

• 进入HDService目录，打开终端依次执行以下步骤：

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

• 更新本地依赖库

sudo ldconfig

• 最后在HDService目录中执行以下命令，完成服务器端的部署和服务启动

./HDService

3.2. Web客户端部署和运行

Web客户端部署即Unity WebGL + Nginx（Ubuntu）部署。Web客户端建议和服务器端放在同一台电脑上，这样只需要部署一遍。

3.2.1. 环境准备

• 更新系统并安装Nginx：

sudo apt update
sudo apt install -y nginx

• 创建“Web客户端部署目录”，例如/var/www/handdriver，并复制HDWebClient.zip解压后的所有文件到该目录。

• 确保server-config.json内容正确，例如：

{
  "serverUrl": "ws://192.168.5.215:7789" //该ip为服务器端所在的地址
}

• 如使用UFW或其他防火墙，开放80（或 443）端口：sudo ufw allow 'Nginx Full'。

3.2.2. Nginx配置

1. 新建站点配置：使用命令sudo vim /etc/nginx/conf.d/handdriver.conf (没有vim的话可以使用nano来进行写入)创建配置文件，并将以下内容写入该文件：

server {
    listen 8080; # 为监听端口，可根据自身实际情况设定该端口号
    server_name 192.168.5.215; # 为服务器端所在实际IP或域名，同Web客户端所在地址

    root /var/www/handdriver; # 为实际Web客户端部署目录
    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. 修改nginx.conf文件

sudo vim /etc/nginx/nginx.conf (没有vim的话可以使用nano来进行写入)将第一行 user www:data 修改为 user root

1. 启用站点并检测配置：

sudo nginx -t

3.2.3. 权限与部署

• 更新版本时，只需替换“Web客户端部署目录”（例如/var/www/handdriver）下的文件并再次执行sudo systemctl reload nginx即可。

3.2.4. 验证和运行

• （本步骤非必须）通过 curl http://192.168.5.215:8080/server-config.json（替换为实际ip或域名和端口）检查JSON是否可访问、响应头是否符合预期。

• 打开浏览器访问 http://192.168.5.215:8080/（替换为实际ip或域名和端口）确认WebGL页面可加载，即可开始运行HandDriver Web软件。

• 若需要 HTTPS，可自行按需配置证书（如使用 Let's Encrypt）并将监听端口listen 8080替换为相应的listen 443 ssl设置

4. 注意事项

1. 连接同一个服务器端的不同Web客户端，在其中一个客户端的操作（如动作标定、数据发送设置等）会同步给所有其他客户端。

2. 数据发送：每个角色生成的数据作为独立的包，分开向外发送。

3. 服务器端崩溃时，之前正在连接的手套指示灯显示绿灯常亮，需要重启服务器端后再次连接手套。

4. 数据发送功能中“旧插件”选项目前勾选时功能无效。