Heterogeneous 7-DoF Bilateral Teleoperation

This repository contains the manuscript, canonical robot models, pre-prototype closed-loop simulator, and reproducible evidence pipeline for heterogeneous 7-DoF master--slave teleoperation.

The current implementation supports numerical and simulation evidence only. It must not be used to claim physical wrench accuracy, hardware stability, or human-subject performance before the corresponding locked hardware studies are completed.

Repository layout

• code/core/: SEW retargeting, H1 baselines, wrench estimation, feedback mapping, network emulation, command allocation, and passivity supervision.
• code/simulate_closed_loop.py: rigid-body bilateral simulation using master_7dof.urdf and real_slave_7dof.urdf.
• code/experiments/: immutable plans, paired random streams, atomic trial logging, manifests, validation, and executable H1--H4 adapters.
• code/analysis/: independent endpoint reconstruction and paper source-data generation.
• code/config/experiments/: smoke, calibration, locked simulation, and locked-template study specifications.
• docs/calibration/: calibration policy, traceable audit, and machine-readable freeze decisions.
• paper/exoskeleton/IEEEtran/main2.tex: canonical manuscript source.

Reproducible environment

Python 3.10 is required. From the repository root:

uv sync --locked

The lock file pins the Pinocchio-compatible urdfdom and tinyxml2 ABIs.

Verification

PYTHONDONTWRITEBYTECODE=1 \
MPLCONFIGDIR=/tmp/exoskeleton-mpl-cache \
XDG_CACHE_HOME=/tmp/exoskeleton-xdg-cache \
.venv/bin/python -m unittest discover -s code/test -p 'test_*.py' -v

Minimal H1 smoke study

.venv/bin/exo-experiment plan \
  --spec code/config/experiments/h1_smoke.json \
  --output /tmp/h1-plan.json

.venv/bin/exo-experiment run \
  --plan /tmp/h1-plan.json \
  --batch-dir output/experiments/h1-smoke \
  --executor experiments.executors:execute_h1_retargeting

.venv/bin/exo-experiment validate \
  --batch-dir output/experiments/h1-smoke

.venv/bin/exo-paper-artifacts \
  --batch-dir output/experiments/h1-smoke \
  --metric-config code/config/experiments/metrics_h1_calibration.json

Equivalent executor/config pairs are documented in code/experiments/README.md.

The current v3 numerical redesign provides two deliberately separate calibration paths:

• h1_calibration_v3.json crosses the SEW angle representation cut once and then twice on a round trip, while recording the actual SEW 7-by-7 differential and descriptive 50 Hz timing.
• bilateral_calibration_v3_stable_contact.json calibrates slow, unsaturated contact before any network study.
• bilateral_calibration_v3_energy_challenge.json adds a synthetic, smooth upstream energy stress only for H4; it is not eligible for H3.
• bilateral_network_v3_screening.json pairs nominal, symmetric-delay, asymmetric-delay, jitter, and loss profiles across free-space and contact trajectories using common random numbers.

All four remain pre-prototype calibration evidence and are not manuscript Results or physical-system validation.

Disjoint-root locked protocols are provided for stable contact, the active H4 energy challenge, and the proposed-loop Stage-B network study. The network protocol is proposed-only: even if it passes, it cannot establish superiority over mapping baselines.

The current calibration decision is recorded in docs/calibration/CALIBRATION_AUDIT_2026-07-27.md. It deliberately leaves H1 and the bilateral gain/energy settings unfrozen; calibration values are not manuscript Results. The companion formula-linked workbook is outputs/calibration-20260727/calibration_audit_2026-07-27.xlsx.

The expanded v3 confirmation, network endpoint semantics, Stage-B calibration outcome, and frozen locked thresholds are recorded in docs/calibration/V3_CONFIRMATION_AND_NETWORK_STAGE_B_2026-07-27.md.

Manuscript build

Compile from paper/exoskeleton so the assets/ paths resolve:

cd paper/exoskeleton
latexmk -pdf -interaction=nonstopmode -halt-on-error IEEEtran/main2.tex

Evidence locking

Calibration and pilot studies may run without Git provenance. A locked study requires a clean Git worktree, an immutable commit, and matching hashes for the environment lock and canonical URDFs. Restoring a locked batch from a different commit or modified source files is rejected by design.