Vega-1U Field Manual

This robot is already set up. Nothing in Part B needs repeating — the certificate is installed, the libraries are in place, and the Jetson joins CMU-DEVICE on its own at boot. A normal session is: SSH in, run a script onboard.

When you have to spell out ROBOT_NAME

Dexmate pre-sets ROBOT_NAME on the Jetson, so once you are sitting in an interactive shell it is already there — echo $ROBOT_NAME confirms it, and scripts run normally with no prefix. The prefix matters in exactly one situation: a command that never gets an interactive shell, because ~/.bashrc is not sourced and Robot() then raises ValueError.

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

A session, start to finish

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

That is the whole required part. Everything below is per-task — bring up only the subsystem you are about to use.

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

The head service already runs on this unit. Subscribe with A2; the wrist API starts capture on demand. Wiring and boot configuration are in 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

Cameras (A2), grippers (A5) and arm motion (A4) are independent of each other. For arms always go through the named poses, never a pose_pool entry.

When the IP has moved

172.26.161.243 is a DHCP lease on CMU-DEVICE and will change eventually. When SSH stops answering, in ascending order of effort:

1. Scan the subnet: nmap -sn 172.26.160.0/22 | grep -B2 -A2 "vega\|dexmate\|ubuntu"
2. Plug in a cable and use the wired address 192.168.50.20, which does not move.
3. Plug a monitor and keyboard into the IO hub and read the address off the desktop.

Working from a workstation instead

We currently run everything onboard. Driving the robot from your own machine is possible but needs its own one-time setup — dextop, the same certificate unpacked locally, and the environment variables — described in B5. It buys you a better GPU at the cost of network latency.

The head camera is published by the existing dexsensor service. The two OEM wrists use the local WristCameras Python API. Both can be read together. Use the sensor-only examples below to obtain images without constructing Robot(), which homes the head. Setup: B8.

Joints, current, wrench, buttons — no dexsensor needed

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()

Head camera: subscribe to the running service

Run on the Jetson as dexmate with the installed system Python. Set the robot name explicitly in non-interactive shells. Do not launch a second head service or open another ZED SDK camera while dexsensor owns it.

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()

With include_timestamp=True, each stream returns a record with data, timestamp_ns and receive_time_ns; a stream can be None before it is ready. With the default include_timestamp=False, each value is the array directly. Left/right RGB are (1200, 1920, 3); depth is a (1200, 1920) floating-point array in metres.

Head camera resolution and intrinsics

Current head settings: HD1200, 1920×1200, configured 30 fps, NEURAL depth. In /etc/dexmate/dexsensor/default.toml, locate the sensor whose id = "head_camera", then its parameters and stream flags. Do not edit by line number. The generic ZED X One wrist entries must stay disabled: they do not describe these ISX031 cameras. Measured throughput is listed in 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

Configuration edits require administrator privileges. Normal head and wrist API reads run without sudo.

Runtime rectified intrinsics at HD1200, from head_camera.get_camera_info() — distortion is empty because the stream is already rectified:

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

Two wrists: local Python API

On the Jetson, use /usr/bin/python3 as dexmate (already in the video and i2c groups). Wrist-only reads require neither sudo nor ROBOT_NAME. Code is installed in /opt/wrist-cameras/ and exposed through wrist_cameras_local.pth in the system Python 3.10 dist-packages directory. A separate virtual environment may not see this module or its GStreamer bindings.

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.

The API discovers V4L2 devices by their sensor names, owns both wrists under one lock and runs software triggering in a separate process. A second reader is rejected with RuntimeError. Always close the context before restarting initialization. This is a local API, not a network endpoint; it is not registered as robot.sensors.left_wrist_camera or right_wrist_camera.

Read head + both wrists in one process

Set ROBOT_NAME as above, save this as a Python script on the Jetson, then run it with /usr/bin/python3. The existing head publisher continues running while the wrist context acquires its two cameras.

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()

To save an RGB frame with OpenCV, convert it first:

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

A tested four-view recorder is installed at /home/dexmate/wrist-camera-debug/coexistence/record_api_demo.py. It subscribes through these APIs, waits 15 seconds for the operator, then records; it sends no motion commands. Close other wrist readers first.

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)"

The new output directory contains preview.avi and recording.json. The AVI writer uses a fixed 6 fps; use the JSON's actual capture duration and frame timestamps when measuring time. Encoding a preview does not measure native camera frame rate.

Other sensors / custom dexsensor configuration

