跨维智能产品文档中心

简体中文

English

简体中文

English

外观

软件进阶功能介绍

约 21903 字大约 73 分钟

此章节介绍了W1 Pro机器人的进阶功能，必须由经过跨维智能培训的人员进行操作。

4.1 底盘建图及导航

4.1.1 建图

手柄使用方法请参考 移动控制手柄 。

4.1.1.1 关闭导航服务

在PC1上执行如下指令关闭导航服务

sudo systemctl stop dexe-auto.service dexe-auto.timer dexe-map.service

4.1.1.2 启动建图服务

  • 在远程桌面的 Terminal 中，输入以下命令启动建图服务：
sudo systemctl start dexe-map.service
  • 查看日志输出
cd /home/dexforce/log && tail -f mapping.log

4.1.1.3 设置地图名称，开始建图

# 通过服务调用建图
# 设置地图名称
ros2 service call /mapping_node/set_map_name nav_interfaces/srv/SetMapName "{map_name: map_2_standard}"
# 启动建图服务
ros2 service call /mapping_node/start_mapping std_srvs/srv/Trigger

4.1.1.4 在PC1中使用如下指令打开建图rivz

rviz2 -d /home/dexforce/w1/install/cartographer_ros/share/cartographer_ros/rviz/2d_mapping_indoor.rviz

  • 遥控建图

    • 此时可以遥控手柄控制机器人移动进行建图，建图效果如图。

  • 建图完成，保存地图

# 完成建图服务
ros2 service call /mapping_node/finish_mapping std_srvs/srv/Trigger

4.1.1.5 查看地图保存的结果

  • 将建图目录下的结果，拷贝到本地，查看结果
scp -r dexforce@{机器人IP}:/home/dexforce/.dexe/data/maps/map_2_standard .
  • 查看文件夹，包含如下的地图文件：

  • 评估建图结果

没有重影，没有建图错误，则认为该地图可以用于导航

4.1.1.6 关闭建图服务

sudo systemctl stop dexe-map.service

4.1.2 导航

4.1.2.1 重启导航服务

关闭建图服务，重启导航服务

systemctl stop dexe-map.service && systemctl restart dexe-auto.timer dexe-auto.service

4.1.2.2 开启可视化（PC2）

TF树启动方式，PC2上启动指令如下（若PC2已经开启可视化界面，则表示TF已经启动）

cd /home/dexforce/workspace && source install/setup.bash &&  rviz2 -d dexe_application/tools/visualization/scripts/display.rviz

4.1.2.3 启动导航节点(PC1)

重启导航服务后，导航节点就会启动

在导航时，若准备需要采用之前构建的地图，可以通过map_manager相关服务修改当前使用的地图

  • 查看当前所有地图文件
cd ~/w1 && source install/setup.bash && ros2 service call /map_manager/get_map_list nav_interfaces/srv/GetMapList
  • 修改为要使用的地图：
ros2 service call /map_manager/load_map  nav_interfaces/srv/LoadMap "{map_name: 地图名称}"

4.1.2.4 导航可视化

  • 在PC2的可视化界面左上角中，更改“Fixed Frame”为“map”；同时勾选第一个和第二个“Map”选项，如图所示：

  • 勾选后，可视化界面显示如下：

当前启动会自定位，若激光点云和map中障碍物未重合，系当前机器人未定位成功导致。

  • 遥控定位

此时需开启手柄，控制机器人原地旋转，待点云和障碍物重合，即彩色点云和黑色障碍物重合，表示定位成功，如下图所示：

  • 此时点击Rviz中的2D goal发送目标点，包括位置和姿态，其中箭头表示姿态，如图所示；

导航成功后机器人到达目标点如图所示：

4.1.3 常见异常问题定位及解决方案

  • Rviz可视化界面点击导航后机器人不运动；

    • 查看手柄节点信息是否存在打印，若存在打印，则表示手柄控制机器人节点并未关闭，导致手柄发送零速，和导航速度冲突，解决方案为按手柄start按键，停止手柄控制节点发布速度；

  • 定位长时间不成功，且定位终端输出打印存在IMU内容，如下图，则为IMU信息中断，需要重新启动IMU发布节点；

  • 导航节点启动失败，只输出部分内容，由于上次ROS相关节点并未完全杀死导致，需要完全杀死导航节点，再重新启动导航节点。

  • 建图与导航过程中的常用调试和故障恢复指令

用途命令
查看server状态
ros2 topic echo /feedback/robot_server_state --field data --once
开启拖动ros2 service call /control/set_property robot_server_interfaces/srv/SetProperty "{property_type: 'EnableDrag', value: '1'}"
清错ros2 service call /control/set_property robot_server_interfaces/srv/SetProperty "{property_type: 'ClearError', value: ''}"
查看server日志cat ~/dexe_robot_server_data/logs/robot_server.txt
修改安全等级，1.0为最不敏感，当前默认为0.5ros2 service call /control/set_property robot_server_interfaces/srv/SetProperty "{property_type: 'SafeLevel', value: 0.9}"
查看torque limit是否有变化，可用于确认安全等级是否生效ros2 topic echo /feedback/robot_server_state --field data --once

4.1.4 自动回充

自动回充是指设置一个固定的回充位置，让机器人在电量低时自动返回该位置充电。这种充电方式仅应用于"移动+操作"类的场景，如工业场景、广东数采、京东物流等。

4.1.4.1 前提条件

  • 自动回充之前，需确保机器人建图完成，已生成一张完整的地图，让机器人知道自己身处的地图环境。

  • 自动回充之前，需要开启导航功能，让机器人能够自动导航到充电桩位置。

4.1.4.2 切换为自动模式

自动回充功能仅在自动模式下生效，机器人需处于自动模式才能接收系统任务并实现自动回充。若当前模式为遥操、建图或其他模式，需先切换至自动模式。

  • 临时切换为自动模式（重启后恢复原模式）

在 PC1 的 Terminal 终端执行以下指令：

/home/dexforce/w1/dexe_mobile_application/script/change_mode.sh auto
  • 设置开机自启自动模式（重启后仍保持自动模式）

在 PC1 的 Terminal 终端执行以下指令：

/home/dexforce/w1/dexe_mobile_application/script/change_mode.sh auto start

4.1.4.3 重定位机器人

在设置回充点之前，必须在地图上重定位机器人，确保机器人的定位是准确的，否则后续设置的回充点坐标是错的。

  • 机器人开机后，通过比对当前传感器数据与已有地图，自动完成定位。在Rviz2可视化界面中，如果激光雷达获得的点云与地图轮廓完全重合，表示定位成功。

  • 如果Rviz2可视化界面显示位置错误或漂移，表明当前机器人未自动定位成功，需要手动遥控让机器人移动一小段距离以及原地旋转，直到点云和地图轮廓完全重合。如下图所示，点云与地图中障碍物未重合。

4.1.4.4 设置回充点位置

  • 使用手柄遥控机器人，将机器人移动到充电桩正前方0.7m-1m，如图所示。

设置回充点时，请确保充电桩位置永久固定。如果移动了充电桩，必须重新设置回充点。

  • 打开 PC1 的 Terminal 终端，执行如下命令，得到机器人当前在地图中的位置并将这个位置保存为回充点。
ros2 service call /save_charging_pose std_srvs/srv/Trigger "{}"

请确保机器人完全静止，否则保存的位置坐标可能不准。

  • 执行如下指令，开启auto_charging脚本
python3 auto_charging.py
  • 执行如下命令，启用自动回充功能，记录这个位置为回充点，并开启后台监听，系统会持续监控电池电量。
ros2 service call /auto_charging std_srvs/srv/Trigger "{}"

4.2 遥操使用说明

4.2.1 遥操手柄使用说明

使用Oculus quest 3s，包含一个头戴VR设备和两个手持遥控手柄，左右遥控手柄按键说明如下：

注意：

VR眼镜和手柄是一对一的固定配对关系，无法共用，注意不能混用。

按键按键操作说明
左右摇杆左摇杆向前 / 向后腿部运动模式为摇杆升降时，控制机器人腿部直上直下
左摇杆向左 / 向右底盘差速模式下，控制机器人底盘向左 / 向右自旋转
右摇杆向前 / 向后底盘差速模式下，控制机器人底盘向前 / 向后移动
单次点击左摇杆启动数据录制功能
再次点击左摇杆停止录制数据
单次点击右摇杆删除上段录制数据
再次点击右摇杆删除上段录制数据
X键左手柄单次点击 X 键切换左灵巧手的手势
Y键单次点击Y键

  • 切换腿部动作

    切换腿部动作时需要松开握柄键退出遥操，待单击 Y 键切换完成后，再按住握柄键重新进入遥操。

    • 体感升降：通过遥操控制腿部升高降低，腿部仅沿竖直轴线移动，不改变自身倾斜角度。

    • 摇杆升降：通过左摇杆向前/后 控制腿部升高降低。

      • 左摇杆向前，腿部升高
      • 左摇杆向后，腿部降低

  • 遥操过程中，发生关节电机报警时，单击 Y 键可清除错误，然后通过遥操调整机器人姿态。

