机械手臂控制与调试工具

适用版本： v1.1.2
发布日期： 2026 年 8 月 3 日

版本	适配环境	入口
v2026.08.03	Windows、macOS、Linux	打开 Star Arm 102 网页版上位机

1. 产品说明

这是机械手臂的统一控制与调试入口。当前网页版上位机提供 Star Arm 102 的数字孪生与操作功能，包括：

Star Arm 102-LD / HD Leader 与 Star Arm 102-FL Follower 串口连接。
Leader 到真实或虚拟 Follower 的实时遥操作。
J1–J7 实时角度与三维姿态显示。
HD 和 FL 的关节目标控制与世界坐标目标控制。
真实 Star Arm 102-FL 手动轨迹录制、虚拟预演和实机回放。
重设零点、恢复出厂参数和新舵机配置。
中文、英文界面切换。

页面提示「指令已发送」只代表命令已经写入串口，不代表机械臂已经精准到位。实机方向、零位、平滑度和精度必须单独验收。

2. 使用准备

2.1 推荐环境

使用最新版 Google Chrome 或 Microsoft Edge。
机械臂控制板通过 USB 串口连接电脑。
确认浏览器已获得串口访问权限。
关闭其他可能占用机械臂串口的软件。

2.2 安全检查

操作真实机械臂前，必须完成以下检查：

将机械臂放在稳固、宽敞的工作台上。
移除机械臂运动范围内的人员和障碍物。
确保可以随时点击页面的「紧急停止」，并可以立即切断机械臂电源。
第一次执行目标姿态或轨迹时，使用较慢速度和较小运动范围。
执行卸力、重设零点或恢复出厂参数时，用手扶稳机械臂，防止关节突然下落。
串口写入、参数恢复或舵机配置过程中，不要拔出 USB 线或关闭网页。

浏览器或 USB 驱动永久无响应时，页面可能无法撤回已经提交的串口写入。此时应直接切断机械臂电源。

3. 界面总览

顶部功能区包括 5 个页面：

页面	用途	适用设备
实时控制	串口连接、遥操作、三维姿态、关节及世界坐标控制	LD、HD、FL、虚拟 FL
轨迹记录	手动录制、导入导出、虚拟预演、实机回放	仅真实 Star Arm 102-FL
重设零点	将当前姿态设置为 ID 0–6 舵机零点	Leader 或 Follower
恢复出厂参数	恢复指定型号的舵机参数	FL、HD、Violin U25、U45
舵机配置	配置单颗新舵机的 ID 和波特率	单颗新舵机

4. 实时控制

4.1 设备角色与权限

型号或模式	角色	主要能力
Star Arm 102-LD	Leader	无动力，只采集姿态，不执行关节或世界坐标目标
Star Arm 102-HD	Leader	采集姿态，可执行关节或世界坐标目标
Star Arm 102-FL	Follower	接收遥操作，可执行关节或世界坐标目标
虚拟 FL	浏览器三维模型	跟随 Leader 姿态，不连接或写入 Follower 串口
reBot Arm B601 / 星海图 A1Z	虚拟模型	仅跟随 J1–J6，不发送硬件命令

4.2 连接真实 Leader 与 Follower

打开「实时控制」。
在「Leader 类型」中选择 Star Arm 102-LD 或 Star Arm 102-HD。
在「Follower 类型」中选择「真实 FL」。
点击「连接 Leader」，在浏览器串口窗口中选择 Leader 对应端口。
点击「连接 Follower」，选择真实 FL 对应端口。
确认 Leader 和 Follower 状态均显示「已连接」。
检查三维模型和 J1–J7 实时值是否随实机姿态变化。

连接时务必确认端口归属。不要将同一个串口同时选作 Leader 和 Follower。

4.3 连接虚拟 Follower

虚拟模式用于验证 Leader 采集、映射和三维跟随，不控制真实 Follower。

选择 Leader 类型并连接 Leader。
将「Follower 类型」切换为「虚拟 FL」。
在「虚拟 Follower 型号」中选择目标模型。
确认页面显示「仅驱动三维模型，不发送 Follower 串口指令」。
点击「启动遥操作」。

虚拟模式不需要选择 Follower 串口。停止后，虚拟模型保持最后姿态。

4.4 遥操作参数

参数	范围	默认值	说明
控制循环间隔	0–100 ms	20 ms	`0` 表示浏览器与串口允许的最快非阻塞循环
滤波窗口	0–100	30	`0` 表示关闭滤波，直接使用最新有效角度
Leader 响应超时	100–2000 ms	800 ms	等待 Leader 串口响应的最长时间
原始串口日志	开/关	关	排查串口通信时使用

控制循环间隔和滤波窗口在运行中锁定。需要修改时，先停止遥操作。

4.5 启动与停止遥操作

确认所需设备已经连接。
设置控制循环间隔和滤波窗口。
点击「启动遥操作」。
缓慢移动 Leader，观察真实 Follower 或虚拟模型是否正确跟随。
点击「停止」结束遥操作。
完成后点击「全部断开」。

