nanoFramework.Tools.FirmwareFlasher 2.5.90

---

文档语言： 英文 | 中文简体

欢迎使用 .NET nanoFramework 固件闪存工具仓库

此存储库包含 nano firmware flasher 工具。它是一个 .NET Core Tool，允许使用固件镜像（nanoBooter 和 nanoCLR）闪存 .NET nanoFramework 目标，部署应用程序（运行 .NET 应用程序所需的所有程序集）以及恢复之前保存的部署镜像。它是 .NET nanoFramework 工具箱的一部分，包括其他在 .NET nanoFramework 开发、使用或仓库管理中所需的工具。

它使用了几个第三方工具

• Espressif esptool 您可以在以下存储库中找到esptool和许可信息：此处。
• STM32 Cube Programmer 您可以在以下位置找到源代码、许可信息和文档：此处。
• 德州仪器 Uniflash 您可以在以下位置找到Uniflash工具和许可信息：此处。
• SEGGER J-Link 您可以在以下位置找到J-Link、许可信息和文档：此处。

我们还将此工具作为.NET库分发，以便它可以集成到第三方应用程序中。请查看Samples文件夹中的README以获取更多详细信息以及示例应用程序。

安装 .NET nanoFramework 固件烧写器

使用以下.NET Core CLI命令一次性安装.NET nanoFramework 固件烧写器工具

dotnet tool install -g nanoff

安装成功后，将显示一条消息，显示用于调用工具的命令以及已安装的版本。类似于以下示例

You can invoke the tool using the following command: nanoff
Tool 'nanoff' (version '9.9.9') was successfully installed.

安装路径问题

⚠️ 已知问题：当nanoff安装在一个包含重音字符的路径中时，运行STM32设备的命令。这是由STM32 Cube Programmer中的已知错误引起的。如果您的用户路径存在问题，例如，您必须将其安装在一个没有这些字符的位置。为了完成此操作，请使用以下.NET Core CLI命令，其中指定了工具将安装的路径

dotnet tool install nanoff --tool-path c:\a-plain-simple-path-to-install-the-tool

请注意，如果您未使用nanoff与STM32设备一起使用，则此限制不适用。

MacOS用户

安装后，您还需要将nanoff添加到您的路径中，然后运行

export PATH=$PATH:~/.dotnet/tools

更新 .NET nanoFramework 固件烧写器

要更新.NET nanoFramework 固件烧写器工具，请使用以下.NET Core CLI命令

dotnet tool update -g nanoff

如果工具安装在有特定路径的位置，则使用以下.NET Core CLI命令代替

dotnet tool update nanoff --tool-path c:\path-where-the-tool-was-installed

用法

安装工具后，您可以通过其命令nanoff调用它，这是其名称的简写版本，以方便输入。

nanoff [command] [args]

该工具包含所有可用命令的帮助。您可以通过输入以下内容查看所有可用命令的列表

nanoff --help

按平台和通用选项划分的用法示例列表

• ESP32
• STM32
• TI CC13x2
• Silabs Giant Gecko
• 普通连接使用示例
• 通用选项

请注意，如果平台.support这些操作，则可以组合多个选项，例如，在相同的执行中更新CLR和部署托管应用程序。

ESP32使用示例

有多个ESP32映像可用，其中一些是针对特定目标构建的。请查阅以下列表。您还需要知道您的设备使用的COM端口。您可以在以下位置找到如何操作的说明：此。或者，您还可以列出可用的COM端口。如果您首先列出了端口，然后ла设备进行烧写，并插入设备，那么将显示的附加端口就是用于烧写作设备的端口。此方法适用于所有操作系统。

nanoff --listports

ESP32_PSRAM_REV0映像将适用于ESP32系列的所有变体，无论是否带有PSRAM，以及所有硅版本。您可以在此了解有关不同映像之间差异的更多信息：此处。

FEATHER_S2映像将适用于大多数ESP32-S2系列变体，这些系列对外开放了嵌入式USB CDC引脚。您可以在此了解有关不同映像之间差异的更多信息：此处。

当使用nanoff时，您可以通过添加--target MY_TARGET_NAME_HERE来使用特定的镜像。如果只是使用--platform esp32指定平台，则nanoff将根据连接设备的特性选择最合适的镜像。类似于以下输出的内容将显示以提示将要使用哪个镜像：

No target name was provided! Using 'ESP32_REV0' based on the device characteristics.

注意：请注意，对于ESP32-S2目标，无法安全地确定适合使用的最佳镜像。因此，必须提供适当的名称，使用--target MY_TARGET_NAME_HERE。

