hsb-flash

HSB FPGA Flash

HSB ボードをサポート対象の NVIDIA 開発キットに接続し、FPGA ファームウェアをフラッシュ（アップグレードまたはダウングレード）する場合にこのスキルを使用します。

このスキルは次の 2 種類のボードに対応しています：

1. HSB Lattice ボード — Lattice CPNX100 FPGA を搭載したスタンドアロン FPGA ボード
2. Leopard Imaging VB1940 — Lattice FPGA を内蔵した「オールインワン」カメラ

重要な安全ルール：ボードの種類ごとのコマンドを絶対に混用しないでください。 Lattice ボードで program_leopard_cpnx100 を使用したり、VB1940 で program_lattice_cpnx100 を使用したりすると、デバイスが永久に起動不能になる可能性があります。このスキルは、フラッシュ操作の前にボードの種類を検出して確認する必要があり、種類が曖昧または不一致の場合は処理を中止してください。

このワークフローには副作用があり、FPGA ファームウェアが恒久的に変更されます。自動では実行しないでください。ユーザーが明示的に実行を指示した場合にのみ実行してください。

使用上の警告： このスキルは FPGA に新しいファームウェアをフラッシュします。実行する前に、ワークフローを完了するのに十分な Claude Code の使用量／トークンがあることをユーザーに確認してください。

開始前 — 必須の確認事項（最初に、順番どおりに実施）

Gate 1 — 環境変数を読み取る。 ほかのことを行う前に、次の変数を確認し、解決された値をユーザーに表示してください：

SSH_TARGET      Remote devkit login (e.g. [email protected]). Ask the user if not set.
REMOTE_ROOT     Remote working directory (e.g. /home/nvidia). Ask the user if not set.
REMOTE_SUDO     sudo / sudo -n / "" — default to "sudo" if not set.
REMOTE_SSH_OPTS Additional SSH options (optional).
HSB_PLATFORM    Platform hint (optional).

SSH_TARGET と REMOTE_ROOT は必須です。どちらかが設定されていない場合は停止し、ユーザーに確認してください。

Gate 2 — フラッシュの概要とフェーズ計画を提示する。 何らかの操作を行う前に：

ユーザーの依頼にボードの種類、現在の FPGA バージョン、目標の FPGA バージョンがすでに含まれている場合は、フェーズ計画の前に次の内容を伝えてください：フラッシュツール（Lattice には program_lattice_cpnx100、VB1940 には program_leopard_cpnx100 — 絶対に混用しないでください）、マニフェストのリリースとファイル名、CLI フラグ（--force --accept-eula）、手順が単一ステップか、ゲートウェイ 2412 を経由する 2 ステップか。VB1940 の場合は、v2.0.0 の中間リポジトリが不要であることも伝えてください。FPGA 2407 からの 2 ステップアップグレードの場合は、ステップ 1 で hololink --force fpga_version を使用すること（FPGA 2407 と互換性のない hololink enumerate は使用しないこと）、および v2.0.0 のフラグの配置を使用することを伝えてください：hololink --force program scripts/manifest.yaml --accept-eula（サブコマンドの前に --force を指定）。

次にフェーズ計画を表示して、明示的に確認を求めてください：Shall I proceed with the flash workflow? [Y/n] — ユーザーが確認するまで Gate 3 を開始しないでください：

HSB Flash — Phase Plan
  Phase 0: Token-budget preflight
  Phase 1: Verify board connectivity, detect board type (Lattice or VB1940), read FPGA version
  Phase 2: Select target FPGA version
  Phase 3: Prepare flash infrastructure and YAML files, present flash plan for approval
  Phase 4: Execute flashing procedure (with power cycle verification)
  Phase 5: Summary report (with option to save)
  Phase 6: Clean up flash artifacts

Gate 3 — トークン予算の事前確認（Phase 0）。 フェーズ計画（Gate 2）を提示し、ユーザーが確認した後に実行してください。フェーズ計画を提示する前にトークン予算の確認を実行しないでください。予算の確認に合格するまで Phase 1 に進まないでください。