A键右手柄单次点击 A 键切换右灵巧手的手势
B键右手柄单次点击 B 键底盘切换驻车模式和差速模式，当前是驻车模式，点一下 B 键→切换成差速模式；再点一下 B 键，可切回驻车模式。
Meta键
短按 Meta 键
  • VR 眼镜开机后，单击 Meta 键，退出当前应用，回到 VR 眼镜主界面；
  • 在全屏 VR 遥操中，单击 Meta 键，显示隐藏的应用栏，可以在浏览器打开 VR 界面；再按一次就隐藏应用栏。
长按 Meta 键VR 桌面视角异常时，长按 Meta 键，复位 VR 视角，VR 桌面恢复至用户正前方（正视角）；
扳机键单击左扳机键控制左灵巧手的抓握
单击右扳机键控制右灵巧手的抓握
握柄键
双手同时按住握柄键左右手同时按住握柄键，进入遥操作
双手松开握柄键任意一只手松开握柄键即退出遥操作；
退出遥操作后，若想再次进入遥操作，建议先长按 Meta 键复位视角，再同时按住握柄键重新进入遥操。
双手按住握柄键 + 移动双臂机器人双臂动作与用户现实动作一致。
若机器人关节异常反转，请用户立即将双臂向两侧展开 → 向异常方向的反方向转动手腕，直至将机器人手臂调正 → 继续遥操
双手按住握柄键 + 做出躯干动作控制机器人躯干关节运动，如下蹲 / 站起、左右转腰
前倾 / 后仰（暂不支持）
组合键长按3s左手点击 X 键 + 右手点击 A 键 长按3秒在头戴式 VR 模式下，未开始遥操且未开启数据录制时，可以返回模式选择界面。

4.2.2 切换遥操模式

出厂默认设置开机自启自动模式，进入遥操模式需要按照如下步骤手动切换遥操模式。

  • 在PC1的Terminal终端上执行以下指令，查看当前模式
systemctl status dexe-tele.service #查看遥操模式状态

若返回结果中包含 active (running)，表示当前是遥操模式。

若返回 inactive (dead)，表示当前不是遥操模式。

若提示 “Unit not found”，可能是指令输入错误。

  • 若当前不是遥操模式，可在PC1的Terminal终端上执行以下指令，临时切换为遥操模式（即重启后恢复原模式）。
cd /home/dexforce/w1/dexe_mobile_application/script
./change_mode.sh tele
  • 若当前不是遥操模式，可在PC1的Terminal终端上执行以下指令，设置开机自启遥操模式（即重启后仍保持遥操模式）。
cd /home/dexforce/w1/dexe_mobile_application/script
./change_mode.sh tele start

4.2.3 VR眼镜连接

  • 当使用USB信号放大器进行长距离有线遥操时，请勿将USB信号放大器与电源适配器放置过近，建议间距≥20cm。

  • 若USB信号放大器紧贴电源适配器，可能导致机器人底盘的对外USB接口（2.0/3.0）通信中断。

  • 如果使用有线方式连接VR眼镜和PC1，可用USB数据线一端连接VR眼镜的接口，一端连接机器人底盘后的PC1下的USB接口。

有线连接VR眼镜时，需注意拖拽底盘的风险

  • 如果使用Wi-Fi方式连接VR眼镜和PC1，VR眼镜开机后，单击 Meta 键进入 VR 桌面，移动手柄，将 VR 桌面中的光标移动到下方的应用栏中，按动扳机键，点击"设置"图标连接相应的Wi-Fi。

  • 使用Wi-Fi连接时，机器人的动作延迟较大，不建议常用。

  • 如果没有底下那栏应用，应短摁右手柄的Meta键。

4.2.4 进入遥操

  • VR 眼镜开机，单击 Meta 键 进入 VR 桌面，可以从VR眼镜中看到 VR 桌面，如果 VR 桌面存在视角不正的情况，可长按 Meta 键，复位 VR 视角，让 VR 桌面处于用户正前方。

  • 左右手自然前伸，双臂位置与机器人双臂保持一致。

手腕过度下探可能导致手柄超出VR眼镜的视觉追踪范围。

  • 移动手柄，将光标移动到应用栏的"浏览器"图标，按动扳机键，点击"浏览器"；

  • 打开浏览器后，移动手柄，在地址栏输入网址打开模式选择界面。

    • VR眼镜有线连接时，输入网址https://localhost:8443/；

    • VR眼镜通过Wi-Fi连接时，输入网址https://192.168.158.XX:8443/（该地址是机器人的外网IP，随接入网络变化而变化，即您的局域网分配给机器人的IP地址，您可在个人电脑上打开终端输入 ifconfig 命令，查看PC1当前的外网IP是多少）。

    • 将网址保存，后续就使用书签（右上角的三个点里面）可以直接找到网址。

  • 进入模式选择界面，共有三种模式：穿戴式 VR 模式、头戴式 VR 模式、人机配准。扳机键点击“进入VR”/“开始配准”即可进入对应的遥操模式。

    • 穿戴式 VR 模式：用户将 VR 眼镜挂在脖子上，通过这种方式进行机器人遥操作。这种佩戴方式会让用户的视线自然向前，底盘处于用户的下方视野盲区，因此挂颈模式适用于无需移动机器人，只需专注机器人上半身动作的场景。

    • 头戴式 VR 模式：用户将 VR 眼镜戴在头上，通过 VR 眼镜的第一视角进行机器人遥操作。这种佩戴方式不存在视野遮挡，用户可以看到底盘状态，因此头戴模式适用于需要机器人自主移动，用户需实时掌控机身整体状态的场景。

    • 人机配准：校准用户与机器人之间的空间关系，确保机器人能复刻用户的肢体动作。首次使用机器人的遥操作功能、切换遥操作用户、动作精度要求较高等情况下，需要进行人机配准。

注意：进入遥操之后不可以长距离走动

4.2.5 穿戴式/头戴式 VR 模式

进入穿戴式 VR 模式 / 头戴式 VR 模式，同时左手点击 X 键 + 右手点击 A 键 长按3秒可返回模式选择界面。

穿戴式 VR 模式

头戴式 VR 模式

信息类别模式/状态含义描述
底盘/腿部模式底盘机器人底盘模式驻车：底盘4个轮子方向成十字交叉，位置被锁定，防止机器人误移动。
差速：轮子解除锁定，可通过摇杆控制移动方向，用于移动机器人。
腿部通过摇杆/遥操控制腿部动作的模式体感升降：通过遥操控制腿部升高降低，腿部仅沿竖直轴线移动，不改变自身倾斜角度，适用于需要调整机器人腿部高度的场景。
锁定高度：机器人腿部关节锁定，保持固定高度。
摇杆升降：通过左摇杆向前/后 控制腿部升高降低。
位姿同步：通过遥操控制腿部上下升降和前后俯仰，腿部自身发生角度倾斜，以此调整机器人整体姿态。
遥操/录制状态遥操机器人本体是否处于遥操控制状态ON：可遥操状态
OFF：不可遥操状态
录制是否正在进行数据采集ON：开启数据录制，同时语音播放"数据采集已开启"。
OFF：结束数据录制，同时语音播放"数据已成功保存"/"数据保存失败"。
网络延迟/帧率网络延迟实时网络延迟 （ms）网络延迟<250ms表示延迟正常；
300ms＞延迟≥250ms表示延迟较高。
延迟≥300ms表示延迟过高，可以通过检查网络信号强度、关闭个人电脑的无关应用、清理机器人本体的后台程序解决。
帧率遥操 VR 桌面每秒刷新的次数，反映 VR 桌面的流畅度数值越高 VR 桌面越流畅，数值过低会出现卡顿、拖影。
左右手左手当前左灵巧手的抓握动作包含 “捏取”“握杯”“握拳” 等预设手势，也支持用户自定义动作
右手当前右灵巧手的抓握动作包含 “捏取”“握杯”“握拳” 等预设手势，也支持用户自定义动作

4.2.6 开始遥操

  • 双手中指同时按住左右手柄的握柄键，按住后不要松开，松开则会退出遥操作。

  • 开始遥操后，VR 界面上遥操状态显示为ON，提示“遥操模式已激活”，遥操激活后用户无法通过长按A+X三秒回到模式选择界面。

手柄操作过程中，若手腕过度下探或手柄脱离 VR 眼镜的视觉追踪范围，可能导致检测不到手柄，从而使遥操状态变为 OFF 并中断数据录制。

  • 单击左摇杆开启数据录制，VR 界面上的数据录制状态显示为ON，弹窗提示“数据采集已开启”。

  • 人的双手、双臂、腿部、腰部动作，机器人也会随之做出相应的动作。单击 B 键可切换底盘模式，单击 Y 键可切换腿部动作，单击 X 键可切换左灵巧手的手势，单击 A 键可切换右灵巧手的手势。

4.2.6.1 底盘模式

  • 底盘模式默认为驻车模式，当需要移动机器人位置时，应当从 “驻车模式” 切换到 “差速模式”，然后用右摇杆控制前后移动、左摇杆控制左右旋转。

  • 当 下蹲 / 站起、前倾 / 俯仰、左右转腰时，需要固定机器人位置，应当切换回 “驻车模式”，避免机器人误移动。

  • 当切换腿部模式时，系统会自动将底盘模式切换为 “驻车模式”，无需手动切换，保证腿部操作时机器人位置稳定。