出现异常运动、方向错误或障碍物风险时，立即点击「紧急停止」；必要时直接切断电源。

5. 关节目标控制

关节目标控制仅适用于有动力的 HD 或 FL。LD 只显示实时值，不允许目标执行。

连接可控的 HD 或 FL，并在「姿态来源」中选择对应设备。
点击「进入滑块控制」。
拖动 J1–J7 滑块，或在角度输入框中输入目标值。
检查青色目标预览和页面显示的目标关节角。
设置「执行时长」，默认值为 800 ms。
确认机械臂周围安全后，点击「确认执行关节目标」。
执行结束后，根据需要继续预览，或点击「退出滑块控制」。

拖动滑块或输入角度只生成预览，不会立即驱动机械臂。只有点击确认执行后，页面才发送运动命令。J7 对应夹爪。

6. 世界坐标控制

世界坐标控制通过末端 TCP 的 X、Y、Z 位置生成目标姿态，同样遵循「先预览、再确认」的安全流程。

连接可控的 HD 或 FL。
切换到「世界坐标」。
使用以下任一方式设置目标：
输入 TCP X、Y、Z，单位为 mm，然后点击「计算并预览」。
拖动红色 X、绿色 Y、蓝色 Z 箭头进行单轴移动。
拖动 XY、YZ、XZ 半透明平面进行双轴移动。
拖动中心方块沿屏幕平面移动。
按住 Shift 拖动时，以 1 mm 为步进。
检查青色目标预览、目标 TCP、关节角和校准状态。
设置执行时长，并点击确认执行。
点击「退出世界坐标控制」返回关节控制。

如果目标不可达、计算失败或校准状态异常，请取消预览并缩小移动范围。切换控制方式会自动取消尚未确认的预览。

7. 真实 FL 手动轨迹

轨迹页只支持真实 Star Arm 102-FL。轨迹录制源是卸力后真实 FL 的 J1–J7 有效串口回读，不使用 Leader、虚拟设备或青色预览数据。

7.1 连接与录制

打开「轨迹记录」。
点击「连接真实 FL」，选择 FL 对应串口。
连接后页面会卸力并持续回读 J1–J7。用手扶稳机械臂。
输入轨迹名称，最长 40 个字符。
点击「开始录制」。
平稳地手动拖动已卸力的 FL 完成动作。
点击「停止录制」。
确认页面显示帧数、时长和「轨迹已保存」。

当前轨迹会自动保存到当前浏览器。单次录制上限为 10 分钟或 30,000 帧；默认最小采样间隔为 20 ms，关节变化阈值为 0.1°。

7.2 导出和导入

点击「导出 JSON」可将当前轨迹保存为 JSON 文件。
点击「导入 JSON」可选择已有轨迹文件。
文件只有通过设备身份、时间、帧数、关节数量、数值和限位校验后才会导入。
无效文件不会覆盖当前轨迹。

重要轨迹完成后应立即导出备份。浏览器数据被清理、更换浏览器或使用隐私模式时，本地保存的轨迹可能丢失。

7.3 安全步骤 1：虚拟试播放

保持同一真实 FL 连接，选择当前轨迹。
点击「开始虚拟试播放」。
观察青色虚拟 FL 的完整动作。虚拟预演不会发送串口运动指令。
确认动作无误后，点击「结束并确认无误」。

仅点击「停止预演」或等待预演自然播放到末尾，不会解锁实机回放。必须明确点击「结束并确认无误」。

录制新轨迹、导入其他轨迹、断开连接、急停或切换页面都会撤销已有预演确认，需要重新预演。

7.4 安全步骤 2：实机回放

完成并确认虚拟试播放。
确保机械臂周围无人和障碍物，并准备随时急停或断电。
点击「实机播放」。
在确认窗口中核对执行设备、轨迹名称、帧数和时长。
点击「确认重播真实 FL」。
机械臂先用 2000 ms 平滑进入首帧，再按原始时间执行轨迹。
回放期间每 20 ms 刷新一次插值目标，每条命令使用 100 ms 重叠运动窗口。
需要中止时，点击「停止实机播放」；紧急情况点击「紧急停止」。

正常播放完成或手动停止后，机械臂会保持当前位置和力矩，不会自动卸力。页面出现「保持力矩 · 请点击『卸力』」后：

用手扶稳机械臂。
确认卸力不会导致碰撞或跌落。
点击「卸力」。
等待页面恢复实时回读状态。

急停会取消尚未发送的目标，并尝试对当前真实 FL 执行安全卸力。

8. 重设零点

「重设零点」会将当前连接机械臂 ID 0–6 舵机的当前位置设置为零点，不区分 Leader 或 Follower。

