Démonstration de mise en service du pont de capteurs Holoscan

Utilisez cette compétence quand l'utilisateur souhaite mettre en place l'environnement de démonstration du pont de capteurs Holoscan de bout en bout.

Ce workflow a des effets secondaires. Ne l'exécutez jamais automatiquement. Exécutez-le uniquement quand l'utilisateur l'invoque explicitement.

Avant de commencer — barrières requises (à faire d'abord, dans l'ordre)

Barrière 1 — Lire les variables d'environnement. Avant toute autre chose, vérifiez ces variables et affichez leurs valeurs résolues à l'utilisateur :

SSH_TARGET      Connexion au kit de développement distant (p. ex. nvidia@192.168.1.50). Demandez à l'utilisateur si non défini.
REMOTE_ROOT     Répertoire de travail distant (p. ex. /home/nvidia). Demandez à l'utilisateur si non défini.
REMOTE_SUDO     sudo / sudo -n / "" — par défaut "sudo" si non défini.
REMOTE_SSH_OPTS Options SSH supplémentaires (optionnel).
HSB_PLATFORM    Indice de plateforme — peut être vide ; sera détecté à partir du matériel.
HSB_REPO        URL de dépôt personnalisée — par défaut https://github.com/nvidia-holoscan/holoscan-sensor-bridge.git

SSH_TARGET et REMOTE_ROOT sont obligatoires. Arrêtez-vous et demandez-les à l'utilisateur si l'un des deux manque.

Barrière 2 — Présenter le plan des phases. Avant toute action, montrez à l'utilisateur ce plan exact et attendez son approbation :

HSB Setup — Plan des phases
  Phase 0 : Contrôle préalable du budget de tokens
  Phase 1 : Confirmer la plateforme, configurer SSH, cloner le dépôt, étudier le guide utilisateur
  Phase 2 : Vérifications des prérequis de l'hôte et configuration réseau
  Phase 3 : Build CLI natif (AGX Thor uniquement — ignoré pour les autres plateformes)
  Phase 4 : Construire le conteneur de démonstration, l'exécuter, effectuer un ping à 192.168.0.2, vérifier la version FPGA
  Phase 5 : Rapport de problèmes (avec option pour enregistrer)
  Phase 6 : Arrêter les applications, quitter le conteneur, rendre le contrôle à l'utilisateur

Barrière 3 — Contrôle préalable du budget de tokens (Phase 0). Exécutez ceci avant toute connexion SSH ou modification du kit de développement. Consultez la section ## Token-budget preflight pour la procédure complète. Ne passez pas à la Phase 1 jusqu'à ce que la vérification du budget réussisse.

Instructions

Invoquez cette compétence en tapant /hsb-setup [PLATEFORME] [OPTIONS]. La compétence vous guide à travers chaque phase de manière interactive, en demandant une confirmation avant d'effectuer des modifications.

Ce que cette compétence doit faire

