Vega-1U 操作手册

这台机器人已经完成配置。不需要重复 B 部分——证书已安装、库已就位，Jetson 开机后会自动连接 CMU-DEVICE 。正常使用流程：SSH 登录，在机载计算机上运行脚本。

何时必须显式设置 ROBOT_NAME

Dexmate 在 Jetson 上预设了 ROBOT_NAME ，因此进入交互式 shell 后它就已存在——用 echo $ROBOT_NAME 确认，运行脚本无需前缀。只有一种情况必须加前缀：命令没有经过交互式 shell，因为不会加载 ~/.bashrc ，此时 Robot() 会抛出 ValueError.

ssh dexmate@172.26.161.243 \
  'ROBOT_NAME="dm/vg3eb20f25bb-1u" python3 ~/py_scripts/inspect_joints.py'

一次完整的使用流程

ssh dexmate@172.26.161.243

# is the robot healthy and talking?
dextop topic list --timeout 10
dextop doctor check

# where are the joints right now? (before commanding any motion)
python3 ~/py_scripts/inspect_joints.py

以上就是全部必需步骤。下面按任务选择——只启用即将使用的子系统。

systemctl status dexsensor wrist-camera-init.service --no-pager
cat /run/wrist-cameras/ready.json

本机的头部相机服务已经运行。通过 A2订阅；腕部 API 按需启动采集。接线和启动配置见 B8.

sudo modprobe gs_usb                                    # asks for hello-dex
sudo ip link set can1 up type can bitrate 1000000 \
     loopback off listen-only off                       # ip is NOPASSWD

cd ~/py_scripts && python3 goto_ready.py --dry-run

相机（A2）、夹爪（A5）和机械臂运动（A4）相互独立。机械臂始终使用命名位姿，不要使用 pose_pool 条目。

IP 地址变化时

172.26.161.243 是以下网络上的 DHCP 租约： CMU-DEVICE 和 迟早会变化。SSH 无响应时，按从易到难的顺序尝试：

1. 扫描子网： nmap -sn 172.26.160.0/22 | grep -B2 -A2 "vega\|dexmate\|ubuntu"
2. 接网线，使用固定有线地址 192.168.50.20，它不会变化。
3. 将显示器和键盘接到 IO hub，从桌面查看地址。

改用工作站运行

目前所有代码都在机载计算机运行。也可以从自己的电脑控制机器人，但需要单独完成一次配置—— dextop、在本地解压同一份证书，并设置环境变量——详见 B5。这样能使用更好的 GPU，代价是增加网络延迟。

头部相机由现有的 dexsensor 服务发布。两路原装腕部相机使用本地 WristCameras Python API，可以同时读取。下面的纯传感器示例不构造 Robot()，避免触发头部归位。配置见： B8.

关节、电流、力矩、按钮——不需要 dexsensor

from dexcontrol.robot import Robot

robot = Robot()

robot.left_arm.get_joint_pos()      # joint positions
robot.left_arm.get_joint_vel()      # joint velocities
robot.right_arm.get_joint_current() # current — arms only
robot.left_arm.wrench_sensor.get_wrench_state()   # [fx,fy,fz,tx,ty,tz]
robot.right_arm.wrench_sensor.get_button_state()  # blue / green wrist buttons

robot.shutdown()

头部相机：订阅正在运行的服务

在 Jetson 上以 dexmate 身份使用已安装的系统 Python 运行。在非交互式 shell 中显式设置机器人名称。当 dexsensor 占用相机时，不要启动第二个头部服务或打开另一个 ZED SDK 相机。

export ROBOT_NAME=dm/vg3eb20f25bb-1u

from dexcontrol.core.config import get_robot_config
from dexcontrol.sensors.manager import Sensors

configs = get_robot_config()
configs.sensors["head_camera"].enabled = True
sensors = Sensors({"head_camera": configs.sensors["head_camera"]})
try:
    sensors.wait_for_all_active(timeout=10)
    head = sensors.head_camera.get_obs(
        obs_keys=["left_rgb", "right_rgb", "depth"],
        include_timestamp=True,
    )
    if any(head[k] is None for k in ("left_rgb", "right_rgb", "depth")):
        raise RuntimeError("Head streams are not ready")
    rgb = head["left_rgb"]["data"]
    print(rgb.shape, head["left_rgb"]["timestamp_ns"])
    print(sensors.head_camera.get_camera_info())
finally:
    sensors.shutdown()

设置 include_timestamp=True时，每个流返回的记录包含 data, timestamp_ns 和 receive_time_ns；就绪前可能返回 None 。使用默认值 include_timestamp=False时，每项直接返回数组。左右 RGB 为 (1200, 1920, 3)；深度为以米为单位的 (1200, 1920) 浮点数组。

头部相机分辨率与内参

当前头部配置： HD1200、1920×1200、配置帧率 30 fps、NEURAL 深度。在 /etc/dexmate/dexsensor/default.toml中找到 id = "head_camera"对应的传感器，再查看其参数和流开关。不要按行号修改。通用的 ZED X One 腕部条目必须保持禁用：它们并不描述这些 ISX031 相机。实测吞吐率见 B8.

