使用手册

1 使用前须知

1.1 阅读说明

首次使用前，请完整阅读本手册。出现故障时，请先按照本手册进行排查；如未找到对应的解决方法，请联系相关工作人员处理。

1.2 产品用途

LinkerBot 上位机用于连接和管理灵巧手，并提供关节控制、状态读取、手势、手势舞和视觉互动功能。电脑或树莓派负责连接 CAN 适配器；手机和其他电脑可连接该主机上的控制服务。

1.3 通信、连接与通电

连接设备前，请确认 CAN 连接线、适配器、驱动和接口定义均与当前型号匹配，不得混用不兼容的连接线或适配器。不同型号的通电方式和启动动作可能不同，通电时请确保夹持区域内无障碍物。

设备无法检测或运行异常时，请先重启上位机或重新上电灵巧手；问题仍然存在时，更换匹配的 CAN 连接线，再按照故障排查处理。

2 安装与启动

2.1 安装包

从版本下载页选择与操作系统和 CPU 架构一致的安装包。保留随包动态库；.h 和 .lib 是开发文件，运行时无需安装。

2.2 Windows

1. 完整解压 ZIP 文件，保留主程序和随包 DLL 的目录结构。
2. 双击 linker-dashboard.exe。
3. 保持程序窗口运行，在浏览器打开 http://127.0.0.1:7081。
4. 需要从其他设备访问时，在防火墙提示中允许专用网络访问。

2.3 Linux 和树莓派

推荐一条命令安装。 在运行 64 位 Raspberry Pi OS、Debian 或 Ubuntu 的树莓派终端执行；无屏设备可先通过 SSH 登录，再执行相同命令：

首次部署先准备网络、SSH 和蓝牙依赖，按树莓派云端连接教程操作。电脑网线直连树莓派时，需要由联网电脑提供地址、DNS 和互联网共享；能 SSH 不代表树莓派能下载软件。

curl -fL https://doc.linkerhub.work/linker-dashboard/install.sh -o install-linker-dashboard.sh && bash install-linker-dashboard.sh

需要联网和本机 sudo 权限，无需源码仓库账号、Go 或 Node.js。脚本自动识别 ARM64 / x64，下载当前稳定版、校验 SHA-256、补齐 iproute2 / udev 并设置开机启动。32 位系统请先更换为 64 位系统。缺少 curl 时先执行 sudo apt-get update && sudo apt-get install -y curl ca-certificates。

脚本下载完成后也可先查看内容，再运行 bash install-linker-dashboard.sh --check 仅验证下载和安装包，不安装、不需要 sudo。指定版本使用 bash install-linker-dashboard.sh --version v26.9.3，旧包缺少必需文件时会停止并报错。

安装成功后，本机浏览器打开 http://127.0.0.1:7081；手机或其他电脑打开 http://主机IP:7081。 部署及局域网使用无需云账号；云端注册需要管理员提供邀请码，普通账号即可生成设备接入码。

升级前先停止手势舞和跟随，再次运行安装命令即可。脚本停止已有标准服务，备份并保留 /var/lib/linker-dashboard 数据和 /etc/linker-dashboard.env 云配置。首次安装使用公司云地址；已有云配置不会被改写。自定义服务文件、端口、数据路径或 systemd 附加配置应手动升级，脚本遇到这些配置会停止。

备份位于 /var/backups/linker-dashboard/install-*，仅 root 可读；安装或启动检查失败时自动尝试恢复原程序、配置和数据。确认升级正常后可自行清理旧备份。安装依赖和防火墙端口设置不随回退撤销。原先手动运行程序的 ./data 不会自动迁移，已有手动部署请按原方式升级或先安排数据迁移。

查看服务和日志：

sudo systemctl status linker-dashboard --no-pager
sudo journalctl -u linker-dashboard -n 100 --no-pager

需要蓝牙配网时另行准备 BlueZ 和 NetworkManager，并确认蓝牙可用、Wi-Fi 已由 NetworkManager 管理；安装脚本不自动接管现有网络配置。详见蓝牙依赖检查。