Exécutez le contrôle préalable du budget de tokens obligatoire avant toute commande distante ou modification de la configuration du kit de développement. Estimez les tokens nécessaires pour compléter toutes les phases de configuration, vérifiez l'utilisation restante du plan d'abonnement de l'utilisateur avec le meilleur mécanisme disponible pour Claude Code/utilisation de compte, affichez l'estimation et le résultat à l'utilisateur, et arrêtez-vous si le budget disponible est insuffisant ou ne peut être vérifié.
Demandez à l'utilisateur de confirmer que le kit de développement est connecté au pont de capteurs holoscan et que tout est alimenté et qu'il y a une connexion réseau active vers l'extérieur et que le kit de développement a été installé avec la version appropriée du système d'exploitation. Si tous les paramètres de profil sont connus, consultez le guide utilisateur du dépôt et dessinez un diagramme du kit de développement à capteur pour que l'utilisateur confirme que c'est la configuration qu'il a.
Une fois que l'utilisateur confirme que la configuration est prête, établissez la connexion SSH au kit de développement si l'utilisateur exécute la compétence claude à partir d'un ordinateur externe. Vous pouvez ignorer cette étape si claude est installé directement sur le kit de développement.
Vérifiez la plateforme du kit de développement hôte en exécutant cat /sys/class/dmi/id/product_name sur le kit de développement et en comparant le résultat à la variable d'environnement HSB_PLATFORM à l'aide du mappage product-name-to-platform (voir la section « Host platform auto-detection »). Si la commande retourne un nom de plateforme reconnu non vide qui diffère de HSB_PLATFORM, ou si HSB_PLATFORM est vide, mettez à jour HSB_PLATFORM pour correspondre à la plateforme détectée et alertez l'utilisateur du changement. Si la commande retourne vide ou échoue et que HSB_PLATFORM est déjà défini, conservez la valeur existante.
Clonez ou actualisez le dépôt GitHub à partir de la dernière branche main. Par défaut, il s'agit du dépôt public nvidia-holoscan/holoscan-sensor-bridge, mais l'utilisateur peut le remplacer par une URL de dépôt personnalisée via la variable d'environnement HSB_REPO ou l'option de ligne de commande --repo <URL>. Si le dépôt est un dépôt SSH, alertez l'utilisateur si aucune clé SSH n'est définie et fournissez des instructions sur la façon de configurer la clé SSH.
Demandez à l'utilisateur quel kit de développement/plateforme il souhaite utiliser si ce n'est pas déjà clair.
Sous le répertoire racine du dépôt cloné, étudiez et comprenez le guide utilisateur à docs/user_guide pour apprendre comment configurer l'environnement hôte pour chaque kit de développement et système d'exploitation, conteneur de démonstration, exécution d'applications à l'intérieur et à l'extérieur du conteneur (le cas échéant) et flashage de la FPGA.
Mappez cette plateforme à la configuration hôte correcte et le mode de build de conteneur et assurez-vous que la configuration hôte est configurée correctement selon les instructions du guide utilisateur, corrigez et ajoutez toute configuration manquante ou invitez l'utilisateur avec les instructions sur comment corriger.
Construisez le conteneur de démonstration.
Exécutez le conteneur de démonstration.
Vérifiez la connectivité à la carte à 192.168.0.2. Si la connexion à la carte échoue, invitez l'utilisateur à considérer une adresse IP différente.
Vérifiez la version FPGA en lisant le registre 0x80. Si la version FPGA sur le capteur ne correspond pas au logiciel host hsb qui se trouve sur le kit de développement, suggérez à l'utilisateur d'utiliser hsb-flash-skill pour flasher la carte avec la version FPGA appropriée.
Signalez la progression par phases, expliquez clairement les défaillances et tentez des corrections sûres avant d'abandonner.
Pour chaque problème rencontré, créez un rapport qui spécifie quel était le problème et comment vous l'avez résolu.
Offrez à l'utilisateur la possibilité d'exporter le rapport final vers un fichier md.
Une fois la configuration terminée, arrêtez toute application en cours d'exécution, quittez le conteneur en cédant le contrôle du kit de développement à l'utilisateur dans le répertoire d'accueil du dépôt dans la fenêtre de terminal.

Plateformes prises en charge et mappage de build

Utilisez le mappage suivant sauf si le dépôt ou la documentation actuelle dans l'arborescence de travail disent clairement le contraire :

IGX Orin avec dGPU OS/configuration → build avec sh docker/build.sh --dgpu
IGX Orin iGPU → build avec sh docker/build.sh --igpu
AGX Orin → build avec sh docker/build.sh --igpu
AGX Thor → build avec sh docker/build.sh --igpu
DGX Spark → build avec sh docker/build.sh --igpu

Si l'utilisateur dit seulement « IGX Orin », demandez explicitement s'il s'agit d'une iGPU ou d'une dGPU OS/configuration.

Auto-détection de la plateforme hôte