sudo cp -a /etc/dexmate/dexsensor/default.toml /etc/dexmate/dexsensor/default.toml.camera-$(date +%Y%m%d-%H%M%S).bak
sudoedit /etc/dexmate/dexsensor/default.toml
# After saving the intended head settings (interrupts head streaming):
sudo systemctl restart dexsensor.service

修改配置需要管理员权限。正常读取头部和腕部 API 不需要 sudo.

HD1200 下运行时的校正内参，来自 head_camera.get_camera_info() — distortion 为空，因为流已经过校正：

image_width: 1920
image_height: 1200
K: [734.7626953125, 0.0, 966.6296997070312,
    0.0, 734.7626953125, 653.073486328125,
    0.0, 0.0, 1.0]
# example from 2026-09-15 · query runtime for current calibration
# distortion [] · baseline ~0.0497 m · serial 53756133 · ZedXMini

双腕：本地 Python API

在 Jetson 上使用 /usr/bin/python3 ，以 dexmate 身份运行（已经属于 video 和 i2c 组）。仅读取腕部不需要 sudo ，也不需要 ROBOT_NAME。代码安装在 /opt/wrist-cameras/ ，通过系统 Python 3.10 dist-packages 目录中的 wrist_cameras_local.pth 暴露。单独的虚拟环境可能找不到这个模块或 GStreamer 绑定。

from wrist_cameras import WristCameras

with WristCameras() as cameras:
    for _ in range(30):
        obs = cameras.get_obs(timeout=3)
        rgb_a = obs["wrist_a"]["rgb"]
        rgb_b = obs["wrist_b"]["rgb"]
        print(rgb_a.shape, rgb_b.shape,
              obs["wrist_a"]["frame_id"], obs["wrist_b"]["frame_id"])
# Context exit stops capture/trigger and releases both devices.

API 按传感器名称发现 V4L2 设备，在一个锁下占用双腕，并在独立进程中运行软件触发。第二个读取进程会被拒绝，并抛出 RuntimeError。重启初始化前务必关闭上下文。这是本地 API，不是网络端点；它没有注册为 robot.sensors.left_wrist_camera 或 right_wrist_camera.

在一个进程中读取头部和双腕

按上文设置 ROBOT_NAME ，在 Jetson 上保存为 Python 脚本，然后使用 /usr/bin/python3运行。腕部上下文获取两路相机时，现有的头部发布服务继续运行。

from dexcontrol.core.config import get_robot_config
from dexcontrol.sensors.manager import Sensors
from wrist_cameras import WristCameras

configs = get_robot_config()
configs.sensors["head_camera"].enabled = True
sensors = Sensors({"head_camera": configs.sensors["head_camera"]})
try:
    sensors.wait_for_all_active(timeout=10)
    with WristCameras() as wrists:
        for _ in range(30):
            wrist = wrists.get_obs(timeout=3, fresh=True)
            head = sensors.head_camera.get_obs(
                obs_keys=["left_rgb", "right_rgb", "depth"],
                include_timestamp=True,
            )
            if any(head[k] is None for k in ("left_rgb", "right_rgb", "depth")):
                raise RuntimeError("Head streams are not ready")
            head_left = head["left_rgb"]["data"]
            head_right = head["right_rgb"]["data"]
            depth = head["depth"]["data"]
            wrist_a = wrist["wrist_a"]["rgb"]
            wrist_b = wrist["wrist_b"]["rgb"]
            print(head_left.shape, wrist_a.shape, wrist_b.shape)
finally:
    sensors.shutdown()

使用 OpenCV 保存 RGB 图像前，先转换：

import cv2
if not cv2.imwrite("wrist_a.png", cv2.cvtColor(wrist_a, cv2.COLOR_RGB2BGR)):
    raise RuntimeError("Could not save wrist_a.png")

已测试的四视角录像工具安装在 /home/dexmate/wrist-camera-debug/coexistence/record_api_demo.py。它通过上述 API 订阅，等待操作员 15 秒后开始录像；不发送运动命令。先关闭其他腕部读取进程。

ROBOT_NAME=dm/vg3eb20f25bb-1u /usr/bin/python3   /home/dexmate/wrist-camera-debug/coexistence/record_api_demo.py   --seconds 45 --output "$HOME/wrist-camera-debug/coexistence/demo-$(date +%Y%m%d-%H%M%S)"

新输出目录包含 preview.avi 和 recording.json。AVI 写入器固定为 6 fps；测量时间应使用 JSON 中的实际采集时长和帧时间戳。预览编码速度不代表相机原生帧率。

其他传感器／自定义 dexsensor 配置

这是 dexsensor 支持传感器的通用参考，不是 ISX031 腕部相机配置步骤。启动自定义发布器前，先停止占用同一相机的已有发布器。本机正常读取头部相机时使用上述运行中的服务。

dexsensor gen-cfg                                       # writes to ~/.dexmate/sensors/
dexsensor launch --config ~/.dexmate/sensors/default_config.yaml

除了各传感器的 enabled 开关，配置文件还可调整分辨率、帧率、深度范围、传输方式（rtc 或 zenoh）以及 JPEG 质量，以便在图像质量和带宽之间取舍。

头部——3 自由度，但顺序为俯仰／偏航／俯仰

import numpy as np
from dexcontrol.robot import Robot

robot = Robot()
robot.head.set_joint_pos(np.array([-np.pi/6, 0.0, 0.0]), wait_time=2.0)
robot.shutdown()