This is a generic reference for sensors supported by dexsensor, not an ISX031 wrist setup step. Only launch a custom publisher after stopping any existing publisher that owns the same camera. On this unit, normal head reads use the running service described above.

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

Beyond the per-sensor enabled flag, the config file tunes resolution, frame rate, depth range, transport (rtc or zenoh) and JPEG quality — the levers for trading image quality against bandwidth.

Head — 3 DOF, but pitch / yaw / pitch

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()

Arms — 7 DOF, joint space

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

Hands, torso, chassis

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()

Software e-stop

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

This complements the physical e-stop buttons. It does not replace them.

Two named poses, two scripts. The thing worth carrying away: the collision risk lives in the schedule, not in the target pose.

Real jaw clearance — measured, not assumed

The gripper-equipped URDF at ~/Downloads/Dexmate/vega_1u_gripper.urdf models the jaws, so clearance can be computed properly: closest point on the left gripper to closest point on the right, over the collision meshes, sampled along a 25-step joint-space interpolation.

Sequencing buys 7–11 cm on the working move, which is why goto_ready.py and goto_rest.py lead with opposite arms. It buys nothing on folded: all three schedules bottom out at the same 5 cm, because there the collision is in the target pose itself, not in the path.

The two poses

pre_move was recorded from the robot's own resting position, which is what makes it the one pose empirically known to be safe to park in. manip_init is the arm half of BrickBench's 23-long Joint_Home_Position; the wrists end up 0.656 m apart, roughly level with the shoulders.

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

Any flag overrides the script's default, e.g. --step 0.02 --wait 1.0 to go slower, because goto_pose reads the first occurrence and your arguments come first.

Why the arms move one at a time

Minimum wrist separation along the path, by schedule:

The clearance guard

goto_pose.py simulates the exact waypoints the move will visit — the same per-joint clipping the real loop uses, and the same left/right schedule — computes wrist separation at each one by URDF forward kinematics, and raises SystemExit if any waypoint falls below MIN_WRIST_SEP (0.35 m, override with --min-sep). Calibration points, all from real outcomes:

folded is banned

folded and folded_closed_hand from the arm pose_pool are in goto_pose.py's BANNED set and refuse to run. They were designed around Dexmate's own end effectors. Do not reach for them as a "safe stow" — pre_move is the stow pose on this robot. Gravity torque is not the criterion either: zero has the lowest static torque of any pose (4.88 N·m) because the arms point straight up, which is an unstable equilibrium with the longest possible fall.

Finishing up

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()"

Leave the arms energised at pre_move. They hold position on their own; de-energised arms would simply sag. Leaving can1 up between sessions is fine.

The grippers are not part of dexcontrol — the robot reports hand type UNKNOWN, so robot.left_hand does nothing. They are two MG4005-i10 V3 servos on a shared CAN bus, wrapped by /home/dexmate/gripper.py, which you drive in parallel with normal arm control. Wiring, bus rates and the protocol archaeology are in C3; this section is how to use the library.

Before anything: the bus has to be up

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 is the Jetson's own on-SoC controller and is not the adapter — always can1. tx stalling at exactly 3 means nobody is ACKing, not success.

The object model

A normal session

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

Homing is not optional

The reason is in the firmware: 0x80 (motor off) discards the multi-turn count, after which the angle reads only the single-turn value wrapped to (−180, 180]. Absolute coordinates are therefore valid only while the motor stays continuously enabled — which is exactly why the driver homes against a real stop at startup and then stays enabled for the whole session.

close() vs grip()

What healthy numbers look like

Shutting down

Two library traps

Files

Ordered by what you see first. Most of these are in no documentation — they were found the hard way.

1. Connect the assembled harness

The assembled harness has a CAN adapter at one end and a 4-pin / 6-pin pair on each of its two branches. Connect each 6-pin plug to the gripper and each 4-pin plug to the robot.

2. Connect the wrist camera cable

Connect the camera cable as well. Use only the connector on the inward-facing side, as shown in IMG_9360.

3. Connect USB and set both switches

Plug the CAN adapter into a robot USB port. Both switches must be toward the K side, as shown in IMG_9369.

Complete assembly

Reference: Waveshare MAX9296-GMSL-Deser-Module · Jetson Orin. Power off before changing connections.

1. Mount the capture board and connect power

Use the brass standoffs supplied in the kit to connect the capture board and PCB, then connect the power cable. Connect the red wires to header pins 2 and 4 (5 V), and ground to pin 6 (GND). These Jetson header pins are 5 V; the grippers' 24 V supply must not be connected here.