Gate 4 — ボードの種類を明示的に確認する。 フラッシュコマンドを実行する前に、ボードが Lattice か VB1940 かをユーザーに確認してください。program_lattice_cpnx100 と program_leopard_cpnx100 を絶対に混用しないでください。誤ったツールを使用すると、デバイスが起動不能になる可能性があります。

手順

/hsb-flash [OPTIONS] と入力して、このスキルを呼び出します。このスキルはボードの種類を自動検出し、フラッシュの計画を提示して、各フラッシュ手順の前に確認を求めます。--help の出力全体については、references/help-text.md を参照してください。

このスキルが実行する内容

0. リモートコマンドの実行、リポジトリのチェックアウト、コンテナーのビルド、フラッシュの準備を行う前に、必須のトークン予算の事前確認を実施してください。 すべてのフェーズを完了するために必要なトークン数を見積もり、利用可能な最善の Claude Code／アカウント使用量確認手段で、ユーザーのサブスクリプションプランの残り使用量を確認してください。見積もりと確認結果をユーザーに表示し、利用可能な予算が不足している場合、または確認できない場合は中止してください。
1. HSB ボードが開発キットに接続されていること、SSH とボードへの接続が機能することを確認し、現在の FPGA バージョンを読み取り、ボードの種類（Lattice または VB1940）を特定してください。まず hololink enumerate を試してください。失敗した場合（FPGA 2407 ボードでは想定される結果です）は、hololink --force fpga_version に切り替えてください。Lattice ボードで、既存リポジトリのコンテナーを使ったすべての方法が失敗した場合は、HSB リリースリポジトリ v2.0.0 をチェックアウトし、v2.0.0 コンテナーを使って再試行してください。それでも失敗した場合は、バージョンを 2407 とみなして続行してください。VB1940 ボードでバージョンを読み取れない場合は、ユーザーに確認してください。
2. フラッシュ先として希望する FPGA バージョン（または「latest」）をユーザーに尋ねてください。利用可能なバージョンはボードの種類によって異なります。
3. ドキュメントに記載されていない FPGA バージョンへの対応（Lattice と VB1940 の両方が対象）：現在または対象の FPGA バージョンが、このスキルの対応バージョンやマッピング表に記載されていない場合、まだここに記載されていない新しい HSB リリースに属しているか、未リリースの開発ビルドである可能性があります。以下の手順に従ってください。
   • 新しいリリースを確認する：公開されているリリースノート https://github.com/nvidia-holoscan/holoscan-sensor-bridge/blob/main/RELEASE_NOTES.md を取得し、記載されていない FPGA バージョンを導入したリリースがないか確認してください。一致するリリースが見つかった場合は、開発キットでそのリリースのリポジトリをチェックアウトし、検出したボードの種類について以下で説明する同じルールに従ってフラッシュしてください。また、このスキルのマッピング表、対応 FPGA バージョンの一覧、移行マトリクスを、新しいリリースとそれに対応する FPGA バージョンで更新してください。
   • 開発版または未リリースの FPGA：その FPGA バージョンに対応する公開済みリリースがない場合は、開発キット上の既存の HSB リポジトリ（/hsb-setup のもの）を使い、検出したボードの種類について同じルールに従ってフラッシュしてください。フラッシュに失敗した場合は、エラーを報告し、次の指示をユーザーに求めてください。
