hsb-flash

HSB FPGA 闪存

当用户想要为连接到受支持 NVIDIA 开发套件的 HSB 板卡刷写（升级或降级）FPGA 固件时，使用此技能。

此技能支持两种板卡类型：

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 使用额度/令牌来完成此工作流。

开始前 — 必须通过的关卡（按顺序执行）

关卡 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 为必填项。缺少其中任何一项时，停止并向用户询问。

关卡 2 — 提供刷写摘要和阶段计划。 采取任何操作前：

如果用户的请求已包含板卡类型、当前 FPGA 版本和目标 FPGA 版本，则在阶段计划前说明以下内容：刷写工具（Lattice 使用 program_lattice_cpnx100，VB1940 使用 program_leopard_cpnx100 — 切勿混用）、清单版本和文件名、CLI 标志（--force --accept-eula），以及此流程是单步操作还是通过网关 2412 进行的两步操作。对于 VB1940，还要说明无需使用 v2.0.0 中间仓库。对于从 FPGA 2407 开始的两步升级，还要说明第 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] — 用户确认前，不得开始关卡 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

关卡 3 — 令牌预算预检（阶段 0）。 在展示阶段计划（关卡 2）并获得用户确认后运行。不得在展示阶段计划前运行令牌预算检查。预算检查通过前，不得进入阶段 1。

关卡 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 release 仓库 v2.0.0，并使用 v2.0.0 容器重试。如果仍然失败，则假定版本为 2407 并继续。对于 VB1940 板卡，如果无法读取版本，则询问用户。
2. 询问用户希望烧录到哪个目标 FPGA 版本（也可接受“latest”）。可用版本取决于板卡类型。
3. 处理未记录的 FPGA 版本（适用于 Lattice 和 VB1940）：如果当前或目标 FPGA 版本未列在本技能支持的版本或映射表中，该版本可能属于本技能尚未记录的较新 HSB release，也可能是尚未发布的开发版本。按以下步骤处理：
   • 检查是否有较新版本：获取公开的发行说明 https://github.com/nvidia-holoscan/holoscan-sensor-bridge/blob/main/RELEASE_NOTES.md，查找是否有引入该未记录 FPGA 版本的 release。如果找到匹配的 release，则在开发套件上检出该 release 仓库，并根据检测到的板卡类型，按照下文相同的规则使用它进行烧录。同时更新本技能的映射表、支持的 FPGA 版本列表和版本转换矩阵，加入新 release 及其对应的 FPGA 版本。
   • 开发版或未发布的 FPGA 版本：如果没有已发布的 release 对应此 FPGA 版本，则使用开发套件上已有的 HSB 仓库（来自 /hsb-setup）进行烧录，并遵循对应板卡类型的相同规则。如果烧录失败，则报告错误并询问用户下一步指示。
4. 确定正确的烧录流程，并准备烧录脚本和 YAML 文件：
   • Lattice 板卡：
     1. 读取 HSB 板卡当前已烧录的 FPGA 版本。根据烧录方向确定所需的 HSB release 仓库：升级时使用对应目标 FPGA 版本的仓库；降级时使用对应当前 FPGA 版本的仓库（见下文“FPGA 版本到仓库的映射”）。如果开发套件上尚无此仓库，则检出该仓库。
     2. 将目标 FPGA 清单 YAML 从本技能相关的 scripts/ 目录复制到已检出的仓库，并根据需要补充文件中缺少的信息（例如 fpga_uuid）。
     3. 确定烧录流程：
        • 单步升级：如果当前版本和目标版本均为 2412 或更高，或从任意版本升级到 2412，则直接从当前版本烧录到目标版本，并使用对应目标 FPGA 版本的仓库（见“FPGA 版本到仓库的映射”）。
        • 单步降级：如果当前版本和目标版本均为 2412 或更高，则直接从当前版本烧录到目标版本，并使用与当前 FPGA 版本匹配的仓库。
        • 两步降级：如果目标版本早于 2412（即 2407），且当前版本晚于 2412。第 1 步：使用与当前 FPGA 版本匹配的仓库，从当前版本烧录到 2412。第 2 步：使用 HSB release 仓库 v2.0.0，从 2412 烧录到目标版本。两步之间必须断电重启。（特殊情况：如果当前版本恰好为 2412，则只需执行第 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 release 仓库。
   • VB1940 摄像头：直接使用开发套件上已有的 HSB 仓库（无需 v2.0.0 临时仓库）。烧录始终为单步操作。 请先向用户完整展示烧录计划并征得批准。
