hapticajetson

Jetson AGX Orin bring-up repo for the Haptica Sensorics ZED Link Quad setup.

Contents

• AGENTS.md: hard acceptance criteria for the bring-up and validation flow
• docs/JETSON_STEREOLABS_CODEX_RUNBOOK.md: host and Jetson setup runbook
• scripts/zed-mosaic: canonical CLI for the laptop-side 4-stream viewer
• scripts/zed-studio-forever.sh: Jetson-side guarded ZED Studio auto-launcher
• scripts/setup_zed_python_venv.sh: builds the supported Jetson-side Python venv for the ZED SDK
• scripts/zed-python: runs Python inside the Jetson-side ZED SDK venv
• scripts/zed-pip: runs pip inside the Jetson-side ZED SDK venv
• scripts/build-virtual-stereo-depth-demo.sh: builds the Jetson-side virtual stereo demo binary
• scripts/virtual-stereo-depth-demo.sh: keeps the virtual stereo demo running on the Jetson display
• scripts/deploy-virtual-stereo-depth-demo.sh: pushes the depth demo files from the host to the Jetson and rebuilds there
• scripts/complete-sensor-demo.sh: keeps the integrated stereo + wrist + telemetry demo running on the Jetson display
• scripts/deploy-complete-sensor-demo.sh: pushes the integrated demo files from the host to the Jetson
• scripts/launch-complete-sensor-demo.sh: desktop-launch wrapper that shows startup progress while the Jetson camera stack comes up
• scripts/collect_zed_support_bundle.sh: gathers a vendor-aligned Jetson support bundle
• scripts/ptp_network_readiness.sh: checks whether an interface and host are ready for linuxptp/PTP sync
• scripts/zedx-fourcam-diagnose.py: lower-level 4-camera CameraOne diagnostic
• config/complete-sensor-demo.env.example: known-good Jetson env for the integrated showcase app
• systemd/user/zed-mosaic.service: user service for the laptop mosaic viewer
• systemd/user/zed-studio-forever.service: Jetson-side user service for ZED Studio
• systemd/user/virtual-stereo-depth-demo.service: Jetson-side user service for the virtual stereo depth demo
• systemd/user/complete-sensor-demo.service: Jetson-side user service for the integrated showcase dashboard

Usage

Run directly from the command line:

/home/bob-smith/dev/hapticajetson/scripts/zed-mosaic run

Or install the command and service into your user environment:

/home/bob-smith/dev/hapticajetson/scripts/zed-mosaic install
systemctl --user enable --now zed-mosaic.service

After install, use:

zed-mosaic run
zed-mosaic watch
zed-mosaic start
zed-mosaic stop
zed-mosaic restart
zed-mosaic status
zed-mosaic logs

Optional user config can live in ~/.config/zed-mosaic.env, for example:

JETSON_IP=192.168.1.232
LATENCY_MS=80

Jetson ZED Studio Auto-Launch

Run directly on the Jetson:

~/bin/run_zed_studio_forever.sh

Or install the repo-managed script and user service on the Jetson:

REPO_ROOT=~/dev/hapticajetson
install -Dm755 "$REPO_ROOT/scripts/zed-studio-forever.sh" ~/bin/run_zed_studio_forever.sh
install -Dm644 "$REPO_ROOT/systemd/user/zed-studio-forever.service" ~/.config/systemd/user/zed-studio-forever.service
systemctl --user daemon-reload
systemctl --user enable --now zed-studio-forever.service

Optional Jetson-side overrides can live in ~/.config/zed-studio-forever.env, for example:

SETTLE_DELAY_S=30
REQUIRED_CAMERAS=4
PROBE_TIMEOUT_S=10
RESTART_CAMERA_STACK_BEFORE_LAUNCH=1
STACK_RESTART_SETTLE_S=8

On this Jetson, the launcher is intentionally conservative. By default it:

• restarts nvargus-daemon, zed_x_daemon, and IMU_Daemon
• waits for /dev/video0-3
• waits an additional settle delay
• requires 4/4 AVAILABLE from ZED_Explorer --all

That root-level restart path depends on the helper:

install -Dm755 "$REPO_ROOT/scripts/restart-zed-camera-stack" /usr/local/bin/restart-zed-camera-stack

If you want Studio to come up pinned to one camera instead of its default UI, set:

TARGET_SERIAL=306073138
TARGET_RES=HD1200
TARGET_FPS=60

Logs live in ~/.local/state/zed_studio_forever.log and ~/.local/state/zed_studio_systemd.log.

To control whether Studio starts automatically on login without editing systemctl commands manually, install the helper:

install -Dm755 "$REPO_ROOT/scripts/zed-studio-autostart" /usr/local/bin/zed-studio-autostart

Useful commands on the Jetson:

zed-studio-autostart status
zed-studio-autostart enable
zed-studio-autostart disable

The repo also includes desktop launchers for enable, disable, and status. Those can be copied into ~/Desktop/ for a one-click persistent autostart toggle.

Jetson Python Environment

The sustainable Python setup on the Jetson is a dedicated venv built with the official Stereolabs get_python_api.py installer plus pip-managed OpenCV. Do not rely on the mixed system Python environment for GUI Python samples.

Install or rebuild it on the Jetson:

REPO_ROOT=~/dev/hapticajetson
"$REPO_ROOT/scripts/setup_zed_python_venv.sh"
sudo install -Dm755 "$REPO_ROOT/scripts/zed-python" /usr/local/bin/zed-python
sudo install -Dm755 "$REPO_ROOT/scripts/zed-pip" /usr/local/bin/zed-pip

After install:

zed-python -c "import cv2, numpy, pyzed.sl as sl; print(cv2.__version__, numpy.__version__, len(sl.CameraOne.get_device_list()))"
zed-pip check

