Marvin Pro 终端直贴式通讯排查手册
适用:Marvin Pro,M6 696、M6 Lite、M3 等机械臂构型。
本文所有排查代码均可整段粘贴到控制器终端运行,不需要复制或调用外部排查脚本。
1. 使用规则
- 每个代码块都是独立命令,可在新终端直接粘贴。
- 默认命令只读取状态,不控制机器人。
- 输出同时保存在:
~/apex_direct_pro_check/
gripper-active一节会真实控制夹爪,必须单独确认安全。- 配置了
APEX_ROS_NAMESPACE=tj时,代码会自动把/info/...、/control/...解析为/tj/info/...、/tj/control/...;夹爪根 Topic 仍会优先按原名检查。
结果标记:
| 标记 | 含义 |
|---|---|
[MISSING] | Topic 不存在 |
[DATA] | 在等待时间内收到一帧数据 |
[NO_DATA] | Topic 存在,但没有收到数据 |
| Publisher count 大于 0 | ROS 图中发现发布端,不等同于正在发布数据 |
| Subscription count 大于 0 | ROS 图中发现订阅端 |
2. 推荐启动顺序
在 Tianji M Apex 前端按测试需要启动:
Robot -> StartTeleop -> StartTool -> Start,选择实际末端类型Camera -> Start,仅相机测试需要- 连接头显并进入遥操
模块与前置进程:
| 模块 | 必需服务/进程 |
|---|---|
| 系统和版本 | 无 |
| 机器人反馈 | apex-robot.service、marvin_robot_node |
| 头显输入 | apex-teleop.service、controller_udp.py、teleop_manager |
| 控制链 | Robot、Teleop、qp_controller、joint_cmd_mux |
| DM/ZY 夹爪 | apex-tool.service、对应夹爪节点 |
| 相 机 | apex-camera.service、nvargus-daemon.service |
| 录制/回放 | apex-teleop.service、录制和回放节点 |
3. 模块一:系统、版本、Domain 和网络
3.1 进程要求
无。
3.2 直接粘贴运行
source /etc/apex/apex_ros_env.sh 2>/dev/null || source /opt/ros/humble/setup.bash
source /etc/apex/apex.env 2>/dev/null || true
OUT="$HOME/apex_direct_pro_check"
mkdir -p "$OUT"
{
echo "===== 时间和 系统 ====="
date --iso-8601=seconds
hostnamectl 2>/dev/null || true
uname -a
grep -E '^(PRETTY_NAME|VERSION_ID)=' /etc/os-release
echo
echo "===== Apex / ROS 环境 ====="
printf 'ROS_DISTRO=%s\n' "${ROS_DISTRO:-}"
printf 'ROS_DOMAIN_ID=%s\n' "${ROS_DOMAIN_ID:-}"
printf 'ROS_LOCALHOST_ONLY=%s\n' "${ROS_LOCALHOST_ONLY:-}"
printf 'RMW_IMPLEMENTATION=%s\n' "${RMW_IMPLEMENTATION:-}"
grep -E '^(APEX_|ROS_|RMW_|BAG_STORAGE_ROOT)' /etc/apex/apex.env 2>/dev/null || true
echo
echo "===== 安装版本 ====="
dpkg-query -W -f='${binary:Package}\t${Version}\t${Architecture}\n' 2>/dev/null \
| grep -Ei 'kernelmind|apexteleop|apex-teleop|marvin-sdk' || true
echo
echo "===== 网络 ====="
ip -brief address
ip route
echo
echo "===== 机器人连通性 ====="
if [[ -n "${APEX_ROBOT_IP:-}" ]]; then
ping -c 3 -W 1 "$APEX_ROBOT_IP" || true
else
echo "APEX_ROBOT_IP 未设置"
fi
} 2>&1 | tee "$OUT/01_env.txt"
3.3 预期输入
无人工动作。
3.4 正常结果
- 天准/Orin 通常为 Ubuntu 22.04、ROS 2 Humble;灵境 Thor 为 Ubuntu 24.04、ROS 2 Jazzy。
APEX_ROBOT_PLATFORM=pro。APEX_ROBOT_MODEL与实际机械臂构型一致。APEX_ROBOT_IP与机器人控制器 IP 一致且能 ping 通。ROS_DOMAIN_ID与 Apex 服务配置一致。- 能查询到 Apex、Teleop、Tool 和 Marvin SDK 版本。
4. 模块二:服务和进程状态
4.1 进程要求
无。该模块用于判断哪些进程已经启动。
4.2 直接粘贴运行
OUT="$HOME/apex_direct_pro_check"
mkdir -p "$OUT"
{
echo "===== systemd 服务 ====="
for unit in apex-backend.service apex-robot.service apex-teleop.service \
apex-tool.service apex-camera.service apex-replay.service; do
if systemctl cat "$unit" >/dev/null 2>&1; then
printf '%-26s active=%-10s enabled=%s\n' \
"$unit" \
"$(systemctl is-active "$unit" 2>/dev/null || true)" \
"$(systemctl is-enabled "$unit" 2>/dev/null || true)"
else
printf '%-26s NOT_INSTALLED\n' "$unit"
fi
done
echo
echo "===== 关键进程 ====="
pgrep -af 'marvin_robot_node|teleop_manager|motion_node|qp_controller|controller_udp|VR_reader|planner_joint|joint_cmd_mux|dm_motor|zy_gripper|wuji|quad_csi|webrtc' || true
echo
echo "===== 失败服务 ====="
systemctl --failed --no-pager || true
} 2>&1 | tee "$OUT/02_services.txt"
4.3 预期输入
无人工动作。
4.4 结果判断
- 测机器人时 Robot 必须为
active。 - 测头显和控制链时 Robot、Teleop 必须为
active。 - 测夹爪时 Tool 必须为
active。 - 测相机时 Camera 和 Argus 必须为
active。 - 服务为 active 仅说明进程在运行,仍需后续 Topic 数据验证。
5. 模块三:ROS 图总表
5.1 进程要求
启动需要检查的业务模块。
5.2 直接粘贴运行
source /etc/apex/apex_ros_env.sh 2>/dev/null || source /opt/ros/humble/setup.bash
OUT="$HOME/apex_direct_pro_check"
mkdir -p "$OUT"
echo "===== Node =====" | tee "$OUT/03_graph.txt"
timeout 10 ros2 node list 2>&1 | tee -a "$OUT/03_graph.txt"
echo "===== Topic =====" | tee -a "$OUT/03_graph.txt"
timeout 10 ros2 topic list -t 2>&1 | tee -a "$OUT/03_graph.txt"
echo "===== Service =====" | tee -a "$OUT/03_graph.txt"
timeout 10 ros2 service list -t 2>&1 | tee -a "$OUT/03_graph.txt"
5.3 预期输入
无人工动作。
5.4 正常结果
Pro 至少应能看到机器人状态、关节反馈、关节状态和双臂命令。配置 tj 命名空间时通常表现为:
/tj/info/robot_state
/tj/info/joint_feedback
/tj/joint_states
/tj/control/joint_cmd_A
/tj/control/joint_cmd_B
如果 ros2 node list 偶发为空,但 Topic 仍有端点,应继续用 topic info -v 和 topic echo 判断,不能只依赖节点列表。
6. 模块四:机器人连接和反馈
6.1 进程要求
Robot -> Start,确认 apex-robot.service=active。
6.2 直接粘贴 运行
source /etc/apex/apex_ros_env.sh 2>/dev/null || source /opt/ros/humble/setup.bash
source /etc/apex/apex.env 2>/dev/null || true
OUT="$HOME/apex_direct_pro_check"
mkdir -p "$OUT"
resolve_topic() {
local logical="$1" ns candidate list
list="$(ros2 topic list 2>/dev/null)"
if grep -Fxq "$logical" <<<"$list"; then echo "$logical"; return; fi
ns="${APEX_ROS_NAMESPACE:-}"
ns="${ns#/}"; ns="${ns%/}"
candidate="/${ns}${logical}"
if [[ -n "$ns" ]] && grep -Fxq "$candidate" <<<"$list"; then echo "$candidate"; return; fi
echo "$logical"
}
check_topic() {
local logical="$1" actual output
actual="$(resolve_topic "$logical")"
echo; echo "===== $logical -> $actual ====="
if ! ros2 topic list 2>/dev/null | grep -Fxq "$actual"; then
echo "[MISSING] $actual"; return
fi
ros2 topic info "$actual" -v 2>&1 | sed -n '1,80p'
if output="$(timeout 6 ros2 topic echo "$actual" --once 2>&1)"; then
echo "[DATA] $actual"
printf '%s\n' "$output" | sed -n '1,35p'
else
echo "[NO_DATA] $actual:6秒内没有收到数据"
fi
}
{
for topic in /info/robot_info /info/robot_state /info/arm_state \
/info/joint_feedback /joint_states /info/eef_left /info/eef_right; do
check_topic "$topic"
done
echo; echo "===== 关节反馈频率,观察约10秒 ====="
timeout 12 ros2 topic hz "$(resolve_topic /info/joint_feedback)" || true
} 2>&1 | tee "$OUT/04_robot.txt"
6.3 预期输入动作
保持机 器人连接。允许时低速、小幅运动一侧机械臂,使关节数据发生变化。
6.4 结果判断
/info/joint_feedback、/joint_states应为[DATA]。/info/robot_info可能只在 Robot Node 启动阶段发布;晚启动监听得到[NO_DATA]时,若发布端存在且 Robot 日志已经打印正确型号,不单独判为故障。- Robot active 但反馈
[NO_DATA]:检查 Robot Node、SDK 数据线程和 DDS 通讯。 - 日志反复
Robot connection lost:检查机器人 IP、网线、网卡和 SDK 连接。 /info/joint_feedback有数据但/joint_states无数据:Robot Node 内部转换或发布异常。- 机器人静止时数值不变化正常;实际运动时不变化异常。
7. 模块五:头显和手柄输入
7.1 进程要求
Robot、Teleop 已 Start,头显已连接并进入遥操。
7.2 直接粘贴运行
source /etc/apex/apex_ros_env.sh 2>/dev/null || source /opt/ros/humble/setup.bash
source /etc/apex/apex.env 2>/dev/null || true
OUT="$HOME/apex_direct_pro_check"
mkdir -p "$OUT"
resolve_topic() {
local logical="$1" ns candidate list
list="$(ros2 topic list 2>/dev/null)"
if grep -Fxq "$logical" <<<"$list"; then echo "$logical"; return; fi
ns="${APEX_ROS_NAMESPACE:-}"; ns="${ns#/}"; ns="${ns%/}"
candidate="/${ns}${logical}"
if [[ -n "$ns" ]] && grep -Fxq "$candidate" <<<"$list"; then echo "$candidate"; return; fi
echo "$logical"
}
{
echo "请在每个 Topic 的监听窗口内操作对应手柄。"
for logical in /info/vr_connected /control/target_poseL /control/target_poseR \
/control/enableL /control/enableR \
/control/gripperValueL /control/gripperValueR \
/control/vr_joy_L /control/vr_joy_R /control/vr_body /control/footkey; do
actual="$(resolve_topic "$logical")"
echo; echo "===== $logical -> $actual ====="
if ros2 topic list 2>/dev/null | grep -Fxq "$actual"; then
ros2 topic info "$actual" 2>&1
timeout 7 ros2 topic echo "$actual" --once 2>&1 || echo "[NO_DATA] 7秒内无数据"
else
echo "[MISSING] $actual"
fi
done
} 2>&1 | tee "$OUT/05_teleop.txt"
7.3 测试人员输入动作
按终端正在检查的 Topic,依次移动左右手柄、操作左右使能、开合左右末端。脚踏和身体控制未配置时可跳过。
7.4 结果判断
target_poseL/R有变化:头显位姿已进入 ROS。enableL/R有变化:使能映射正常。gripperValueL/R有变化:头显夹爪输入正常。- 夹爪目标有数据但夹爪不动:继续排查 Tool、vCAN 和电机,不再归因于头显。
- 全部无数据:检查 Teleop、VR 连接、ROS Domain 和网络端口。
8. 模块六:Pro 双臂完整控制链
8.1 进程要求
Robot、Teleop active,头显已连接,机器人处于 ready,现场允许低速遥操。
8.2 直接粘贴运行
source /etc/apex/apex_ros_env.sh 2>/dev/null || source /opt/ros/humble/setup.bash
source /etc/apex/apex.env 2>/dev/null || true
OUT="$HOME/apex_direct_pro_check"
mkdir -p "$OUT"
resolve_topic() {
local logical="$1" ns candidate list
list="$(ros2 topic list 2>/dev/null)"
if grep -Fxq "$logical" <<<"$list"; then echo "$logical"; return; fi
ns="${APEX_ROS_NAMESPACE:-}"; ns="${ns#/}"; ns="${ns%/}"
candidate="/${ns}${logical}"
if [[ -n "$ns" ]] && grep -Fxq "$candidate" <<<"$list"; then echo "$candidate"; return; fi
echo "$logical"
}
{
echo "每个 Topic 最多监听7秒,请持续做小幅左右臂动作。"
for logical in /control/target_poseL /control/target_poseR \
/control/enableL /control/enableR \
/control/ik_request \
/control/qp_controller/joint_cmd_A \
/control/qp_controller/joint_cmd_B \
/info/joint_cmd_mux/active_source \
/control/input_mode \
/control/joint_cmd_A /control/joint_cmd_B \
/info/joint_feedback; do
actual="$(resolve_topic "$logical")"
echo; echo "===== $logical -> $actual ====="
if ros2 topic list 2>/dev/null | grep -Fxq "$actual"; then
ros2 topic info "$actual" 2>&1
timeout 7 ros2 topic echo "$actual" --once 2>&1 || echo "[NO_DATA] 7秒内无数据"
else
echo "[MISSING] $actual"
fi
done
} 2>&1 | tee "$OUT/06_pipeline.txt"
8.3 测试人员输入动作
在整个检查期间持续、小幅、低速移动左右手柄,并明确触发对应使能。
8.4 数据顺序和判断
target_pose
-> ik_request
-> qp_controller/joint_cmd_A、B
-> joint_cmd_A、B
-> Marvin SDK
-> joint_feedback
target_pose无:头显或 controller_udp 层。target_pose有、ik_request无:Teleop Manager、使能或坐标映射。ik_request有、QP 无:QP、模型或 Pinocchio/eiquadprog 动态库。- QP 有、最终关节命令无:joint_cmd_mux 或输入源选择。
- 最终命令有、反馈无:Robot Node、SDK 或机器人连接。