2. Set the CFG switches to 0100

Read the switches in their numbered order 1 → 2 → 3 → 4 and set them to 0 → 1 → 0 → 0.

3. Replace the robot's standoffs

Remove and keep the robot's original brass standoffs. First secure the steel frame with 15 mm standoffs, then add 10 mm standoffs to mount the remaining memory/storage assembly and fan.

4. Connect the internal wrist camera cables

• Female–female cable: disconnect the existing internal wrist-camera connection and connect it to the capture board.
• Male–female cable: remove the external-camera connector from the robot's rear cover and connect directly with the male–female cable. IMG_9277 demonstrates this connection.

5. Replace the CAM1 ribbon cable

Disconnect the cable originally attached to Jetson CAM1. Use the ribbon cable supplied in the kit to connect Jetson CAM1 ↔ capture board CSI0.

A robot with no known WiFi brings up its own hotspot on boot. The rule is: no known network → hotspot; known network in range → joins it and the hotspot disappears. You only do this once per robot.

Three ways to reach a shell

For Ethernet, give your own computer a static address first: 192.168.50.x on Vega-1 and Vega-1U (pick any x from 1–255 except 20 and 21). On Vega-1-Pro use 192.168.5.x for the chassis port or 192.168.50.x for the torso port. Netmask 255.255.255.0, gateway empty.

Hotspot credentials by build date

Give it 2–3 minutes after power-on before looking for the hotspot. SSH credentials are always dexmate / hello-dex.

ssh dexmate@10.42.0.1

Joining your 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

Now find the robot on its new network. Use the router's admin page if you have it; otherwise scan:

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

When it won't connect

• No hotspot appears — wait the full 5 minutes; make sure no saved network is left on the robot (it will join that instead); reboot if needed.
• SSH connection refused — confirm you are actually on the robot's hotspot, that you used the IP for your batch, and that boot has finished.
• WiFi join fails — recheck SSID and password, confirm the network is 2.4 GHz or dual-band, move the robot closer to the router.
• Can't find it on the new network — allow 2–3 minutes; if you set a static IP, restart the router and confirm the address doesn't clash with its settings.

The certificate is the ticket onto the bus: install it once, it lasts until it expires. Firmware updates are optional; the certificate is not. Dexmate documents two paths, and the certificate can only go through the web portal.

Method 1 · Web portal (required for the certificate)

The SoC board sits on the 192.168.50.x subnet, unreachable from the WiFi side, so open a route first:

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

1. Open https://192.168.50.21:57832. First visit asks you to set a password — make it memorable.
2. Upgrade the dashboard itself first (Check for Updates). If that fails, download the socbridge file from software.dexmate.ai and upload it manually.
3. Upload the Dexmate-issued certificate in the communication section.
4. Firmware updates, if you want them, happen in the same portal.

Method 2 · Command line (only with a valid certificate already installed)

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

Skip this section if you only ever run code onboard. To drive the robot from your own machine, the workstation has to join the same Zenoh bus.

pip install dextop --upgrade

dextop cert unpack <certificate_file>.dzcfg

dextop node install-service

Below 0.5.0 the relay is manual and has to stay running, so put it in 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

For a fleet, give each robot its own terminal with its own ROBOT_NAME — one workstation drives all of them.

dexcontrol — control

pip install dexcontrol

Examples are open source at github.com/dexmate-ai. Dexmate suggests running examples/advanced_examples/fold_robot.py first to unfold a new robot — do not run that on this one; see the trap table.

dexsensor — perception, Jetson only

Download the right architecture from software.dexmate.ai (arm64 for Jetson), then:

sudo dpkg -i <dexsensor_xxx>.deb

• Coming from the Python-based dexsensor ≤ 0.3.1, uninstall it cleanly first, then install ≥ 0.6.9.
• The ZED SDK ships pre-installed at /usr/local/zed, with PyZED in the base conda env. For your own environment, run python get_python_api.py from that directory.
• ZED SDK not found while import pyzed works is a C++ stdlib mismatch: conda update -c conda-forge libstdcxx-ng -y.
• Each dexsensor release expects a particular ZED SDK version — pull it from the Stereolabs release archives.
• Never launch dexsensor over ssh -X; the ZED camera will fail to initialize.

Run these before writing any code. Confirming the link works first saves a lot of "is it my script or the robot?"

dextop topic list --timeout 10