5. 执行烧录流程：
   • 执行烧录前必要的安全检查（ping 板卡，确认板卡类型和当前 FPGA 版本）。
   • 记录完整日志并执行每个烧录步骤；烧录前告知用户即将执行的操作。
   • 每次关键烧录操作前，以及每次所需的板卡／摄像头断电重启后，均须获得用户明确确认。
   • 所有编程命令都必须在演示容器内执行（容器内无需 sudo）。
   • 烧录后，验证新的 FPGA 版本与预期目标一致，再继续操作。
   • 如遇任何错误或版本不匹配，立即停止工作流，报告当前状态，并提出是否清理。
6. 生成整个流程的总结报告，并提供保存选项。
7. 清理所有烧录产物，使开发套件恢复就绪状态，以便用户检出所需的任何 HSB release。

支持的板卡类型

板卡类型	标识符	描述
Lattice	lattice	HSB Lattice CPNX100-ETH-SENSOR-BRIDGE 独立 FPGA 板卡
VB1940	vb1940	Leopard Imaging VB1940“一体化” Eagle Camera，集成了 Lattice FPGA

在阶段 1 期间，系统会根据 hololink enumerate 的输出检测板卡类型，并与用户确认。如果检测结果不明确，用户必须明确指定板卡类型。

支持的 FPGA 版本

Lattice 板卡 FPGA 版本

版本	YAML 源代码发布版本	备注
2407	v2.0.0	支持的最旧版本
2412	v2.0.0	两步刷写的网关版本
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 的版本不受支持。在这两种情况下，均应拒绝操作并显示该板卡类型支持的版本。

刷写基础设施

请参阅 references/flashing-infrastructure.md，了解 GitHub 发布标签、捆绑的清单 YAML 布局、特定板卡的刷写命令、v2.0.0 CLI 标志差异，以及 FPGA 2407 枚举的解决方法。

仓库选择与检出（仅限 Lattice）

上方的“Lattice 板卡 FPGA 版本”表格决定要使用哪个 HSB 发布仓库。查找依据取决于升级或降级方向：

• 升级：查找目标 FPGA 版本对应的 YAML 源代码发布版本。
• 降级：查找当前 FPGA 版本对应的 YAML 源代码发布版本。

自我更新：如果遇到未记录的 FPGA 版本，此技能会检查公开发布说明，查找匹配的 HSB 发布版本（请参阅“处理未记录的 FPGA 版本”）。如果找到，此技能会更新“支持的 FPGA 版本”表格和转换矩阵，并记录新发布版本的清单文件。

仓库检出逻辑

1. 检查是否已有仓库：如果用户已在开发套件上有 HSB 仓库（来自 /hsb-setup），请从 VERSION 文件中读取其版本。
2. 确定所需仓库：升级时，在映射表中查找目标 FPGA 版本。降级时，查找当前 FPGA 版本。
3. 按需检出：如果现有仓库与所需版本不匹配，则将所需版本的仓库克隆并检出到单独目录。现有仓库保持不变。
4. 两步刷写情况：如果需要两步刷写，则两个步骤所需的仓库都必须可用。对于两步降级（当前版本 > 2412，目标版本 = 2407），步骤 1 使用当前 FPGA 对应的仓库，步骤 2 使用 v2.0.0。对于两步升级（当前版本 = 2407，目标版本 > 2412），步骤 1 使用 v2.0.0（目标版本 2412 对应的仓库），步骤 2 使用最终目标 FPGA 版本对应的仓库。如果任何所需仓库尚不存在，则将其检出。

VB1940 注意事项：VB1940 刷写始终使用开发套件上的现有仓库——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 阶段：预检 Token 预算；确认用户剩余的计划用量足以完成整个刷写工作流
• 第 1 阶段：验证开发板连接，检测开发板类型（Lattice 或 VB1940），并读取当前 FPGA 版本
• 第 2 阶段：选择目标 FPGA 版本（可用版本取决于开发板类型）
• 第 3 阶段：准备刷写基础设施和 YAML 文件，并提交刷写计划供批准
  • Lattice：检出所需仓库（升级时使用目标 FPGA 对应的仓库，降级时使用当前 FPGA 对应的仓库；如果本地尚未存在该仓库）
  • VB1940：直接使用现有仓库
• 第 4 阶段：执行刷写流程（并验证电源循环）
• 第 5 阶段：生成摘要报告（可选择保存）
• 第 6 阶段：清理刷写产生的文件

然后一次执行一个阶段。

每个非最终阶段（第 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。