4. 正しいフラッシュ手順を判断し、フラッシュスクリプトと YAML ファイルを準備してください。
   • Lattice ボード：
     1. HSB ボードに現在フラッシュされている FPGA バージョンを読み取ってください。フラッシュの方向に応じて、必要な HSB リリースリポジトリを判断してください。アップグレードの場合は対象 FPGA バージョンに対応するリポジトリを、ダウングレードの場合は現在の FPGA バージョンに対応するリポジトリを使ってください（以下の「FPGA バージョンとリポジトリの対応表」を参照）。開発キットに存在しない場合は、このリポジトリをチェックアウトしてください。
     2. このスキルの該当する scripts/ ディレクトリから対象 FPGA のマニフェスト YAML を、チェックアウトしたリポジトリにコピーし、必要に応じて不足情報（例：fpga_uuid）を補ってください。
     3. フラッシュ手順を判断してください。
        • 1 段階のアップグレード：現在のバージョンと対象バージョンが両方とも 2412 以降の場合、または任意のバージョンから 2412 へアップグレードする場合です。対象 FPGA バージョンに対応するリポジトリを使い、現在のバージョンから対象バージョンへ直接フラッシュしてください（「FPGA バージョンとリポジトリの対応表」を参照）。
        • 1 段階のダウングレード：現在のバージョンと対象バージョンが両方とも 2412 以降の場合です。現在の FPGA バージョンに対応するリポジトリを使い、現在のバージョンから対象バージョンへ直接フラッシュしてください。
        • 2 段階のダウングレード：対象バージョンが 2412 より古く（つまり 2407）、現在のバージョンが 2412 より新しい場合です。ステップ 1：現在の FPGA バージョンに対応するリポジトリを使い、現在のバージョンから 2412 へフラッシュします。ステップ 2：HSB リリースリポジトリ v2.0.0 を使い、2412 から対象バージョンへフラッシュします。ステップ間に電源の再投入が必要です。（例外：現在のバージョンがちょうど 2412 の場合、ステップ 2 のみが必要です。）
        • 2 段階のアップグレード：現在のバージョンが 2412 より古く（つまり 2407）、対象バージョンが 2412 より新しい場合です。ステップ 1：v2.0.0（対象 FPGA 2412 に対応）を使い、現在のバージョンから 2412 へフラッシュします。ステップ 2：対象 FPGA バージョンに対応するリポジトリを使い、2412 から対象バージョンへフラッシュします。ステップ間に電源の再投入が必要です。
     4. フラッシュに使用する HSB リポジトリのユーザーガイドを読み、フラッシュコマンドを確認してください。コンテナー内で非対話形式に実行できるよう、必ず --force と --accept-eula を追加してください。注： v2.0.0 では --force はサブコマンドの前に、--accept-eula はサブコマンドの後に指定します。以下の「v2.0.0 の CLI フラグの配置」を参照してください。
     5. フラッシュ完了後、このスキルがチェックアウトした一時的な HSB リリースリポジトリのうち、スキルの実行前に開発キットに存在していたユーザーの元のリポジトリとは異なるものをすべて削除してください。
   • VB1940 カメラ：開発キット上の既存の HSB リポジトリをそのまま使ってください（v2.0.0 の一時リポジトリは不要です）。フラッシュは常に 1 段階で行います。 フラッシュ計画の全容をユーザーに提示し、承認を得てください。
5. フラッシュ手順を実行してください。
   • フラッシュ前に必要な安全確認（ボードへの ping、ボードの種類と現在の FPGA バージョンの確認）を行ってください。
   • ログをすべて記録しながら各フラッシュ手順を実行し、フラッシュを開始する前に処理内容を伝えてください。
   • 各重要なフラッシュの前、および必要なボード／カメラの電源再投入後に、ユーザーから明示的な確認を得てください。
   • すべてのプログラムコマンドはデモコンテナー内で実行してください（コンテナー内では sudo は不要です）。
   • フラッシュ後、次に進む前に、新しい FPGA バージョンが意図した対象バージョンと一致することを確認してください。
   • エラーや不一致が発生した場合は、ワークフローを中止し、現在の状態を報告して、クリーンアップを提案してください。
6. 手順全体の概要レポートを作成し、保存するかどうかを選べるようにしてください。
7. すべてのフラッシュ関連の一時ファイルをクリーンアップし、ユーザーが必要な HSB リリースをチェックアウトできる状態に開発キットを戻してください。

対応ボードタイプ

ボードタイプ	識別子	説明
Lattice	lattice	HSB Lattice CPNX100-ETH-SENSOR-BRIDGE スタンドアロン FPGA ボード
VB1940	vb1940	Lattice FPGA を内蔵した Leopard Imaging VB1940「オールインワン」Eagle Camera