点击 B 键可切换底盘模式，界面提示“底盘控制模式已切换为：XXXX”。

注意：

当使用穿戴式 VR 模式进入遥操，底盘模式强制切换为 驻车模式，而且不能通过摇杆移动机器人底盘，不响应用户B键切换底盘状态。

4.2.6.2 腿部动作

  • 当机器人需要下蹲/站起时，应当将腿部模式切换到 “体感升降” 或“摇杆升降”，“体感升降”通过人的动作带动机器人站起/下蹲，“摇杆升降”用左摇杆控制腿部站起/下蹲。

若已通过“摇杆升降” 将机器人高度降低，将腿部模式切换为“体感升降”并进入遥操后，机器人将自动恢复至预设的自然高度。请提前确认机器人本体周围无障碍物，避免发生碰撞。

  • 每次切换腿部模式，底盘会自动切换为驻车模式，防止机器人在腿部模式切换时动作失控摔倒。腿部动作完成后，如需移动机器人位置，需要将底盘切换为差速模式。

切换腿部动作时，需要双手中指松开握柄键退出遥操，单击 Y 键切换，切换完成后再按住握柄键重新进入遥操。

点击 Y 键可切换腿部动作，界面提示“腿部动作已切换为：XXXX”，同时语音播报“XXXX（腿部状态名称）”。

4.2.6.3 左右灵巧手控制

控制左右灵巧手的抓握需要双手食指按住扳机键

点击 A 键可切换右灵巧手的手势，界面提示“右手手势已切换为：XX”，同时语音播报“XX（手势名称）”；点击 X 键可切换左灵巧手的手势，界面提示“左手手势已切换为：XX”，同时语音播报“XX（手势名称）”。

所有手势列表如下：

捏取握杯握拳点赞比心摇滚手枪
比六比一敬礼ok

4.2.6.4 清错

遥操过程中可能发生关节电机报警，单击 Y 键可清除错误，然后通过遥操调整机器人姿态。

4.2.6.4.1 自碰撞保护

遥操过程中，机器人手臂动作出现关节自碰撞风险时，会自动触发自碰撞保护，界面提示“关节自碰撞保护，请及时调整手臂动作”，语音播报“自碰撞保护，调整手臂远离身体”。

自碰撞保护触发后，用户本次的动作机器人不会跟随，因此无需用户清错，只需要用户更换一个不会触发碰撞保护的姿态，机器人会缓慢跟随直至重新和人的动作同步。

4.2.6.4.2 关节电机报警

在快速遥操场景下（比如遥操动作幅度过大 / 速度过快），关节电机会出现过载、异常负载等情况，会触发关节电机报警，语音播报“关节电机保护，按Y键清错”。确认机器人周围没有阻碍后，单击 Y 键消错，然后通过遥操调整机器人姿态。

4.2.7 数据录制

  • 数据录制会占用较多系统内存与算力，建议在录制前关闭 VR 桌面上不必要的后台进程，以获得更稳定的录制体验。

  • 一次录制时长不宜过长，如过长可能出现尾部丢帧问题。

4.2.7.1 开启数据录制

  • 单击左摇杆开启数据录制，VR 界面上的数据录制状态显示为ON，弹窗提示“数据采集已开启”，语音播报“数据采集已开启”。

4.2.7.2 结束录制

  • 再按一次左摇杆可结束本次录制，VR 界面上的数据录制状态显示为OFF，弹窗提示“正在储存本次采集数据，请稍等...”，进度条实时反馈保存百分比。

数据录制过程中如果退出了遥操，本次录制数据会自动保存至对应的文件夹。

结束录制后，数据将从内存写入硬盘，此过程需一定时间，请耐心等待保存完成，不要在保存期间进行其他操作，避免中断保存。

4.2.7.3 数据保存

  • VR 界面上弹窗提示“数据已成功保存”/“数据保存失败”，同时语音播报“数据已成功保存”/“数据保存失败”。

  • 保存成功的录制数据存储在/home/dexforce/w1/dexe_teleoperate/data/recorded/20260113_192729（20260113是时间戳）

4.2.7.4 删除录制数据

数据录制过程中不能删除数据，应当退出录制后才能删除

  • 单次点击右摇杆可删除上一段录制的数据，VR 界面上弹窗提示“请确认是否删除数据”，同时语音播报“请确认是否删除数据”。

  • 再次点击右摇杆确认删除录制的数据，VR 界面上显示“正在删除上次采集数据，请稍等...”。删除成功后，VR界面上弹窗提示“遥操数据已删除”，同时语音播报“遥操数据已删除”。如果遥操数据未成功删除，语音播报“数据删除失败”。

4.2.8 人机配准

进入人机配准模式，遥操作手柄的射线指向滑动条的点位，同时左手点击 X 键 + 右手点击 A 键 长按3秒可返回模式选择界面。

  • 设置身高

身高是指头顶最高点到地面的距离，身高默认值为170 cm，用户可进行快速选择，确认选择后系统会记录当前数值，用户下一次进入人机配准界面时，身高默认值变为记录的当前数值。

点击遥操作手柄的 A 键 或 扳机键 选中滑动条的不同点位，选择后 扳机键 点击"确定"按钮。

  • 设置臂长

臂长是指肩峰至中指指尖的距离，臂长默认值为70 cm，用户可进行快速选择，确认选择后系统会记录当前数值，用户下一次进入人机配准界面时，臂长默认值变为记录的当前数值。

点击遥操作手柄的 A 键 或 扳机键 选中滑动条的不同点位，选择后 扳机键 点击"确定"按钮。

  • 配准成功

系统提示"设置成功"，2 秒后自动返回模式选择界面，表示配准完成。

  • 配准失败

系统弹出"系统记录异常"提示，表示此次配准失败，可以点击"重新开始"按钮再次进行配准流程；或点击"退出"按钮返回模式选择界面。

4.2.9 结束遥操

  • 双手中指松开握柄键退出遥操作，VR 界面上遥操状态显示为OFF，提示“遥操模式已退出”。

如果退出遥操时没有关闭数据录制，数据会自动保存

  • 若需再次进入遥操作，建议先长按 Meta 键复位视角，再双手中指按住握柄键进入遥操。

4.2.10 遥操语音交互

类型事件界面提示语语音播报
错误提示自碰撞保护关节自碰撞保护，请及时调整手臂动作“自碰撞保护，调整手臂远离身体”
关节电机报警关节电机保护，请确认环境状态后按Y键清错“关节电机保护，按Y键清错”
底盘未上使能底盘未上使能，无法进行遥操移动-
数据采集&删除开始数据采集数据采集已开启“数据采集已开启”
数据保存中正在储存本次采集数据，请稍等...-
采集数据保存成功数据已成功保存“数据已成功保存”
采集数据保存失败数据保存失败“数据保存失败”
采集数据删除请确认是否删除上次记录数据，如确认删除，请再次点击右摇杆“请确认是否删除数据”
数据删除中正在删除上次采集数据，请稍等...-
采集数据删除成功遥操数据已删除“遥操数据已删除”
采集数据删除失败数据删除失败“数据删除失败”
交互反馈手势切换左/右手手势已切换为：XX“XX（手势名称）”
腿部动作切换腿部动作已切换为：XX“XXXX（腿部状态名称）”
底盘运动模式切换底盘运动模式切换为：XX-
进入遥操遥操模式已激活【遥操激活音效】
退出遥操遥操模式已退出【遥操退出音效】
异常提示VR模式无法进入提示VR模式无法进入，请检查后端服务-
VR界面中的后端服务断连提示服务异常
服务断开连接，正在尝试重新连接		"服务断开连接"

4.2.11 遥操录制动作

如需自行录制动作，可通过遥操作，将一系列连贯的运动姿态记录下来，生成一个动作文件，之后就可以在W1控制界面中一键让机器人自动复现刚才录制的整套动作。

4.2.11.1 指令录制demo

请参考 遥操使用说明 控制机器人完成动作，录制你需要的动作，数据自动保存为 .json 文件。

① 进入遥操界面，双手控制灵巧手时，按下左手柄的摇杆按键，触发开始录制。再按一次，退出录制。

如果你要录制“比心”的打卡动作，为了保证它和其他动作顺利衔接，建议在开始时让双手自然垂下，再依次完成单手或双手比心动作，最后双手再自然垂下作为结束。

② 当你松开双手中指、退出遥操作模式后，录制的文件（如 pose_record_xxxx.json）会自动保存在w1/dexe_teleoprate/recorded_data/时间戳路径下。

4.2.11.2 替换动作文件

用新录制的动作文件替换掉旧的动作文件

① 在w1/dexe_teleoprate/recorded_data/时间戳路径下，能找到对应录制的完整动作文件。以下路径为对应的重录制完整动作文件：

② 将这个文件放入路径 w1/dexe_mobile_application/script/records/ACTIONS/动作名下（动作名是新录制的动作的英文名，比如hearts是比心，pinch是捏合，cup是杯状、fist是握拳、like是点赞） 。

③ 将w1/dexe_mobile_application/script/records/ACTIONS/动作名目录下原有的文件删掉，然后将新录制的的文件重命名，名称本身没有限制，只要能区分即可。

