hsb-setup

Holoscan Sensor Bridge デモのセットアップ

Holoscan Sensor Bridge のデモ環境を最初から最後までセットアップしたい場合に、このスキルを使用してください。

このワークフローには副作用があります。自動的に実行しないでください。ユーザーが明示的に呼び出した場合にのみ実行してください。

開始前 — 必須ゲート（この順番で実施してください）

ゲート 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 — may be empty; will detect from hardware.
HSB_REPO        Custom repo URL — defaults to https://github.com/nvidia-holoscan/holoscan-sensor-bridge.git

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

ゲート 2 — フェーズ計画を提示します。 何らかの作業を行う前に、次の計画をそのままユーザーに示し、確認を待ってください。

HSB Setup — Phase Plan
  Phase 0: Token-budget preflight
  Phase 1: Confirm platform, set up SSH, clone repo, study user guide
  Phase 2: Host prerequisite checks and network setup
  Phase 3: Native CLI build (AGX Thor only — skipped for other platforms)
  Phase 4: Build demo container, run it, ping 192.168.0.2, verify FPGA version
  Phase 5: Issues report (with option to save)
  Phase 6: Stop apps, exit container, hand control back to user

ゲート 3 — トークン予算の事前確認（フェーズ 0）。 SSH 接続や devkit の変更を行う前に、これを実行してください。詳しい手順については、## Token-budget preflight セクションを参照してください。予算チェックに合格するまでフェーズ 1 に進まないでください。

手順

/hsb-setup [PLATFORM] [OPTIONS] と入力して、このスキルを呼び出してください。このスキルは各フェーズを対話形式で進め、変更を加える前に確認を求めます。

このスキルで実行すること

0. リモートコマンドの実行や devkit の設定変更を行う前に、必須のトークン予算の事前確認を実施します。 すべてのセットアップフェーズを完了するために必要なトークン数を見積もり、利用可能な最善の Claude Code／アカウント使用量確認手段で、ユーザーのサブスクリプションプランの残り使用量を確認します。見積もりと確認結果をユーザーに表示し、利用可能な予算が不足している場合、または確認できない場合は作業を中止します。
1. devkit が holoscan センサーブリッジに接続され、すべての機器に電源が入っており、外部ネットワークへの接続が有効で、適切な OS バージョンがインストールされていることをユーザーに確認します。プロファイルのパラメーターがすべて判明している場合は、リポジトリのユーザーガイドを参照し、devkit からセンサーまでの構成図を作成して、ユーザーにこの構成で間違いないか確認します。
2. ユーザーがセットアップの準備完了を確認したら、ユーザーが外部コンピューターから Claude スキルを実行している場合は、devkit への SSH 接続を確立します。devkit に Claude が直接インストールされている場合は、この手順を省略できます。
3. devkit で cat /sys/class/dmi/id/product_name を実行し、結果を HSB_PLATFORM 環境変数と比較して、ホストの devkit プラットフォームを確認します（「ホストプラットフォームの自動検出」セクションを参照）。コマンドが認識可能で空でないプラットフォーム名を返し、それが HSB_PLATFORM と異なる場合、または HSB_PLATFORM が空の場合は、検出したプラットフォームに合わせて HSB_PLATFORM を更新し、変更をユーザーに知らせます。コマンドの結果が空、またはコマンドが失敗し、HSB_PLATFORM がすでに設定されている場合は、既存の値を維持します。
4. 最新の main ブランチから GitHub リポジトリをクローンまたは更新します。デフォルトでは公開リポジトリ nvidia-holoscan/holoscan-sensor-bridge を使用しますが、ユーザーは HSB_REPO 環境変数または --repo <URL> コマンドラインフラグでカスタムリポジトリ URL を指定できます。リポジトリが SSH リポジトリの場合、SSH キーが設定されていなければユーザーに知らせ、SSH キーの設定手順を提示します。
5. どの devkit／プラットフォームを使用するかがまだ明らかでない場合は、ユーザーに確認します。
6. クローンしたリポジトリのルートディレクトリにある docs/user_guide のユーザーガイドを調べて内容を理解し、各 devkit および OS のホスト環境のセットアップ方法、デモコンテナー、コンテナー内外でのアプリケーションの実行方法（該当する場合）、FPGA のフラッシュ方法を把握します。
7. プラットフォームを適切なホストセットアップおよびコンテナーのビルドモードに対応付け、ユーザーガイドの手順に従ってホストのセットアップが正しく設定されていることを確認します。不足している設定を修正・追加するか、修正手順をユーザーに提示します。
8. デモコンテナーをビルドします。
9. デモコンテナーを実行します。
10. 192.168.0.2 のボードへの接続を確認します。接続に失敗した場合は、別の IP アドレスの可能性がないかユーザーに確認します。
11. レジスター 0x80 を読み取って FPGA のバージョンを確認します。センサー上の FPGA バージョンが devkit 上の HSB ホストソフトウェアと一致しない場合は、ボードを適切な FPGA バージョンにフラッシュするために hsb-flash-skill を使用するようユーザーに提案します。
12. フェーズごとに進捗を報告し、失敗について明確に説明し、断念する前に安全な修正を試みます。
13. 発生したすべての問題について、問題の内容と解決方法を明記したレポートを作成します。
14. 最終レポートを md ファイルにエクスポートするオプションをユーザーに提示します。
15. セットアップが完了したら、実行中のアプリをすべて停止し、コンテナーを終了して、devkit の操作権をユーザーに返します。その際、端末ウィンドウはリポジトリのホームディレクトリに置きます。

