跨维智能产品文档中心

简体中文

English

简体中文

English

外观

软件进阶功能介绍

约 26683 字大约 89 分钟

此章节介绍了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 Controller 中一键让机器人自动复现刚才录制的整套动作。

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 菜单栏

功能项说明
状态监测可视化监控机器人运行状态，包含关节看板、末端执行器看板等子模块，支持查看关节参数、部件状态等核心运行数据。
整机控制
提供机器人全局控制功能，包含模式选择（自动控制 / 遥操作模式切换）、预设动作调用等子功能，支持对机器人整机运行逻辑的配置与管理。
模型部署暂不对外开放
手眼标定实现机器人 “手（末端执行器）” 与 “眼（视觉传感器）” 的坐标系统一校准功能，为视觉引导的作业任务提供精度保障。
故障诊断显示当前未解除的故障集合，记录所有的报错与预警历史，可排查关节电机相关的软硬件故障。
运动速度通过运动速度滑块可调节机器人所有关节电机的运动速度（除底盘电机）。
休眠模式开启后机器人关节电机将进入“去使能，抱闸开启”状态。适用于需要机器人进入短暂休息的场景。
拖拽模式开启拖拽模式后，机器人双臂可自由拖拽。
复位点击后将重启system/devices/当前整机模式（自动/建图/遥操/ACT/），重启后可通过状态监测/故障诊断等页面判断系统各个模块是否恢复为正常状态
打包日志支持日志一键导出至指定路径
导出日志内容：
"PC1": [
"/home/dexforce/log",
"/etc/dexe_robot",
],
"PC2": [
"/home/dexforce/log",
"/etc/dexe_robot",
]
清错恢复点击清错恢复后将执行关节电机清错指令。
故障排查开启故障排查后可排查关节电机接线问题，Ethercat软件问题，电机故障，该功能已合并至 故障诊断 模块。

4.3.1.2 可视化视窗

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

4.3.1.3 日志区

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

4.3.1.4 状态栏

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

4.3.1.5 机器人信息

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

说明
基础信息
DexE版本显示DexE系统大版本号
机器人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 关节曲线

支持显示头、躯干、左臂、右臂、左手、右手的关节曲线（行程/行程error/速度/力矩），灵巧手（电流），保存打开X-Wiz后1h内的数据，便于现场操作人员实时查看与分析。

  • 可查看头+躯干、左臂、右臂、左手、右手的关节曲线，支持选中关节组内的任意一个关节查看；可查看左手、右手的电流。

  • 可切换时间轴长度

  • 可放大框选指定区域，支持重置放缩。

  • 支持导出当前数据

4.3.2.3 末端执行器看板

实时显示机器人末端执行器的闭合程度、力矩、末端执行器状态告警等关键参数，显示末端执行器的品牌和型号，通过工作状态指示灯（绿灯表示连通，红灯表示未连通）反馈末端执行器的连通状态。

说明取值范围单位
左/右手灵巧手有6个指关节，分别是大拇指1、大拇指2、食指、中指、无名指、小拇指//
闭合程度手指当前的弯曲状态，0 代表完全张开，100 代表完全闭合。[0.0, 100.0]%
力矩手指关节输出的力[-100.0, 100.0]牛米（N·m）
末端执行器状态告警支持灵心/强脑两款灵巧手的运行状态监测
空闲中/运动中/电机报错/USB未连接/找不到ID/

支持一键修改末端执行器ID

4.3.2.4 传感器

支持一键查看头部相机、腕部相机、底盘3D相机、底盘激光雷达、IMU的连通性、帧率、取图状态，实时显示防撞条、急停按钮的触发状态。

  • 头部相机

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

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

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

  • 腕部相机

提供末端执行器近距离视角，显示 RGB 图、深度图和点云图。

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

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

  • 底盘3D相机

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

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

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

  • 底盘激光雷达

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

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

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

  • 防撞条

底盘前后各有1个防撞条，“触发”表示防撞条与周围物体发生碰撞，触发了机器人的急停功能。

  • 急停按钮

“触发”表示出现紧急情况，触发了机器人的急停功能。

  • IMU

惯性测量单元安装于底盘内，用于实时感知机器人的姿态、角速度和线加速度。

4.3.2.5 运维看板

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

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

4.3.3 整机控制

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

4.3.3.1 模式切换

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

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

4.3.3.2 预设动作

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

4.3.4 手眼标定

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

4.3.4.1 校验已标定矩阵

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

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