如果不删除旧文件，可能会因系统存在多个文件导致调用的不是你最新录制的动作。

4.2.11.3 测试demo

此时再运行预设动作，点击比心的动作时，对应播放的就是录制好的比心动作。

4.2.11.4 重播demo

如需重播预设动作或新录制的demo，可在PC1的 Terminal 终端上执行如下指令。

cd w1
source install/setup.bash
cd dexe_mobile_application/script
python replay.py /path/to/action.json #action.json是指预设动作和新录制demo的存储路径，比如records/ACTIONS/hearts/hearts_01.json

4.2.11.5 使机器人缓慢回到起始姿态

执行完预设动作或新录制的demo后，如果想让机器人回到起始姿态（即动作的第一帧），可在PC1的 Terminal 终端上执行如下指令。

cd w1
source install/setup.bash
cd dexe_mobile_application/script
python slowly_move_to.py /path/to/action.json#action.json是指预设动作和新录制demo的存储路径，比如records/ACTIONS/hearts/hearts_01.json

4.3 X-Wiz使用指南

X-Wiz 是一个面向机器人开发和应用的综合性主控系统，包含状态监测、整机控制、感知传感、手眼标定等功能，让机器人能够感知环境、听懂指令并执行各种复杂任务。

机器人上电后，在 PC2 的终端上输入xwiz命令打开X-Wiz软件。

4.3.1 主界面

软件自动连接 W1 Pro机器人，进入主界面，可视化视窗实时显示机器人 3D 姿态。

区域说明
菜单栏集成机器人控制相关功能入口，涵盖状态监测、感知传感、整机控制、手眼标定等核心功能模块。
可视化视窗实时3D可视化同步机器人本体状态
日志区实时显示系统运行过程中的关键信息，支持查看运行数据、辅助功能调试；同时提供日志筛选、清空、搜索等功能。
状态栏展示机器人整机运行状态，包含整机状态、机器人 ID、当前电量、任务状态等关键运行信息。
机器人信息
展示机器人核心功能模块，支持查看机器人基础软硬件版本信息

4.3.1.1 菜单栏

功能项说明
状态监测可视化监控机器人运行状态，包含关节看板、末端执行器看板等子模块，支持查看关节参数、部件状态等核心运行数据。
感知传感集成机器人各类传感器（如环境、视觉传感器）的数据采集与展示功能，支持对感知数据的实时监控与分析。
整机控制
提供机器人全局控制功能，包含模式选择（自动控制 / 遥操作模式切换）、预设动作调用等子功能，支持对机器人整机运行逻辑的配置与管理。
手眼标定实现机器人 “手（末端执行器）” 与 “眼（视觉传感器）” 的坐标系统一校准功能，为视觉引导的作业任务提供精度保障。
运动速度通过运动速度滑块可调节机器人所有关节电机的运动速度（除底盘电机）。
拖拽模式开启拖拽模式后，机器人双臂可自由拖拽。
清错恢复点击清错恢复后将执行关节电机清错指令。
开启故障排查开启故障排查后可排查关节电机接线问题，Ethercat软件问题，电机故障。

4.3.1.2 可视化视窗

通过可视化界面实时展示机器人 3D 姿态，提供直观的视觉反馈。

4.3.1.3 日志区

功能项说明
时间按时间顺序采集并展示系统运行过程中的关键信息。
等级支持 INFO/ERROR/WARNING 不同等级的日志类型区分。
内容展示系统运行过程中的关键信息，涵盖机器人状态、操作、移动等。
搜索支持快速检索目标日志内容，辅助调试与排障。
筛选支持筛选不同等级的日志。
清空可一键清除当前日志。

4.3.1.4 状态栏

功能项说明
整机状态机器人当前的整体运行状态，绿色表示正常，黄色表示预警，红色表示故障，蓝色表示待机。
机器人ID实时展示当前连接机器人的 ID，用于区分多设备场景下的机器人。
电量实时监控机器人当前电量，低于 30%时提醒充电。
任务显示机器人当前任务的执行状态，便于跟踪任务进程。

4.3.1.5 机器人信息

展示机器人基础软硬件信息。

说明
基础信息机器人ID实时展示当前连接机器人的 ID，用于区分多设备场景下的机器人。
PC1 IP机器人内主控电脑PC1的网络 IP 地址，PC1安装于底盘。
PC2 IP机器人内主控电脑PC2的网络 IP 地址，PC2安装于胸腔。
电源固件版本机器人电源模块的固件版本信息，用于版本匹配、固件升级及故障排查。
软件版本PC1PC1上所搭载的DexE各模块软件版本
PC2PC2上所搭载的DexE各模块软件版本

4.3.2 状态监测

实时获取关节、末端执行器、传感器等关键组件的参数，并可视化展示机器人各部件的运行状态，用于监控机器人的状态，并一键排查Ethercat硬件/软件及电机故障。

4.3.2.1 关节看板

实时显示各关节的位置、速度、力矩、温度等参数，通过OP状态指示灯（绿色表示正常，红色表示异常）直观反馈各关节的通信状态。

在关节看板点击 左臂、右臂、颈部电机、腰、膝盖、脚踝，左侧会显示对应关节的位置、速度、力矩、温度、状态码。

关节组说明
左臂左臂有7个关节，分别是肩部3个关节J1、J2、J3，肘部一个关节J4，腕部3个关节J5、J6、J7
右臂右臂有7个关节，分别是肩部3个关节J1、J2、J3，肘部一个关节J4，腕部3个关节J5、J6、J7
颈部电机颈部有2个关节，分别是颈部水平关节（NECK1-水平）、颈部俯仰关节（NECK2-俯仰）
腰腰部有2个关节，分别是腰部水平关节（WAIST）、腰部俯仰关节（BUTTOCK）
膝盖脚踝腿部有2个关节，分别是踝关节（ANKLE）、膝关节（KNEE）
参数说明取值范围单位
OP状态OP状态表示关节电机的通信状态，如果关节组内任意一个关节的OP状态为“下 OP”，则整个关节组的OP状态也为“下 OP”。
绿灯表示“上 OP”，关节通信正常；
红灯表示“下 OP”，关节通信异常。
-
位置各个关节电机当前的位置信息，反映每个关节的旋转角度[-π, π]弧度（rad）
速度各个关节电机当前的运动速度[-π, π]弧度/秒（rad/s）
力矩各个关节电机当前的力矩[-100.0, 100.0]牛米（N・m）
温度各个关节电机的实时温度，若关节温度过高，数值会标红，提示过热风险。°C
状态码各个关节电机的错误码
错误码如下表

-
错误码故障描述
0x001硬件短路保护：检测到功率器件的短路保护
0x002软件过流：检测到相电流过大
0x003存储读异常：Eeprom 读取异常
0x004存储写异常：Eeprom 存储异常、或频繁存储
0x005EEPROM 初始化故障：检测到 EEPROM 异常
0x006AD 采样故障：AD 模块故障
0x007编码器异常 1：编码器断线
0x008编码器异常 2：编码器 CRC 校验错误
0x009编码器异常 3：编码器内部计数错误
0x00A母线欠电压：48V 供电时，母线电压低于 36V
0x00B母线过压故障：48V 供电时，母线电压高于 59V
0x00C电机电流采样故障：电机 U,V,W 电流采样故障
0x00D电机过载：负载超过电机额定的 120% 以上超过一定时间
0x00E驱动器过载：负载超过驱动器额定的 110% 以上超过一定时间
0x010驱动器过热：驱动器主回路温度将达到过热故障
0x012驱动器过速：电机转速超过驱动器速度上限
0x013位置偏差过大：偏差计数器中的滞留脉冲超过了允许范围
0x018编码器过热：编码器温度超过上限值
0x019编码器电池电压低警告：编码器电池电压低于 3.1V
0x01A编码器电池电压低报警：编码器电池电压低于 2.5V
0x01B驱动器和电机不匹配：电机代码选择错误
0x01C原点回归失败
0x01D主电源掉电：主电源输入缺相
0x01E电机堵转：电机堵转
0x020ECAT 初始化错误：ECAT 初始化从站 ESC 错误
0x021DC 丢步
0x022ECAT 网线通讯中断：ECAT 通过网线与主机通讯中断
0x023PDO 参数只读：ECAT PDO 通信参数在 Servo-on 时只读
0x024非法索引和子索引：ECAT PDO 通信没有查找的索引和子索引
0x025同步时间超范围：ECAT PDO 通信设置同步时间超范围
0x026通信数据超范围：ECAT PDO 通信数据超范围
0x027ECAT 看门狗超时：ECAT 长时间未接收到 PDO 通信
0x028ECAT 看门狗无效：SM 打开看门狗，但看门狗周期寄存器时间为零
0x029ECAT 目标增量过大：位置指令对应得速度指令超过额定转速 2 倍
0x02AECAT 位置正向极限：目标值大于 0x607D 索引 2 的值
0x02BECAT 位置负向极限：目标值小于 0x607D 索引 1 的值
0x02C第二编码器断线：第二编码器通信线缆断路
0x02D第二编码器内部故障：第二编码器解析位置出错
0x02E第二编码器 CRC 故障：第二编码器连续 CRC 校验错误
0x02F第二编码器配置错误：第二编码器配置错误
0x030第二编码器电池电压报警：第二编码器电池低报警
0x031第二编码器电池电压警告：第二编码器电池低警告
0x032速度指令超限：位置环输出速度指令超限
0x033扭矩偏差过大：扭矩闭环使用
0x034扭矩传感器断线：内置扭矩传感器通信故障
0x035EEPROM 参数校验失败：读取配置参数失败
0xE81电机过热警告：电机温度超过报警值
0xE82驱动器温度过高警告：驱动器温度超过报警值
0xE83电机过载警告：将达到电机过载反时限曲线
0xE84驱动器过载警告：将达到驱动器过载反时限曲线
0xE85位置偏差过大警告：偏差计数器中的滞留脉冲超过了警告范围
0xE86制动过载警告：制动器超载
0xE87正向超程警告：位置超过正限位（电机已经运行到限位）
0xE88反向超程警告：位置超过反限位（电机已经运行到限位）
0x2214电机电流过流
0x2250电机三相电流和超限
0x2341U 相过流
0x2342V 相过流
0x2343W 相过流
0x3210母线电压过压
0x3220母线电压欠压
0x4110功率部分温度过高
0x7121电机堵转
0x7305负载端单圈编码器读取的数据出错
0x7306电机端单圈编码器读取的数据出错
0x730D电池警告错误
0x730F电池电压低
0x7311采样的电机端位置误差超限
0x7314检测编码器电池重新接入
0x7315采样的负载端位置误差超限
0x7350电机端编码器类型不支持
0x7374多圈位置错误
0x7377检测到复位引脚的报错信息
0x737A负载端单圈编码器启动错误
0x737E电机端单圈编码器启动错误
0x8130CAN 心跳错误
0x8400速度误差超出限制值
0x8401电机速度过高
0x8500位置误差超出限制值
0xA000主站掉线
0xF004EtherCAT 初始化错误
0xF005STO 功能被激活
0xF006多圈计数错误
0xF008母线电压低于允许的最小供电电压（19V）