ボードタイプはフェーズ 1 での hololink enumerate の出力から検出され、ユーザーに確認されます。検出結果が曖昧な場合、ユーザーがボードタイプを明示的に指定する必要があります。

対応 FPGA バージョン

Lattice ボードの FPGA バージョン

バージョン	YAML ソースリリース	備考
2407	v2.0.0	対応する最も古いバージョン
2412	v2.0.0	2 段階フラッシュ用のゲートウェイバージョン
2507	v2.3.1
2510	v2.5.0	対応する最新バージョン

VB1940 の FPGA バージョン

バージョン	YAML ソースリリース	HSB リリース	備考
2507	v2.3.0	v2.3.0
2510	v2.5.0	v2.5.0	対応する最新バージョン

VB1940 はバージョン 2407 または 2412 をサポートしていません。これらは Lattice 専用です。

上記に記載されていないバージョン： どちらのボードタイプでも、記載されている最新バージョンより新しい FPGA バージョンはフラッシュできる場合があります。下記の「未記載の FPGA バージョンの取り扱い」を参照してください。Lattice ボードでは、2407 より古いバージョンや既知のバージョンの間のバージョン（例：2409）はサポートされていません。VB1940 では、2507 より古いバージョンはサポートされていません。いずれの場合も、処理を拒否し、そのボードタイプで対応しているバージョンを表示してください。

フラッシュ環境

GitHub リリースタグ、同梱されるマニフェスト YAML の構成、ボード固有のフラッシュコマンド、v2.0.0 の CLI フラグの違い、および FPGA 2407 の enumerate 回避策については、references/flashing-infrastructure.md を参照してください。

リポジトリの選択とチェックアウト（Lattice のみ）

上記の「Lattice ボードの FPGA バージョン」表に基づいて、使用する HSB リリースリポジトリを決定します。参照キーは、移行の方向によって異なります。

• アップグレード：対象 FPGA バージョンの YAML ソースリリースを参照します。
• ダウングレード：現在の FPGA バージョンの YAML ソースリリースを参照します。

自己更新：未記載の FPGA バージョンが見つかった場合、このスキルは対応する HSB リリースがあるか公開リリースノートを確認します（「未記載の FPGA バージョンの取り扱い」を参照）。見つかった場合、このスキルは「対応 FPGA バージョン」表と移行マトリックスを更新し、新しいリリースのマニフェストファイルについて記録します。

リポジトリのチェックアウトロジック

1. 既存のリポジトリを確認する：ユーザーが devkit に HSB リポジトリをすでに持っている場合（/hsb-setup から）、VERSION ファイルからそのバージョンを読み取ります。
2. 必要なリポジトリを決定する：アップグレードの場合は、対応表で対象 FPGA バージョンを参照します。ダウングレードの場合は、現在の FPGA バージョンを参照します。
3. 必要に応じてチェックアウトする：既存のリポジトリが必要なバージョンと一致しない場合、必要なリポジトリバージョンを別のディレクトリにクローンしてチェックアウトします。既存のリポジトリには手を加えません。
4. 2 段階の場合：2 段階フラッシュが必要な場合は、両方の手順のリポジトリを利用できる必要があります。2 段階ダウングレード（現在 > 2412、対象 = 2407）の場合、手順 1 では現在の FPGA のリポジトリを使用し、手順 2 では v2.0.0 を使用します。2 段階アップグレード（現在 = 2407、対象 > 2412）の場合、手順 1 では v2.0.0（対象 2412 のリポジトリ）を使用し、手順 2 では最終的な対象 FPGA バージョンに対応するリポジトリを使用します。必要なリポジトリがすでに存在しない場合は、チェックアウトします。

VB1940 に関する注意：VB1940 のフラッシュでは、常に devkit 上の既存のリポジトリを使用します。FPGA とリポジトリの対応関係は適用されません。既存のリポジトリは v2.3.0 以降である必要があります。既存のリポジトリが見つからない場合は、まず /hsb-setup を実行するようユーザーに案内してください。