4.3.4.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.3.5 故障诊断

功能项说明
当前故障实时显示系统当下未解除的故障集合，提供故障排查指引。
  • 支持显示故障和预警数量
  • 支持模糊搜索与时间筛选
  • 支持关节/末端执行器/传感器/运维/其他（故障排查中的故障）分类筛选
  • 支持配置低电量阈值
历史记录记录所有的报错与预警历史，用于事后溯源。
故障排查支持主动排查关节电机相关的软硬件故障。
点击 开始故障排查按钮可排查硬件和软件问题
  • 排查软件问题，若排查出软件问题，点击 清错恢复 可尝试重新建立通信并让从站回到正常运行状态。
  • 排查电机接线问题，比如电机接线是否存在断线，统计断线次数提醒问题所在，可以检测到具体断开的线束，请根据排查结果检查机器人电机线缆。
提示窗口支持在任意页面（除故障诊断）中实时显示当下未解除的故障集合。可上报关节/底盘电机、灵巧手、雷达、相机、系统资源、网络、电池等故障详情。

4.4 W1 Controller

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

在PC2的桌面双击 W1 Controller 图标打开软件

布局功能
顶部工具栏全局机器人控制、模式切换、文件管理及添加行为按钮
中央画布区任务流编排区，包含独立行为库与多个自定义任务列，顶部是任务流编辑工具
右侧辅助面板包含全局“任务与行为树”导航，以及“Vision Teach”视觉示教坐标管理。

4.4.1 功能操作

功能模块功能描述
文件管理
新建json文件
点击左上角新建按钮，默认打开workspaces路径，命名后创建新的 JSON 配置文件。
打开json文件点击【打开】按钮，在默认 workspaces 文件夹中选择 JSON 文件加载。
保存json文件
  • 修改参数后，按 Ctrl+S 或通过菜单栏【文件】→【保存】执行保存
  • 系统自动将连线逻辑（continuous）、参数字典、示教点位打包格式化为符合底层要求的 JSON 格式并写入文件
  • 自动恢复：关闭软件后再次打开，会自动加载上次打开的文件路径
  • 退出防丢：若有未保存的修改，关闭软件时会弹窗提醒。
画布操作平移画布画布空白处点击并拖动，或使用横向/纵向滚动条
缩放画布Ctrl + 鼠标滚轮（向上放大，向下缩小）
横向滚动Shift + 鼠标滚轮
复制/剪切/粘贴Ctrl+C / Ctrl+X / Ctrl+V（选中行为块后操作）
保存配置Ctrl+S
系统服务控制
语音服务控制软件启动时默认不显示语音界面。界面提供两个控制按钮：
  • 关闭语音服务：停止后台语音服务
  • 打开语音界面：显示语音交互面板
HTTP 服务点击开启http，再次点击触发后端关闭http
仿真服务点击开启仿真，再次点击触发关闭仿真服务
启动 PickWiz调用pickwiz_start.py，成功打开pickwiz
数据获取与日志获取内参接收内参话题数据，获取内参文件并保存至 vision/config 文件夹。内参用于视觉传感器的标定与图像校正。
实时取图点击弹出实时左右目图像窗口，窗口会自动关闭。用于验证双目视觉传感器的图像采集功能。
保存 PC1 日志点击获取 PC1 日志并保存，用于故障排查与运行状态分析。
机器人控制开关拖拽
开启拖拽后，机器人双臂可自由拖拽。
中断执行运动中点击中断执行，停止执行任务
选择模式
点击选择对应模式，机器人将会切换模式
清除op错误点击按钮查看终端，已经清除op错误

4.4.2 任务流与行为块管理

功能模块功能描述
任务流
新增任务流
点击顶部【新增任务流】按钮，输入名称即可创建一个新的列。
列排序
  • 点击列标题旁的左右箭头按钮可以移动任务流。
任务级配置
  • 点击列头的【配置】可编辑该任务的自定义数据（如 thread_move 等 JSON 数据）。
执行任务流点击列头的【任务】会向机器人下发该列中所有的行为。
行为


ACT默认配置act行为，包含打招呼、握手、打招呼+握手，支持直接执行或拖动到主任务流后点击执行
添加行为块
可以点击左上角添加运动行为、定位行为、视觉行为到画布中，默认添加到独立行为库中，用户可以选择任务中某个行为添加插入到任务中该行为下。
拖拽行为块鼠标按住行为块左上角的拖拽图标或类型标签（如“运动行为”），即可将其拖入任意任务流中，或改变其在当前流中的顺序。跨行为拖拽机械臂卡片：可以按住单条机械臂指令旁的拖拽图标，实现上下排序，甚至将该机械臂指令直接拖拽到另一个运动行为块中。
展开/折叠行为行为点击展开按钮可以展开和折叠展开前：展开后，可以修改其中参数：
多选删除拖拽多选行为，键盘点击dele删除全部