一些ESP32板在进入引导加载程序模式时存在问题。这通常可以通过按住板上的BOOT/FLASH按钮来解决。如果在nanoff检测到这种情况，将显示以下警告：

*** Hold down the BOOT/FLASH button in ESP32 board ***

⚠️要更新FeatherS2、TinyS2和一些S3模块，需要通过按住[BOOT]，点击[RESET]，然后释放[BOOT]将板置于下载模式。

更新ESP32目标的固件

将连接到COM31的ESP32目标的固件更新到最新可用的开发版本。

nanoff --update --target ESP32_PSRAM_REV0 --serialport COM31

使用本地CLR文件更新ESP32-S2 KALUGA 1的固件

要使用本地CLR文件（例如从构建）更新连接到COM31的ESP32-S2 KALUGA 1目标的固件，此文件必须是一个包含有效CLR的二进制文件。对文件内容不进行其他检查或验证。

nanoff --update --target KALUGA_1 --serialport COM31 --clrfile "C:\nf-interpreter\build\nanoCLR.bin" 

您可以调整您想要使用的核心镜像名称。请参阅上一节以获取完整列表。

显示连接的ESP32设备详细信息

要显示连接到COM31的ESP32设备的详细信息。

nanoff --platform esp32 --serialport COM31 --devicedetails 

可选地，可以通过传递额外参数--checkpsram强制检测PSRAM的可用性。

将托管应用程序部署到ESP32目标

将托管应用程序部署到连接到COM31的ESP32_PSRAM_REV0目标。

注意：部署镜像的二进制文件可以在Visual Studio项目的“发布”或“调试”文件夹中找到（在成功构建后）。此文件包含将托管应用程序部署到目标所需的一切（即应用程序可执行文件以及所有引用的库和程序集）。

nanoff --target ESP32_PSRAM_REV0 --serialport COM12 --deploy --image "E:\GitHub\nf-Samples\samples\Blinky\Blinky\bin\Debug\Blinky.bin"

更新ESP32目标固件以及托管应用程序

要将应用程序部署到连接到COM31的ESP32目标，并使用你的应用程序，你必须指定托管应用程序的路径。可选地，你可以提供一个地址，这将覆盖默认的部署地址。此示例使用在构建应用程序时可以找到的二进制格式文件。注意，由于只能运行应用程序，当你在构建库时，不会自动创建bin文件。仅适用于应用程序。

nanoff --target ESP32_PSRAM_REV0 --update --serialport COM31 --deploy --image "c:\eps32-backups\my_awesome_app.bin" --address 0x1B000

STM32使用示例

更新特定STM32目标的固件

要使用JTAG连接将ST_STM32F769I_DISCOVERY目标的固件更新到最新可用的稳定版本。

nanoff --update --target ST_STM32F769I_DISCOVERY --jtag

将托管应用程序部署到ST_STM32F769I_DISCOVERY目标

要将托管应用程序部署到具有部署区域在0x08080000闪存地址的ST_STM32F769I_DISCOVERY目标，并在闪存后将其MCU重置。

注意：部署镜像的二进制文件可以在Visual Studio项目的“发布”或“调试”文件夹中找到（在成功构建后）。此文件包含将托管应用程序部署到目标所需的一切（即应用程序可执行文件以及所有引用的库和程序集）。

nanoff --target ST_STM32F769I_DISCOVERY --deploy --image "E:\GitHub\nf-Samples\samples\Blinky\Blinky\bin\Debug\Blinky.bin" --address 0x08040000 --reset

更新ST_STM32F769I_DISCOVERY的固件以及托管应用程序

要使用JTAG连接将ST_STM32F769I_DISCOVERY目标的固件更新到最新可用的版本，并同时更新托管应用程序。您必须指定托管应用程序的路径。此示例使用Visual Studio构建任何nanoFramework C#应用程序时生成的二进制格式文件。因为它是二进制文件，所以您还必须指定部署区域的闪存地址（此处为0x08000000，注意十六进制格式）。

nanoff --update --target ST_STM32F769I_DISCOVERY --jtag --binfile "c:\dev\my awesome app\bin\debug\my_awesome_app.bin" --address 0x08000000

列出所有带有JTAG连接的STM32设备

此功能可以列出所有通过JTAG连接的STM32设备。

nanoff --listjtag

列出所有带有DFU连接的STM32设备

此功能可以列出所有通过DFU连接的STM32设备。

nanoff --listdfu

安装STM32 JTAG驱动程序

要安装STM32 JTAG连接目标的驱动程序。

nanoff --installjtagdrivers