在关节看板点击 底盘，左侧会显示底盘左右两个电机的使能状态、速度、电流、温度、线速度、角速度、位置、方向、状态码。

参数说明取值范围单位
使能状态底盘的两个驱动轮是否处于使能状态
ENABLED表示使能，DISABLED表示未使能-
速度底盘当前的运动速度[-π, π]弧度/秒（rad/s）
电流底盘运行时电机的实时电流值
[0.0, 100.0]
%
温度底盘电机的实时温度-℃
线速度(x,y,z)
底盘左右两个电机沿 x/y/z 轴方向直线运动的速度。[-1.0, 1.0]m/s
角速度(x,y,z)
底盘左右两个电机绕 x/y/z 轴旋转运动的速度。[-1.0, 1.0]弧度/秒（rad/s）
位置底盘的坐标-m
方向底盘的旋转姿态，用四元数表示--
状态码底盘电机的错误码
底盘错误码如下表-

底盘错误码如下：

故障码故障描述排查建议
0x0001过压电源电压过高
0x0002欠压电源电压过低
0x0004过流负载过重或机械碰撞
0x0008过载负载过重或机械碰撞
0x0010电流超差负载过重或机械碰撞
0x0020编码器超差负载过重或机械碰撞
0x0040速度超差负载过重或机械碰撞
0x0080参考电压出错驱动器内部故障，若重启后无法清除需更换
0x0100EEPROM 读写出错驱动器内部故障，若重启后无法清除需更换
0x0200霍尔出错HALL 线信号不正确或未接线
0x0400电机高温负载过重，降温后继续使用
0x0800编码器错误编码器断线或接错
0x2000速度给定错误控制指令异常

4.3.2.2 末端执行器看板

实时显示机器人灵巧手的闭合程度、速度、力矩、状态码等关键参数，通过工作状态指示灯（绿灯表示连通，红灯表示未连通）反馈各个末端执行器的连通状态。

说明取值范围单位
左/右手灵巧手有6个指关节，分别是大拇指1、大拇指2、食指、中指、无名指、小拇指--
状态码各个手指关节的状态
0：IDLE（空闲 / 到位停止）
1：RUNNING（运动中）
2：STALL（堵转 / 保护停止）
3：UNKNOWN（未连接）		-
闭合程度手指当前的弯曲状态，0 代表完全张开，100 代表完全闭合。[0.0, 100.0]%
速度手指在张开 / 闭合过程中的运动速度[0.0, 100.0]%/s
力矩手指关节输出的力[-100.0, 100.0]牛米（N·m）

4.3.2.3 传感器

实时显示防撞条、急停按钮的触发状态。“触发”表示防撞条与周围物体发生碰撞，触发了机器人的急停功能。

4.3.2.4 运维看板

实时展示电源板连通性、充电线接入状态、充电状态；电池电压、电流、温度、剩余电量；CPU、GPU、硬盘、内存利用率。

状态说明
电源板连通性表示电源板是否能建立物理连接，是电源板与其他部件通信的基础状态检测项。
充电状态反映电源板的充电情况，帮助判断电池当前是否处于充电过程中。
充电线（IO 触发状态）体现充电线的 IO 触发情况，用于监测充电线与电源板之间的连接触发状态。
电池电压电池的电压值，可用于判断电池的供电能力，是电池状态的核心指标之一。
电流电池的电流值，正值表示放电、负值表示充电，用于监控电池的充放电情况。
电池温度电池的实时温度，用于监控电池健康状况，预防过热风险，温度过高时会触发告警。
剩余电量电池剩余的电量，可直观判断是否需要充电，当电量低于 30%时会提示充电。
CPU-PC1和PC2的的运算核心和控制核心，负责处理和执行各种指令，其占用情况反映系统运算负载。
GPU-PC1和PC2中专门用于图形处理的处理器，可加速图形渲染和计算，其占用情况反映图形/计算任务的负载。
硬盘-用于长期存储数据的设备，其使用情况反映存储资源的占用率，辅助判断存储是否充足。
内存-暂时存放 CPU 运算数据以及与硬盘等外部存储器交换的数据，其占用情况反映系统临时数据处理的负载。

4.3.2.5 故障排查

若关节电机异常，此时点击 开始故障排查按钮可排查硬件和软件问题，并执行清错恢复。

  • 排查软件问题，若排查出软件问题，点击 软件恢复 可尝试重新建立通信并让从站回到正常运行状态。

  • 排查电机接线问题，比如电机接线是否存在断线，统计断线次数提醒问题所在，请根据排查结果检查机器人电机线缆。

点击 已排查并检查从站状态 ，系统将自动检查从站状态并执行相应的恢复动作。

点击 清错恢复 按钮可手动复位，让电机重新使能。

4.3.3 感知传感

感知传感是机器人获取外部环境信息并进行初步处理的基础模块，通过 RGB 相机、深度相机和激光雷达获取环境信息，实现全方位的环境感知，为机器人的决策、导航和交互提供数据支持。

4.3.3.1 头部相机

提供头部视角的视觉信息，显示左目右目两张 RGB 彩色图。若无法查看到相机画面，可点击 整机控制 切换整机模式为自动模式或遥操模式，系统会自动重启相机服务。

连通性：表示头部相机是否能建立物理连接。

帧率：指相机每秒钟能够拍摄到的图像数量。

4.3.3.2 腕部相机

提供手部近距离视角，显示 RGB 图、深度图和点云图。

连通性：表示腕部相机是否能建立物理连接

帧率：指相机每秒钟能够拍摄到的图像数量。

4.3.3.3 底盘相机

底盘前后各有一个3D相机，提供底盘视角的 RGB 图、深度图和点云图。

连通性：表示底盘相机是否能建立物理连接。

帧率：指相机每秒钟能够拍摄到的图像数量。

4.3.3.4 底盘激光雷达

底盘前后各安装有一个激光雷达，提供点云图。

连通性：表示激光雷达是否能建立物理连接。

帧率：指激光雷达每秒能够完成的扫描次数或输出点云数据的次数。

4.3.4 整机控制

整机控制提供模式切换、预设动作调用功能，实现对机器人整机运行模式的配置与管理。

4.3.4.1 模式切换

可手动切换整机模式（自动模式/遥操模式/建图模式/ACT模式），支持临时切换与开机自启模式设定。开机自启默认为自动模式，如果选择临时切换整机模式，重启后默认为自动模式；如果设定开机自启模式，重启后默认是设定的整机模式。

模式说明
自动模式系统默认模式，机器人在无人干预下自主完成任务，适用于日常任务执行、自动化作业等，如工厂流水线的精密装配。
遥操模式通过遥操作设备控制机器人运动，采集高质量数据为AI提供学习数据，适用于教会机器人做复杂动作。遥操模式请参考 遥操使用说明。
建图模式机器人对其所处的物理环境进行扫描，构建出数字地图，适用于进入新环境后让机器人认识环境。
ACT模式学习遥操模式采集的海量数据，自主生成并执行一连串流畅的动作。ACT模式使用请参考 表演挥手和握手。

4.3.4.2 预设动作

选择预设动作并点击 开启动作 启动执行，界面实时显示动作执行状态，点击 停止运动 按钮可终止动作。

4.3.5 手眼标定