4.4.3 核心行为模块

系统提供四种核心模块：运动行为、视觉行为、定位行为、底盘行为。

4.4.3.1 运动行为

用于控制机器人头部、躯干以及双臂的运动。

功能描述
多段语音控制支持展开添加多行语音，可配置模式（auto/tts/wav）、音色、情绪与语速。
头与躯干控制
  • 可填写目标坐标，支持点击【获取】直接读取机器人当前位姿，点击【执行】进行动作测试。支持勾选“双臂同动”与设置“延迟躯干”。
机械臂与夹爪卡片
  • 支持动态添加多种运动类型（movel_l, movec_r, movej_l 等）。
  • 支持删除、隐藏运动行为卡片
  • 每个卡片包含：机械臂 6 轴坐标、运动速度、夹爪前/后延时、夹具坐标。
  • 示教绑定：可下拉选择右侧面板中保存的 Vision Teach 点位。
  • 固定运动/额外属性：可通过勾选框开启固定运动（hto）等拓展参数。
  • 自定义参数：可点击顶部【添加自定义参数】挂载任意特殊键值对。
4.4.3.2 视觉行为

用于配置 YOLO 视觉识别及分支逻辑。

功能描述
基础参数
  • 配置摄像头数量、置信度阈值 (conf_thresh)、连续识别帧数、模型路径。
保存图片选择在识别成功 (T) 或失败 (F) 时是否保存现场图片。
ROI 与类型识别
  • 点击【添加类型】定义需识别的物体（如 cup）。
  • 点击【ROI配置】，将弹出实时相机画面，支持用鼠标在画面上直接拉框，自动生成坐标数据填入。
动态条件分支
  • 根据您添加的识别类型，系统会自动生成真值表（如 T, F）。
  • 您可以在下拉菜单中为每种识别结果绑定后续要执行的“行为名称”，实现逻辑分流。
  • 一种类型有两种情况，两种类型有四种情况
4.4.3.3 定位行为

用于 3D 视觉与位姿配准。

功能描述
视觉模型下拉选择点云匹配算法（point_and_match 或 plane_fitting）。
匹配类型与映射语音
  • 设定全部匹配成功时的语音 (in_voice)。
  • 点击【添加匹配类型】，配置目标类型，以及对应的“无视觉目标语音 (no_voice)”和“点云异常语音 (no_3d_voice)”。
4.4.3.4 底盘行为

用于底盘运动与导航。

模式选择：有ctrl nav 两种模式

ctrl模式：控制机器人偏移多个点位

nav模式：导航机器人到对应导航点

4.4.4 辅助工具与右侧面板

布局功能描述
右侧面板任务与行为树整个画布内容的精简目录结构。点击树中的任意任务、行为或机械臂卡片，中央画布会自动平移并缩放定位到该模块，非常适合在大型项目中快速导航。树节点右侧附带快捷执行按钮，方便测试。
最左上角全部折叠按键全部展开/折叠操作
视觉示教坐标管理
视觉定位点数据用于管理全局的视觉定位点数据（即 vision_app_pose.json）。
操作
  • 点击【获取坐标】可从本地参数文件vision_app_pose.json加载视教坐标到parameter.json。
  • 列表中可单独一【同步】当前坐标，或勾选是否加入 acc_test 属性。
  • 在运动行为模块的“示教”下拉框中，会自动读取这里的点位名称。

4.5 二次开发入门

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

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

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

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

4.5.1 常用话题

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