安装STM32 DFU驱动程序

安装连接的STM32 DFU目标的驱动程序。

nanoff --installdfudrivers

TI CC13x2使用示例

更新特定TI CC13x2目标的固件

将TI_CC1352R1_LAUNCHXL目标的固件更新到最新版本。

nanoff --update --target TI_CC1352R1_LAUNCHXL

安装TI LaunchPad目标所需的XDS110 USB驱动程序

安装XDS110 USB驱动程序。

nanoff --installxdsdrivers

Silabs Giant Gecko使用示例

更新特定Silabs目标的固件

将SL_STK3701A目标的固件更新到最新版本。

nanoff --update --target SL_STK3701A

从本地文件更新Silabs目标的固件

使用本地固件文件（例如来自构建）更新Silabs目标的固件。此文件必须是一个包含来自构建的有效的启动器和CLR的二进制文件。不对文件内容进行任何检查或验证。

nanoff --update --platform gg11 --binfile "C:\nf-interpreter\build\nanobooter-nanoclr.bin" --address 0x0

将托管应用程序部署到SL_STK3701A目标

将托管应用程序部署到SL_STK3701A目标，部署区域位于0x000EE000闪存地址，并在烧录后重置MCU。

注意：部署镜像的二进制文件可以在Visual Studio项目的“发布”或“调试”文件夹中找到（在成功构建后）。此文件包含将托管应用程序部署到目标所需的一切（即应用程序可执行文件以及所有引用的库和程序集）。

nanoff --target SL_STK3701A --deploy --image "E:\GitHub\nf-Samples\samples\Blinky\Blinky\bin\Debug\Blinky.bin" --address 0x000EE000

更新SL_STK3701A的固件以及托管应用程序

使用J-Link连接，将SL_STK3701A目标的固件更新到最新可用的版本，并带有托管应用程序。您必须指定托管应用程序的路径。此示例使用Visual Studio在构建任何nanoFramework C#应用程序时生成的二进制格式文件。因为它是一个二进制文件，所以还必须指定部署区域的闪存地址（在此处为0x000EE000，请留意十六进制格式）。

nanoff --update --target SL_STK3701A --binfile "c:\dev\my awesome app\bin\debug\my_awesome_app.bin" --address 0x000EE000

列出通过J-Link连接的所有Silabs设备

列出所有通过J-Link连接的Silabs设备。

nanoff --listjlink

普通连接使用示例

可以更新nano设备，使用与Visual Studio连接相同的连接，这意味着不需要专用连接（例如JTAG或JLink）。这仅在设备之前已使用工作的nanoFramework固件进行闪存的情况下才可能。

更新nano设备的CLR

将连接到串行端口的nano设备的CLR更新到最新可用的版本。这将找到连接设备的最新可用固件，并更新CLR。

nanoff --nanodevice --update --serialport COM9

部署托管应用程序

要部署（或更新）托管应用程序，必须提供托管应用程序的路径。此示例使用Visual Studio在构建任何nanoFramework C#应用程序时生成的二进制格式文件。因为可以从连接的设备检索所有所需详细信息，所以不需要其他配置。

nanoff --nanodevice --deploy --serialport COM9 --image "c:\dev\my awesome app\bin\debug\my_awesome_app.bin"

从本地文件更新nano设备的CLR

使用本地固件文件（例如来自构建）更新nano设备的固件。此文件必须是一个包含来自构建的有效nanoCLR的二进制文件。不对文件内容进行任何检查或验证。

nanoff --nanodevice --update --serialport COM9 --clrfile "C:\nf-interpreter\build\nanoclr.bin"

从nano设备获取细节

获取连接到串行端口的nano设备的详细信息。

nanoff --nanodevice --devicedetails --serialport COM9

通用选项

预先检查目标是否适合连接的设备

该工具试图尽最大努力执行最佳努力健康检查，以确定请求的目标是否适合连接的目标。有时由于目标名称的差异和变化，或者连接设备提供的详细资料不足，甚至（例如DFU连接设备）无法确定连接的确切设备，这不可能。这并不一定意味着固件不会工作，所以只把这个作为建议。

要禁用此验证，请在命令行中添加--nofitcheck选项。

工具输出详细程度

可以通过设置v|verbosity选项来设置工具的输出详细程度。

这对于例如在一个需要最小输出以简化处理执行返回结果的自动化过程中使用此工具来说很方便。它可以设置为

• q[uiet]
• m[inimal]
• n[ormal]
• d[etailed]
• diag[nostic]

nanoff -v q

列出连接的nano设备