対応プラットフォームとビルドの対応関係

リポジトリまたは作業ツリー内の最新ドキュメントに明確な別の記載がない限り、以下の対応関係を使用してください。

• dGPU OS／構成の IGX Orin → sh docker/build.sh --dgpu でビルド
• iGPU の IGX Orin → sh docker/build.sh --igpu でビルド
• AGX Orin → sh docker/build.sh --igpu でビルド
• AGX Thor → sh docker/build.sh --igpu でビルド
• DGX Spark → sh docker/build.sh --igpu でビルド

ユーザーが「IGX Orin」としか指定していない場合は、iGPU か dGPU OS／構成 かを明確に尋ねてください。

ホストプラットフォームの自動検出

フェーズ 1（SSH 接続の確立後、またはローカルでの実行時）に、DMI の製品名を読み取り、HSB_PLATFORM 環境変数と比較して、実際の開発キットのハードウェアを確認してください。

製品名からプラットフォームへの対応関係

以下の表は、既知の /sys/class/dmi/id/product_name の値と、対応する HSB_PLATFORM の値を示しています。大文字と小文字を区別しない部分文字列で照合してください。製品名には、追加のテキスト（例：「Developer Kit」、リビジョン番号）が含まれる場合があります。

product_name に含まれる文字列（大文字と小文字を区別しない）	対応する HSB_PLATFORM	備考
IGX Orin	IGX Orin	iGPU か dGPU かがまだ不明な場合は、引き続き確認が必要です
AGX Orin	AGX Orin
AGX Thor	AGX Thor
DGX Spark	DGX Spark

製品名が既知のパターンのいずれにも一致しない場合は、未認識として扱い、手順 5 のプラットフォームに関する質問に進んでください。

検出と調整のロジック

開発キット上で以下を実行してください（フェーズ 1 の SSH heredoc 内、またはローカルで実行します）。

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:-}"

出力を収集した後、以下の調整ルールを適用してください。

1. DETECTED_PLATFORM が空でなく、HSB_PLATFORM が空 → HSB_PLATFORM に DETECTED_PLATFORM を設定します。ユーザーに通知してください。

   Platform auto-detected from hardware: <DETECTED_PLATFORM> (product_name: <DETECTED_PRODUCT>).
   HSB_PLATFORM was not set — updating to "<DETECTED_PLATFORM>".
   