机械臂——7 自由度，关节空间控制

current = robot.left_arm.get_joint_pos()
robot.left_arm.set_joint_pos(current, wait_time=1.0)          # absolute

delta = np.zeros(7); delta[-1] += 0.2
robot.left_arm.set_joint_pos(delta, relative=True, wait_time=4.0)  # relative

手、躯干、底盘

robot.right_hand.close_hand()

# torso — not present on this robot; Vega-1 / Pro only
robot.torso.set_joint_target(target, tracked=True)   # dexcontrol == 0.5.0
robot.torso.set_joint_pos_vel(target, joint_vel=np.ones(3)*0.1, wait_time=3.0)  # < 0.5
robot.torso.stop()

# chassis — not present on this robot
robot.chassis.move_straight(speed=0.4, wait_time=2.0)
robot.chassis.move_sideways(speed=0.4, wait_time=2.0)
robot.chassis.turn(angular_speed=0.4, wait_time=2.0, center='base_center')
robot.chassis.stop()

软件急停

robot.estop.activate()
robot.estop.deactivate()

它补充实体急停按钮的功能，不能替代实体按钮。

两个命名位姿、两个脚本。要记住：碰撞风险在于 运动顺序，而不在目标位姿。

真实夹爪间隙——实测，不靠假设

带夹爪的 URDF 位于 ~/Downloads/Dexmate/vega_1u_gripper.urdf ，包含夹爪模型，因此可以正确计算间隙：在 25 步关节空间插值沿途，计算左右夹爪碰撞网格之间的最近点距离。

顺序运动在工作位姿切换中多提供 7–11 cm 的间隙，因此 goto_ready.py 和 goto_rest.py 采用相反的先动机械臂。顺序运动的额外收益为 零 在 folded三种顺序都降到约 5 cm，因为碰撞发生在 目标位姿本身，而不是路径上。

两个位姿

pre_move 记录自机器人自身的休息位置，因此它是经实际验证可安全停放的位姿。 manip_init 是 BrickBench 23 维 Joint_Home_Position中的机械臂部分；腕部最终相距 0.656 m，约与肩部等高。

cd ~/py_scripts && export ROBOT_NAME="dm/vg3eb20f25bb-1u"

python3 goto_ready.py            # pre_move  -> manip_init, right arm first
python3 goto_rest.py             # manip_init -> pre_move,  left arm first
python3 goto_ready.py --dry-run  # plan + limit check + clearance, no motion

所有参数都可覆盖脚本默认值，例如使用 --step 0.02 --wait 1.0 降低速度，因为 goto_pose 采用第一次出现的参数，而用户参数排在前面。

为什么机械臂要逐一运动

不同运动顺序下的路径最小腕间距：

间隙保护

goto_pose.py 模拟实际运动经过的全部路点——采用实际循环相同的逐关节限幅和左右臂顺序——以 URDF 正运动学计算各点腕间距，并抛出 SystemExit ，如果任一路点低于 MIN_WRIST_SEP （0.35 m，可通过 --min-sep覆盖）。以下标定点均来自实际结果：

folded 已禁用

folded 和 folded_closed_hand 来自机械臂 pose_pool ，被列入 goto_pose.py的 BANNED 集合，拒绝执行。这些位姿是针对 Dexmate 自有末端执行器设计的。不要把它们当作“安全收纳”—— pre_move 才是本机的收纳位姿。 重力力矩也不能作为判据： zero 静态力矩最低（4.88 N·m），因为双臂垂直向上，但这是不稳定平衡，且可能下落的距离最大。

收尾

cd ~/py_scripts && export ROBOT_NAME="dm/vg3eb20f25bb-1u"
python3 goto_rest.py
python3 -c "import gripper; g=gripper.Grippers(); g.release(); g.close_bus()"

让机械臂保持通电，停在 pre_move. 。它们会自行保持位置；断电后则会下垂。两次使用之间保持 can1 运行是可以的。

夹爪 不 属于 dexcontrol——机器人报告的手类型为 UNKNOWN，因此 robot.left_hand 不起作用。它们是共享 CAN 总线的两台 MG4005-i10 V3 伺服电机，由 /home/dexmate/gripper.py封装，与普通机械臂控制并行使用。接线、总线速率和协议考证见 C3；本节介绍库的使用方式。

先确保总线已启动

sudo modprobe gs_usb                                          # prompts for hello-dex
sudo ip link set can1 up type can bitrate 1000000 \
     loopback off listen-only off                             # NOPASSWD; spell out both flags
ip -details -statistics link show can1                        # want ERROR-ACTIVE and tx > 3

can0 是 Jetson SoC 自带的控制器， 不 是适配器——始终使用 can1. tx 恰好停在 3 表示没有节点 ACK，并非成功。

对象模型

正常使用流程

from gripper import Grippers

g = Grippers()          # opens can1, probes both motors
g.home()                # find the closed stop on each; ~1 min, do not skip

g.both_open()           # both jaws, concurrently — 9 s at 500 dps
g.both_close()
g.both_move_to(0.4, speed=500)   # 40% open

print(g.position())     # fraction per motor
print(g.status())       # angle, current, temp, voltage, error state

g.grip(current=0.6)     # close until the current limit says contact

g.halt()                # stop motion, keep the frame
g.close_bus()           # release the socket, leave motors energised

