hsb-setup

What this skill does

# Holoscan Sensor Bridge demo bring-up

Use this skill when the user wants to bring up the Holoscan Sensor Bridge demo environment end to end.

This workflow has side effects. Never run it automatically. Only run it when the user explicitly invokes it.

## Before you start — required gates (do these first, in order)

**Gate 1 — Read environment variables.** Before doing anything else, check these variables and print their resolved values to the user:

```
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 and REMOTE_ROOT are required. Stop and ask the user for them if either is missing.**

**Gate 2 — Present the phase plan.** Before taking any action, show the user this exact plan and wait for acknowledgement:

```
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
```

**Gate 3 — Token-budget preflight (Phase 0).** Run this before any SSH connection or devkit change. See `## Token-budget preflight` section for the full procedure. Do not proceed to Phase 1 until the budget check passes.

## Instructions

Invoke this skill by typing `/hsb-setup [PLATFORM] [OPTIONS]`. The skill walks through each phase interactively, prompting for confirmation before making changes.

## What this skill must do

0. **Run the mandatory token-budget preflight before any remote command or devkit configuration change.** Estimate the tokens needed to complete all setup phases, check the user's remaining subscription-plan usage with the best available Claude Code/account usage mechanism, display the estimate and result to the user, and stop if the available budget is insufficient or cannot be verified.
1. prompt the user to confirm that the devkit is connected to the holoscan sensor bridge and everything is powered up and there is an active network connection to the outside world and that the devkit was installed with the proper OS version. if all profile parameters are known look into the repo user guide and draw a diagram of the devkit to sensor for the user to confirm that this is the setup they have.
2. Once the user confirms the setup is ready, build the ssh connection to the devkit if the user is running the claude skill from an external computer. you can skip this step if claude installed directly on the devkit.
3. Verify the host devkit platform by running `cat /sys/class/dmi/id/product_name` on the devkit and comparing the result to the `HSB_PLATFORM` environment variable using the product-name-to-platform mapping (see "Host platform auto-detection" section). If the command returns a recognized non-empty platform name that differs from `HSB_PLATFORM`, or if `HSB_PLATFORM` is empty, update `HSB_PLATFORM` to match the detected platform and alert the user about the change. If the command returns empty or fails and `HSB_PLATFORM` is already set, keep the existing value.
4. Clone or refresh the GitHub repository from the latest `main` branch. By default this is the public `nvidia-holoscan/holoscan-sensor-bridge` repo, but the user can override it with a custom repo URL via the `HSB_REPO` environment variable or the `--repo <URL>` command-line flag. if the repo is an ssh repo, alert the user if no ssh key is set and provide instructions how to set up the ssh key.
5. Ask the user which devkit/platform they want to use **if it is not already clear**.
6. under the cloned repo root dir, study and understand the user guide at docs/user_guide to learn how to set up host environment for each devkit and OS, demo container, running applications inside and outside the container (where applicable) and flashing the FPGA.
7. Map that platform to the correct host setup and container build mode and make sure host set up is configured properly per user guide instructions, fix and add any missing configuration or prompt the user with instruction how to fix.
8. Build the demo container.
9. Run the demo container.
10. Verify connectivity to the board at `192.168.0.2`. if the connection to the board fails, prompt the user for a possiblity of a different ip address.
11. Verify the FPGA version reading register 0x80. if the FPGA version on the sensor does not match the hsb host software that is on the devkit, suggest the user to use the hsb-flash-skill to flash the board to the proper FPGA version.
12. Report progress in phases, explain failures clearly, and attempt safe fixes before giving up.
13. For every issue encountered, create a report that specifies what was the issue and how you overcame it.
14. Allow the user an option to export the final report to an md file.
15. once you are done setup, stop any running apps and exit the container giving up control on the devkit to the user at repo home directory on terminal window.

## Supported platforms and build mapping

Use the following mapping unless the repository or current docs in the working tree clearly say otherwise:

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

If the user says only “IGX Orin”, explicitly ask whether it is **iGPU** or **dGPU OS/configuration**.


## Host platform auto-detection

During Phase 1 (after SSH is established or when running locally), verify the actual devkit hardware by reading the DMI product name and comparing it to the `HSB_PLATFORM` environment variable.

### Product-name-to-platform mapping

The following table maps known `/sys/class/dmi/id/product_name` values to supported `HSB_PLATFORM` values. Match using **case-insensitive substring** search — the product name may contain additional text (e.g., "Developer Kit", revision numbers).

| `product_name` contains (case-insensitive) | Mapped `HSB_PLATFORM` | Notes |
|---|---|---|
| `IGX Orin` | `IGX Orin` | Still need to ask iGPU vs dGPU if not already known |
| `AGX Orin` | `AGX Orin` | |
| `AGX Thor` | `AGX Thor` | |
| `DGX Spark` | `DGX Spark` | |

If the product name does not match any known pattern, treat it as **unrecognized** and fall through to the manual platform question in step 5.

### Detection and reconciliation logic

Run the following on the devkit (inside the Phase 1 SSH heredoc or locally):

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

After collecting the output, apply the following reconciliation rules:

1. **`DETECTED_PLATFORM` is non-empty and `HSB_PLATFORM` is empty** → set `HSB_PLATFORM` to `DETECTED_PLATFORM`. Alert the user:
   ```