The first call from an external machine often returns nothing — dextop needs a moment to reach the robot. Run it again or raise the timeout.

The head stereo camera and both wrists have delivered images concurrently on dm/vg3eb20f25bb-1u. Hardware: Orin Nano 8 GB p3767-0005 on the stock p3768 carrier; L4T 36.5 with Linux 5.15.185-tegra. Daily API examples are in A2.

Current repository: boot startup

Wrist initialization is already included. scripts/install.py --apply installs and enables wrist-camera-init.service. At boot it waits for both wrist devices, initializes them, and writes a readiness marker. active (exited) is normal for this oneshot service. It does not keep streaming: WristCameras() starts capture and triggering when your application opens it, and stops them when it closes.

Head streaming uses the vendor's dexsensor.service. The installer does not explicitly enable this service. --configure-head writes the head configuration and robot name, but does not enable or start the service. Check its state and enable it using the commands below. This is the repository's behavior; the commands inspect the robot on which you run them.

For a new robot, follow the repository Quick start with the matching vendor packages installed first. --camera-boot --activate-camera-boot builds and selects DexmateSetupHeadWrists, using /boot/initrd-dexmate-setup and /boot/tegra234-dexmate-setup.dtbo. Without --activate-camera-boot, the entry is only staged. The installer does not start services or reboot. The older HeadWrists paths in the integration record below belong to the original robot setup.

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

After installation, enable both services for future boots. If a unit is reported as “not found”, install its package first: the vendor dexsensor package for the head, or this repository's installer for wrist initialization.

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

Then reboot manually after reviewing the selected boot entry. To start or reinitialize cameras in the current boot, first close wrist readers and any standalone ZED viewer. These commands interrupt camera streams; they do not reboot the robot. They cannot activate a newly selected kernel overlay without a reboot.

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

If cameras do not work

Start on the Jetson to separate hardware/service problems from workstation communication. Inspect status and logs first:

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'

After recovery, use the A2 head + wrists example. Confirm head RGB/depth are nonempty, head source timestamps advance across repeated reads, and both wrist frame IDs increase. Service “active” and video device nodes alone do not prove frames are arriving. Do not hot-unload the camera driver stack; use the preserved boot entries and a controlled reboot for boot/driver recovery.

Original robot integration record · 2026-09-15

Physical connections

The tested enumeration was wrists /dev/video0, /dev/video1 and head /dev/video2, /dev/video3. These numbers can change after boot: use the API's discovery, not hard-coded indices. A power LED alone does not establish that frames are arriving; the stream tests below do.

Installed boot and initialization chain

1. /boot/extlinux/extlinux.conf selects DEFAULT HeadWrists, loading /boot/tegra234-head-wrists.dtbo and /boot/initrd-head-wrists-default.
2. The initrd supplies patched tegra-camera.ko and isx031-gmsl-camera-b.ko through read-only bind mounts before modules load. The original kernel, base DTB, on-disk modules and /boot/initrd are retained.
3. The enabled wrist-camera-init.service waits for both wrist probes, applies camera-specific initialization and writes /run/wrist-cameras/ready.json. It is a oneshot: active (exited) with exit status 0 is normal. It skips the old single-camera fallback configuration.
4. dexsensor.service continues publishing the head through the ZED stack. WristCameras() starts wrist capture and software triggering on demand; closing its context stops them. Boot initialization does not start continuous wrist recording.

Why the stock packages were insufficient

The two original overlays overlapped VI/CSI channels. The combined overlay preserves the head's 26 channels and adds wrists at 26/27, with six physical CSI lanes total. It also removes the permanent CAM0-select GPIO hog and places the head board's TCA9546 below the carrier's CAM0 GPIO-mux branch.

The camera framework needed a parent-walk patch for that nested I²C mux; otherwise the head probe failed with i2c bus regbase unavailable / error -75. The wrist driver needed MAX9295 identification and a 3 Gbps link configuration, followed by the OEM camera's reset, clock, video and trigger initialization. Device nodes alone were not enough to produce frames.

The supplied Downloads/orin_kernel_img_260506_v3.4/ package contains a 5.15.148-rt kernel and AGX-specific device tree. Those binaries do not match this Nano's 5.15.185-tegra. Only the camera-specific initialization was adapted; do not apply that package's whole-system installer to this setup. Rebuild/recheck the custom modules after any kernel or JetPack upgrade.

Readiness and recovery checks

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

A successful initialization marker must belong to the current boot. If it is missing, inspect the service log and selected boot files. Device-busy errors mean another reader owns the wrists; close that reader. A plain V4L2 pull does not provide the required software triggering.

