hsb-flash

What this skill does

# HSB FPGA Flash

Use this skill when the user wants to flash (upgrade or downgrade) the FPGA firmware on an HSB board connected to a supported NVIDIA devkit.

**This skill supports two board types:**

1. **HSB Lattice boards** — standalone FPGA board with a Lattice CPNX100 FPGA
2. **Leopard Imaging VB1940** — "all-in-one" camera with an integrated Lattice FPGA

**CRITICAL SAFETY RULE: Never mix board-type commands.** Using `program_leopard_cpnx100` on a Lattice board or `program_lattice_cpnx100` on a VB1940 **can permanently brick the device**. The skill must detect and confirm the board type before any flash operation, and refuse to proceed if the board type is ambiguous or mismatched.

This workflow has side effects (it permanently modifies FPGA firmware). Never run it automatically. Only run it when the user explicitly invokes it.

**Usage warning:** This skill flashes the FPGA with new firmware. Before invoking it, ask the user to make sure they have enough Claude Code usage/tokens to complete the workflow.

## 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 (optional).
```

**SSH_TARGET and REMOTE_ROOT are required. Stop and ask the user for them if either is missing.**

**Gate 2 — Present the flash summary and phase plan.** Before taking any action:

If the user's request already includes board type, current FPGA version, and target FPGA version, state the following before the phase plan: flash tool (`program_lattice_cpnx100` for Lattice, `program_leopard_cpnx100` for VB1940 — never mix), manifest release and filename, CLI flags (`--force --accept-eula`), whether the procedure is single-step or two-step via gateway 2412. For VB1940, also state that no v2.0.0 interim repo is needed. For two-step upgrades from FPGA 2407, state that step 1 uses `hololink --force fpga_version` (not `hololink enumerate`, which is incompatible with FPGA 2407) and uses v2.0.0 flag placement: `hololink --force program scripts/manifest.yaml --accept-eula` (`--force` before the subcommand).

Then show the phase plan and ask explicitly: `Shall I proceed with the flash workflow? [Y/n]` — do not start Gate 3 until the user confirms:

```
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 — Token-budget preflight (Phase 0).** Run after the phase plan (Gate 2) has been presented and the user has confirmed. Do not run the token-budget check before the phase plan is shown. Do not proceed to Phase 1 until the budget check passes.

**Gate 4 — Confirm board type explicitly.** Before any flash command, confirm with the user whether the board is **Lattice** or **VB1940**. Never mix `program_lattice_cpnx100` and `program_leopard_cpnx100` — wrong tool can brick the device.

## Instructions

Invoke this skill by typing `/hsb-flash [OPTIONS]`. The skill detects the board type automatically, presents a flashing plan, and prompts for confirmation before each flash step. See [references/help-text.md](references/help-text.md) for the full `--help` output.

## What this skill must do

0. **Run the mandatory token-budget preflight before any remote command, repo checkout, container build, or flash preparation.** Estimate the tokens needed to complete all 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. Verify that an HSB board is connected to a devkit, that SSH and board connectivity work, read the current FPGA version, and **identify the board type** (Lattice or VB1940). Try `hololink enumerate` first; if it fails (which is expected for FPGA 2407 boards), fall back to `hololink --force fpga_version`. For Lattice boards, if all methods fail with the existing repo's container, checkout HSB release repo v2.0.0 and retry using the v2.0.0 container. If that also fails, assume the version is 2407 and continue. For VB1940 boards, ask the user if the version cannot be read.
2. Ask the user for the target FPGA version they want to flash to (or accept "latest"). The available versions depend on the board type.
3. **Handle undocumented FPGA versions** (applies to both Lattice and VB1940): If the current or target FPGA version is not listed in this skill's supported versions or mapping tables, it may belong to a newer HSB release not yet documented here, or it may be an unreleased development build. Proceed as follows:
   - **Check for a newer release**: Fetch the public release notes at `https://github.com/nvidia-holoscan/holoscan-sensor-bridge/blob/main/RELEASE_NOTES.md` and look for a release that introduces the undocumented FPGA version. If a matching release is found, checkout that release repo on the devkit and use it for flashing following the same rules described below for the detected board type. Also update this skill's mapping tables, supported FPGA versions lists, and transition matrices with the new release and its corresponding FPGA version.
   - **Development or unreleased FPGA**: If no published release corresponds to the FPGA version, use the existing HSB repo already on the devkit (from `/hsb-setup`) to flash, following the same rules for the detected board type. If the flash fails, report the error and prompt the user for further instructions.
4. Determine the correct flashing procedure and prepare flash scripts and YAML files:
   - **Lattice boards**:
     1. Read the FPGA version currently flashed on the HSB board. Determine the required HSB release repo based on the flash direction: for upgrades, use the repo corresponding to the target FPGA version; for downgrades, use the repo corresponding to the current FPGA version (see "FPGA version to repo mapping" below). Checkout this repo if it does not already exist on the devkit.
     2. Copy the target FPGA manifest YAML from the relevant `scripts/` directory of this skill to the checked-out repo, and patch the file as needed for any missing details (e.g., `fpga_uuid`).
     3. Determine the flashing procedure:
        - **Single-step upgrade**: If the current version is 2412 or newer and the target is also 2412 or newer, or if upgrading from any version to exactly 2412. Flash directly from the current version to the target using the repo that corresponds to the target FPGA version (see "FPGA version to repo mapping").
        - **Single-step downgrade**: If both the current and target versions are 2412 or newer. Flash directly from the current version to the target using the repo that matches the current FPGA version.
        - **Two-step downgrade**: If the target is older than 2412 (i.e., 2407) and the current version is newer than 2412. Step 1: flash from the current version to 2412 using the repo that matches the current FPGA version. Step 2: flash from 2412 to the target using HSB release repo v2.0.0. Power cycle required between steps. (Special case: if the current version is exactly 2412, only step 2 is needed.)
        - **Two-step upgrade**: If the current version is older than 2412 (i.e., 2407) and the target is newer than 2412. Step 1: flash from the current version to 2412