获取已连接纳米设备的列表。如果需要更多详细信息，请添加设置 above normal 的 verbose 选项。

nanoff --listdevices [ -v d ]

输出示例

-- Connected .NET nanoFramework devices --
SKY_EEVB_Debug @ COM7

------------------------------------------

包含详细信息的输出示例

-- Connected .NET nanoFramework devices --
SKY_EEVB_Debug @ COM7
  Target:      SKY_EEVB_Debug
  Platform:    GGECKO_S1
  Date:        May 31 2023
  Type:        MinSizeRel build with Azure RTOS v6.2.0
  CLR Version: 1.8.1.124

------------------------------------------

在 Windows 上查找设备 COM 端口

您需要知道连接到您的设备的 COM 端口。搜索：计算机管理，选择 设备管理器 然后展开 端口（COM & LPT），您将找到连接设备的 COM 端口。

重要：您可能需要安装驱动程序。请参考制造商网站或使用 Windows 更新来安装最新版本的驱动程序。

使用 nanoff 查找设备 COM 端口

您可以使用 nanoff 的 --listports 命令列出可用的 COM 端口。此方法适用于所有操作系统。如果您在没有连接设备的情况下先运行该命令，您将得到第一个列表。然后插入您的设备并再次运行该命令。出现的新 COM 端口就是来自您的设备的那个！

nanoff --listports

没有插入设备时的输出示例

No available COM port

然后您插入设备并再次运行该命令

Available COM ports:
  COM12

列出目标

您可以使用 -platform 参数列出受支持的命令行参数，以及它们的版本。

列出 ESP32 目标可用的包

nanoff --listtargets --platform esp32

列出 STM32 目标可用的包

nanoff --listtargets --platform stm32

如果您将 -listtargets 开关与 -preview 结合使用，您将获得具有实验性或重大功能更改的可用的固件包列表。

将文件部署到设备存储

一些设备（如 ESP32、Orgpal以及其他）可使用存储。可以在此存储中部署文件。您必须使用 filedeployment 参数指向一个 JSON 文件，在闪存设备时部署文件。

nanoff --target XIAO_ESP32C3 --update --masserase --serialport COM21  --filedeployment C:\path\deploy.json

JSON 包含可选的 SerialPort，在此情况下上传文件的端口可能不同于用于闪存设备的端口，或者未在主命令行中指定，并包含一个 必需的 Files 条目列表。每个条目必须包含 DestinationFilePath（目标完整路径文件名）和 SourceFilePath（部署内容），否则要删除文件，请提供要部署的源文件的完整路径和文件名。

{
   "serialport":"COM42",
   "files": [
      {         
         "DestinationFilePath": "I:\\TestFile.txt",
         "SourceFilePath": "C:\\tmp\\NFApp3\\NFApp3\\TestFile.txt"
      },
      {
         "DestinationFilePath": "I:\\NoneFile.txt"
      },
      {
         "DestinationFilePath": "I:\\wilnotexist.txt",
         "SourceFilePath": "C:\\WRONGPATH\\TestFile.txt"
      }
   ]
}

如果您只想部署文件而不进行其他操作，则可以仅指定

nanoff --filedeployment C:\path\deploy.json

在这种情况下，JSON 文件中必须存在 SerialPort。

[!注意] 如果存储中已存在文件，则新文件将覆盖旧文件。

如果文件不存在且请求删除，则不发生任何操作，将显示警告。

如果由于问题无法上传文件，则其他文件的部署将继续并显示错误。

清除缓存位置

如果需要，可以从存储固件包的本地缓存中清除。附加信息是缓存位置是用户文件夹中的 -nanoFramework\fw_cache 目录。

在命令中包含此选项时，不处理其他选项。

nanoff --clearcache

退出代码

可以在此源文件中检查退出代码。

遥测

此工具正在使用匿名遥测来帮助我们改进使用情况。您可以通过设置环境变量 NANOFRAMEWORK_TELEMETRY_OPTOUT 为 1 来选择退出。

遥测信息主要与命令行参数、安装的固件版本以及代码执行期间可能发生的任何问题相关。

反馈和文档

要提供反馈、报告问题以及获取有关如何贡献的信息，请参阅 主存储库。

加入我们的Discord社区这里。

鸣谢

本项目贡献者名单可在CONTRIBUTORS中找到。

许可证

nanoFramework固件烧录工具遵循MIT许可证。

行为准则

本项目遵循贡献者公约中的行为准则，以明确社区中的预期行为。更多信息请参阅.NET基金会行为准则。

.NET基金会

本项目由.NET基金会支持。