exoskeleton/README.md

# 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:

```bash
uv sync --locked
```

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

## Verification

```bash
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

```bash
.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`.
The first locked execution passed stable contact and the active H4 challenge
20/20, but the network final gate passed 199/200 because one 2% loss instance
exceeded the frozen maximum source-age limit. The audit preserves that failure.

## Manuscript build

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

```bash
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.