归零不可省略

原因在固件中： 0x80 （关闭电机） 会丢弃多圈计数，此后角度只返回折叠到 (−180, 180] 的单圈值。因此绝对坐标仅在电机持续使能时有效——这正是驱动启动时靠机械限位归零、并在整个会话保持使能的原因。

close() 与 grip()

正常数值参考

关闭

两个库使用陷阱

文件

按最先看到的现象排序。多数问题没有文档记录，都是实际排查得到的。

1. 连接 assembled 线束

组装好的线束一头是 CAN adapter，两侧分支各有一组 4-pin／6-pin 接口。两侧均将 6-pin 接夹爪，4-pin 接机器人。

2. 连接腕部相机线

相机线也要连接，只接偏向内部的一边，位置见 IMG_9360。

3. 连接 USB，并设置两个开关

CAN adapter 插入机器人的 USB 口。两个开关都一定要拨向 K 那边，见 IMG_9369。

整体连接示例

参考：Waveshare MAX9296-GMSL-Deser-Module · Jetson Orin。改线前先断电。

1. 安装采集卡并连接电源

用 kit 自带的铜柱连接采集卡和 PCB，然后接电。红线接 排针 2、4（5 V），地线接 6（GND）。这里是 Jetson 的 5 V 排针，不能接夹爪的 24 V 电源。

2. 设置 CFG 开关为 0100

按板上编号 1 → 2 → 3 → 4 读取，依次设置为 0 → 1 → 0 → 0。

3. 更换机器人内的铜柱

拆下机器人的原装铜柱，妥善保存。先用 15 mm 铜柱固定钢架，再接 10 mm 铜柱安装剩余的内存／存储组件及风扇。

4. 连接内部腕部相机线

• 拿到母母线：直接拆开内部连接腕部相机的连线，连接到采集卡。
• 拿到公母线：把机器人后盖上接外部相机的接口拆下，用公母线直连。IMG_9277 walkthrough 演示的就是这种接法。

5. 更换 CAM1 排线

拆下原来接在 Jetson CAM1 上的线，使用 kit 自带的排线连接 Jetson CAM1 ↔ 采集卡 CSI0。

没有已知 WiFi 的机器人会在开机时启动自己的热点。规则是： 没有已知网络 → 热点；已知网络在范围内 → 自动加入，热点消失。每台机器人只需配置一次。

三种进入 shell 的方式

以太网连接前，先给自己的电脑设置静态地址： 192.168.50.x 用于 Vega-1 和 Vega-1U（x 可取 1–255， 但不包括 20 和 21）。Vega-1-Pro 的底盘端口使用 192.168.5.x ，躯干端口使用 192.168.50.x 。子网掩码为 255.255.255.0，网关留空。

按生产日期区分热点凭据

开机后等 2–3 分钟再寻找热点。SSH 凭据始终是 dexmate / hello-dex.

ssh dexmate@10.42.0.1

加入自己的 WiFi

# see what's around
timeout 5 sudo iw dev wlP1p1s0 scan > /tmp/scan_results
nmcli device wifi list

sudo nmcli device wifi connect "YourNetworkName" password "YourPassword"

sudo nmcli device wifi connect "YourNetworkName" password "YourPassword" \
  ip4 JETSON_STATIC_IP/24 gw4 WIFI_GATEWAY

然后在新网络中寻找机器人。有权限时用路由器管理页面，否则扫描：

nmap -sn 192.168.1.0/24 | grep -B2 -A2 "vega\|dexmate"

无法连接时

• 没有出现热点 ——完整等待 5 分钟；确认机器人没有保存其他网络（否则会加入那个网络）；必要时重启。
• SSH 连接被拒绝 ——确认确实连上机器人热点、使用了对应批次的 IP，并且启动已完成。
• 加入 WiFi 失败 ——重新检查 SSID 和密码，确认网络为 2.4 GHz 或双频，把机器人移近路由器。
• 在新网络中找不到机器人 ——等待 2–3 分钟；若设置了静态 IP，重启路由器并确认地址不与其设置冲突。

证书是接入总线的凭证：安装一次，直到过期前都有效。固件更新可选，证书不可省略。Dexmate 提供两条路径，而 证书只能通过 Web 管理页面安装.

方式 1 · Web 管理页面（证书必需）

SoC 板位于 192.168.50.x 子网，WiFi 侧无法直接访问，因此先建立路由：

sudo apt install sshuttle
sshuttle -r dexmate@$ROBOT_IP 192.168.50.0/24

1. 打开 https://192.168.50.21:57832。首次访问会要求设置密码——请记住它。
2. 先升级管理页面本身 （Check for Updates）。如果失败，从 software.dexmate.ai 下载 socbridge 文件并手动上传。
3. 在通信部分上传 Dexmate 签发的证书。
4. 如果需要，也在同一页面更新固件。

方式 2 · 命令行（仅适用于已安装有效证书）

dextop firmware info      # per-board version table
dextop firmware update    # prompts for the version to install

如果只在机载计算机运行代码，可跳过本节。从自己的电脑控制机器人时，工作站必须加入同一 Zenoh 总线。

pip install dextop --upgrade

dextop cert unpack <certificate_file>.dzcfg

dextop node install-service

低于 0.5.0 时中继需手动启动并持续运行，因此放在 tmux 中：