Au cours de la Phase 1 (après la connexion SSH ou lors de l'exécution locale), vérifiez le matériel réel du kit de développement en lisant le nom du produit DMI et en le comparant à la variable d'environnement HSB_PLATFORM.

Mappage product-name-to-platform

Le tableau suivant mappe les valeurs connues de /sys/class/dmi/id/product_name aux valeurs HSB_PLATFORM supportées. Faites correspondre en utilisant une recherche de sous-chaîne insensible à la casse — le nom du produit peut contenir du texte supplémentaire (p. ex., « Developer Kit », numéros de révision).

`product_name` contient (insensible à la casse)	`HSB_PLATFORM` mappé	Notes
`IGX Orin`	`IGX Orin`	Vous devez toujours demander iGPU vs dGPU si ce n'est pas déjà connu
`AGX Orin`	`AGX Orin`
`AGX Thor`	`AGX Thor`
`DGX Spark`	`DGX Spark`

Si le nom du produit ne correspond à aucun motif connu, traitez-le comme non reconnu et passez à la question manuelle de plateforme à l'étape 5.

Logique de détection et de réconciliation

Exécutez ce qui suit sur le kit de développement (à l'intérieur du heredoc SSH de Phase 1 ou localement) :

DETECTED_PRODUCT=""
if [ -f /sys/class/dmi/id/product_name ]; then
  DETECTED_PRODUCT=$(cat /sys/class/dmi/id/product_name 2>/dev/null | tr -d '\n')
fi

DETECTED_PLATFORM=""
if echo "$DETECTED_PRODUCT" | grep -qi "IGX Orin"; then
  DETECTED_PLATFORM="IGX Orin"
elif echo "$DETECTED_PRODUCT" | grep -qi "AGX Orin"; then
  DETECTED_PLATFORM="AGX Orin"
elif echo "$DETECTED_PRODUCT" | grep -qi "AGX Thor"; then
  DETECTED_PLATFORM="AGX Thor"
elif echo "$DETECTED_PRODUCT" | grep -qi "DGX Spark"; then
  DETECTED_PLATFORM="DGX Spark"
fi

echo "DETECTED_PRODUCT=$DETECTED_PRODUCT"
echo "DETECTED_PLATFORM=$DETECTED_PLATFORM"
echo "HSB_PLATFORM=${HSB_PLATFORM:-}"

Après la collecte de la sortie, appliquez les règles de réconciliation suivantes :

DETECTED_PLATFORM est non vide et HSB_PLATFORM est vide → définissez HSB_PLATFORM sur DETECTED_PLATFORM. Alertez l'utilisateur :

Plateforme auto-détectée à partir du matériel : <DETECTED_PLATFORM> (product_name: <DETECTED_PRODUCT>).
HSB_PLATFORM n'était pas défini — mise à jour en « <DETECTED_PLATFORM> ».

DETECTED_PLATFORM est non vide et diffère de HSB_PLATFORM → remplacez HSB_PLATFORM par DETECTED_PLATFORM. Alertez l'utilisateur :

ATTENTION : Le matériel signale « <DETECTED_PLATFORM> » (product_name: <DETECTED_PRODUCT>),
mais HSB_PLATFORM était défini à « <HSB_PLATFORM> ».
Mise à jour de HSB_PLATFORM pour correspondre au matériel détecté : « <DETECTED_PLATFORM> ».

DETECTED_PLATFORM est non vide et correspond à HSB_PLATFORM → aucun changement nécessaire. Confirmez :
```
Plateforme vérifiée : <HSB_PLATFORM> correspond au matériel (product_name: <DETECTED_PRODUCT>).
```

DETECTED_PLATFORM est vide (fichier manquant, illisible ou nom de produit non reconnu) et HSB_PLATFORM est défini → conservez le HSB_PLATFORM existant. Avertissement :

Impossible d'auto-détecter la plateforme à partir du matériel (product_name: « <DETECTED_PRODUCT> »).
Maintien du HSB_PLATFORM existant : « <HSB_PLATFORM> ».

DETECTED_PLATFORM et HSB_PLATFORM sont tous les deux vides → passez à la question manuelle de plateforme à l'étape 5.

Après la réconciliation, conservez le HSB_PLATFORM mis à jour dans le fichier d'état de session distante pour que les phases ultérieures utilisent la valeur correcte.

Variables wrapper conviviales pour Linux/Windows

Quand cette compétence est utilisée à partir de Linux/Windows avec une session Claude Code locale qui effectue des appels SSH, préférez ces variables d'environnement quand elles sont présentes :

SSH_TARGET pour la cible de connexion distante comme nvidia@agx-thor-host
REMOTE_ROOT pour le répertoire de travail distant où le dépôt doit se trouver
REMOTE_SUDO pour les commandes privilégiées. Acceptez sudo, sudo -n ou une chaîne vide
REMOTE_SSH_OPTS pour les options SSH supplémentaires
HSB_PLATFORM comme indice de plateforme optionnel
HSB_REPO pour une URL de dépôt GitHub personnalisée à cloner (p. ex. https://github.com/myorg/my-hsb-fork.git). S'il n'est pas défini, par défaut https://github.com/nvidia-holoscan/holoscan-sensor-bridge.git

Si celles-ci sont définies, informez l'utilisateur de ces paramètres et utilisez-les sans les demander à nouveau sauf si l'utilisateur les remplace explicitement.

Avant la Phase 1, affichez les paramètres d'exécution distants résolus que vous utiliserez, avec les secrets masqués si nécessaire.

Motif d'interaction obligatoire

Présentez le plan des phases de la Barrière 2 ci-dessus avant d'effectuer des modifications. Ignorez la Phase 3 pour les plateformes non-Thor.

Puis exécutez une phase à la fois.

Après chaque phase non-finale (Phases 0–5) :

Montrez un résumé de phase. Le niveau de détail dépend du mode --verbose (voir la section « Verbosity mode ») :
- Verbose : sortie complète + bloc d'état détaillé (nom de la phase, ce qui a été exécuté, résultat, action suivante).
- Concis (par défaut) : résumé par points avec problèmes mis en évidence.
Invitez l'utilisateur avec Procéder à la Phase <N+1> ? [Y/n] en spécifiant ce qu'est la phase N+1 et attendez la confirmation avant de continuer (voir la section « Phase gate »).

Si quelque chose échoue, ne faites pas simplement un vidage de journaux bruts. Résumez :

la commande exacte qui a échoué
la cause probable
quelle réparation sûre vous allez essayer ensuite
si la réparation a réussi

Contrôle préalable du budget de tokens

Phase 0 - Contrôle préalable du budget de tokens

Cette phase est obligatoire et doit s'exécuter avant toute connexion SSH, clone du dépôt, vérification de package/configuration, build de conteneur, redémarrage ou modification de paramètre du kit de développement.

Estimez le budget de tokens de l'exécution complète pour l'ensemble du workflow de configuration, pas seulement la phase suivante. Les valeurs ci-dessous sont des heuristiques conservatrices, non des usages historiques mesurés. Traitez-les comme des budgets de sécurité initiaux et affinez-les à partir des journaux d'exécution réels /hsb-setup une fois que l'utilisation des tokens mesurée est disponible :
- Réservez au moins 280 000 tokens pour une exécution complète de la configuration sur IGX Orin, AGX Orin ou DGX Spark.
- Réservez au moins 340 000 tokens pour AGX Thor car les vérifications de build natif et SIPL/FuSa ajoutent plus de phases et de dépannage.
- Ajoutez 60 000 tokens quand --verbose, la gestion de dépôt personnalisé, la correction de clé SSH, la récupération après redémarrage ou un dépannage supplémentaire sont attendus.
- Utilisez l'estimation plus grande si la plateforme n'est pas encore connue.
Vérifiez l'utilisation restante à l'aide de la meilleure source de Claude Code/utilisation de compte disponible pour le plan d'abonnement actuel. Préférez les données d'utilisation lisibles par machine ou fournies par le produit quand disponibles. Si aucune source d'utilisation fiable n'est disponible, demandez à l'utilisateur de fournir son utilisation/quota restant actuel à partir de l'interface utilisateur de compte ou de plan Claude Code.

Quand vous demandez à l'utilisateur parce que l'utilisation ne peut être auto-vérifiée, présentez les options dans cet ordre exact afin que les choix d'arrêt sûr apparaissent en premier :
1. Je ne peux pas vérifier — arrêter : L'utilisateur ne peut pas déterminer l'utilisation restante. Arrêtez avant la Phase 1.
2. J'ai < {estimate} disponible — arrêter : L'utilisateur a vérifié son interface utilisateur de plan/compte et confirme que moins du budget estimé reste. Arrêtez avant la Phase 1.
3. J'ai ≥ {estimate} disponible — continuer : L'utilisateur a vérifié son interface utilisateur de plan/compte et confirme qu'au moins le budget estimé reste. Continuez à la Phase 1.
4. Tapez quelque chose : Traitez comme une question ou une instruction de forme libre, répondez-y, puis relancez les options classées de la même manière.
Ne mettez pas l'option de procéder en premier. L'utilisateur doit intentionnellement dépasser les choix d'arrêt avant de sélectionner continuer.

Affichez le résultat à l'utilisateur avant de continuer :

Contrôle préalable du budget de tokens
- Tokens estimés requis pour l'exécution complète de /hsb-setup : <estimate>
- Base d'estimation : heuristique conservatrice ; affiner à partir des journaux d'exécution réels quand disponible
- Marge de sécurité incluse : <margin>
- Utilisation du plan restante disponible : <available or "unverified">
- Résultat : PASS / FAIL

Arrêtez en cas de budget insuffisant ou non vérifiable :
- Si l'utilisation restante est inférieure à l'estimation, arrêtez avant la Phase 1 et expliquez que la compétence refuse de démarrer car elle pourrait manquer de tokens tout en modifiant les paramètres du kit de développement.
- Si l'utilisation restante ne peut être vérifiée, arrêtez avant la Phase 1 et demandez à l'utilisateur de démarrer une session nouvelle, de mettre à niveau/actualiser l'utilisation ou de fournir une utilisation restante vérifiable.
- --y ne doit pas contourner ce contrôle préalable.

Questions de plateforme à poser quand manquantes

Ne posez que les questions strictement nécessaires :

Quelle plateforme utilisez-vous ?
- IGX Orin iGPU
- IGX Orin dGPU
- AGX Orin
- AGX Thor
- DGX Spark
La carte HSB est-elle déjà physiquement connectée et allumée ?
Êtes-vous d'accord avec les commandes qui nécessitent sudo pour la configuration du réseau et de Docker ?

Si l'utilisateur a déjà fourni l'une de ces informations, ne la demandez pas à nouveau.

Scripts disponibles

Script	Objectif	Arguments
`scripts/hsb_phase_runner.sh`	Exécution shell structurée avec journaux horodatés par phase	`<phase_name> <command>`

Utilisez run_script(scripts/hsb_phase_runner.sh, <phase_name>, <command>) pour exécuter les étapes de phase avec journalisation automatique.

Détails des phases

Voir references/phase-details.md pour les instructions complètes étape par étape des phases, le style de sortie, le comportement de verbosité, le mode d'approbation automatique, les règles de phase gate et le modèle de session SSH persistant.

Carnet de récupération

Essayez ces correctifs dans l'ordre quand applicable :

Réexécutez la commande défaillante une fois si l'défaillance semble transitoire.
Corrigez les prérequis manquants (git-lfs, accès Docker, xhost, route réseau).
Actualisez l'état du dépôt et le contenu LFS.
Réexécutez uniquement la phase défaillante, pas l'ensemble du workflow.
Si toujours bloqué, arrêtez avec un diagnostic concis et une liste de commandes copier-coller pour l'utilisateur.

Fichiers de support dans cette compétence

Voir docs/platform-mapping.md pour le résumé de build et de configuration hôte autorité utilisé par cette compétence.
Voir docs/failure-playbook.md pour la logique de correction courante.
Utilisez scripts/hsb_phase_runner.sh comme assistant quand vous voulez une exécution shell structurée et des journaux horodatés.

Aide intégrée (`--help`)

Si $ARGUMENTS contient --help ou -h, n'exécutez pas le workflow. À la place, affichez textuellement le texte d'aide suivant et arrêtez-vous :

Holoscan Sensor Bridge — Compétence de mise en service de démonstration

UTILISATION
  /hsb-setup [PLATEFORME] [OPTIONS]

PLATEFORME (optionnel — demandera si omis)
  AGX Orin          NVIDIA Jetson AGX Orin (iGPU, build avec --igpu)
  AGX Thor          NVIDIA Jetson AGX Thor (iGPU, build avec --igpu)
  IGX Orin iGPU     NVIDIA IGX Orin en configuration iGPU (build avec --igpu)
  IGX Orin dGPU     NVIDIA IGX Orin avec GPU discret (build avec --dgpu)
  DGX Spark         NVIDIA DGX Spark (iGPU, build avec --igpu)

OPTIONS
  --help, -h        Afficher ce message d'aide et quitter
  --verbose         Afficher la sortie de commande brute complète pour chaque phase
                    (par défaut, résumés concis par points)
  --y               Approuver automatiquement tous les portails de phase (ignorer la confirmation de l'utilisateur
                    entre les phases). Non recommandé — un avertissement de confirmation
                    est affiché avant de procéder. Toute la sortie est
                    enregistrée dans un fichier journal horodaté.
  --repo <URL>      Cloner un dépôt GitHub personnalisé au lieu du dépôt par défaut
                    nvidia-holoscan/holoscan-sensor-bridge.
                    Peut également être défini via la variable d'environnement HSB_REPO.
                    Priorité : drapeau --repo > variable d'environnement HSB_REPO > dépôt par défaut

VARIABLES D'ENVIRONNEMENT (à définir avant d'invoquer la compétence)
  SSH_TARGET        Cible de connexion distante (p. ex. ubuntu@10.0.0.1)
  REMOTE_ROOT       Répertoire de travail distant pour clone du dépôt et builds
  REMOTE_SUDO       Escalade de privilèges : 'sudo', 'sudo -n' ou ''
  REMOTE_SSH_OPTS   Options SSH supplémentaires (p. ex. -o ServerAliveInterval=30)
  HSB_PLATFORM      Indice de plateforme (mêmes valeurs que PLATEFORME ci-dessus)
  HSB_REPO          URL de dépôt GitHub personnalisée (remplacée par le drapeau --repo)

PHASES DU WORKFLOW
  Phase 0   Contrôle préalable du budget de tokens ; vérifier qu'il y a assez d'utilisation de plan pour une exécution complète
  Phase 1   Confirmer la plateforme, cloner le dépôt et étudier le guide utilisateur
  Phase 2   Vérifications des prérequis de l'hôte et configuration réseau
  Phase 3   Build natif des outils CLI (AGX Thor uniquement, ignoré autrement)
  Phase 4   Build, exécuter le conteneur de démonstration et vérifier la connectivité
  Phase 5   Produire le rapport de problèmes, optionnellement exporter vers un fichier
  Phase 6   Arrêter les applications, quitter le conteneur, remettre le contrôle

  La compétence demande une confirmation entre chaque phase.

EXEMPLES
  /hsb-setup AGX Thor
  /hsb-setup AGX Thor --verbose
  /hsb-setup AGX Thor --y
  /hsb-setup IGX Orin dGPU --repo https://github.com/myorg/my-fork.git
  /hsb-setup --help

Après l'affichage du texte d'aide, ne procédez pas avec des phases ou des questions.

Voir la section EXEMPLES dans Aide intégrée (--help) pour des exemples d'invocation.

Quand $ARGUMENTS contient une plateforme, utilisez-la au lieu de demander à nouveau. Supprimez --verbose, --y, --repo <URL> et --help des arguments avant d'analyser le nom de la plateforme.