83 lines
2.6 KiB
Markdown
83 lines
2.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, and locked-template study
|
||
|
|
specifications.
|
||
|
|
- `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`.
|
||
|
|
|
||
|
|
## 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.
|