手动启动： 完整解压安装包，在解压目录执行：

chmod +x linker-dashboard
sudo ./linker-dashboard

保持程序运行，本机或局域网使用上面的访问地址。

2.4 Android

打开 App 后选择局域网控制服务，扫描附近主机或输入 http://主机IP:7081。Android App 是操作端，电脑或树莓派仍需连接 CAN 适配器并运行控制服务。

3 控制台通用区域

4 总体控制

点击顶部导航栏中的“总体控制”。该页面用于选择设备、执行预设手势，以及控制多型号设备执行手势舞。

4.1 连接和选择设备

1. 展开“设备管理”，查看型号、接口、左右手和在线状态。
2. 勾选需要控制的设备。“全选”选中全部在线设备，“清空”取消全部选择。
3. 未识别到灵巧手时，点击“重新扫描”；已识别但未连接时，点击“重新连接”。重新扫描或重新连接会停止正在执行的控制任务。
4. 识别信息与实物不一致时，修改型号或左右手并保存；点击“恢复自动识别”可撤销手动设置。

4.2 执行手势

1. 在“通用手势”中点击手势按钮，所有已勾选且支持该手势的设备执行对应动作。
2. 需要执行某一型号的专属手势时，展开“型号专属手势”，再点击相应按钮。
3. 点击“刷新”重新载入手势列表。

4.3 同时执行手势舞

步骤 1： 选择“同时”。开始后，各型号设备同时执行当前手势舞的动作序列。

步骤 2： 设置全局间隔，即相邻两个动作之间的等待时间，范围为 50～2000 ms。

步骤 3： 需要单独调整某一型号时，拖动该型号后方的滑块；未单独设置的型号使用全局间隔。

步骤 4： 设置循环次数和轮间隔。循环次数是整套动作重复执行的次数，0 表示持续循环；轮间隔是一轮结束到下一轮开始之间的等待时间。

步骤 5： 点击手势舞按钮开始执行。

步骤 6： 点击“停止”结束当前手势舞；点击“刷新”重新载入列表。

步骤 7： 点击“重置默认”恢复本区域的默认参数。

4.4 滚动执行手势舞

步骤 1： 选择“滚动”。各型号按页面显示的顺序逐组执行，同一型号的多台设备同时执行。

步骤 2： 设置组间隔，即上一型号完成后到下一型号开始前的等待时间。

步骤 3： 使用型号两侧的箭头调整执行顺序；“默认顺序”恢复原排列。页面将这个排列称为“型号顺序”。

步骤 4： 设置动作间隔、循环次数和轮间隔，然后点击手势舞按钮开始执行。其余按钮与同时执行相同。

5 型号控制

点击顶部导航栏中的“型号控制”。该页面用于控制某一型号的关节、制作动作，以及读取设备数据。

5.1 选择型号和设备

步骤 1： 点击型号名称，打开该型号的控制界面。

步骤 2： 勾选需要接收指令的设备接口。“全选”和“清空”用于批量选择。

5.2 直接控制关节

步骤 1： 选择要设置的参数。

• 位置： 设置各关节要移动到的位置。
• 速度： 设置各关节执行位置动作时的速度，不会直接使关节运动。
• 力矩： 设置各关节可输出力量的上限，不会直接使关节运动。仅支持力矩设置的型号显示此项。
• 全局速度： 把所有关节的速度设为同一数值。
• 全局力矩： 把所有关节的力量上限设为同一数值。
• 读取位置： 读取主目标设备的当前位置，并更新位置滑块。

步骤 2： 操作关节控制区。

• 关节滑块： 拖动或输入数值后立即发送；速度和力矩可分别设置到每个关节。
• 下发： 将当前页面显示的全部关节数值再次发送到已勾选设备。
• 保存为单步手势： 只保存当前关节位置。保存后可在手势区域重复执行，不保存速度和力矩。

L30 页面还显示“使能”和“失能”。“使能”允许运动输出，“失能”关闭运动输出；进行关节控制时，上位机会按需自动使能。