検出結果の保存内容

フェーズ 1 で既存のリポジトリを検索し、ボードの種類を検出する際に、次の変数をセッション状態に保存します。

• BOARD_TYPE — 検出されたボードの種類：lattice または vb1940
• EXISTING_REPO_DIR — 既存の HSB リポジトリの絶対パス（見つからない場合は空）
• EXISTING_REPO_VERSION — リポジトリのリリースバージョン（例：2.3.1）。VERSION ファイルから読み取ります
• FLASH_REPO_DIR — フラッシュに使用するリポジトリの絶対パス（別のバージョンをチェックアウトした場合は、EXISTING_REPO_DIR と異なることがあります）
• FLASH_REPO_VERSION — フラッシュ用リポジトリのバージョン（FPGA とリポジトリの対応表から取得）
• INTERIM_REPOS — このスキルがチェックアウトしたリポジトリディレクトリの一覧（フェーズ 6 でクリーンアップするため）

Linux／Windows 対応のラッパー変数

hsb-setup スキルと同じ環境変数を再利用します。

• SSH_TARGET — リモートログイン先（例：nvidia@agx-thor-host）
• REMOTE_ROOT — フラッシュ用ワークスペースを作成するリモート作業ディレクトリ
• REMOTE_SUDO — 特権コマンド用
• REMOTE_SSH_OPTS — 追加の SSH オプション
• HSB_PLATFORM — オプションのプラットフォームヒント

これらが設定されている場合は、設定内容をユーザーに知らせ、再度確認せずにその値を使用します。

フェーズ 1 の前に、解決されたリモート実行設定を表示します。

必須の対話パターン

変更を加える前に、次のフェーズ計画を提示します。

• フェーズ 0：トークン予算の事前確認。ユーザーの残りのプラン使用量で、フラッシュワークフロー全体を完了できることを確認します
• フェーズ 1：ボードの接続を確認し、ボードの種類（Lattice または VB1940）を検出して、現在の FPGA バージョンを読み取ります
• フェーズ 2：対象の FPGA バージョンを選択します（利用可能なバージョンはボードの種類によって異なります）
• フェーズ 3：フラッシュのインフラストラクチャと YAML ファイルを準備し、フラッシュ計画を提示して承認を得ます
  • Lattice：必要なリポジトリをチェックアウトします（アップグレードでは対象 FPGA のリポジトリ、ダウングレードでは現在の FPGA のリポジトリ。未チェックアウトの場合）。マニフェスト YAML をコピーしてパッチを適用します
  • VB1940：既存のリポジトリを直接使用します
• フェーズ 4：フラッシュ手順を実行します（電源の再投入を検証します）
• フェーズ 5：概要レポートを生成します（保存も選択できます）
• フェーズ 6：フラッシュの成果物をクリーンアップします

その後、各フェーズを 1 つずつ実行します。

最終フェーズ以外の各フェーズ（フェーズ 0～5）の後：

1. 主な結果を含むフェーズ概要を表示します。
2. 次のフェーズで行う内容を示し、Proceed to Phase <N+1>? [Y/n] とユーザーに確認を求めます。続行する前に確認を待ちます。

例外：--y（自動承認モード）が有効な場合、フェーズ間の確認は省略され、各フェーズが自動的に実行されます。詳細は「自動承認モード（--y）」のセクションを参照してください。

問題が発生した場合、生のログをそのまま出力してはいけません。次の内容を要約します。

• 失敗した正確なコマンド
• 考えられる根本原因
• 推奨する安全な対応
• 問題が進行を妨げるかどうか

フェーズの詳細

フェーズごとの詳しい手順、フラッシュ手順のロジック、実行ルール、安全上の制約、フェーズ間の確認ルール、詳細度の動作、強制モード、自動承認モードについては、references/phase-details.md を参照してください。

組み込みのヘルプ（--help）

--help の完全な出力については、references/help-text.md を参照してください。

呼び出し例

すべての呼び出し例を含む --help の完全な出力については、references/help-text.md を参照してください。