nanoff 2.5.90

---

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

欢迎使用 .NET nanoFramework 固件烧录工具仓库

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

它使用了一些第三方工具

• Espressif esptool 您可以在仓库 此处 找到 esptool 及许可信息。
• STM32 Cube Programmer 您可以在 此处 找到源代码、许可信息和文档。
• Texas Instruments 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 Core CLI命令更新.NET nanoFramework固件刷新器工具

dotnet tool update -g nanoff

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

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

用法

该工具安装后，您可以通过其命令nanoff调用它，其中nanoff是名称的简写形式，以简化输入。

nanoff [command] [args]

此工具包括所有可用命令的帮助。您可以通过输入查看所有可用的命令列表

nanoff --help

每个平台的使用示例和常见选项列表

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

请注意，如果这些操作被平台所支持，则可以组合多个选项，例如，在同一个执行过程中更新CLR并部署托管应用程序。

ESP32使用示例

有多个ESP32映像可用，有些是为目标构建的。请查看此处的列表。您还需要知道您的设备使用的COM端口。下面介绍 如何找到此信息。或者，您还可以列出可用的COM端口。如果您首先列出它们而没有连接要闪存的设备，然后再插上设备，那么新显示的端口即为要闪存设备所使用的端口。此方法适用于所有操作系统。

nanoff --listports

ESP32_PSRAM_REV0映像将适用于ESP32系列的所有变体，无论是带PSRAM还是不带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

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

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

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

普通连接使用示例

可以使用与Visual Studio连接相同的连接更新nano设备，这意味着不需要专门的连接（如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设备。

要获取连接的nano设备的列表。如果需要更多信息，请添加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 基金会 支持。