手眼标定是指机器人“手”（末端执行器）与“眼”（头部的双目相机）之间的坐标系统一校准，通过视觉与机械臂协同校准算法，无需标定板，基于灵巧手自动完成手眼坐标映射校准，无需人工干预，提升标定效率与精度，为机器人执行任务提供精度保障。

4.3.5.1 校验已标定矩阵

点击校验标定精度，可校验当前已标定矩阵的精度，如果标定结果偏差在阈值内，则无需重新标定，如果标定结果的偏差超过阈值，则需要重新标定。

勾选开机校验手眼位置，支持开机自动校验已标定矩阵精度。

4.3.5.2 标定流程

（1）新增手眼标定

（2）标定信息

  • 标定名称可自行命名当前的标定配置

  • 标定ID用于机器人切换标定配置

  • 相机为相机类型Stereo Camera

  • 相机品牌为当前连接的相机的品牌KFC

  • 机器人类型为Dexforce W1 Pro

  • 相机安装方式 默认为 眼在手外

  • 标定目标类型可选BrainCo Revo 1、Linker Hand L6

  • 标定方式为预设轨迹自动采样

  • 在线获取坐标为是，机器人系统写有对应的标定程序，支持眼在手外的基于灵巧手的自动手眼标定。

（3）标定前检查

  • 确保机器人已稳固安装

  • 机器人手臂处于相机视野范围内

  • 相机精度已满足项目使用需求

  • 机器人精度已满足项目使用需求

  • 请保持背景简洁并移除视野内杂物

（4）标定前诊断

点击 标定前诊断 ，开始检查相机内外参，若左目右目的极线对应的画面物品所处位置偏差不大，则判定通过。

一般不检查机器人精度，若标定结果（左臂、右臂）偏差>1.5 mm，需要点击 校验 检查机器人精度，检测机器人绝对精度比值不大于 0.005，则判定机器人精度符合要求，对标定结果的偏差没有影响。

（5）标定移动路径

机器人左臂 、 右臂 、 头部的起始位姿是默认值，不需要进行配置，直接点击下一步进行采样。

（6）采集样本

采集末端执行器不同位姿下的图像与位姿数据，用于后续手眼坐标映射计算。

  • 点击 开始采样 按钮，按钮自动切换为 停止采样，机器人手臂自动下降，开始自动标定 ；

  • 开始采样后会自动采集50个样本（约4-5分钟），系统将自动筛选其中10~25个效果最好的样本计算出标定矩阵。

（7）计算结果

系统自动计算标定结果，标定误差（左臂 、右臂）≤1.5 mm，表示标定结果有效。若机器人末端执行器与相机的相对位姿未发生改变，该标定结果支持复用。如果二者的相对位姿发生变动，则需要重新标定。

（8）标定诊断

查看误差图，确认标定结果的准确性与可靠性。如果三张图的样本点都集中在原点附近则标定结果精度正常，若误差图显示样本点分散，需重新标定。

（9）手动覆盖标定数据

标定过程可能多次进行，为了防止机器人误使用标定失败的数据，导致抓取失败或碰撞，因此标定后需要用户手动覆盖标定数据才能生效。

  • 获取标定结果：本次标定结果被保存为一个临时文件 calibration_result.json，位置在 /home/dexforce/.dexforce/XWiz/calibration/。

  • 手动替换标定数据：复制临时文件 calibration_result.json中的左右手数据，粘贴替换到另一个正式工作目录下的参数文件里（/home/dexforce/workspace/dexe_application/application/parameters/ 中的calibration_result.json标定文件）。

calibration_result.json文件中的左臂、右臂标定数据可根据 标定结果 确定。

4.4 W1 控制界面

W1控制界面提供机器人关节/笛卡尔空间下的手动示教、任务轨迹录制与回放，以及执行预设任务（如泡咖啡）的一键触发功能。为操作人员提供集中且可视化的主控平台。它是协调调度底层控制系统、视觉模块与语音模块的“指挥中心”，是将各子系统整合为完整应用的关键，同时用于高级任务控制、运动调试和系统监控。

在W1控制界面，自动判断连接状态，并进行通讯连接。

4.4.1 外设通讯模块

名称功能描述
视觉通讯若"视觉通讯"灯亮，说明与pickwiz建立了Tcp通讯
启动PickWiz打开启动器界面并启动 PickWiz，停止 PickWiz 按键仅停止终端日志显示，若要关闭 PickWiz 需手动关闭。
语音通讯若"语音通讯"灯亮，说明已经和语音服务器建立了通讯，此时检查麦克风和音响是否安装及选择到位后，即可使用麦克风触发语音交互。
语音服务控制-语音服务控制：需配合语音通讯按钮连接到语音 Server，连接后持续通讯，可正常对话与下发任务；
-关闭语音服务：隐藏语音UI界面
-展示语音服务：展示语音UI界面
用户说话为最高优先级，会打断当前语音服务。
启用HTTP服务点击"启用 HTTP 服务"后，用户可通过PC/平板 打开网址进行应用，可通过平板咖啡点单界面远程控制机器人
恢复 ACT点击 恢复 ACT 可让机器人主动打招呼和握手。
ACT: OFF点击 ACT: OFF ，机器人停止打招呼和握手，自动回到设置的默认位置。

4.4.2 配置信息模块

配置读取读取新的配置，暂时配置会自动加载，不支持在新的路径读取配置(目前软件自动读取配置，该按键暂无作用)
配置编辑打开配置编辑UI，用户修改参数，需要点击保存才能更新配置信息修改dexe_application/application/parameters/parameter.json中的w1_manager配置项，通过预先在profiles参数下存储好需要的w1_manager控制器信息，需要更换末端执行器时，只修改active_profile参数即可。
刷新配置配置编辑保存完成后，需要点击该按钮，才会在当前程序中生效，否则需要重启软件
保存PC1日志点击后会弹出提醒是否保存框，点击"确认"，开始后台运行保存，PC1的~log文件夹整个保存到PC2的~log/log_pc1文件中。

4.4.3 额外功能

图像分析用于判断当前ROI区域的颜色是否等于设定的颜色，不相等时触发对应逻辑
物体检测主要基于 yolo 检测模型，支持咖啡工作站全类别检测，支持选择 ROI 区域进行检测，可在图像中划定特定区域查看检测结果
获取KFC内参点击后会弹出是否获取KFC内参弹窗，点击确认后，会将KFC内参保存到/home/dexforce/workspace/dexe_application/vision/config/KFC-ROS.0.yaml中。
实时取图点击后，会打开实时左右目检测窗口，点击关闭取图会变成黑屏，随后约3-5秒该取图框会自动退出。
配准查看查看点云配准结果的功能
资产同步自动管理机器人运行所需的资产文件，确保本地资产与云端配置一致。点击界面中的 “资产同步” 按钮后，系统会自动读取/home/dexforce/workspace/dexe_application/tools/asset_manager/assets_config.json配置文件，检查本地资产是否完整，若存在缺失则从云端下载对应文件。
开启支付判断触发支付功能
启动仿真用于在虚拟环境中模拟机器人运动及任务执行，支持两种模式切换。
数字孪生模式 ：仿真机器人与真机同步运动，实时映射真机状态。
纯仿真模式 ：触发set_sim_mode切换，通过 UI 下发运动指令时，仅仿真机器人运动，真机保持静止。

4.4.4 W1状态获取及控制模块

坐标系机器人运动控制中用于定位和描述部件位置 / 姿态的参考坐标系。
-base（基坐标系）：机器人的 “全局参考坐标系”，通常固定在机器人的底座或安装平面上（是整个机器人系统的 “原点基准”）。
-bottom（底部 / 基座坐标系）：靠近机器人底座的局部坐标系（比base更贴近机器人本体的基准）。
-grasp（抓取坐标系）：绑定在机器人末端执行器（灵巧手）上的 “工具坐标系”，原点通常位于抓手的中心或接触点位置。
左臂/右臂获取左/右臂当前位姿的笛卡尔坐标，返回[x,y,z,a,b,c]，在终端日志中可以看到关节坐标点击"左臂"、"右臂"终端中会打印对应的cartpose和jointpose
左手/右手获取左/右灵巧手当前姿态，共六个控制量，前两个是拇指，后四个对应食指到尾指。每个控制量取值范围均为[0-100]，0为张开，100为合紧
头部/躯干获取头部/躯干当前姿态，头部共两个控制量[左右转头，上下转头]、躯干四个控制量[从下往上三个电机、第四个躯干水平旋转]
六个运动按键(左臂运动、右臂运动、左手运动、右手运动、头部运动、躯干运动)点击后会运动到当前控制量的位置
导航/控制暂未开放
开拖拽打开W1左右臂力限制，点击后"拖拽"亮绿灯，此时可以手动拖拽W1的左右臂
关拖拽恢复W1左右臂力限制，当W1运动停止且点击后，"拖拽"灯灭
设置初始位核心作用是确认初始机械臂构型，在后续坐标运动中会参考该初始零位做运动规划，配置里使用“回原点”时可回到该位置。
模式选择切换"当前模式"、"自动模式"、"遥操模式"三种W1控制模式
清除OP错误当W1无法运动，终端日志出现“Streaming command send failed"时，代表OP有报错无清理，点击清理报错可恢复正常
W1下电点击确认后会提醒是否关闭PC1或PC2
执行任务选择已制作好的任务，仅选择的任务一次
"人脸跟踪"功能：点击后，W1具有以下功能人脸追踪、用户挥手回礼、用户语音"真棒"、"你好"、"你是谁"、"有什么推荐"，W1会做出一些动作并语音回复对应话术
中断执行任务执行过程中，点击后，可以终止任务执行
执行状态当任务执行中时，会显示绿色，任务结束后显示灰色
胶囊数量应用于胶囊咖啡师场景
开启支付判断点击后，进行订单检测，若为关闭状态，直接可以通过点单平板或语音触发冲泡