完整的接口说明请参考附件：二次开发接口说明 V0.4.5.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/ee/left
左侧末端执行器信息
/feedback/ee/left
右侧末端执行器信息
/feedback/ee/right
header：标准消息头
string ee_name：末端设备名称
uint8[] status：末端执行器状态
EEJointState[] joint_states：关节状态
EETactileState[] tactile_states：触觉传感器状态
机器人关节控制话题
全身关节控制
/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/ee/left
控制右侧末端执行器
/control/ee/right
消息类型：end_effector_interfaces/msg/EEJointControl
header：标准消息头
string[] joint_names{ //关节名称列表
// 6自由度灵巧手：
“T_MCP”; //拇指弯曲
“T_CMC_YAW”; //拇指摆动
“IF_MCP_PITCH”; //食指弯曲
“MF_MCP_PITCH”; //中指弯曲
“RF_MCP_PITCH”; //无名指弯曲
“LF_MCP_PITCH”; //小指弯曲
// 夹爪
“FINGER1”; // 夹爪开合
};
uint8 mode{ //控制模式，枚举
0：POSITION; //位置控制
1：VELOCITY; //速度控制
2：CURRENT; // 电流控制
3：FORCE; // 力控制
};
float32[] 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]
  • 当mode=3时value为各关节的 “力输出比例”，取值范围是[-100, 100]
可直接在命令行输入如下指令测试话题接口
#强脑/灵心巧手L6
ros2 topic pub /control/ee/left
end_effector_interfaces/msg/EEJointControl "{mode: 0, joint_names: ['T_CMC_YAW','T_MCP','IF_MCP_PITCH','MF_MCP_PITCH','RF_MCP_PITCH','LF_MCP_PITCH'], values: [10.0,10.0,10.0,10.0,20.0,20.0]}"
#灵心巧手L20
ros2 topic pub /control/ee/left end_effector_interfaces/msg/EEJointControl "{mode: 0, joint_names: ['T_CMC_ROLL','T_CMC_YAW','T_CMC_PITCH','T_MCP','IF_MCP_ROLL','IF_MCP_PITCH','IF_PIP','MF_MCP_ROLL','MF_MCP_PITCH','MF_PIP','RF_MCP_ROLL','RF_MCP_PITCH','RF_PIP','LF_MCP_ROLL','LF_MCP_PITCH','LF_PIP'], values: [10.0,10.0,10.0,10.0,20.0,20.0,20.0,20.0,20.0,20.0,20.0,20.0,20.0,20.0,20.0,20.0]}"
#大寰夹爪
ros2 topic pub /control/ee/left end_effector_interfaces/msg/EEJointControl "{mode: 0, joint_names: ['FINGER1'], values: [10.0]}"
#松灵夹爪
ros2 topic pub /control/ee/right end_effector_interfaces/msg/EEJointControl "{mode: 0, joint_names: ['FINGER1'], values: [100.0]}"
#灵巧dexhand021s
ros2 topic pub /control/ee/left end_effector_interfaces/msg/EEJointControl "{mode: 0, joint_names: ['FINGER1', 'FINGER2', 'FINGER3', 'REVOLVE'], values: [10.0,10.0,10.0,10.0]}"
底盘话题获取当前底盘位置
/feedback/chassis_pose
标准ROS2消息 geometry_msgs/PoseStamped
  • header：标准消息头
  • float[] pose.position：[x,y,z]笛卡尔坐标系下位置矩阵
  • float[] pose.orientation：[x,y,z,w]笛卡尔坐标系代表姿态的四元数
直接订阅获取底盘当前位置
ros2 topic echo /feedback/chassis_pose
控制底盘前往目标位置（带避障）
/control/nav2_pose
标准ROS2消息 geometry_msgs/PoseStamped
  • header：标准消息头
  • float[] pose.position：[x,y,z]笛卡尔坐标系下位置矩阵
  • float[] pose.orientation：[x,y,z,w]笛卡尔坐标系代表姿态的四元数
# 以下指令会让机器人带动态避障地去到{x: -0.215, y: -0.193, z: 0.0}点位
ros2 topic pub --once /control/nav2_pose geometry_msgs/msg/PoseStamped "{header: {stamp: {sec: 0, nanosec: 0}, frame_id: 'map'}, pose: {position: {x: -0.215, y: -0.193, z: 0.0}, orientation: {w: 1.0}}}"
控制底盘相对移动（无避障）
/control/ctrl_pose
标准ROS2消息 geometry_msgs/PoseStamped
  • header：标准消息头
  • float[] pose.position：[x,y,z]笛卡尔坐标系下位置矩阵
  • float[] pose.orientation：[x,y,z,w]笛卡尔坐标系代表姿态的四元数
# 以下指令会让机器人前进0.1m
ros2 topic pub --once /control/ctrl_pose geometry_msgs/msg/PoseStamped "{header: {stamp: {sec: 0, nanosec: 0}, frame_id: 'base_link'}, pose: {position: {x: 0.1, y: 0.0, z: 0.0}, orientation: {w: 1.0}}}"

4.5.2 二次开发指引

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

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

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

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

