HSB FPGA Flash

Utilisez cette skill quand l'utilisateur souhaite flasher (mettre à niveau ou rétrograder) le firmware FPGA sur une carte HSB connectée à un devkit NVIDIA supporté.

Cette skill supporte deux types de cartes :

1. Cartes HSB Lattice — carte FPGA autonome avec un FPGA Lattice CPNX100
2. Leopard Imaging VB1940 — caméra « tout-en-un » avec un FPGA Lattice intégré

RÈGLE DE SÉCURITÉ CRITIQUE : Ne mélangez jamais les commandes de type de carte. Utiliser program_leopard_cpnx100 sur une carte Lattice ou program_lattice_cpnx100 sur une VB1940 peut rendre l'appareil inutilisable de façon permanente. La skill doit détecter et confirmer le type de carte avant toute opération de flash, et refuser de procéder si le type de carte est ambigu ou incompatible.

Ce workflow a des effets secondaires (il modifie de façon permanente le firmware FPGA). Ne l'exécutez jamais automatiquement. Exécutez-le uniquement quand l'utilisateur l'invoque explicitement.

Avertissement d'utilisation : Cette skill flashe le FPGA avec un nouveau firmware. Avant de l'invoquer, demandez à l'utilisateur de s'assurer qu'il dispose de suffisamment d'utilisation Claude Code / de tokens pour compléter le workflow.

Avant de commencer — portes requises (faites-les d'abord, dans l'ordre)

Porte 1 — Lire les variables d'environnement. Avant de faire quoi que ce soit, vérifiez ces variables et affichez leurs valeurs résolues à l'utilisateur :

SSH_TARGET      Connexion au devkit 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 (optionnel).

SSH_TARGET et REMOTE_ROOT sont obligatoires. Arrêtez et demandez-les à l'utilisateur s'ils manquent.

Porte 2 — Présenter le résumé du flash et le plan des phases. Avant de prendre toute mesure :

Si la demande de l'utilisateur inclut déjà le type de carte, la version FPGA actuelle et la version FPGA cible, énoncez ce qui suit avant le plan des phases : outil de flash (program_lattice_cpnx100 pour Lattice, program_leopard_cpnx100 pour VB1940 — ne jamais mélanger), version et nom de fichier du manifest, drapeaux CLI (--force --accept-eula), si la procédure est à une seule étape ou à deux étapes via la porte 2412. Pour VB1940, indiquez aussi qu'aucun repo intermédiaire v2.0.0 n'est nécessaire. Pour les mises à niveau en deux étapes à partir de FPGA 2407, indiquez que l'étape 1 utilise hololink --force fpga_version (pas hololink enumerate, qui est incompatible avec FPGA 2407) et utilise le placement du drapeau v2.0.0 : hololink --force program scripts/manifest.yaml --accept-eula (--force avant la sous-commande).

Affichez ensuite le plan des phases et demandez explicitement : Dois-je procéder avec le workflow de flash ? [O/n] — ne commencez pas la porte 3 jusqu'à la confirmation de l'utilisateur :

HSB Flash — Plan des phases
  Phase 0 : Préflight budget de tokens
  Phase 1 : Vérifier la connectivité de la carte, détecter le type de carte (Lattice ou VB1940), lire la version FPGA
  Phase 2 : Sélectionner la version FPGA cible
  Phase 3 : Préparer l'infrastructure de flash et les fichiers YAML, présenter le plan de flash pour approbation
  Phase 4 : Exécuter la procédure de flash (avec vérification de redémarrage)
  Phase 5 : Rapport de synthèse (avec option pour enregistrer)
  Phase 6 : Nettoyer les artefacts de flash

Porte 3 — Préflight budget de tokens (Phase 0). Exécutez après que le plan des phases (Porte 2) a été présenté et que l'utilisateur a confirmé. N'exécutez pas la vérification du budget de tokens avant l'affichage du plan des phases. Ne procédez pas à la Phase 1 jusqu'à ce que la vérification du budget réussisse.

Porte 4 — Confirmer explicitement le type de carte. Avant toute commande de flash, confirmez avec l'utilisateur si la carte est Lattice ou VB1940. Ne mélangez jamais program_lattice_cpnx100 et program_leopard_cpnx100 — le mauvais outil peut rendre l'appareil inutilisable.

Instructions

Invoquez cette skill en tapant /hsb-flash [OPTIONS]. La skill détecte automatiquement le type de carte, présente un plan de flash et demande une confirmation avant chaque étape de flash. Consultez references/help-text.md pour la sortie --help complète.

Ce que cette skill doit faire