注意事项

  • 注意这部分运动均是通过修改数值来运动，请一定要小心修改，再运动。

  • 注意左右臂之间没有运动碰撞检测，运动输入错误，可能会导致左臂撞右臂。

4.4.5 日志显示区

名称功能描述
清除日志清空当前界面上展示的所有日志，日志存储文件不会清空
保存日志保存当前界面上展示的所有日志
自动滚动将最新的日志内容自动滚动到可视范围内
显示时间显示日志时间

4.4.6 语音模块

该模块包含语音识别（ASR）与语音合成（TTS）服务，使其能够监听并理解用户的语音指令（如“泡一杯咖啡”），并通过语音进行反馈和状态提示。实现自然的人机交互，允许用户通过最直观的语音命令触发复杂的任务流程，提升操作的便捷性与用户体验，为机器人提供“耳朵”和“嘴巴”。

开机自动连接麦克风、音响设备，打开W1控制界面的语音服务。

然后与机器人进行语音交互（“小维同学”“你好，小维”“你好，小薇”“维总”“维维”“小薇！小薇！”（支持任意音调）），检查语音模块是否正常启动。

4.5 二次开发入门

开发者可通过标准的ROS2话题（Topic）、服务（Service）和动作（Action）机制，便捷地获取机器人状态、发送控制指令，实现复杂任务的编程与集成。

Topic：订阅式话题，接收方订阅某个消息，发送方根据订阅列表向接收方发送消息，主要用于中高频或持续的数据交互。

Service：问答式服务，通过请求实现数据获取或操作。用于低频或功能切换时的数据交互。

Action：持续式动作，用于长时间运行的任务，支持任务执行过程中的状态反馈和取消操作，适用于复杂动作控制和任务执行。

4.5.1 常用话题

以下列出几个二次开发过程中的常用话题，用于获取图像、机器人状态、机器人控制。

完整的接口说明请参考附件：二次开发接口说明 V0.4.2.pdf

类型话题名称话题内容使用方法
相机话题
原图：
/camera/left_eye
/camera/right_eye		1920*1080图像，5Hz
可直接在终端命令行输入如下指令测试话题接口
# 查看左目的图像数据及其参数
ros2 topic echo /camera/left_eye
# 查看图像尺寸
ros2 topic echo /camera/left_eye --field height
ros2 topic echo /camera/left_eye --field width
resize图像：
/camera/left_eye_resize
/camera/right_eye_resize		960*540图像，30Hz
压缩图像：
/camera/kfc_compressed
3840*1080的组合压缩图像，解码后为1920*1080图像,30Hz
相机通过话题 /camera/kfc_compressed 发布压缩图像。订阅端不能直接使用原始二进制数据，必须进行解码处理。示例代码中的 callback 方法演示了如何利用 OpenCV 将压缩数据转换为可处理的图像矩阵。
import rclpy
from rclpy.node import Node
from sensor_msgs.msg import CompressedImage
import cv2
import numpy as np
class StereoReceiver(Node):
def __init__(self):
super().__init__('stereo_receiver')
self.subscription = self.create_subscription(
CompressedImage,
'/camera/kfc_compressed',
self.callback,
1
)
def callback(self, msg: CompressedImage):
# ====== 解码 JPEG ======
np_arr = np.frombuffer(msg.data, np.uint8)
combined_img = cv2.imdecode(np_arr, cv2.IMREAD_COLOR)
if combined_img is None:
self.get_logger().warn("Decode jpeg failed!")
return
# ====== 分割左右图 ======
height, width_total = combined_img.shape[:2]
width = width_total // 2
if width <= 0:
self.get_logger().warn("Invalid image width!")
return
left_img = combined_img[:, :width]
right_img = combined_img[:, width:width + width]
# ====== 调试输出 ======
self.get_logger().info(f"Received: {width_total}x{height}, left/right={width}x{height}")
# （可选）显示图像
# cv2.imshow("left", left_img)
# cv2.imshow("right", right_img)
# cv2.waitKey(1)
def main(args=None):
rclpy.init(args=args)
node = StereoReceiver()
rclpy.spin(node)
node.destroy_node()
rclpy.shutdown()
if __name__ == '__main__':
main()
机器人关节信息话题
真实机器人关节信息
/feedback/joint
仿真机器人关节信息
/feedback/joint_sim		header：标准消息头
string[] name：关节名称
float64[] position：关节角度（弧度）
float64[] velocity：关节速度（百分比）
float64[] effort：关节力矩（牛米）		 # 查看机器人关节信息
ros2 topic echo /feedback/joint
# 查看机器人左灵巧手信息
ros2 topic echo /feedback/hand/left
左手灵巧手信息
/feedback/hand/left
右手灵巧手信息
/feedback/hand/right
string[] name：关节名称列表
float64[] position：手指位置状态
float64[] velocity：手指关节运动速度
float64[] current：手指关节电机电流
uint8[] state：手指关节电机状态
机器人关节控制话题
全身关节控制
/control/joint_position

消息类型：joint_interfaces/msg/JointPositionControl

header：标准消息头
string[] name：控制的关节名称
  • 下半身：ANKLE、KNEE、BUTTOCK、WAIST
  • 头部：NECK1、NECK2
  • 左臂：LEFT_J1、LEFT_J2、LEFT_J3、LEFT_J4、LEFT_J5、LEFT_J6、LEFT_J7
  • 右臂：RIGHT_J1、RIGHT_J2、RIGHT_J3、RIGHT_J4、RIGHT_J5、RIGHT_J6、RIGHT_J7
float64[] position：关节目标位置（角度），单位是弧度（rad），取值范围是[-π, π]		可直接在命令行输入如下指令测试话题接口
# 以控制头部关节为例
ros2 topic pub /control/joint_position joint_interfaces/msg/JointPositionControl "
header:
  stamp:
    sec: $(date +%s)
    nanosec: 0
  frame_id: 'base_link'
name: ['NECK1', 'NECK2']
position: [0.0, 0.5]
" --once
左手灵巧手
/control/hand/left
右手灵巧手
/control/hand/right

消息类型：end_effector_interfaces/msg/EEJointControl

string[] name{ //关节名称列表（控制时可自定义顺序），默认对应 6 个手指关节：
“THUMBMCP”; //拇指弯曲
“THUMBCMC”; //拇指摆动
“INDEXMCP”; //食指弯曲
“MIDDLEMCP”; //中指弯曲
“RINGMCP”; //无名指弯曲
“LITTLEMCP”; //小指弯曲
};
uint8 mode{ //控制模式，枚举
0：POSITION; //位置控制
1：VELOCITY; //速度控制
2：CURRENT; // 电流控制
};
float64[] value：格式为数组 [q1,q2,q3,q4,q5,q6]，关节数量由name决定，与name一一对应，默认 6 个，含义由mode决定，单位为百分比（%）
  • 当mode=0时value为各关节的 “弯曲程度比例”，取值范围是[0.0, 100.0]；
  • 当mode=1时value为各关节的 “运动速度比例”，取值范围是[-100, 100]；
  • 当mode=2时value为各关节的 “电流输出比例”，取值范围是[-100, 100]
可直接在命令行输入如下指令测试话题接口
# 模式0：位置控制，value范围[0,100]，0=全开，100=全闭
ros2 topic pub /control/hand/left end_effector_interfaces/msg/EEJointControl "
header:
stamp: now
frame_id: 'left_hand'
mode: 0
name: ['THUMBMCP', 'THUMBCMC','INDEXMCP','MIDDLEMCP','RINGMCP','LITTLEMCP']
value: [50.0, 50.0, 20.0, 30.0, 30.0, 30.0] # 指定灵巧手六个自由度的闭合度
" --once
# 模式1：速度控制，value范围[-100,100]# 正值=闭合，负值=打开
ros2 topic pub /control/hand/left end_effector_interfaces/msg/EEJointControl "
header:
stamp: now
frame_id: 'left_hand'
mode: 1
name: ['THUMBMCP', 'THUMBCMC','INDEXMCP','MIDDLEMCP','RINGMCP','LITTLEMCP']
value: [30.0, 40.0, 50.0, 100.0, -20.0, -50.0] # 大于0为闭合速度，小于0为打开速度
" --once

4.5.2 二次开发指引

跨维智能封装了ROS2底层通信（Topic/Service/Action），提供了更高级、更易用的Python API，让您无需直接操作复杂的ROS2消息格式即可控制机器人。

您需要调用的API取决于您的具体应用场景，下面是一个简单的开发步骤示例：

（1）创建一个Python文件，比如example_get_current_qpos.py