If camera initialization must be repeated, first close every wrist reader, then run:

sudo systemctl restart wrist-camera-init.service

This restarts camera initialization, not the robot. Re-open the API after the service succeeds.

Boot configuration backup: /boot/extlinux/extlinux.conf.before-default-head-wrists-20260915. Selecting the old ISX031 entry restores the wrist-only boot path; it does not provide the combined head + wrists configuration. New default initrd SHA256:

f449a4ea16dc1bda7a0ce3dc6508c82472faf07e6b02e7b31cd102d72eedad69

Measured results and limits

The raw test had 19.662 seconds of common overlap, unique increasing source timestamps and zero application-level capture/trigger errors. Some startup/stop kernel messages remained; this does not establish an error-free kernel log. Long-duration stability, 30 fps wrists, disconnect/reconnect and new-default cold boot are still unverified.

Rebuild files and evidence

Jetson workspace: /home/dexmate/wrist-camera-debug/coexistence/. Mac archive: /Users/huxinyu/Documents/ChatGPT/ICL/camera-coexistence/. Keep the archive with this manual when reproducing the setup; the prose alone is not a replacement for the patched modules and camera register initialization.

• default-camera/README.md, api-test.json and initrd-build-verification.json: installed API, service checks and new-default validation scope.
• build_candidate.py, sensor-common-nested-gpio-mux.patch and default-camera/build_default_initrd.py: combined overlay, framework patch and default initrd builder.
• RESULTS.md and concurrent-independent-trigger-20s.json: concurrent capture results.
• Mac motion demo: /Users/huxinyu/Documents/ChatGPT/ICL/output/head-wrists-motion-demo-20260915/head-wrists-motion-demo.mp4.

Every Dexmate component talks over Zenoh, authenticated by a single encrypted certificate. Knowing which library lives on which machine is the prerequisite for everything below — installing one in the wrong place is the most common way to lose an afternoon.

Two ways to run

• Onboard — code executes on the Jetson. Lowest latency, ROBOT_NAME already set, and the right default for demos and real-time control.
• From a workstation — run AI models on a better GPU and send control over WiFi or Ethernet. You pay latency for the convenience. Both machines must sit on the same LAN, both need dextop, and both need the same certificate unpacked.

The environment variables

Vega-1U is the upper body of a Vega-1. Total controllable DOF is 17: left arm 7 (L_arm_j1..j7), right arm 7 (R_arm_j1..j7), head 3 (head_j1..j3). No torso and no chassis — Vega1UConfig.components lists only the two arms, head, estop and heartbeat, and the 16 keys from dextop topic list contain no state/torso or control/torso.

Arm joint limits (rad) — asymmetric between sides

Arm pose_pool: folded, folded_closed_hand, L_shape, lift_up, zero. Head: home, tucked.

Scripts already on the robot

Two third-party grippers hang off a shared CAN bus driven by a Jhoinrch RH-02 USB-to-CAN adapter (a Canable/candleLight clone, STM32F072C8T6, USB ID 1d50:606f). The robot reports hand type UNKNOWN, so they cannot be driven through robot.left_hand — they are commanded over can1 in parallel with arm control.

gs_usb has to be built by hand

The L4T kernel ships no gs_usb (CONFIG_CAN_GS_USB is not set, and the whole drivers/net/can/usb/ directory is absent), and no slcan either — so reflashing the adapter with slcan firmware is not a way around it. The headers are present and an out-of-tree build works:

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

Any kernel change wipes this — rebuild against the new version (match the source tag to the running kernel). DKMS would make it permanent.

On 2026-08-25 this robot was reflashed to JetPack 6.2.3, which wiped the entire factory Dexmate config: ZED SDK, dexsensor, dextop, the Zenoh certificate, and the static IP on enP8p1s0. Dexmate documents no reflash-recovery procedure. What follows is Rahul's four steps from ticket #126892650 plus everything we had to work out to finish the job.

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

The camera problem was never a missing driver

Stereolabs' ZED Link driver ships prebuilt kernel modules with no DKMS source, pinned to an exact kernel: stereolabs-zedlink-duo_1.4.3-LI-MAX96712-L4T36.5.0 declares Depends: nvidia-l4t-kernel (>= 5.15.185), (<< 5.15.186). JetPack 6.2.3 / L4T 36.5.2 ships kernel 5.15.199, so every .ko had the wrong vermagic.