2. DETECTED_PLATFORM が空でなく、HSB_PLATFORM と異なる → HSB_PLATFORM を DETECTED_PLATFORM で上書きします。ユーザーに通知してください。

   WARNING: Hardware reports "<DETECTED_PLATFORM>" (product_name: <DETECTED_PRODUCT>),
   but HSB_PLATFORM was set to "<HSB_PLATFORM>".
   Updating HSB_PLATFORM to match the detected hardware: "<DETECTED_PLATFORM>".
   

3. DETECTED_PLATFORM が空でなく、HSB_PLATFORM と一致する → 変更は不要です。確認してください。

   Platform verified: <HSB_PLATFORM> matches hardware (product_name: <DETECTED_PRODUCT>).
   

4. DETECTED_PLATFORM が空（ファイルが存在しない、読み取れない、または製品名が未認識）で、HSB_PLATFORM が設定済み → 既存の HSB_PLATFORM を維持します。警告してください。

   Could not auto-detect platform from hardware (product_name: "<DETECTED_PRODUCT>").
   Keeping existing HSB_PLATFORM: "<HSB_PLATFORM>".
   

5. DETECTED_PLATFORM と HSB_PLATFORM の両方が空 → 手順 5 のプラットフォームに関する質問に進みます。

調整後、更新した HSB_PLATFORM をリモートセッションの状態ファイルに保存し、後続のフェーズで正しい値が使われるようにしてください。

Linux／Windows に対応したラッパー変数

このスキルを Linux／Windows 上のローカル Claude Code セッションから SSH 経由で実行する場合、以下の環境変数が設定されていれば優先して使用してください。

• リモートログイン先（例：nvidia@agx-thor-host）には SSH_TARGET
• リポジトリを配置するリモート作業ディレクトリには REMOTE_ROOT
• 特権コマンドには REMOTE_SUDO。sudo、sudo -n、または空文字列を受け付けます
• 追加の SSH オプションには REMOTE_SSH_OPTS
• 任意のプラットフォームヒントには HSB_PLATFORM
• クローンするカスタム GitHub リポジトリ URL（例：https://github.com/myorg/my-hsb-fork.git）には HSB_REPO。設定されていない場合は、デフォルトで https://github.com/nvidia-holoscan/holoscan-sensor-bridge.git が使用されます

これらが設定されている場合は、ユーザーに設定内容を通知し、ユーザーが明示的に変更を指示しない限り、再度尋ねずにその値を使用してください。

フェーズ 1 の前に、使用するリモート実行設定を表示してください。必要に応じて、秘密情報は伏せてください。

必須の対話パターン

変更を加える前に、上記の Gate 2 のフェーズ計画を提示します。Thor 以外のプラットフォームでは Phase 3 をスキップします。

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

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

1. フェーズの概要を表示します。詳細度は --verbose モードによって異なります（「Verbosity mode」セクションを参照）。
   • 詳細：全出力と、詳細なステータスブロック（フェーズ名、実行内容、結果、次のアクション）。
   • 簡潔（デフォルト）：問題点を強調した箇条書きの概要。
2. 次の内容を指定して、Proceed to Phase <N+1>? [Y/n] とユーザーに確認を求め、続行前に回答を待ちます（「Phase gate」セクションを参照）。

問題が発生した場合、生のログをそのまま表示するだけにしないでください。次の内容を要約します。

• 失敗した正確なコマンド
• 考えられる根本原因
• 次に試す安全な修復方法
• 修復が成功したかどうか

トークン予算の事前確認

Phase 0 - トークン予算の事前確認

このフェーズは必須です。SSH 接続、リポジトリのクローン、パッケージ／設定の確認、コンテナのビルド、再起動、devkit 設定の変更を行う前に実行する必要があります。