打开「重设零点」。
点击「选择手臂串口」，连接需要设置的机械臂。
用手扶稳机械臂，将所有关节摆到目标零位。
点击「重设零点」。
在安全确认窗口中再次检查姿态，然后确认执行。
设置和自动校验期间不要移动机械臂。
查看结果卡片和日志；失败信息会指出具体舵机 ID。

操作完成后机械臂保持卸力状态，不会自动恢复锁力。请继续扶稳，再根据使用场景重新连接或控制。

9. 恢复出厂参数

此工具恢复舵机参数，但不会设置或改变机械臂零点。

支持型号：

Star Arm 102-FL
Star Arm 102-HD
Violin U25
Violin U45

操作步骤：

打开「恢复出厂参数」。
先选择正确的手臂型号。
点击「选择手臂串口」，连接对应机械臂。
连接后型号会锁定。如需更改型号，必须先断开串口。
用手扶稳机械臂，点击「恢复出厂参数」。
在确认窗口中核对型号，然后确认执行。
等待右侧 4 步进度全部完成：机械臂卸力、写入公开参数、写入内部参数、自动校验。
查看详细日志。设置或校验失败时，记录页面报告的舵机 ID。
成功后，按照提示关闭机械臂电源，再重新上电后使用。

恢复过程中不要移动机械臂、断开 USB 或关闭页面。

10. 新舵机配置

此功能只用于尚未安装到机械臂上的单颗新舵机。

严禁连接整台机械臂执行此操作，否则可能出现舵机 ID 冲突和错误写入。

将单颗新舵机独立连接到串口转接设备。
打开「舵机配置」。
输入目标舵机 ID，范围为 0–6，对应机械臂 J1–J7。
勾选「我确认当前只连接了这一颗新舵机」。
点击「连接舵机」。工具使用 115200 bps 连接新舵机。
点击「写入配置」。
在确认窗口中核对目标 ID 和 1 Mbps 波特率，然后确认写入。
等待进度达到 100%，并检查日志显示配置成功。
断开舵机电源和串口，再将舵机安装到机械臂。
安装后根据需要使用「重设零点」和「恢复出厂参数」。

11. 三维视图操作

鼠标左键拖动：旋转视角。
鼠标滚轮：缩放视角。
「默认视角」：恢复预设观察角度。
「适应模型」：使模型自动适配当前窗口。
「全屏」：全屏显示三维场景。
白色模型：真实设备回读姿态。
青色模型：尚未执行的目标预览或虚拟轨迹预演。

三维模型只用于观察和预览，不能替代实机空间、碰撞和精度检查。

12. 常见问题

12.1 浏览器没有弹出串口选择窗口

确认使用 Chrome 或 Edge。
确认浏览器已获得串口访问权限。
检查 USB 线、串口转接板和机械臂电源。
关闭其他占用同一串口的软件后重试。

12.2 串口连接失败或频繁超时

确认选择了正确设备端口。
检查 USB 连接是否稳定。
适当增大「Leader 响应超时」。
停止其他串口程序，重新拔插设备后再连接。
打开「原始串口日志」并记录错误信息。

12.3 三维模型没有跟随实机

确认设备状态为「已连接」。
检查「姿态来源」是否选择正确。
确认遥操作已经启动，或轨迹页实时回读频率不为 0.0 Hz。
点击「适应模型」重新定位视角。
查看运行日志是否存在缺失舵机 ID 或角度越界错误。

12.4 无法进入滑块或世界坐标控制

LD 是无动力 Leader，只允许姿态采集。
请连接 HD 或 FL，并选择对应姿态来源。
先停止正在运行的遥操作、轨迹播放或其他占用控制通道的操作。

12.5 实机播放按钮仍被锁定

确认真实 FL 仍保持同一串口连接。
重新开始虚拟试播放。
必须点击「结束并确认无误」，仅停止或自然播完不算确认。
轨迹发生变化后，需要重新完成预演确认。

12.6 回放结束后机械臂仍然锁力

这是正常安全行为。正常完成或手动停止后，机械臂保持当前位置和力矩。扶稳机械臂并确认安全后，点击「卸力」。

12.7 参数设置或校验失败

记录页面显示的具体舵机 ID 和错误内容。
检查对应舵机供电、接线和通信。
不要连续重复写入；先排除连接和型号选择问题。
恢复出厂参数时，再次确认所选型号与实机一致。

13. 轨迹数据说明

轨迹 JSON 的固定身份如下：

schemaVersion: 1
robotModel: "FL"
source: "manual_fl"
frames[].t：相对录制时间，单位为 ms。
frames[].jointsRad：J1–J7 模型逻辑角，单位为弧度。

不要手工修改轨迹 JSON 后直接用于实机回放。导入校验可以排除格式和限位错误，但不能证明轨迹在真实环境中无碰撞。

14. 结束操作

停止遥操作或轨迹播放。
如果页面显示保持力矩，扶稳机械臂并点击「卸力」。
点击「全部断开」或当前页面的「断开」。
关闭机械臂电源。
整理 USB 线和机械臂，避免关节承受外力。