软件进阶功能介绍

约 12193 字大约 41 分钟

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

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 重启导航服务

关闭建图服务，重启导航服务，默认导航使用map_2_standard地图

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相关节点并未完全杀死导致，需要完全杀死导航节点，再重新启动导航节点。

4.1.4 自动回充

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

4.1.4.1 前提条件

自动回充之前，需确保机器人建图完成，已生成一张完整的地图，让机器人知道自己身处的地图环境。
自动回充之前，需要开启导航功能，让机器人能够自动导航到充电桩位置。

4.1.4.2 重定位机器人

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

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

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

4.1.4.3 设置回充点位置

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

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

打开 PC1 的 Terminal 终端，执行如下命令，得到机器人当前的位置并将这个位置保存为回充点。

cd ~/w1 && source install/setup.bash && ros2 run mobile_perception create_charging_pose.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键	长按 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 模式，同时左手点击 X 键 + 右手点击 A 键长按3秒可返回模式选择界面。

信息类别	模式/状态	含义	描述
底盘/腿部模式	底盘	机器人底盘模式	驻车：底盘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”。

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 结束遥操

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

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

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

4.2.9 遥操语音交互

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

4.2.10 遥操录制动作

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

4.2.10.1 指令录制demo

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

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

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

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

4.2.10.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.10.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.10.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 W1 控制界面

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

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

4.3.1 外设通讯模块

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

4.3.2 配置信息模块

配置读取	读取新的配置，暂时配置会自动加载，不支持在新的路径读取配置(目前软件自动读取配置，该按键暂无作用)
配置编辑	打开配置编辑UI，用户修改参数，需要点击保存才能更新配置信息
刷新配置	配置编辑保存完成后，需要点击该按钮，才会在当前程序中生效，否则需要重启软件

4.3.3 额外功能

图像分析	用于判断当前ROI区域的颜色是否等于设定的颜色，不相等时触发对应逻辑
P_vis检测	直接触发检测流程，调试配置算法参数，模块参数使用 p_vision 即启用该技术路径，视觉参数配置在 vision_config.json 文件中
物体检测	主要基于 yolo 检测模型，支持咖啡工作站全类别检测，支持选择 ROI 区域进行检测，可在图像中划定特定区域查看检测结果
配准查看	查看点云配准结果的功能

4.3.4 W1状态获取及控制模块

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

注意事项
注意这部分运动均是通过修改数值来运动，请一定要小心修改，再运动。
注意左右臂之间没有运动碰撞检测，运动输入错误，可能会导致左臂撞右臂。

4.3.5 日志显示区

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

4.3.6 语音模块

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

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

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

4.4 二次开发接口说明

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

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

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

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

类型	话题名称	话题内容	使用方法
相机话题	原图： /camera/left_eye /camera/right_eye	1920*1080图像，5Hz	直接订阅获取图像
resize图像： /camera/left_eye_resize /camera/right_eye_resize	960*540图像，30Hz
压缩图像： /camera/kfc_compressed	38401080的组合压缩图像，解码后为19201080图像,30Hz	需要解码话题图像使用。解码范例文件如下，可以使用代码中callback方法进行解码 Stereo_Receiver.py
机器人关节信息话题	真实机器人关节信息 /feedback/joint 仿真机器人关节信息 /feedback/joint_sim	header：标准消息头 Name：关节顺序 Position：关节角度（弧度） Velocity：关节速度（百分比） effort：	直接订阅获取关节状态
左手灵巧手信息 /feedback/hand/left 右手灵巧手信息 /feedback/hand/right	header：标准消息头 Name：灵巧手关节顺序 Position：关节角度（弧度） Velocity：关节速度（百分比） current： force： state：
机器人关节控制话题	全身关节控制 /control/joint_position	关节名称（用于控制）： 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	可直接在命令行输入如下指令测试话题接口 # 以控制头部关节为例 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/joint	下半身：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	可直接在命令行输入如下指令测试话题接口 # 以控制头部关节为例 ros2 topic pub /control/joint joint_interfaces/msg/JointControl " header: stamp: now frame_id: 'robot_base' name: ['NECK1', 'NECK2'] position: [0.2, 0.2] positive_velocity_limit: [0.5, 0.5] negative_velocity_limit: [-0.5, -0.5] positive_torque_limit: [5.0, 5.0] negative_torque_limit: [-5.0, -5.0] " --once
左手灵巧手 /control/hand/left 右手灵巧手 /control/hand/right	关节名称（用于控制）： name: 大拇指开合：THUMBMCP 大拇指旋转：THUMBCMC 食指：INDEXMCP 中指：MIDDLEMCP 无名指：RINGMCP 小拇指：LITTLEMCP	可直接在命令行输入如下指令测试话题接口 # 模式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.4.2 接口使用方法

4.4.2.1 上半身运动控制接口

现在每一台W1机器人都已经安装了dexe_robot_client包。使用时先进行实例化

相关核心接口示例文件如下，可通过以下文件中py代码单独运行某个运动接口。

example_script.zip

函数	参数	返回/效果	接口单例文件
get_current_qpos 获取当前坐标（关节坐标系）	`name` (str, 可选)：指定部件名称，可选值：`"full_body"`、`"torso"`、`"head"`、`"left_arm"`、`"right_arm"`、`"left_arm_ee"`、`"right_arm_ee"`，默认 `"full_body"`	返回 `tuple[bool, np.ndarray]`：成功标志 + 当前关节位置数组	example_get_current_qpos.py
get_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
move_joint_full_body 关节全身运动（关节坐标系）	`waypoints_dict` (dict)：各部件目标关节位置字典，支持多路点 `speed_ratio` (float, 可选)：速度比例，默认 `1.0`	返回 `bool`：执行是否成功同时观察机器人是否运动成功	example_move_joint_full_body.py
move_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是否运动成功	example_move_linear_full_body.py
set_ee_qpos 夹具开合设置	`name` (str)：末端执行器名称，`"left_arm_ee"` 或 `"right_arm_ee"qpos` (np.ndarray)：目标位置，范围 0~100	返回 `bool`：设置是否成功同时观察灵巧手是否运动成功	example_set_ee_qpos.py
stop_move 停止运动	`timeout_sec` (float, 可选)：停止等待超时时间，默认 `3.0` 秒	返回 `bool`：停止是否成功	example_stop_move.py
set_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.4.2.2 2D视觉接口

目前基于2D视觉的相关功能都写在home/workspace/dexe_application/application/basic_function.py中的Function类中。

类别	主要函数	参数	返回
传统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_yolo`	`roi_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_image`	`image`: 要保存的图像 (numpy数组) `picture_name`: 图片名称前缀 `result`: 检测结果("T"/"F") `class_name`: 目标类别 `confidence`: 置信度	无返回值。函数执行以下操作： • 成功: 将图像保存到 `qt/error/` 目录 • 失败: 记录错误日志 • 如果图片数量超过200张，删除最早的图片

4.4.2.3 3D点云、Topic取图、外参标定接口

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.4.2.4 语音接口

4.4.2.4.1 常用核心接口

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

from tools.voice_controller import VoiceController

常用核心接口说明

Function	Parameter	Description
chatStrByStr	String	根据用户提供的字符串返回一个模型回答的字符串
push_task_res	String	将话语添加到播放队列
play_text	String	打断当前话语并且直接播放该字符串
_execute_command	String，String	根据用户的话语以及任务模块做出对应处理
recorder_task	None	持续检测录音音频并转成对应字符串

提供用户可选择的配置文本，可在启动服务之前自由切换，若不填则用语音配置的默认文本，将唤醒状态以及每一次的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)