1. セットアップワークフロー全体に必要なトークン予算を見積もります。次のフェーズだけでなく、実行全体を対象にしてください。以下の値は保守的なヒューリスティックであり、過去の実測値ではありません。実測トークン使用量が取得できるようになるまでは、初期の安全予算として扱い、測定値が得られたら実際の /hsb-setup 実行ログを基に調整してください。

   • IGX Orin、AGX Orin、または DGX Spark でセットアップを完全に実行する場合は、少なくとも 280,000 トークンを確保します。
   • AGX Thor では、ネイティブビルドと SIPL／FuSa の確認によってフェーズやトラブルシューティングが増えるため、少なくとも 340,000 トークンを確保します。
   • --verbose、カスタムリポジトリの処理、SSH キーの修復、再起動からの復旧、または追加のトラブルシューティングが想定される場合は、60,000 トークンを追加します。
   • プラットフォームがまだ不明な場合は、より大きい方の見積もりを使用します。

2. 現在のサブスクリプションプランで利用できる、最適な Claude Code／アカウントの使用量情報源を使って、残りの使用量を確認します。利用可能な場合は、機械可読な使用量データまたは製品が提供するデータを優先します。信頼できる使用量情報源がない場合は、Claude Code のアカウントまたはプランの UI に表示される現在の残り使用量／クォータをユーザーに確認します。

   使用量を自己確認できないためにユーザーへ尋ねる場合は、安全な停止選択肢が先に表示されるよう、次の順序を厳守します。

   1. 確認できません — 停止：ユーザーが残りの使用量を確認できません。Phase 1 の前に停止します。
   2. 残りは {estimate} 未満です — 停止：ユーザーがプラン／アカウントの UI を確認し、推定予算より残りが少ないことを確認しました。Phase 1 の前に停止します。
   3. 残りは {estimate} 以上です — 続行：ユーザーがプラン／アカウントの UI を確認し、推定予算以上の残りがあることを確認しました。Phase 1 に進みます。
   4. 入力する：質問または自由形式の指示として扱い、回答してから同じ順序の選択肢を再度提示します。

   続行の選択肢を最初に表示しないでください。ユーザーが続行を選択する前に、停止の選択肢を意図的に確認できるようにする必要があります。

3. 続行する前に、結果をユーザーに表示します。

   Token-budget preflight
   - Estimated tokens required for complete /hsb-setup run: <estimate>
   - Estimate basis: conservative heuristic; refine from actual run logs when available
   - Safety margin included: <margin>
   - Remaining plan usage available: <available or "unverified">
   - Result: PASS / FAIL
   

4. 予算が不足している、または確認できない場合は停止します。

   • 残りの使用量が見積もりを下回る場合は、Phase 1 の前に停止し、devkit 設定の変更中にトークンを使い切る可能性があるため、このスキルは開始を拒否していると説明します。
   • 残りの使用量を確認できない場合は、Phase 1 の前に停止し、新しいセッションの開始、使用量のアップグレード／更新、または確認可能な残り使用量の提示をユーザーに求めます。
   • --y を使用しても、この事前確認を回避できません。

不明な場合に尋ねるプラットフォームの質問

必要最小限の質問だけを尋ねます。

1. 使用しているプラットフォームはどれですか？
   • IGX Orin iGPU
   • IGX Orin dGPU
   • AGX Orin
   • AGX Thor
   • DGX Spark
2. HSB ボードはすでに物理的に接続され、電源が入っていますか？
3. ネットワークと Docker のセットアップに sudo が必要なコマンドを実行しても問題ありませんか？

ユーザーがこれらのいずれかをすでに伝えている場合は、再度尋ねないでください。

利用可能なスクリプト

スクリプト	目的	引数
scripts/hsb_phase_runner.sh	フェーズごとにタイムスタンプ付きログを記録する、構造化されたシェル実行	<phase_name> <command>

run_script(scripts/hsb_phase_runner.sh, <phase_name>, <command>) を使用して、ログを自動記録しながらフェーズのステップを実行します。

フェーズの詳細