5.3 制作手势或手势舞

“暂存序列”是保存前的动作草稿。每次点击“添加当前姿势”，当前关节位置就会成为一个动作步骤；多个步骤按照 #1、#2 的顺序执行。只有点击“保存为手势”或“保存为手势舞”后，这组动作才会进入动作库。

步骤 1： 调整关节位置后，点击“添加当前姿势”。重复操作，将需要的动作依次加入暂存序列。

步骤 2： 选择手势舞每轮结束后的动作：“执行防撞手势”执行预设结束动作；“保持最后姿势”停在最后一步。

步骤 3： 检查和调整每个动作步骤。

• holdMs（手势）： 保存为手势后，该步骤保持多久。
• durationMs（手势舞）： 保存为手势舞后，该步骤持续多久；填写 0 时使用执行页面设置的动作间隔。
• 执行： 单独运行该步骤，检查实际效果。
• 编辑： 将该步骤的位置载入关节滑块。调整完成后，点击该行出现的“回填”更新步骤。
• 删除： 从暂存序列中移除该步骤。

步骤 4： 点击“保存为手势”，将序列加入手势区域；点击“保存为手势舞”，将序列加入手势舞区域。“清空”删除全部暂存步骤。

编辑 O30i 时，可以选择“通用”“左手”或“右手”序列。执行时优先使用与设备左右手一致的序列；没有对应序列时使用通用序列。

5.4 执行型号专属动作

步骤 1： 点击手势按钮，当前型号中已勾选的设备执行该动作。

步骤 2： 设置相邻动作的间隔和整套动作的循环次数，再点击手势舞按钮。循环次数为 0 时持续循环；点击“停止”结束当前手势舞。

两个区域中的“刷新”分别重新载入对应的手势或手势舞列表。

5.5 读取设备数据

协议功能码

“状态查询”用于读取速度、位置、电流、温度等设备状态。选择状态类型后点击“读取”，结果按关节显示；下方原始帧用于查看本次通信的发送和返回数据。

“参数维护”用于修改当前型号开放的设备参数。先选择功能码，再按照页面说明填写子命令和参数，最后点击“确认并发送”。以 CAN ID 为例：子命令 1 同时设置接收和发送 ID，2 设置接收 ID，3 设置发送 ID；保存后需要重启设备才能生效。可用功能码和子命令以当前型号的页面说明为准。

触觉感知

点击“读取全部”，读取五个手指的触觉数据。每个方格对应一个触觉点，颜色变化表示该位置检测到的触觉强度，“峰值”显示该手指当前的最大值。

设备信息

点击“读取”，查看型号、软件版本、左右手、机械版本、产品编号、硬件版本和通信协议。

页面显示“无数据”时，表示设备未返回对应内容或当前型号不支持该项。

6 游戏中心

点击顶部导航栏中的“游戏中心”。先在页面上方的设备管理中勾选参与互动的设备，再选择互动模式。

6.1 2D 手势跟随

步骤 1： 打开“2D 手势跟随”。

步骤 2： 选择摄像头。需要调整时，展开默认收起的“视觉处理参数”，设置处理分辨率和处理频率，然后点击“启动跟随”。收起参数不会重置已保存的设置。处理分辨率决定参与识别的画面尺寸；处理频率决定每秒识别次数。数值越高，对主机性能的要求越高。

处理频率是识别目标，实际新画面的更新速度还受摄像头帧率和推理耗时限制。例如摄像头协商为 30 FPS 时，设置 60 Hz 不会让摄像头输出 60 张新画面。性能信息默认折叠，展开后可查看实际处理 FPS、处理分辨率、摄像头参数、单帧处理耗时和“取帧→结果”平均耗时；摄像头画面不再叠加实际处理 FPS 和处理分辨率。2D 跟随和剪刀石头布默认使用 CPU + Lite 组合，优先响应速度；可独立切换 CPU/GPU 与 Lite/Full，在相同模型下比较速度和识别效果。“自动”按浏览器图形环境选择后端，不会自动测速。