（2）初始化机器人管理对象，比如导入dexe_robot_client包，实例化W1Manager

（3）调用API，获取机器人当前全身坐标

（4）运行example_get_current_qpos.py程序，即可获取机器人当前全身坐标。

4.5.2.1 上半身运动控制API

上半身运动控制接口是二次开发任务的核心必用接口，在/home/dexforce/.local/lib/python3.10/site-packages/dexe_robot_client/w1/w1_manager.py可以找到。

您可以直接参考其源码实现，也可以在您的项目中基于ROS2原生接口（Topic/Service/Action）重新实现更灵活的控制逻辑，而非强制依赖该封装类。

下面列出一些上半身运动控制API的示例： example_script.zip

序号函数参数返回/效果接口单例文件
1get_current_qpos
获取当前坐标（关节坐标系）		name (str, 可选)：指定部件名称，默认 "full_body"，可选值：
"full_body"
"torso"
"head"
"left_arm"
"right_arm"
"left_arm_ee"
"right_arm_ee"		返回 tuple[bool, np.ndarray]：成功标志 + 当前关节位置数组example_get_current_qpos.py
2get_current_pose
获取当前机械臂坐标（笛卡尔坐标系）		name (str)：机械臂名称，"left_arm" 或 "right_arm"
is_local (bool, 可选)：是否相对于机械臂基座坐标系，默认 True		返回 tuple[bool, list]：成功标志 + 位姿列表 [x_mm, y_mm, z_mm, roll_deg, pitch_deg, yaw_deg]example_get_current_pose.py
3move_joint_full_body
关节全身运动（关节坐标系）		waypoints_dict (dict)：各部件目标关节位置字典，支持多路点
speed_ratio (float, 可选)：速度比例，默认 1.0		返回 bool：执行是否成功
同时观察机器人是否运动成功		example_move_joint_full_body.py
4move_linear_full_body
线性运动（笛卡尔坐标系）		waypoints_dict (dict)：各部件目标位姿字典，支持多路点
left_qpos_seed (np.ndarray, 可选)：左臂 IK 参考关节位置
right_qpos_seed (np.ndarray, 可选)：右臂 IK 参考关节位置
cartesian_step (float, 可选)：笛卡尔采样步长，默认 0.005
speed_ratio (float, 可选)：速度比例，默认 1.0
is_local (bool, 可选)：是否基于机械臂基座坐标系，默认 True		返回 bool：执行是否成功
同时观察w1是否运动成功		example_move_linear_full_body.py
5set_ee_qpos
夹具开合设置		name (str)：末端执行器名称，"left_arm_ee" 或 "right_arm_ee"
qpos (np.ndarray)：目标位置，取值范围 0~100 		返回 bool：设置是否成功
同时观察灵巧手是否运动成功		example_set_ee_qpos.py
6stop_move
停止运动		timeout_sec (float, 可选)：停止等待超时时间，默认 3.0 秒 返回 bool：停止是否成功example_stop_move.py
7set_tcp
设置夹具，相对于法兰盘		name (str)：机械臂名称，"left_arm" 或 "right_arm"
xpos (np.ndarray)：目标 TCP 位姿变换矩阵，形状为 (4, 4)		返回 bool：设置是否成功 在4.move_linear_full_body的接口单例文件使用
# 左臂(无旋转偏移)
left_tcp_xpos = np.eye(4)
left_tcp_xpos[2, 3] = 0
self.w1_manager.set_tcp("left_arm", ...)
# 右臂(180度旋转)
right_tcp_xpos = np.eye(4)
right_tcp_xpos[2, 3] = 0
right_tcp_xpos[:3, :3] = R.from_rotvec(...)
self.w1_manager.set_tcp("right_arm", ...)

4.5.2.2 2D视觉API

如果您的二次开发任务涉及视觉引导（如“看到红色方块就抓取”），则必须使用下列2D视觉API，或参考其实现方式自行封装。

2D视觉API在 /home/workspace/dexe_application/application/basic_function.py中的Function类可以找到，您也可以直接参考其代码，也可以在您的项目中基于ROS2原生接口（Topic/Service/Action）重新实现更灵活的视觉处理逻辑，而不是强制依赖该类。

下面列出一些2D视觉API的示例：

类别主要函数参数返回
传统2D算法analyze_roi_color_simple
返回图中特定区域的颜色 		roi_coords: ROI坐标 [x, y, w, h]
camera_num: 取图数量
image: 可选，已获取的图像 		color_name：判断出来的颜色
avg_r：平均R值
avg_g：平均G值
avg_b：平均B值
image_with_roi：带ROI标记的图片
_detect_color_type_hsv
利用HSV设置颜色 		r: 红色通道值
g: 绿色通道值
b: 蓝色通道值 		字符串格式的颜色名称
基于检测模型analyze_roi_yoloroi_coords: ROI坐标 [x, y, w, h]
camera_num: 取图数量
class_name: 目标类别
conf_threshold: 置信度阈值
model_path: YOLO模型路径
image: 可选图像

picture_name: 图片保存名称
picture_save: 保存配置
roi_save: 是否保存ROI
roi_name: ROI区域名称 		情况1（图像获取失败）:
返回：("F", 0.0, None, [])

情况2（检测到目标）:
返回：("T", confidence, image_with_roi, detected_objects)
• confidence: 最高置信度值
• image_with_roi: 绘制了ROI和检测框的图像
• detected_objects: 检测对象列表

情况3（未检测到目标）:
返回：("F", 0.0, image_with_roi, [])

情况4（模型推理异常）:
返回：("F", 0.0, image_with_roi, []) 并记录错误日志
_preload_yolo_models无参数无返回。当执行到该函数，会预加载所有parameter.json中用到的模型
_save_detection_imageimage: 要保存的图像 (numpy数组)
picture_name: 图片名称前缀
result: 检测结果("T"/"F")
class_name: 目标类别
confidence: 置信度 		无返回值。函数执行以下操作：
• 成功: 将图像保存到 qt/error/ 目录
• 失败: 记录错误日志
• 如果图片数量超过200张，删除最早的图片

4.5.2.3 3D点云API

如果您的二次开发任务涉及基于3D视觉的空间定位，则需要使用3D点云API 进行双目点云生成与处理。

您可以直接参考其代码，也可以在您的项目中基于ROS2原生接口（Topic/Service/Action）重新实现更灵活的视觉处理逻辑，而不是强制依赖该类。

下面列出一些3D点云 API的示例：

example.zip

from StereoPointAdaptor import StereoPointAdaptor  
from TopicimgDtector import ROSImageGetter  
from RotatingDailyLogger import RotatingDailyLogger  
import json  
from datetime import datetime  

# 读取配置文件  
config_path = "/home/dexforce/workspace/dexe_application/vision/example/vision_config.json"  
with open(config_path, 'r', encoding='utf-8') as f:  
    &nbsp;&nbsp;param = json.load(f)  
log_dir = param["logging_path"]  
logger = RotatingDailyLogger(log_dir=log_dir, max_lines=100000)  
current_time = datetime.now().strftime("%Y%m%d_%H%M%S")  

# ros2 topic获取双目左右目图像  
image_getter = ROSImageGetter(topic_name = '/camera/kfc_compressed', use_left_only=False)  
left_img , right_img = image_getter.get_image(timeout=0.5) # 获取左右目RGB图像  

# 双目成点云 
stereo_to_point = StereoPointAdaptor()  
stereo_to_point.register(logger=logger, param=param,imgs=[left_img,right_img])  
_,pcd = stereo_to_point.detect(save_name=current_time,imgs=[left_img,right_img])  # 点云保存地址在vision_config中定义

4.5.2.4 语音接口

4.5.2.4.1 常用核心接口

关于语音部分，功能包目前放置在/home/dexforce/workspace/dexe_application/tools，通过以下命令进行导入。

常用核心接口说明

FunctionParameterDescription
chatStrByStrString根据用户提供的字符串返回一个模型回答的字符串
push_task_resString将话语添加到播放队列
play_textString打断当前话语并且直接播放该字符串
_execute_commandString，String根据用户的话语以及任务模块做出对应处理
recorder_taskNone持续检测录音音频并转成对应字符串
4.5.2.4.2 使用方法

提供用户可选择的配置文本，可在启动服务之前自由切换，若不填则用语音配置的默认文本，将唤醒状态以及每一次的TTS与ASR文本输出在UI浏览页面上，方便对语音查看，点击启动语音服务new启动该语音模块ui界面，启动后的配置默认读两个json——device.json和voice.json，其中device.json为高级配置，一般不需要改变，可以调整声音监测的音量大小、间隔时间、ASR与TTS配置，语音chat的角色。voice.json模块放置了一些相似度匹配的话语，可以自由调配或者自定义一个新的该配置文件并且在启动语音之前在用户配置文件中选择自定义配置文件。

  class ConfigManager:

    def __init__(self, user_path: str = None):
        # 设置默认路径
        self.base_path = "/home/dexforce/workspace/dexe_application/application/parameters/device.json"
        
        self.user_path = (
            user_path
            or "/home/dexforce/workspace/dexe_application/application/parameters/voice.json"
        )

        # 加载并合并配置
        self.config = self.load_config(self.base_path, self.user_path)