# 1. 导入功能包
from dexe_robot_client.common import W1Version, W1ArmType
from dexe_robot_client.end_effector_client import EndEffectorType
from dexe_robot_client.w1 import W1Manager

# 2. 实例化 W1Manager
w1_manager = W1Manager(is_sim=False, # 用真机，不是仿真
    arm_type=W1ArmType.ANTHROPOMORPHIC, # 拟人型双臂
    w1_version=W1Version.V2, # W1机器人的V2版本
    end_effector_type=EndEffectorType.BRAINCO_HAND, # 末端是强脑灵巧手
    use_nav=True # 需要导航功能
    )

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

# 获取当前全身坐标
result1 = w1_manager.get_current_qpos("full_body")
print('当前全身关节坐标是:',result1)

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

4.5.2.1 全身运动控制API

全身运动控制接口是二次开发任务的核心必用接口，下面列出一些全身运动控制接口的示例，您可以直接参考其源码实现，也可以在您的项目中基于ROS2原生接口（Topic/Service/Action）重新实现更灵活的控制逻辑。

wholebody_example.zip

使用时先进行带全身运动的实例化：

from dexe_robot_client.common import W1Version, W1ArmType
from dexe_robot_client.end_effector_client import EndEffectorType
from dexe_robot_client.w1 import W1Manager

w1_manager = W1Manager(is_sim=False,
    arm_type=W1ArmType.ANTHROPOMORPHIC,
    w1_version=W1Version.V2,
    end_effector_type=EndEffectorType.BRAINCO_HAND,
    use_nav=False)
序号函数参数返回/效果接口单例文件
1get_current_qpos
获取当前坐标（关节坐标系）
name (str, 可选)：指定部件名称，可选值："full_body"、"torso"、"head"、"left_arm"、"right_arm"、"left_arm_ee"、"right_arm_ee"，默认 "full_body"返回 tuple[bool, np.ndarray]：成功标志 + 当前关节位置数组
# 获取当前全身坐标
result1 = w1_manager.get_current_qpos("full_body")
print('当前全身关节坐标是:',result1)
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]
# 获取当前机械臂坐标
result1 = w1_manager.get_current_pose("left_arm")
print('当前左机械臂笛卡尔坐标是:',result1)
result2 = w1_manager.get_current_pose("right_arm")
print('当前右机械臂笛卡尔坐标是:',result2)
3move_joint_full_body
关节全身运动（关节坐标系）
waypoints_dict (dict)：各部件目标关节位置字典，支持多路点 speed_ratio (float, 可选)：速度比例，默认 1.0返回 bool：执行是否成功
同时观察机器人是否运动成功
# 发送全身关节信息给w1_manager并执行关节运动
success = w1_manager.move_joint_full_body(
waypoints_dict = {
'left_arm': [[0.962, -0.771, -0.949, -2.072, 0.435, -0.004, 0.012]],
"left_arm_ee": [[0.,[100, 0, 50, 50, 50, 50],0.5],],
'right_arm': [[-1.003, 0.722, 0.868, 2.024, -0.459, 0.116, -0.152]],
"right_arm_ee": [[0.,[0, 100, 0, 100, 100, 100],0.5],],
'torso': [[0.6010295675546937, -1.2020591351093874, 0.6010295675546937, 0.03490658503988659]],
'head': [[0.0, 0.0]]
},
speed_ratio = 0.8
)
if success:
print("运动完成")
else:
print("运动失败")
4move_linear_full_body
线性运动（笛卡尔坐标系）
waypoints_dict (dict)：各部件目标位姿字典，支持多路点 left_qpos_seed (np.ndarray, 可选)：左臂 IK 参考关节位置 right_qpos_seed (np.ndarray, 可选)：右臂 IK 参考关节位置 cartesian_step (float, 可选)：笛卡尔采样步长，默认 0.005speed_ratio (float, 可选)：速度比例，默认 1.0is_local (bool, 可选)：是否基于机械臂基座坐标系，默认 True
返回 bool：执行是否成功
同时观察w1是否运动成功
# 设置夹爪初始姿态,若不设置，则右手运动会有180度的旋转偏差
import numpy as np
from scipy.spatial.transform import Rotation
left_tcp_xpos = np.eye(4)
left_tcp_xpos[2, 3] = 0
w1_manager.set_tcp("left_arm", xpos=left_tcp_xpos)
right_tcp_xpos = np.eye(4)
right_tcp_xpos[2, 3] = 0
right_tcp_xpos[:3, :3] = Rotation.from_rotvec([0.0, 0.0, 180.], degrees=True).as_matrix()
w1_manager.set_tcp("right_arm", xpos=right_tcp_xpos)
# 发送左右臂关节信息给w1_manager并执行线性运动
success = w1_manager.move_linear_full_body(
waypoints_dict = {
"left_arm": [
[-107.56, 246.26, 507.46, -57.09, 40.78, 20.93]
],
"left_arm_speed_ratio": [],
"left_arm_ee": [[0.,[100, 0, 50, 50, 50, 50],0.5],],
"right_arm": [
[20.02, 330.78, 186.65, -136.37, -50.51, 72.45]
],
"right_arm_speed_ratio": [],
"right_arm_ee": [[0.,[0, 100, 0, 100, 100, 100],0.5],]
},
speed_ratio = 0.8
)
if success:
print("运动完成")
else:
print("运动失败")
5set_ee_qpos
夹具开合设置
name (str)：末端执行器名称，"left_arm_ee" 或 "right_arm_ee"qpos (np.ndarray)：目标位置，范围 0~100返回 bool：设置是否成功
同时观察灵巧手是否运动成功
# 为右边灵巧手设置一个开合角
success = w1_manager.set_ee_qpos(
"right_arm_ee",
# 或 "right_arm_ee"
[0, 0, 50, 50, 50, 50]
# 6个手指关节角
)

