120 lines
4.6 KiB
Markdown
120 lines
4.6 KiB
Markdown
# 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.
|