tmux new -s relay
dextop node start          # then Ctrl+B, D to detach

export ROBOT_NAME=dm/vg3eb20f25bb-1u
export ZENOH_CONFIG=~/.dexmate/comm/zenoh/<cert_name>/zenoh_peer_config.json5
export ROBOT_IP=172.26.161.243

多机器人场景下，每台机器人使用单独终端，并设置各自的 ROBOT_NAME ——一台工作站就能控制全部机器人。

dexcontrol——控制

pip install dexcontrol

开源示例位于 github.com/dexmate-ai。Dexmate 建议先运行 examples/advanced_examples/fold_robot.py 来展开新机器人—— 不要在本机运行它；见常见问题对照表。

dexsensor——感知，仅限 Jetson

从 software.dexmate.ai 下载正确架构（Jetson 使用 arm64），然后执行：

sudo dpkg -i <dexsensor_xxx>.deb

• 若原先使用基于 Python 的 dexsensor ≤ 0.3.1, 先彻底卸载，再安装 ≥ 0.6.9.
• ZED SDK 预装在 /usr/local/zed，PyZED 位于基础 conda 环境。若使用自己的环境，在该目录运行 python get_python_api.py 。
• ZED SDK not found 但 import pyzed 可用时，是 C++ 标准库不匹配： conda update -c conda-forge libstdcxx-ng -y.
• 每个 dexsensor 版本要求特定 ZED SDK 版本——从 Stereolabs 历史发行版下载。
• 不要通过 ssh -X启动 dexsensor，否则 ZED 相机初始化会失败。

编写代码前先运行这些检查。先确认连接正常，能避免反复猜测“是脚本还是机器人出了问题”。

dextop topic list --timeout 10

外部电脑首次调用常常没有返回——dextop 需要一些时间连接机器人。再运行一次或增加超时。

头部双目和两路腕部相机已在 dm/vg3eb20f25bb-1u上同时输出图像。硬件：Orin Nano 8 GB p3767-0005 配原装 p3768 载板；L4T 36.5，内核为 Linux 5.15.185-tegra。日常 API 示例见 A2.

当前仓库：开机启动

已经包含腕部初始化自启动。scripts/install.py --apply 会安装并启用 wrist-camera-init.service。开机时等待两个腕部设备、完成初始化并写入就绪标记。这是一次性服务，显示 active (exited) 正常。它不会持续取流：应用打开 WristCameras() 后才启动采集和触发，关闭后停止。

头部取流由厂商的 dexsensor.service 负责。目前 installer 没有显式启用此服务。--configure-head 会写入头部配置和机器人名称，但不会启用或启动服务。请用下方命令检查并启用。这里说明的是仓库行为；命令用于检查实际执行它们的机器人。

新机器人先安装匹配的厂商软件，再按仓库 Quick start 操作。--camera-boot --activate-camera-boot 会生成并选中 DexmateSetupHeadWrists，使用 /boot/initrd-dexmate-setup 和 /boot/tegra234-dexmate-setup.dtbo。不加 --activate-camera-boot 只会准备启动项。installer 不会启动服务或重启机器人。下方原机器人集成记录中的 HeadWrists 路径属于原来的安装。

systemctl is-enabled dexsensor.service wrist-camera-init.service
systemctl status dexsensor.service wrist-camera-init.service --no-pager
systemctl cat dexsensor.service wrist-camera-init.service
cat /boot/extlinux/extlinux.conf

安装完成后，启用这两个服务用于后续开机。如果提示 unit “not found”，先安装对应软件：头部需要厂商 dexsensor 包，腕部初始化需要本仓库 installer。

sudo systemctl daemon-reload
sudo systemctl enable dexsensor.service wrist-camera-init.service

检查启动项后手动重启。若只需要在本次开机中启动或重新初始化相机，先关闭腕部读取程序及独立 ZED 查看器，再执行下方命令。它们会中断相机流，不会重启机器人；新选中的内核 overlay 仍需重启后才能生效。

sudo systemctl restart wrist-camera-init.service
sudo systemctl restart dexsensor.service

相机不工作时怎么排查

先在 Jetson 本机检查，区分硬件／服务问题和工作站通信问题。先看状态与日志：

uname -r
systemctl status dexsensor.service wrist-camera-init.service --no-pager
journalctl -u dexsensor.service -u wrist-camera-init.service -b -n 160 --no-pager
v4l2-ctl --list-devices
cat /run/wrist-cameras/ready.json
cat /proc/sys/kernel/random/boot_id
sudo journalctl -k -b --no-pager | grep -Ei 'isx031|max929|tegra.*camera|i2c|csi|vi.*error'

恢复后运行 A2 头部＋双腕示例：确认头部 RGB／深度非空，多次读取时头部源时间戳推进，两个腕部的 frame ID 持续增加。服务 active 和存在视频设备节点都不能单独证明已经出图。不要热卸载相机驱动栈；启动／驱动恢复使用保留的启动项并有序重启。

原机器人集成记录 · 2026-09-15

物理连接

测试时腕部枚举为 /dev/video0, /dev/video1 ，头部为 /dev/video2, /dev/video3。这些编号可能随启动变化：使用 API 发现机制，不要硬编码索引。电源灯亮不能证明收到图像；需要下方取流测试。

已安装的启动和初始化链路