if success:
print("灵巧手运动成功")
6stop_move
停止运动
timeout_sec (float, 可选)：停止等待超时时间，默认 3.0 秒返回 bool：停止是否成功# 停止运动接口
success = w1_manager.stop_move(timeout_sec= 1.0)
if success:
print("停止运动成功")
print("程序结束")
7set_drag_mode
enable (bool)：控制拖拽模式状态的开关。
  • True：开启拖拽模式。
  • False：关闭拖拽模式。
用于控制机器人进入或退出拖拽示教模式（也称为零力控制模式或重力补偿模式）。开启该模式后，操作员可以直接用手物理拖动机械臂的关节或末端到达指定位置from dexe_robot_client.common import W1Version, W1ArmType
from dexe_robot_client.end_effector_client import EndEffectorType
from dexe_robot_client.w1 import W1Manager
import time

w1_manager = W1Manager(is_sim=False,
arm_type=W1ArmType.ANTHROPOMORPHIC,
w1_version=W1Version.V2,
end_effector_type=EndEffectorType.BRAINCO_HAND,
use_nav=False)

success1 = w1_manager.set_drag_mode(True)
if success1:
print("拖拽模式已开启，将持续30s...")

time.sleep(30)

success2 = w1_manager.set_drag_mode(False)
if success2:
print("拖拽模式已关闭...")

time.sleep(1)
8clear_robot_error/用于当机器人出现关节超出限位后的恢复。一般执行后可以通过set_drag_mode回到安全位置from dexe_robot_client.common import W1Version, W1ArmType
from dexe_robot_client.end_effector_client import EndEffectorType
from dexe_robot_client.w1 import W1Manager

w1_manager = W1Manager(is_sim=False,
arm_type=W1ArmType.ANTHROPOMORPHIC,
w1_version=W1Version.V2,
end_effector_type=EndEffectorType.BRAINCO_HAND,
use_nav=False)

success = w1_manager.clear_robot_error(True)
if success:
print("成功执行清错指令")
9set_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", xpos=left_tcp_xpos)

# 右臂(180度旋转)
right_tcp_xpos = np.eye(4)
right_tcp_xpos[2, 3] = 0
right_tcp_xpos[:3, :3] = R.from_rotvec([0.0, 0.0, 180.], degrees=True).as_matrix()
self.w1_manager.set_tcp("right_arm", xpos=right_tcp_xpos)

4.5.2.2 底盘控制接口

下面列出一些底盘控制接口的示例，您可以直接参考其源码实现，也可以在您的项目中基于ROS2原生接口（Topic/Service/Action）重新实现更灵活的控制逻辑。

chasis_example.zip

使用底盘控制接口前需要先完成建图，请参考 底盘建图及导航 进行。

使用时先进行带底盘运动的实例化：

import numpy as np
from dexe_robot_client.common import W1Version, W1ArmType, StatusCode
from dexe_robot_client.end_effector_client import EndEffectorType
from dexe_robot_client.w1 import W1Manager