フェーズごとの手順、出力スタイル、詳細度の動作、自動承認モード、フェーズゲートのルール、永続的な SSH セッションモデルについては、references/phase-details.md を参照してください。

復旧手順

該当する場合は、次の修正を順に試してください。

1. 一時的な失敗と思われる場合は、失敗したコマンドを一度再実行します。
2. 不足している前提条件（git-lfs、Docker へのアクセス、xhost、ネットワーク経路）を解決します。
3. リポジトリの状態と LFS コンテンツを更新します。
4. ワークフロー全体ではなく、失敗したフェーズだけを再実行します。
5. それでも解決しない場合は、簡潔な診断結果と、ユーザーがコピーして実行できるコマンド一覧を提示して停止します。

このスキルの関連ファイル

• このスキルで使用する、信頼できるビルドとホストセットアップの概要については、docs/platform-mapping.md を参照してください。
• よくある問題の解決方法については、docs/failure-playbook.md を参照してください。
• 構造化されたシェル実行とタイムスタンプ付きログが必要な場合は、ヘルパーとして scripts/hsb_phase_runner.sh を使用します。

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

$ARGUMENTS に --help または -h が含まれている場合、ワークフローを実行しないでください。代わりに、次のヘルプテキストをそのまま出力して停止します。

Holoscan Sensor Bridge — Demo Bring-Up Skill

USAGE
  /hsb-setup [PLATFORM] [OPTIONS]

PLATFORM (optional — will prompt if omitted)
  AGX Orin          NVIDIA Jetson AGX Orin (iGPU, build with --igpu)
  AGX Thor          NVIDIA Jetson AGX Thor (iGPU, build with --igpu)
  IGX Orin iGPU     NVIDIA IGX Orin in iGPU configuration (build with --igpu)
  IGX Orin dGPU     NVIDIA IGX Orin with discrete GPU (build with --dgpu)
  DGX Spark         NVIDIA DGX Spark (iGPU, build with --igpu)

OPTIONS
  --help, -h        Show this help message and exit
  --verbose         Show full raw command output for every phase
                    (default is concise bullet-point summaries)
  --y               Auto-approve all phase gates (skip user confirmation
                    between phases). Not recommended — a confirmation
                    warning is shown before proceeding. All output is
                    saved to a timestamped log file.
  --repo <URL>      Clone a custom GitHub repo instead of the default
                    nvidia-holoscan/holoscan-sensor-bridge.
                    Can also be set via the HSB_REPO env var.
                    Priority: --repo flag > HSB_REPO env var > default repo

ENVIRONMENT VARIABLES (set before invoking the skill)
  SSH_TARGET        Remote login target (e.g. [email protected])
  REMOTE_ROOT       Remote working directory for repo clone and builds
  REMOTE_SUDO       Privilege escalation: 'sudo', 'sudo -n', or ''
  REMOTE_SSH_OPTS   Additional SSH options (e.g. -o ServerAliveInterval=30)
  HSB_PLATFORM      Platform hint (same values as PLATFORM above)
  HSB_REPO          Custom GitHub repo URL (overridden by --repo flag)

WORKFLOW PHASES
  Phase 0   Token-budget preflight; verify enough plan usage for a full run
  Phase 1   Confirm platform, clone repo, and study user guide
  Phase 2   Host prerequisite checks and network setup
  Phase 3   Native build of CLI tools (AGX Thor only, skipped otherwise)
  Phase 4   Build, run demo container, and verify connectivity
  Phase 5   Produce issues report, optionally export to file
  Phase 6   Stop apps, exit container, hand off to user

  The skill prompts for confirmation between each phase.

EXAMPLES
  /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

ヘルプテキストを出力した後は、フェーズを実行したり、質問したりしないでください。

呼び出し例については、組み込みヘルプ（--help） の EXAMPLES セクションを参照してください。

$ARGUMENTS にプラットフォームが含まれている場合は、再度尋ねず、その値を使用します。プラットフォーム名を解析する前に、引数から --verbose、--y、--repo <URL>、--help を取り除きます。