1. /boot/extlinux/extlinux.conf 选择 DEFAULT HeadWrists，加载 /boot/tegra234-head-wrists.dtbo 和 /boot/initrd-head-wrists-default.
2. initrd 在模块加载前，通过只读 bind mount 提供修补后的 tegra-camera.ko 和 isx031-gmsl-camera-b.ko 。原内核、基础 DTB、磁盘上的模块和 /boot/initrd 均保留。
3. 已启用的 wrist-camera-init.service 等待两路腕部探测完成，执行相机专用初始化，并写入 /run/wrist-cameras/ready.json。它是 oneshot： active (exited) 且退出状态为 0 属于正常情况。它跳过旧的单相机回退配置。
4. dexsensor.service 继续通过 ZED 软件栈发布头部相机。 WristCameras() 按需启动腕部采集和软件触发；关闭上下文即停止。开机初始化不会启动持续腕部录像。

为什么原厂软件包不够用

两个原始 overlay 的 VI／CSI 通道重叠。合并 overlay 保留头部的 26 个通道，把腕部添加到 26／27，总计使用六条物理 CSI lane。它还移除永久选择 CAM0 的 GPIO hog，并将头部板卡的 TCA9546 放到载板 CAM0 GPIO-mux 分支下。

相机框架需要父节点遍历补丁来处理嵌套 I²C mux；否则头部探测会报 i2c bus regbase unavailable ／错误 -75。腕部驱动需要识别 MAX9295、配置 3 Gbps 链路，再执行原装相机的复位、时钟、视频和触发初始化。只有设备节点还不足以产生图像。

提供的 Downloads/orin_kernel_img_260506_v3.4/ 软件包包含 5.15.148-rt 内核和 AGX 专用设备树。这些二进制不匹配本 Nano 的 5.15.185-tegra。这里只移植了相机专用初始化；不要对本配置使用该包的全系统安装器。任何内核或 JetPack 升级后，都应重新编译／检查自定义模块。

就绪状态与恢复检查

uname -r
systemctl is-enabled wrist-camera-init.service
systemctl status dexsensor wrist-camera-init.service --no-pager
cat /run/wrist-cameras/ready.json
journalctl -u wrist-camera-init.service -b --no-pager

成功初始化标记必须属于本次启动。如果缺失，检查服务日志和选中的启动文件。设备忙表示另一个读取进程占用腕部，应先关闭该进程。单纯 V4L2 取流不提供必需的软件触发。

若需重新初始化相机，先关闭所有腕部读取进程，然后运行：

sudo systemctl restart wrist-camera-init.service

这会重启相机初始化，不会重启机器人。服务成功后重新打开 API。

启动配置备份： /boot/extlinux/extlinux.conf.before-default-head-wrists-20260915。选择旧的 ISX031 启动项会恢复仅腕部的启动路径，不能提供头部＋腕部联合配置。新默认 initrd 的 SHA256：

f449a4ea16dc1bda7a0ce3dc6508c82472faf07e6b02e7b31cd102d72eedad69

实测结果与限制

原始测试有 19.662 秒共同重叠时间，源时间戳唯一且递增，应用层采集／触发错误为零。仍有一些启动／停止内核消息；不能据此认定内核日志完全无错。长时间稳定性、腕部 30 fps、断开重连和新默认冷启动仍未验证。

重建文件与证据

Jetson 工作目录： /home/dexmate/wrist-camera-debug/coexistence/。Mac 归档： /Users/huxinyu/Documents/ChatGPT/ICL/camera-coexistence/。复现配置时请保留该归档与本手册；文字说明不能替代修补后的模块和相机寄存器初始化。

• default-camera/README.md, api-test.json 和 initrd-build-verification.json：已安装 API、服务检查和新默认配置的验证范围。
• build_candidate.py, sensor-common-nested-gpio-mux.patch 和 default-camera/build_default_initrd.py：合并 overlay、框架补丁和默认 initrd 构建器。
• RESULTS.md 和 concurrent-independent-trigger-20s.json：并发采集结果。
• Mac 运动演示： /Users/huxinyu/Documents/ChatGPT/ICL/output/head-wrists-motion-demo-20260915/head-wrists-motion-demo.mp4.

每个 Dexmate 组件都通过 Zenoh通信，使用同一份加密证书认证。了解各库应该运行在哪台机器上，是后续步骤的前提——装错位置最容易白费半天。

两种运行方式

• 机载计算机 ——代码在 Jetson 上执行。延迟最低， ROBOT_NAME 已设置，是演示和实时控制的默认选择。
• 从工作站运行 ——使用更好的 GPU 运行 AI 模型，经 WiFi 或以太网发送控制。便利的代价是延迟。两台机器必须在同一局域网，均需安装 dextop，并解压同一份证书。

环境变量

Vega-1U 是 Vega-1 的上半身。 可控自由度总数为 17：左臂 7（L_arm_j1..j7），右臂 7（R_arm_j1..j7），头部 3（head_j1..j3). 没有躯干，也没有底盘 — Vega1UConfig.components 只列出双臂、头部、急停和心跳，而 dextop topic list 返回的 16 个 key 不包含 state/torso 或 control/torso.

机械臂关节限位（rad）——左右不对称

机械臂 pose_pool： folded, folded_closed_hand, L_shape, lift_up, zero。头部： home, tucked.