# 实例化 W1Manager (系统总指挥)
w1_manager = W1Manager(
    is_sim=False,                                     # 实车模式
    arm_type=W1ArmType.ANTHROPOMORPHIC,               # 拟人臂
    w1_version=W1Version.V2,                          # V2 版本
    end_effector_type=EndEffectorType.BRAINCO_HAND,   # 灵巧手
    use_nav=True                                      # 【必填】开启底盘导航功能
)
序号函数参数返回/效果接口单例
1get_current_chassis_pose
获取底盘当前位姿		无
tuple[StatusCode, np.ndarray]。如果成功，np.ndarray 为 [x_m, y_m, yaw_deg]
获取底盘在地图坐标系下的绝对坐标。底层调用了 Client，并在成功时返回位姿数据。
status, pose = w1_manager.get_current_chassis_pose()
if status == StatusCode.SUCCESS:
print(f"当前底盘坐标: X={pose[0]:.2f}m, Y={pose[1]:.2f}m, 偏航角={pose[2]:.2f}°")
2move_chassis_nav2
执行 Nav2 全局导航
base_position (np.ndarray 或 list) -> [x_m, y_m, yaw_deg]
StatusCode (SUCCESS 或 FAIL)。
通过建好的地图让机器人自动避障前往绝对坐标点。		target_pose = np.array([3.0, -1.5, 180.0])
if w1_manager.move_chassis_nav2(target_pose) == StatusCode.SUCCESS:
print("导航指令发送成功，正在前往目标点...")
3get_nav_status
获取全局导航状态		无获取当前全局导航状态（如 "SUCCEEDED", "NAVIGATING"）。通常配合上面的接口做 while 循环判定到达。
查询 Nav2 导航任务的执行进度，常用于阻塞等待逻辑中的轮询校验。		if w1_manager.get_nav_status() == "SUCCEEDED":
print("全局导航已抵达目标！")
4move_chassis_ctrl
执行 Ctrl 相对运动
base_position (np.ndarray 或 list) -> [x_m, 0.0, yaw_deg]StatusCode
让机器人相对当前位置进行高精度的盲走/盲转。（切记：平移与旋转不可同时进行）。		# 纯平移：向后退 0.3 米
w1_manager.move_chassis_ctrl(np.array([-0.3, 0.0, 0.0]))
# 纯旋转：原地右转 45 度
w1_manager.move_chassis_ctrl(np.array([0.0, 0.0, -45.0]))
5get_control_status
获取相对控制状态 		无str (如 "IDLE", "CONTROL", "DISABLED")。
查询底层高精度相对控制的运行状态。		if w1_manager.get_control_status() == "IDLE":
print("底盘相对运动已停止，处于空闲状态。")
6cancel_chassis_motion
统一取消运动 (紧急刹车) 		无
StatusCode (只要有一个底层的取消指令发送成功即返回 SUCCESS)。
聚合封装的高级接口。无论底盘当前是在跑 Nav2 全局导航，还是在跑 Ctrl 相对运动，调用此方法都会向两者发送取消信号，强制底盘停下。		# 遇到视觉检测到危险，紧急叫停底盘
status = w1_manager.cancel_chassis_motion()
if status == StatusCode.SUCCESS:
print("紧急刹车指令已生效！")
7get_current_battery_percentage
获取电池电量		无tuple[StatusCode, float]。如果成功，float 为电量百分比（如 85.5 代表 85.5%）。status, battery = w1_manager.get_current_battery_percentage()
if status == StatusCode.SUCCESS and battery < 20.0:
print(f"警告：电量仅剩 {battery}%，准备自动回充！")

4.5.2.3 2D视觉接口

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

封装了一部分2D视觉接口在vision_detector.py中，下面列出一些2D视觉接口的示例，您可以直接参考其源码实现，也可以在您的项目中基于ROS2原生接口（Topic/Service/Action）重新实现更灵活的控制逻辑。

vision_detector.py

注意使用时先做如下导入：