推理期间继续观察新视频帧，结束后优先处理最新画面，骨架收到结果即更新，不排队处理旧画面。但模型计算本身仍需要时间，实时视频和骨架仍可能存在差距。“取帧→结果”不包含摄像头内部缓冲、屏幕刷新和机械手执行时间；v26.9.3 已包含新版调度与模型选项。

步骤 3： 将一只完整的人手置于摄像头画面中，左手或右手都可以。上位机最多识别一只人手，将同一姿态按各型号映射后，同步发送给所有已勾选、在线且支持跟随的设备，不按左右手筛选；右侧显示检测手数、跟随设备数和关节目标。L20Lite 根据目标设备的左右手标识转换拇指旋转和横摆方向，请核对设备手别配置。只想控制某台设备时，请仅勾选该设备。未检测到人手时停止下发，点击“停止跟随”结束运行。

支持 L20、L30 跟随的新版软件会将 21 个手部关键点转换为对应型号的关节目标；每台 L30 跟随过程中保持各自的手腕位置。L30 拇指的侧摆和旋转由拇指根部相对手掌的方向连续估算，不再切换四档对指预设：向虎口收拢时侧摆值增大，向内旋转时旋转值增大。这不等同于精确的横滚测量，幅度和稳定性仍需结合实机检查。v26.9.3 已包含 L20/L30 跟随及上述单手同步方式。2D 跟随为演示功能，各型号仍需实机校准。

L6/O6 跟随中，“拇指弯曲”对应人手拇指侧摆，“拇指旋”对应拇指根部旋转；单独弯曲拇指末节不会直接改变这两路。旋转使用与 L30 相同的根部角度估算，并按 L6/O6 的设备方向转换，幅度仍需实机复测。

6.2 剪刀石头布

步骤 1： 打开“剪刀石头布”。

步骤 2： 选择摄像头，按需展开“视觉处理参数”调整分辨率和频率，然后点击“启动必胜模式”。参数和性能信息均默认折叠；实际处理 FPS 与处理分辨率可在性能信息中查看。

步骤 3： 向摄像头展示剪刀、石头或布。上位机识别后，控制已勾选的设备执行克制动作；右侧显示识别结果、设备动作和实时匹配度。点击“停止必胜模式”结束运行。

“3D 手势跟随”当前显示“即将上线”，暂不可用。首次使用摄像头时，请允许浏览器或 App 访问摄像头。本机浏览器建议使用 http://localhost:7081；局域网普通 HTTP 页面可能受浏览器摄像头权限限制。

7 运行日志

7.1 CAN 实时日志

CAN 实时日志位于页面右侧，用于查看上位机发送和设备返回的 CAN 数据。

型号、CAN 接口： 筛选指定型号或接口的日志。

方向： TX 表示上位机发送，RX 表示设备返回。

仅看 ID： 只显示与输入内容匹配的 CAN ID，多个 ID 使用空格或逗号分隔。

屏蔽 ID： 隐藏与输入内容匹配的 CAN ID。

清空： 删除页面当前显示的日志。

7.2 后端终端输出

后端终端记录软件启动、适配器初始化、网络服务和运行错误。

• 直接运行 linker-dashboard 时，在启动程序的终端中查看。
• 使用 install-service.sh 安装为 Linux 或树莓派系统服务后，执行：

sudo journalctl -u linker-dashboard -n 100 --no-pager

8 连接其他操作端

8.1 手机或局域网电脑

1. 在连接 CAN 适配器的电脑或树莓派上启动上位机。
2. 将操作端与主机连接到同一局域网。
3. 在 Android App 中扫描控制服务，或在浏览器中打开 http://主机IP:7081。

127.0.0.1 只能用于当前主机。局域网设备无法发现或访问主机时，请检查主机 IP、防火墙和网络的设备隔离设置。

8.2 更换控制服务

1. 点击顶部导航栏中的控制服务按钮。

1. 在确认窗口中点击“确定”。

