i4h Workflow — Teleop Record

Purpose

Enregistrer des épisodes pour un env agentic via téleopération (clavier, SO-ARM leader, ou VR) dans HDF5. Utiliser quand l'utilisateur veut téléopérer ou enregistrer des démos humaines.

Base Code

Ces étapes pilotent le code de base i4h-workflows (l'arborescence workflows/agentic/). Pour réutiliser un checkout existant, définir I4H_WORKFLOWS sur son chemin (aucun clone ne se produit). Sinon, cela résout le repo courant, ou clone vers ~/i4h-workflows — choisir ce défaut sans demander. Exécuter chaque commande ci-dessous à partir de la racine résolue :

# Resolve the i4h-workflows base code (provides workflows/agentic/).
ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"
if [ ! -d "$ROOT/workflows/agentic" ]; then
  ROOT="${I4H_WORKFLOWS:-$HOME/i4h-workflows}"
  [ -d "$ROOT/workflows/agentic" ] || git clone https://github.com/isaac-for-healthcare/i4h-workflows "$ROOT"
fi
export I4H_WORKFLOWS="$ROOT"; cd "$ROOT"

Basics

• Config env (source de vérité) : workflows/agentic/config/environments/<env>.yaml — robot.type, zenoh.camera_names, et la task pour <env>.
• La téleopération s'exécute via arena/run.sh --teleop.
• Le support des périphériques dépend de l'env. Vérifier arena/run.sh --env <env> --help pour les valeurs --teleop-device valides.
• Ne pas lancer la téleopération sans interface graphique sauf si l'utilisateur le demande explicitement. La téleopération est un handoff GUI/matériel : lancer l'enregistreur n'est pas la même chose qu'enregistrer des démos réussies.

Controls

Touches réservées (cohérentes entre les périphériques) :

Les keybindings spécifiques au périphérique (mouvement, rotation, gripper, changements de mode) sont affichés par le processus teleop au démarrage et varient selon --teleop-device. Les signaler à l'utilisateur à partir du log ; ils ne peuvent pas piloter la sim sans eux. Voir « Surface Device Keybindings ». Pour keyboard_23d, la bannière peut s'afficher tardivement, après la création de la scène et la configuration de l'enregistreur ; attendre les marqueurs de mode/contrôle tels que BOTH_HANDS, HAND MODE, BASE NAVIGATION MODE, SPECIAL KEYS, ou Current Mode avant de dire que les contrôles manquent.

Arrêter depuis le terminal :

workflows/agentic/stop.sh arena --env <env>

Known Devices

Pour les autres envs, consulter arena/run.sh --env <env> --help.

Run

Exécuter les étapes ci-dessous dans l'ordre. Chaque étape est un appel bash séparé ; les variables persistent dans la session tmux de l'agent local.

Step 1 — setup

REPO_ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"; [ -d "$REPO_ROOT/workflows/agentic" ] || REPO_ROOT="$HOME/i4h-workflows"
ENV_ID=scissor_pick_and_place
RUNS_ROOT="${REPO_ROOT}/workflows/agentic/runs"
RUN_DIR="${RUNS_ROOT}/teleop_${ENV_ID}_$(date +%Y%m%d_%H%M%S)"
mkdir -p "${RUN_DIR}/data" "${RUN_DIR}/logs"
ln -sfn "${RUN_DIR}" "${RUNS_ROOT}/.latest"

Step 2 — teleop record

Utiliser la forme foreground quand l'opérateur humain est prêt à piloter immédiatement et que l'agent peut rester attaché jusqu'à l'achèvement :

"${REPO_ROOT}/workflows/agentic/arena/run.sh" \
  --env "${ENV_ID}" \
  --teleop \
  --teleop-device <device> \
  --episodes 3 \
  --record-to "${RUN_DIR}/data/demo.hdf5" \
  2>&1 | tee "${RUN_DIR}/logs/teleop.log"

Si aucun opérateur humain n'est prêt, ne pas simuler des démos et ne pas laisser de processus teleop en arrière-plan. On peut lancer assez longtemps pour confirmer l'interface graphique visible, l'enregistreur, et les contrôles, puis arrêter proprement et signaler que l'enregistrement attend un opérateur humain.

Surface Device Keybindings

Le processus teleop affiche sa table de keybindings sur stdout peu après le lancement (chercher les sections telles que Keybindings, Controls, Key Map, BOTH_HANDS, HAND MODE, BASE NAVIGATION MODE, SPECIAL KEYS, WORKSPACE LIMITS, Current Mode, lignes de changement de mode, ou tout bloc énumérant les touches/actions). Attendre que la table apparaisse, l'extraire du log, et la signaler à l'utilisateur avant qu'il n'ait besoin de piloter la sim.

# After launching teleop and tailing the log:
for i in $(seq 1 180); do
  if grep -qiE 'Keybind|Controls|Key Map|BOTH_HANDS|HAND MODE|BASE NAVIGATION MODE|SPECIAL KEYS|WORKSPACE LIMITS|Current Mode|Mode\] Switched|run complete|Traceback|Error' "${RUN_DIR}/logs/teleop.log" 2>/dev/null; then
    break
  fi
  sleep 1
done
grep -n -A80 -E 'Keybind|Controls|Key Map|BOTH_HANDS|HAND MODE|BASE NAVIGATION MODE|SPECIAL KEYS|WORKSPACE LIMITS|Current Mode|Mode\] Switched' "${RUN_DIR}/logs/teleop.log" | head -120

Si le bloc est multi-section (p. ex. BOTH_HANDS, BASE_NAV, LEFT_HAND, RIGHT_HAND modes), inclure chaque mode dans le rapport. Ajouter les touches réservées ci-dessus pour que l'utilisateur dispose d'une référence consolidée.

Notes

• --record-to doit être absolu. L'enregistreur résout les chemins relatifs par rapport à workflows/agentic/arena (son CWD) et écrit dans un répertoire orphelin imbriqué. ${RUN_DIR}/data/demo.hdf5 construit à partir de ${REPO_ROOT} est absolu.
• Utiliser --save-all-episodes seulement quand les tentatives échouées doivent être conservées.
• Si le prompt demande « Lancer teleop pour N épisodes » et qu'aucune entrée humaine/opérateur n'est disponible, lancer l'enregistreur visible uniquement pour la vérification de disponibilité/contrôle, l'arrêter proprement, et signaler qu'aucune démo n'a été enregistrée ; ne pas prétendre que N épisodes ont été enregistrés.

Verify

• ${RUN_DIR}/data/demo.hdf5 existe.
• Le log contient run complete: N/M episodes succeeded, et N doit égaler le nombre d'épisodes demandés avant de rapporter le succès. Un petit HDF5 avec 0/M episodes succeeded n'est qu'un artefact d'enregistrement échoué/vide, pas un dataset utilisable.
• Avant la réponse finale, vérifier qu'aucun processus teleop involontaire ne reste en cours d'exécution sauf si l'utilisateur a explicitement demandé de le garder ouvert.

Prerequisites

• Workflow configuré via [[i4h-workflow-setup]] (le .venv doit exister).
• Un id env valide et un --teleop-device qu'il supporte (voir Known Devices ou arena/run.sh --env <env> --help).
• Le périphérique teleop choisi disponible (clavier, SO-ARM leader, ou VR).
• Un chemin HDF5 --record-to absolu (les chemins relatifs se résolvent par rapport au CWD d'arena).

Limitations

• Le support des périphériques dépend de l'env ; pas chaque périphérique ne fonctionne avec chaque env.
• --record-to doit être absolu ou l'enregistrement atterrit dans un répertoire orphelin imbriqué.
• Par défaut, seuls les épisodes réussis sont sauvegardés ; utiliser --save-all-episodes pour conserver les tentatives échouées.
• Les keybindings spécifiques au périphérique ne sont affichés qu'au démarrage ; ils ne peuvent pas être connus avant le lancement.

Troubleshooting

• Error: .venv non trouvé / teleop ne démarre pas - Cause : workflow non configuré. Fix : exécuter [[i4h-workflow-setup]] d'abord.
• Error: --teleop-device invalide pour l'env - Cause : périphérique non supporté par cet env. Fix : choisir une valeur parmi arena/run.sh --env <env> --help (ou Known Devices).
• Error: HDF5 écrit à un emplacement inattendu/imbriqué - Cause : --record-to était relatif. Fix : passer un chemin absolu construit à partir de ${REPO_ROOT}.
• Error: keybindings manquants / impossible de piloter la sim - Cause : la table de keybindings du périphérique n'a pas été surfacée. Fix : extraire la table du log avant que l'opérateur ne commence à piloter (voir Surface Device Keybindings).
• Error: l'exécution se termine avec 0/N episodes succeeded - Cause : aucun opérateur humain n'a complété d'épisodes. Fix : enregistrer des démos sources réussies avec un opérateur ; ne pas continuer à mimer/convertir/finetune à partir d'un HDF5 vide.

Final Response

Signaler l'env, le périphérique, la table de keybindings spécifique au périphérique extraite du log, les épisodes demandés vs sauvegardés, le chemin HDF5, le chemin du log.