The default venv path is ~/.venvs/zed-sdk. Override it with ZED_PYTHON_VENV if needed.

Jetson Virtual Stereo Depth Demo

Deploy the demo source, launcher, and user service from the host to the Jetson:

~/dev/hapticajetson/scripts/deploy-virtual-stereo-depth-demo.sh

That rebuilds /home/nvidia/virtual_stereo_depth_demo on the Jetson using the repo source at tools/virtual_stereo_depth_demo.cpp.

Run directly on the Jetson:

~/bin/run_virtual_stereo_depth_demo.sh

Or enable the user service on the Jetson:

systemctl --user enable --now virtual-stereo-depth-demo.service

Optional Jetson-side overrides can live in ~/.config/virtual-stereo-depth-demo.env, for example:

LEFT_SN=305075068
RIGHT_SN=308285223
VIRTUAL_SN=117172000
RESTART_CAMERA_STACK_BEFORE_LAUNCH=1
MIN_VIDEO_NODES=4

Logs live in ~/.local/state/virtual_stereo_depth_demo.log and ~/.local/state/virtual_stereo_depth_demo_systemd.log.

Current known-good Jetson demo settings are documented in stereopair.md under Known Good Demo State (2026-03-19).

Jetson Complete Sensor Demo

The repo also includes an integrated dashboard app that combines:

• virtual stereo left image
• virtual stereo depth view
• left wrist camera
• right wrist camera
• live IMU telemetry from a selected wrist camera
• live GPS status from gpsd

Run directly on the Jetson:

~/dev/hapticajetson/scripts/complete-sensor-demo.sh

Or deploy the current local repo copy from the host:

~/dev/hapticajetson/scripts/deploy-complete-sensor-demo.sh

Or install the repo-managed launcher and user service on the Jetson:

REPO_ROOT=~/dev/hapticajetson
install -Dm755 "$REPO_ROOT/scripts/complete-sensor-demo.sh" ~/bin/run_complete_sensor_demo.sh
install -Dm644 "$REPO_ROOT/systemd/user/complete-sensor-demo.service" ~/.config/systemd/user/complete-sensor-demo.service
systemctl --user daemon-reload
systemctl --user enable --now complete-sensor-demo.service

Optional Jetson-side overrides can live in ~/.config/complete-sensor-demo.env, for example:

cp ~/dev/hapticajetson/config/complete-sensor-demo.env.example ~/.config/complete-sensor-demo.env

If ~/.config/virtual-stereo-depth-demo.env already exists, the launcher will read that first so the known-good stereo tuning carries over automatically.

Known-good integrated demo settings on the current Jetson are:

• stereo head serials 305075068 / 308285223
• virtual stereo serial 117172000
• left wrist 306302901
• right wrist 306073138
• DEPTH_MODE=NEURAL
• DEPTH_MIN_MM=300
• DEPTH_MAX_MM=3000
• DEPTH_STABILIZATION=60
• ROTATE_180=1
• CAMERA_FPS=30
• STEREO_RESOLUTION=HD1080
• WRIST_RESOLUTION=AUTO
• DEPTH_PREVIEW_FPS=15
• RECORD_SEGMENT_MAX_S=600

Current launch behavior on the Jetson desktop:

• the desktop icon calls ~/bin/launch_complete_sensor_demo.sh
• startup commonly takes around 45s because the launcher waits for Argus, the ZED daemons, /dev/video*, and a settle period before opening the app
• the launcher now shows a small Zenity progress window with the real startup phases instead of leaving a stale notification on screen
• pressing q stops the app and the launcher loop, so the desktop icon can be used for a clean relaunch

Recording bundle behavior:

• recording toggles from the running app and writes to /data/recordings/complete_sensor_demo
• each segment is capped at 10 minutes and automatically rolls to a new one
• every bundle contains stereo_head.svo2, left_wrist.svo2, right_wrist.svo2, depth_preview.mp4, depth_preview_timestamps.jsonl, telemetry.jsonl, and session.json

Important implementation note:

• on this Jetson, a minimal Python sl.Camera virtual-stereo probe repeatedly failed with CAMERA STREAM FAILED TO START
• the integrated dashboard therefore uses the proven C++ virtual-stereo path and only reuses the wrist-camera and telemetry learnings from the Python probe

Support Bundle

Stereolabs support wants a diagnostic file from the ZED diagnostic tool. The repo also includes a broader Jetson support bundle collector that captures the key camera, daemon, boot, and Python state in one directory.

Run on the Jetson:

~/dev/hapticajetson/scripts/collect_zed_support_bundle.sh

Or after installing it into PATH:

collect-zed-support-bundle

PTP Readiness

If the rig moves to distributed Ethernet streaming across multiple hosts, use PTP (linuxptp) instead of ad hoc clock sync. The repo includes a quick readiness checker:

~/dev/hapticajetson/scripts/ptp_network_readiness.sh eno1

It checks whether the interface exposes hardware timestamping and whether ptp4l, phc2sys, and pmc are installed.

Lower-Level 4-Camera Diagnostic

Run on the Jetson to validate the four-camera capture path outside ZED_Studio:

zed-python ~/dev/hapticajetson/scripts/zedx-fourcam-diagnose.py --duration 30 --resolution HD1200 --fps 60 --retrieve

Use --retrieve to include image retrieval load. Without it, the script measures grab() throughput only.

Imported From

• /home/dev/AGENTS.md
• /home/dev/HapticaAgenticEng/JETSON_STEREOLABS_CODEX_RUNBOOK.md
• /home/dev/.local/bin/zed_mosaic.sh
• /home/dev/zed_mosaic_loop.sh
• /home/dev/.config/systemd/user/zed-mosaic.service

The older duplicate scripts have been consolidated into scripts/zed-mosaic.