0. Exécutez le préflight obligatoire du budget de tokens avant toute commande distante, checkout de repo, construction de conteneur ou préparation de flash. Estimez les tokens nécessaires pour compléter toutes les phases, vérifiez l'utilisation restante du plan d'abonnement de l'utilisateur avec le meilleur mécanisme disponible d'utilisation Claude Code / compte, affichez l'estimation et le résultat à l'utilisateur, et arrêtez si le budget disponible est insuffisant ou ne peut pas être vérifié.
1. Vérifiez qu'une carte HSB est connectée à un devkit, que SSH et la connectivité de la carte fonctionnent, lisez la version FPGA actuelle, et identifiez le type de carte (Lattice ou VB1940). Essayez d'abord hololink enumerate ; s'il échoue (ce qui est attendu pour les cartes FPGA 2407), basculez vers hololink --force fpga_version. Pour les cartes Lattice, si toutes les méthodes échouent avec le conteneur du repo existant, checkout la v2.0.0 du repo de version HSB et réessayez en utilisant le conteneur v2.0.0. Si cela échoue aussi, supposez que la version est 2407 et continuez. Pour les cartes VB1940, demandez à l'utilisateur si la version ne peut pas être lue.
2. Demandez à l'utilisateur la version FPGA cible qu'il souhaite flasher (ou acceptez « latest »). Les versions disponibles dépendent du type de carte.
3. Gérer les versions FPGA non documentées (s'applique aux deux types de carte Lattice et VB1940) : Si la version FPGA actuelle ou cible n'est pas listée dans les versions supportées ou les tables de correspondance de cette skill, elle peut appartenir à une version HSB plus récente non encore documentée ici, ou il peut s'agir d'une construction de développement non publiée. Procédez comme suit :
   • Vérifier une version plus récente : Récupérez les notes de version publiques à https://github.com/nvidia-holoscan/holoscan-sensor-bridge/blob/main/RELEASE_NOTES.md et recherchez une version qui introduit la version FPGA non documentée. Si une version correspondante est trouvée, checkout ce repo de version sur le devkit et utilisez-le pour flasher en suivant les mêmes règles décrites ci-dessous pour le type de carte détecté. Mettez aussi à jour les tables de correspondance, les listes de versions FPGA supportées et la matrice de transition de cette skill avec la nouvelle version et sa version FPGA correspondante.
   • FPGA en développement ou non publié : Si aucune version publiée ne correspond à la version FPGA, utilisez le repo HSB existant déjà sur le devkit (depuis /hsb-setup) pour flasher, en suivant les mêmes règles pour le type de carte détecté. Si le flash échoue, signalez l'erreur et demandez à l'utilisateur des instructions supplémentaires.
4. Déterminez la procédure de flash correcte et préparez les scripts de flash et les fichiers YAML :
   • Cartes Lattice :
     1. Lisez la version FPGA actuellement flashée sur la carte HSB. Déterminez le repo HSB requis en fonction de la direction du flash : pour les mises à niveau, utilisez le repo correspondant à la version FPGA cible ; pour les rétrograations, utilisez le repo correspondant à la version FPGA actuelle (voir « Correspondance version FPGA vers repo » ci-dessous). Checkout ce repo s'il n'existe pas déjà sur le devkit.
     2. Copiez le manifest YAML FPGA cible du répertoire scripts/ pertinent de cette skill vers le repo checkouté, et corrigez le fichier selon les besoins pour les détails manquants (p. ex., fpga_uuid).
     3. Déterminez la procédure de flash :
        • Mise à niveau à une seule étape : Si la version actuelle est 2412 ou plus récente et la cible aussi est 2412 ou plus récente, ou si vous mettez à niveau à partir de n'importe quelle version exactement à 2412. Flashez directement de la version actuelle à la cible en utilisant le repo qui correspond à la version FPGA cible (voir « Correspondance version FPGA vers repo »).
        • Rétrogradation à une seule étape : Si la version actuelle et la cible sont toutes deux 2412 ou plus récentes. Flashez directement de la version actuelle à la cible en utilisant le repo correspondant à la version FPGA actuelle.
        • Rétrogradation en deux étapes : Si la cible est plus ancienne que 2412 (c.-à-d. 2407) et la version actuelle est plus récente que 2412. Étape 1 : flashez de la version actuelle à 2412 en utilisant le repo correspondant à la version FPGA actuelle. Étape 2 : flashez de 2412 à la cible en utilisant la v2.0.0 du repo HSB. Redémarrage requis entre les étapes. (Cas particulier : si la version actuelle est exactement 2412, seule l'étape 2 est nécessaire.)
        • Mise à niveau en deux étapes : Si la version actuelle est plus ancienne que 2412 (c.-à-d. 2407) et la cible est plus récente que 2412. Étape 1 : flashez de la version actuelle à 2412 en utilisant v2.0.0 (qui correspond à la version FPGA cible 2412). Étape 2 : flashez de 2412 à la cible en utilisant le repo correspondant à la version FPGA cible. Redémarrage requis entre les étapes.
     4. Lisez le guide utilisateur du repo HSB utilisé pour le flash et extrayez la commande de flash. Ajoutez toujours --force et --accept-eula pour assurer une exécution non-interactive à l'intérieur du conteneur. Remarque : v2.0.0 place --force avant la sous-commande et --accept-eula après — voir « Placement des drapeaux CLI v2.0.0 » ci-dessous.
     5. Une fois le flash complété, nettoyez tous les repos de version HSB intermédiaires qui ont été checkoutés par cette skill et qui diffèrent du repo original de l'utilisateur qui existait sur le devkit avant l'invocation de la skill.
   • Caméras VB1940 : Utilisez directement le repo HSB existant sur le devkit (aucun repo intermédiaire v2.0.0 nécessaire). Le flash est toujours à une seule étape. Présentez le plan complet de flash à l'utilisateur pour approbation.
5. Exécutez la procédure de flash :
   • Effectuez les vérifications de sécurité pré-flash requises (ping de la carte, confirmez le type de carte et la version FPGA actuelle).
   • Exécutez chaque étape de flash avec journalisation complète ; annoncez l'opération avant le flash.
   • Exigez une confirmation explicite de l'utilisateur avant chaque flash critique et après tout redémarrage de carte / caméra requis.
   • Toutes les commandes program doivent être exécutées à l'intérieur du conteneur de démonstration (aucun sudo nécessaire dans le conteneur).
   • Après le flash, vérifiez que la nouvelle version FPGA correspond à la cible prévue avant de continuer.
   • Gérez toute erreur ou inadéquation en arrêtant le workflow, en signalant l'état et en proposant de nettoyer.
6. Produisez un rapport de synthèse de l'ensemble de la procédure avec la possibilité de l'enregistrer.
7. Nettoyez tous les artefacts de flash pour que le devkit soit prêt pour l'utilisateur à checkout toute version HSB dont il a besoin.

Types de cartes supportés

Le type de carte est détecté à partir de la sortie hololink enumerate pendant la Phase 1 et confirmé avec l'utilisateur. Si la détection est ambiguë, l'utilisateur doit explicitement spécifier le type de carte.

Versions FPGA supportées

Versions FPGA de la carte Lattice

Versions FPGA VB1940

La VB1940 ne supporte pas les versions 2407 ou 2412 — ce sont des versions réservées à Lattice.

Versions non listées ci-dessus : Les versions FPGA plus récentes que la version documentée la plus récente pour l'un ou l'autre type de carte peuvent encore être flashables — voir « Gestion des versions FPGA non documentées » ci-dessus. Pour les cartes Lattice, les versions plus anciennes que 2407 ou entre les versions connues (p. ex., 2409) ne sont pas supportées. Pour VB1940, les versions plus anciennes que 2507 ne sont pas supportées. Dans l'un ou l'autre cas, refusez et affichez les versions supportées pour le type de carte.

Infrastructure de flash

Consultez references/flashing-infrastructure.md pour les tags des versions GitHub, la disposition du manifest YAML fourni, les commandes de flash spécifiques à la carte, les différences de drapeaux CLI v2.0.0 et la solution de contournement enumerate FPGA 2407.

Sélection et checkout du repo (Lattice uniquement)

Le tableau « Versions FPGA de la carte Lattice » ci-dessus détermine quel repo de version HSB utiliser. La clé de recherche dépend de la direction :

• Mises à niveau : Recherchez la cible Release source du YAML de la version FPGA.
• Rétrograations : Recherchez la Release source du YAML de la version FPGA actuelle.

Auto-mise à jour : Si une version FPGA non documentée est rencontrée, la skill vérifie les notes de version publiques pour une version HSB correspondante (voir « Gestion des versions FPGA non documentées »). Si trouvée, la skill met à jour les tableaux de « Versions FPGA supportées », la matrice de transition, et note les fichiers manifest de la nouvelle version.

Logique de checkout du repo

1. Vérifier un repo existant : Si l'utilisateur a déjà un repo HSB sur le devkit (depuis /hsb-setup), lisez sa version à partir du fichier VERSION.
2. Déterminer le repo requis : Pour les mises à niveau, recherchez la version FPGA cible dans la table de correspondance. Pour les rétrograations, recherchez la version FPGA actuelle.
3. Checkout si nécessaire : Si le repo existant ne correspond pas à la version requise, clonez et checkout la version requise du repo dans un répertoire séparé. Le repo existant est laissé inchangé.
4. Cas à deux étapes : Si un flash à deux étapes est requis, les deux repos d'étape doivent être disponibles. Pour une rétrogradation à deux étapes (current > 2412, target = 2407), l'étape 1 utilise le repo FPGA actuel et l'étape 2 utilise v2.0.0. Pour une mise à niveau à deux étapes (current = 2407, target > 2412), l'étape 1 utilise v2.0.0 (repo cible 2412) et l'étape 2 utilise le repo correspondant à la version FPGA cible finale. Si un repo requis n'est pas déjà présent, il est checkouté.

Remarque VB1940 : Le flash VB1940 utilise toujours le repo existant sur le devkit — la correspondance FPGA-vers-repo ne s'applique pas. Le repo existant doit être en version v2.3.0 ou ultérieure. Si aucun repo existant n'est trouvé, demandez à l'utilisateur d'exécuter /hsb-setup d'abord.

Ce qu'il faut enregistrer depuis la détection

Pendant la Phase 1, lors de la recherche d'un repo existant et de la détection du type de carte, enregistrez ces variables dans l'état de session :

• BOARD_TYPE — le type de carte détecté : lattice ou vb1940
• EXISTING_REPO_DIR — chemin absolu du repo HSB existant (vide si aucun n'est trouvé)
• EXISTING_REPO_VERSION — la version du repo (p. ex., 2.3.1), lue à partir du fichier VERSION
• FLASH_REPO_DIR — chemin absolu du repo qui sera utilisé pour le flash (peut différer de EXISTING_REPO_DIR si une version différente a été checkoutée)
• FLASH_REPO_VERSION — la version du repo de flash (recherchée dans la correspondance FPGA-vers-repo)
• INTERIM_REPOS — liste des répertoires de repo checkoutés par cette skill (pour le nettoyage en Phase 6)

Variables wrapper compatibles Linux/Windows

Réutilisez les mêmes variables d'environnement de la skill hsb-setup :

• SSH_TARGET pour la cible de connexion distante (p. ex. nvidia@agx-thor-host)
• REMOTE_ROOT pour le répertoire de travail distant où l'espace de travail de flash sera créé
• REMOTE_SUDO pour les commandes privilégiées
• REMOTE_SSH_OPTS pour les options SSH supplémentaires
• HSB_PLATFORM comme indice de plateforme optionnel

Si ces variables sont définies, notifiez l'utilisateur de ces paramètres et utilisez-les sans redemander.

Avant la Phase 1, affichez les paramètres d'exécution distante résolus.

Modèle d'interaction obligatoire

Avant d'effectuer des modifications, affichez ce plan des phases :

• Phase 0 : Préflight budget de tokens ; vérifiez que l'utilisation restante du plan de l'utilisateur peut couvrir un workflow de flash complet
• Phase 1 : Vérifier la connectivité de la carte, détecter le type de carte (Lattice ou VB1940), et lire la version FPGA actuelle
• Phase 2 : Sélectionner la version FPGA cible (les versions disponibles dépendent du type de carte)
• Phase 3 : Préparer l'infrastructure de flash et les fichiers YAML, présenter le plan de flash pour approbation
  • Lattice : Checkout le repo requis (repo FPGA cible pour les mises à niveau, repo FPGA actuel pour les rétrograations — s'il n'est pas déjà présent), copier et patcher le manifest YAML
  • VB1940 : Utiliser le repo existant directement
• Phase 4 : Exécuter la procédure de flash (avec vérification de redémarrage)
• Phase 5 : Générer un rapport de synthèse (avec option pour enregistrer)
• Phase 6 : Nettoyer les artefacts de flash

Puis exécutez une phase à la fois.

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

1. Affichez un résumé de phase avec les résultats clés.
2. Demandez à l'utilisateur avec Procéder à la Phase <N+1> ? [O/n] et spécifiez ce que la phase suivante fait. Attendez la confirmation avant de continuer.

Exception : Quand le mode --y (approbation automatique) est actif, les portes de phase sont ignorées et les phases s'exécutent automatiquement. Consultez la section « Mode approbation automatique (--y) » pour les détails.

Si quelque chose échoue, ne videz pas simplement les logs bruts. Résumez :

• la commande exacte qui a échoué
• la cause probable
• quelle action sûre vous recommandez
• si le problème bloque le processus

Détails des phases

Consultez references/phase-details.md pour les instructions détaillées étape par étape des phases, la logique de procédure de flash, les règles d'exécution, les contraintes de sécurité, les règles de porte de phase, le comportement de verbosité, le mode force et le mode approbation automatique.

Aide intégrée (--help)

Consultez references/help-text.md pour la sortie --help complète.

Exemples d'invocation

Consultez references/help-text.md pour la sortie --help complète, incluant tous les exemples d'invocation.