The symptom is deceptive: the SDK's userspace libraries load fine (ZED SDK available) while CAMERA NOT DETECTED persists — because there is no /dev/video*, no zed_x_daemon, and no deserializer modules. Check those three before suspecting cables or config.

The downgrade — no reflash needed

36.5.0 and 36.5.2 live in the same r36.5 apt repo, so a straight package downgrade works. The critical part: enumerate every installed nvidia-l4t-* that has a 36.5.0 version and name them all in one command. Naming only a few makes apt remove the rest, including nvidia-l4t-bootloader and nvidia-l4t-initrd. The correct result is "48 downgraded, 0 to remove."

• Always dry-run with apt-get install -s first.
• apt-mark hold the lot afterwards.
• It rewrites the bootloader via capsule update, so be at the console.

Hardware confirmed on this unit

The capture card is a ZED Link Duo on a stock Orin Nano devkit carrier (p3768 / p3767-0005). The head camera is a ZED X Mini (stereo, one GMSL link, two /dev/video* nodes, S/N 53756133) on port 0. /etc/dexmate/dexsensor/default.toml is generic across Vega variants and includes ZED X One wrist, base-camera and LiDAR entries. The actual wrists on this unit are two OEM ISX031 / MAX9295 cameras on a separate Waveshare MAX9296A; the ZED X One entries do not apply. See B8 for their wiring and driver setup.

Measurements from “整理 DexMate 硬件与控制信息” (2026-09-14 UTC). The wrist cameras were not enabled during this measurement session.

Measured publication rates

Depth back-projection

For a rectified pixel (u, v) with valid depth Z in metres, use the intrinsics of that stream:

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

Calibration records from “暂存代码并重新标定区域”. Its final selection on September 24 restored the clean b90bcac TCP/camera pair. The measured pivot fit and the earlier Y-adjusted pair are listed separately below.

Files

• vega_1u.urdf · supplied robot model.
• vega_1u_gripper.urdf · supplied gripper model, including L_camera_link and R_camera_link.
• Custom gripper URDF from the calibration project · the separate model containing tip_l / tip_r, used for the nominal TCP comparison.
• Clean TCP + camera calibration · Earlier Y-adjusted pair · Measured pivot-fit result.
• All matrices, source file hashes and frame definitions (JSON).

The two supplied URDFs match dexmate_urdf 0.8.4 byte-for-byte. Their original bytes and relative mesh paths are retained. Meshes resolve within the package's directory tree; the URDF downloads alone do not include the meshes. The custom comparison model is a separate file.

Coordinate convention

T_parent_child maps column-vector coordinates from child to parent: p_parent = T_parent_child @ p_child. Translations are in metres; angles in radians. R = Rz(yaw) @ Ry(pitch) @ Rx(roll). Base axes: X forward, Y robot-left, Z up. The calibrated left-camera optical axes are X image-right, Y image-down, Z forward.

Right TCP: model, measured fit and selected values

The two supplied package URDFs define L_ee / R_ee, but do not define a tip_l / tip_r grasp TCP. The nominal tip below comes from the separate custom model.

The selected and Y-adjusted tool-frame convention uses rpy = [π, 0, π/2]. This orientation is nominal, not a pivot-fit measurement. The supplied measured TCP data cover the right gripper.

[
  [ 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]
]

Measured head-camera extrinsics

The clean camera transform was fitted with a horizontal checkerboard constraint and restored together with the clean TCP. Its recorded held-out RMS is 1.176229 mm. Use this pair at its reference head pose:

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]
]

This matrix is for the listed head pose. Head movement changes the base-to-camera transform. The calibration record uses rectified-left fx = fy = 734.7626953125, cx = 966.6296997070312, cy = 653.073486328125, at 1920×1200; these are the saved calibration values, separately from the earlier values in 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]
]

Nominal extrinsics in the supplied URDFs

Each row is the parent-to-child joint origin as stored in the file. The head and EE rows occur in both files; gripper and wrist-camera mounts occur in vega_1u_gripper.urdf.

Forward kinematics through the package URDF, evaluated at the same reference joint positions above, gives the following nominal head transform:

[
  [-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 wrist-camera mounting transforms

The supplied gripper URDF contains both wrist-camera links. Composing its fixed joints gives:

[
  [ 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]
]

These are nominal camera_link mounting frames. The files do not define separate wrist optical frames or establish a measured ISX031 optical-frame transform. The older task's statement that the gripper URDF had no wrist-camera links does not apply to these supplied files.