1. 重新选择连接方式。

局域网连接： 点击“仅使用局域网”，扫描附近的控制服务，或输入服务地址。

云端连接： 填写云服务地址并登录，再选择已关联且在线的控制器。

正式云入口为 https://doc.linkerhub.work/linker-dashboard/cloud，详见云端连接说明。v26.9.3 及后续版本的操作端与控制器填写同一完整地址，包括 /linker-dashboard/cloud。历史稳定版 v26.9.2 使用同一服务根路径兼容入口 https://doc.linkerhub.work。

原 IP 网站 https://39.106.139.73/linker-dashboard/ 和 IP 云入口继续可用，已接入控制器可保持原地址。主动更换控制器云地址时，需要新的设备接入码；网站更新不会自动修改已安装程序或已保存的云配置。

8.3 蓝牙和云端

蓝牙用于为无屏 Linux 主机配置 Wi-Fi 和关联云账号，完成配置后的控制通过局域网或云端进行。使用云端时，手机和控制器都需要能访问云服务。

1. 树莓派按安装与启动部署系统服务，并完成 BlueZ / NetworkManager 检查。
2. Android App 填写完整云地址，用管理员提供的邀请码注册并登录；已有账号直接登录。开启蓝牙，按提示授予附近设备权限，旧版系统或读取 Wi-Fi 名称时可能还需定位权限及定位服务。
3. Dashboard 启动后默认开放 15 分钟配网窗口。在 App 选择“通过蓝牙添加”，选择对应的 LH-… 设备。此功能使用 Android App，普通浏览器不提供蓝牙添加。
4. 树莓派已有可长期使用的网络时，无需勾选“同时配置 Wi-Fi”；安装时仅借用电脑网线、之后需要拔线时，勾选该项，填写树莓派可连接的 Wi-Fi。手机可读取网络名称，无法读取已保存的密码。
5. 点击“配置并关联”。App 自动申请设备接入码并发送，依次完成配网和账号关联；无需提前手动生成接入码。返回列表，选择在线控制器。
6. 停止设备动作后，验证拔掉安装网线仍能保持云端在线；再验证树莓派重启后服务、Wi-Fi 和云端自动恢复。以后无需每次重新配对。

配网窗口超时或补装依赖后，先停止动作，再执行 sudo systemctl restart linker-dashboard，然后在 App 重新扫描。重启会中断当前控制连接。

“更换控制服务”只更改操作端连接目标，不会将主机接入云端。不用蓝牙时，由主机启动参数或系统服务环境文件配置接入，见手动接入。首次网络准备、逐步验收和失败处理见完整云端连接教程。

9 备份与升级

自定义手势、手势舞和设备设置保存在主机的数据目录中。升级前停止手势舞、跟随及其他设备动作，再按部署方式处理。

通过公开脚本安装的标准 Linux 系统服务： 重复执行安装命令，脚本停止服务后自动备份程序、配置与数据到 /var/backups/linker-dashboard/install-*，保留原数据和云地址；安装或启动检查失败时尝试恢复。备份仅 root 可读，确认升级正常后可清理旧备份；依赖和防火墙设置不随回退撤销。

手动启动、Windows 或自定义系统服务： 上位机没有备份按钮，按以下步骤升级：

1. 停止上位机程序或系统服务，并复制整个数据目录及原启动配置。
2. 完整解压新版本，确保主程序和随包动态库同时更新。
3. 使用原数据目录和配置启动新版本，再检查设备设置及自定义动作。

手动运行的 ./data 不会由公开安装脚本自动迁移；自定义服务、端口或数据目录应沿用原部署方式升级。

数据目录包含当前控制服务的身份信息，不应作为动作文件复制给其他控制器。

10 故障排查

出现故障时，先重启上位机或重新上电灵巧手。设备仍然异常时，断电并更换匹配的 CAN 连接线，再按下表处理。

仍无法解决？请保留控制台终端中从启动到失败的日志，以及操作系统、程序架构和适配器型号，交给维护人员。