机器人上已有的脚本

两只第三方夹爪挂在同一条 CAN 总线上，由 Jhoinrch RH-02 USB 转 CAN 适配器驱动（Canable／candleLight 克隆，STM32F072C8T6，USB ID 1d50:606f）。机器人报告的手类型为 UNKNOWN，因此 不能通过 robot.left_hand 控制——而是通过 can1 下发命令，与机械臂控制并行使用。

gs_usb 必须手动编译

L4T 内核没有提供 gs_usb (CONFIG_CAN_GS_USB is not set，而且整个 drivers/net/can/usb/ 目录都不存在），也没有 slcan ——所以给适配器刷 slcan 固件无法绕过这个问题。内核头文件存在，可以进行树外编译：

mkdir -p ~/gs_usb_build && cd ~/gs_usb_build
curl -fsSLO https://raw.githubusercontent.com/gregkh/linux/v5.15.199/drivers/net/can/usb/gs_usb.c
echo 'obj-m += gs_usb.o' > Makefile
make -C /lib/modules/$(uname -r)/build M=$PWD modules
sudo cp gs_usb.ko /lib/modules/$(uname -r)/kernel/drivers/net/can/usb/ && sudo depmod -a

任何内核变更都会使其失效 ——针对新版本重新编译（源码 tag 必须匹配运行中的内核）。DKMS 可使其自动持续生效。

2026-08-25，本机重刷为 JetPack 6.2.3，清除了全部 Dexmate 出厂配置：ZED SDK、dexsensor、dextop、Zenoh 证书以及 enP8p1s0上的静态 IP。Dexmate 没有 提供重刷后的恢复流程。下面是工单 #126892650 中 Rahul 给出的四个步骤，以及我们为完成恢复自行摸索的内容。

pip install dextop
sudo -E $(which dextop) robot set_name dm/vg3eb20f25bb-1u

相机问题从来不是缺少驱动

Stereolabs 的 ZED Link 驱动提供 预编译 内核模块，没有 DKMS 源码，且绑定精确内核版本： stereolabs-zedlink-duo_1.4.3-LI-MAX96712-L4T36.5.0 声明 Depends: nvidia-l4t-kernel (>= 5.15.185), (<< 5.15.186)。JetPack 6.2.3／L4T 36.5.2 附带内核 5.15.199，因此每个 .ko 的 vermagic 都不匹配。

症状很容易误导：SDK 用户态库正常加载（ZED SDK available），但 CAMERA NOT DETECTED 仍然存在——因为没有 /dev/video*、没有 zed_x_daemon，也没有解串器模块。 怀疑线缆或配置前，先检查这三项。

降级——无需重刷

36.5.0 和 36.5.2 位于同一个 r36.5 apt 仓库，因此可以直接降级软件包。关键是： 枚举所有已安装的 nvidia-l4t-* 中具有 36.5.0 版本的包，并在一条命令中列出全部。只列几个会让 apt 删除 其余包，包括 nvidia-l4t-bootloader 和 nvidia-l4t-initrd。正确结果应为“48 downgraded, 0 to remove”。

• 始终先用以下选项试运行： apt-get install -s ，先完成这一步。
• apt-mark hold 随后锁定全部包。
• 它会通过 capsule update 重写引导程序，因此 务必守在控制台前.

本机已确认的硬件

采集卡为 ZED Link Duo ，安装在原装 Orin Nano 开发套件载板上（p3768 / p3767-0005）。头部相机为 ZED X Mini （双目、一条 GMSL 链路、两个 /dev/video* 节点、S/N 53756133），接端口 0。 /etc/dexmate/dexsensor/default.toml 是多个 Vega 型号共用的通用配置，包含 ZED X One 腕部、底部相机和 LiDAR 条目。本机实际腕部为 两只原装 ISX031／MAX9295 相机，连接独立 Waveshare MAX9296A；ZED X One 条目不适用。接线和驱动配置见 B8 。

来自「整理 DexMate 硬件与控制信息」任务的测量记录（2026-09-14 UTC）。该次测量时，左右腕部相机均未启用。

实测发布频率

深度反投影

对校正后的像素 (u, v)，深度 Z 有效且单位为米时，使用对应图像流的内参：

X = (u - cx) * Z / fx
Y = (v - cy) * Z / fy
p_camera = [X, Y, Z, 1]
p_base = T_base_camera @ p_camera

标定记录来自「暂存代码并重新标定区域」任务。该任务在 9 月 24 日最终恢复了 clean 提交 b90bcac 的 TCP／相机组合。原始 pivot 实测拟合值和此前调整 Y 后的组合在下方分别列出。

文件

• vega_1u.urdf · 上传的机器人模型。
• vega_1u_gripper.urdf · 上传的夹爪模型，包含 L_camera_link 和 R_camera_link。
• 标定项目中的自定义夹爪 URDF · 另一份包含 tip_l／tip_r 的模型，用于名义 TCP 对照。
• Clean TCP＋相机标定 · 此前调整 Y 的组合 · Pivot 实测拟合结果。
• 全部矩阵、源文件校验值及坐标系定义（JSON）。

两份上传的 URDF 与 dexmate_urdf 0.8.4 包内文件逐字节一致，保留了原文件及相对 mesh 路径。Mesh 需在软件包的目录结构中解析；单独下载 URDF 不包含 mesh。用于对照的自定义模型单独存放。

坐标约定

T_parent_child 将列向量坐标从 child 转到 parent：p_parent = T_parent_child @ p_child。平移单位为米，角度单位为弧度。R = Rz(yaw) @ Ry(pitch) @ Rx(roll)。基座轴向：X 向前、Y 向机器人左侧、Z 向上；已标定的左相机光学轴向：X 向图像右侧、Y 向图像下方、Z 向前。

右侧 TCP：模型、实测拟合与选用值

两份上传的软件包 URDF 定义了 L_ee／R_ee，但没有定义 tip_l／tip_r 夹持 TCP。下面的名义 tip 来自单独的自定义模型。

最终选用值和调整 Y 的组合使用工具坐标约定 rpy = [π, 0, π/2]。这一旋转是名义约定，并非 pivot 实测结果。提供的实测 TCP 数据针对右夹爪。

[
  [ 0.000000000,  1.000000000,  0.000000000, -0.001000000],
  [ 1.000000000,  0.000000000,  0.000000000, -0.015000000],
  [ 0.000000000,  0.000000000, -1.000000000,  0.198000000],
  [ 0.000000000,  0.000000000,  0.000000000,  1.000000000]
]

[
  [ 0.000000127,  1.000000000, -0.000000046,  0.000000193],
  [ 1.000000000, -0.000000127,  0.000006200, -0.015001328],
  [ 0.000006200, -0.000000046, -1.000000000,  0.197999807],
  [ 0.000000000,  0.000000000,  0.000000000,  1.000000000]
]

[
  [-0.000012680, -1.000000000,  0.000000046, -0.000000005],
  [-1.000000000,  0.000012680, -0.000006200,  0.015001328],
  [ 0.000006200, -0.000000046, -1.000000000,  0.197999807],
  [ 0.000000000,  0.000000000,  0.000000000,  1.000000000]
]

实测头部相机外参

Clean 相机外参使用水平棋盘约束拟合，并与 clean TCP 一起恢复。记录中的留出点 RMS 为 1.176229 mm。该组合对应以下参考头部姿态：

head_j1 = -0.00017453292093705386 rad
head_j2 = -0.00017453292093705386 rad
head_j3 = -0.5056219100952148 rad
torso_flip = 0.22689280275926285 rad
Lift = 0 m

[
  [-0.001383542, -0.636266466,  0.771468126,  0.089032073],
  [-0.999930278, -0.008166881, -0.008528878,  0.026881780],
  [ 0.011727127, -0.771426138, -0.636210805,  1.169376372],
  [ 0.000000000,  0.000000000,  0.000000000,  1.000000000]
]

矩阵对应上面的头部姿态；头部运动后，基座到相机的变换会变化。标定记录保存的校正左目内参为 fx = fy = 734.7626953125、cx = 966.6296997070312、cy = 653.073486328125，分辨率 1920×1200；这是该次标定保存的值，与 C5 中较早记录的值分别列出。

[
  [ 0.000000000,  1.000000000,  0.000000000, -0.001025481],
  [ 1.000000000,  0.000000000,  0.000000000, -0.018000000],
  [ 0.000000000,  0.000000000, -1.000000000,  0.196928685],
  [ 0.000000000,  0.000000000,  0.000000000,  1.000000000]
]

[
  [-0.001383713, -0.636266468,  0.771468125,  0.089057487],
  [-0.999930277, -0.008166772, -0.008529010,  0.023881859],
  [ 0.011727127, -0.771426138, -0.636210805,  1.170447698],
  [ 0.000000000,  0.000000000,  0.000000000,  1.000000000]
]

上传 URDF 中的名义外参

每行是文件中存储的父子关节原点。两份文件均包含头部和 EE 条目；夹爪和腕部相机安装条目位于 vega_1u_gripper.urdf。

在上述相同参考关节位置下，通过软件包 URDF 正运动学计算出的名义头部变换如下：

[
  [-0.000165524, -0.668606938,  0.743615987,  0.084498283],
  [-0.999999986,  0.000085701, -0.000145537,  0.024989645],
  [ 0.000033578, -0.743616000, -0.668606942,  1.144781202],
  [ 0.000000000,  0.000000000,  0.000000000,  1.000000000]
]

URDF 腕部相机安装变换

上传的夹爪 URDF 包含两侧腕部相机 link。连乘固定关节后得到：

[
  [ 1.000000000,  0.000009962,  0.000000872,  0.000199254],
  [-0.000010000,  0.996194738,  0.087155282, -0.074590002],
  [ 0.000000000, -0.087155282,  0.996194738,  0.084250400],
  [ 0.000000000,  0.000000000,  0.000000000,  1.000000000]
]

[
  [-1.000000000,  0.000002643,  0.000000231, -0.000200198],
  [-0.000002654, -0.996194738, -0.087155282,  0.074589999],
  [ 0.000000000, -0.087155282,  0.996194738,  0.084250400],
  [ 0.000000000,  0.000000000,  0.000000000,  1.000000000]
]

这些是名义 camera_link 安装坐标系。文件没有单独定义腕部光学坐标系，也没有给出经实测确认的 ISX031 光学坐标变换。旧任务中“夹爪 URDF 没有腕部相机 link”的结论不适用于这次上传的文件。