from vision_detector import VisionDetector
detector = VisionDetector(image_getter=camera_obj) # imager_getter也可以不传
主要函数参数返回接口单例
get_camera_image
相机取图接口
timeout (float, 默认 0.5): 获取图像的超时时间（秒）
np.ndarray | None: 成功时返回 OpenCV 格式的图像矩阵 (BGR)，失败或超时返回 None
image = detector.get_camera_image(timeout=1.0)
if image is not None:
print("获取图像成功")
detect_color_hsv
HSV 颜色识别接口
image (np.ndarray): 待分析的原图。
roi_coords (list): 需要分析颜色的区域 [x, y, width, height]		tuple: 返回四元组 (颜色名称(str), 平均R值(int), 平均G值(int), 平均B值(int))color_name, r, g, b = detector.detect_color_hsv(image, [100, 100, 50, 50])
print(f"该区域的颜色主要为: {color_name}")
draw_detections
可视化绘制接口
image (np.ndarray): 原始图像。
detections (list): 需要画绿框的目标列表。
roi_coords (list, 默认 None): 静态 ROI 区域列表，格式可为 [x,y,w,h] 或 [[x1,y1,w1,h1], ...]。
is_dynamic (bool, 默认 False): 当前是否启用了动态活框。
ref_rois (list, 默认 None): 动态活框的坐标列表。		np.ndarray: 绘制好框线的全新图像矩阵（不污染原图）。
# 画出目标，并画出两个静态排查区域
draw_img = detector.draw_detections(
image, detections=valid_apples, roi_coords=[[0,0,100,100], [200,200,100,100]]
)

4.5.2.4 ACT运动控制接口

如果您需要让机器人学习遥操采集的海量数据，自主生成并执行一连串流畅的动作，那么就需要使用ACT运动控制接口。下面列出一些ACT运动控制接口的示例，您可以直接参考其源码实现，也可以在您的项目中基于ROS2原生接口（Topic/Service/Action）重新实现更灵活的控制逻辑。

Act.zip

使用前先下载Act代码包，并在你自己的代码中进行如下导入：

from Act.ActOut import CombinedACTNode, ACTLifecycleManager

# 1. 实例化 ACT 节点 (支持传入外部已连接的 w1_manager 和 logger)
act_node = CombinedACTNode(
    config_file_path="/path/to/act_config.json"， 
    external_w1_manager=self.w1_manager, # 可选参数，不传入该参数则ActOut自身会进行w1_manager的实例化
    external_logging=logging # 可选参数，不传入该参数则ActOut自身进行日志管理
)

# 2. 调用连接以确认机器人状态
act_node.connect_robot()

# 3. 实例化并启动生命周期管理器 用于资源管理
act_manager = ACTLifecycleManager(act_node)
act_manager.start()
序号函数参数返回/效果接口单例
1set_act_using()
status (bool): True 表示启用 ACT 运动，False 表示停用（软挂起）。ACT 的“软开关”。开启时恢复控制逻辑并自动加载防碰撞环境；关闭时挂起控制逻辑，清空积压指令，并加载无碰撞空环境act_node.set_act_using(False)
2run_motion_from_origin()
timeout (float, 可选): 等待话题稳定的超时时间，默认 10.0 秒。bool: 启动成功返回 True，话题不稳定或回原点失败返回 False。
启动完整运动流程。会先检查话题稳定性，然后执行插值回到默认姿态，最后正式开启运动权限		success = act_node.run_motion_from_origin(timeout=5.0)
3stop_motion()无
bool: 成功停止返回 True，如果本来就不在运行则返回 False。act_node.stop_motion()
4is_motion_stable()
无bool: 活跃且稳定返回 True，指令流中断返回 False。 检查当前大模型下发的话题指令流是否稳定且活跃。如果超过 0.5 秒未收到新指令，会判定为不稳定if not act_node.is_motion_stable():
logging.warning("数据流中断！")
5check_robot_error()
无
bool: 发现报错返回 True，正常运行返回 False。
检查机器人底层硬件是否报错（如超速、超力矩或未 OP）。一旦发现错误，内部会自动停用 ACT，防止危险发生。		if act_node.check_robot_error():
print("机器人底层报错，已紧急停止。")
6get_current_qpos_20d()无
Optional[np.ndarray]: 成功获取返回 20 维浮点数 numpy 数组，失败返回 None
获取当前机器人全身的 20 维关节真实坐标（包含左右臂、躯干、头部）		current_pos = act_node.get_current_qpos_20d()
if current_pos is not None:
print("当前腰部坐标:", current_pos[3])
7pause()此三类方法为Act资源管理方法无挂起后台的 ROS 2 Spin 线程执行。释放底层的 WaitSet 资源，防止与主任务发生资源竞争引发报错。act_manager.pause()
8resume()无
恢复后台的 ROS 2 Spin 线程执行。重新接管话题订阅与发布。act_manager.resume()
9stop()无永久销毁后台 Spin 线程，退出循环，通常在程序关闭或彻底重启 ACT 时使用。act_manager.stop()