nanoff 2.5.96
See the version list below for details.
dotnet tool install --global nanoff --version 2.5.96
dotnet new tool-manifest # if you are setting up this repo dotnet tool install --local nanoff --version 2.5.96
#tool dotnet:?package=nanoff&version=2.5.96
nuke :add-package nanoff --version 2.5.96
Document Language: English | 中文简体
Welcome to the .NET nanoFramework firmware flasher tool repository
This repo contains the nano firmware flasher tool. It's a .NET Core Tool that allows flashing a .NET nanoFramework target with a firmware image (nanoBooter and nanoCLR), the application deployment (all assemblies required to run a .NET application) and restore previously saved deployment images. Is part of .NET nanoFramework toolbox, along with other various tools that are required in .NET nanoFramework development, usage or repository management.
It makes use of several 3rd party tools:
- Espressif esptool You can find the esptool and licensing information on the repository here.
- STM32 Cube Programmer You can find the source, licensing information and documentation here.
- Texas Instruments Uniflash You can find the Uniflash tool and licensing information here.
- SEGGER J-Link You can find the J-Link, licensing information and documentation here.
We are also distributing this tool as a .NET library so it can be integrated in 3rd party applications. Please check the README in the Samples folder for more details along with sample applications.
Install .NET nanoFramework Firmware Flasher
Perform a one-time install of the .NET nanoFramework Firmware Flasher tool using the following .NET Core CLI command:
dotnet tool install -g nanoff
After a successful installation a message is displayed showing the command that's to be used to call the tool along with the version installed. Similar to the following example:
You can invoke the tool using the following command: nanoff
Tool 'nanoff' (version '9.9.9') was successfully installed.
Install path issues
⚠️ That are know issues running commands for STM32 devices when nanoff
is installed in a path that contains diacritic characters. This is caused by a known bug in STM32 Cube Programmer.
If that's the case with your user path, for example, you have to install it in a location that does have those.
To accomplish that, use the following .NET Core CLI command on which the path where the tool will be installed is specified:
dotnet tool install nanoff --tool-path c:\a-plain-simple-path-to-install-the-tool
Note that if you're not using nanoff
with STM32 devices, this limitation does not apply.
MacOS users
You'll need to add nanoff
to your path as well, once installed run:
export PATH=$PATH:~/.dotnet/tools
Update .NET nanoFramework Firmware Flasher
To update .NET nanoFramework Firmware Flasher tool use the following .NET Core CLI command:
dotnet tool update -g nanoff
If the tool was installed at a specific path, use the following .NET Core CLI command instead:
dotnet tool update nanoff --tool-path c:\path-where-the-tool-was-installed
Usage
Once the tool is installed, you can call it by using its command nanoff
, which is a short version of the name to ease typing.
nanoff [command] [args]
The tool includes help for all available commands. You can see a list of all available ones by entering:
nanoff --help
List of usage examples per platform and common options:
Note that it's possible to combine multiple options if those operations are supported by the platforms, e.g. update the CLR and deploy a managed application in the same execution.
ESP32 usage examples
There are multiple ESP32 images available, some are build specifically for a target. Please check out the list. You will need as well to know the COM port used by your device. Find how to do this here. Alternatively, you can as well list the available COM ports. If you list them first without the device to flash and then plugging the device, the additional port which will show up is the one for the device to flash. This method works for all OS:
nanoff --listports
The ESP32_PSRAM_REV0 image will just work for any variant of the ESP32 series, with or without PSRAM, and for all silicon revisions. You can read more about the differences between the various images here.
The FEATHER_S2 image will just work for pretty much all variants of the ESP32-S2 series that expose the embedded USB CDC pins. You can read more about the differences between the various images here.
When using nanoff
you can add --target MY_TARGET_NAME_HERE
to use a specific image. If, instead, you just specify the platform with --platform esp32
nanoff
will choose the most appropriate image depending on the features of the device that's connected. Output similar to this one will show to advise what's the image about to be used:
No target name was provided! Using 'ESP32_REV0' based on the device characteristics.
Note: Please note that for ESP32-S2 targets is not possible to safely determine what's the best image to use. For this reason it's mandatory providing the appropriate target name with
--target MY_TARGET_NAME_HERE
.
Some ESP32 boards have issues entering bootloader mode. This can be usually overcome by holding down the BOOT/FLASH button in the board.
In case nanoff
detects this situation the following warning is shown:
*** Hold down the BOOT/FLASH button in ESP32 board ***
⚠️ To update FeatherS2, TinyS2 and some S3 modules, the board needs to be put in download mode by holding [BOOT], clicking [RESET] and then releasing [BOOT].
Update the firmware of an ESP32 target
To update the firmware of an ESP32 target connected to COM31, to the latest available development version.
nanoff --update --target ESP32_PSRAM_REV0 --serialport COM31
Update the firmware of an ESP32-S2 KALUGA 1 with a local CLR file
To update the firmware of an ESP32-S2 KALUGA 1 target connected to COM31 with a local CLR file (for example from a build). This file has to be a binary file with a valid CLR from a build. No other checks or validations are performed on the file content.
nanoff --update --target KALUGA_1 --serialport COM31 --clrfile "C:\nf-interpreter\build\nanoCLR.bin"
You can adjust the name of the core image you want to use. Refer to the previous section to get the full list.
Show details of the connected ESP32 device
To show the details of the ESP32 device connected to COM31.
nanoff --platform esp32 --serialport COM31 --devicedetails
Optionally an extra parameter --checkpsram
can be passed, which forces the detection of PSRAM availability.
Deploy a managed application to an ESP32 target
To deploy a managed application to an ESP32_PSRAM_REV0 target connected to COM31.
Note: The binary file with the deployment image can be found on the Release or Debug folder of a Visual Studio project after a successful build. This file contains everything that's required to deploy a managed application to a target (meaning application executable and all referenced libraries and assemblies).
nanoff --target ESP32_PSRAM_REV0 --serialport COM12 --deploy --image "E:\GitHub\nf-Samples\samples\Blinky\Blinky\bin\Debug\Blinky.bin"
Update the firmware of an ESP32 target along with a managed application
To deploy an application on an ESP32 target connected to COM31, with your application, you have to specify the path to the managed application. Optionally you can provide an address which will override the default deployment address. This example uses the binary format file that you can find when you are building an application. Note, as only application can run, when you are building a library, a bin file is not created automatically. Only for applications.
nanoff --target ESP32_PSRAM_REV0 --update --serialport COM31 --deploy --image "c:\eps32-backups\my_awesome_app.bin" --address 0x1B000
STM32 usage examples
Update the firmware of a specific STM32 target
To update the firmware of the ST_STM32F769I_DISCOVERY target to the latest available stable version using the JTAG connection.
nanoff --update --target ST_STM32F769I_DISCOVERY --jtag
Deploy a managed application to a ST_STM32F769I_DISCOVERY target
To deploy a managed application to a ST_STM32F769I_DISCOVERY target, which has the deployment region at 0x08080000 flash address and reset the MCU after flashing it.
Note: The binary file with the deployment image can be found on the Release or Debug folder of a Visual Studio project after a successful build. This file contains everything that's required to deploy a managed application to a target (meaning application executable and all referenced libraries and assemblies).
nanoff --target ST_STM32F769I_DISCOVERY --deploy --image "E:\GitHub\nf-Samples\samples\Blinky\Blinky\bin\Debug\Blinky.bin" --address 0x08040000 --reset
Update the firmware of a ST_STM32F769I_DISCOVERY along with a managed application
To update the firmware of the ST_STM32F769I_DISCOVERY target to the latest available version, using a JTAG connection, along with a managed application. You have to specify the path to the managed application. This example uses the binary format file that is generated by Visual Studio when building any nanoFramework C# application. Because it's a binary file you have to specify too the flash address of the deployment region (here 0x08000000, mind the hexadecimal format).
nanoff --update --target ST_STM32F769I_DISCOVERY --jtag --binfile "c:\dev\my awesome app\bin\debug\my_awesome_app.bin" --address 0x08000000
List all STM32 devices available with JTAG connection
This useful to list all STM32 devices that are connected through JTAG.
nanoff --listjtag
List all STM32 devices available with DFU connection
This useful to list all STM32 devices that are connected through DFU.
nanoff --listdfu
Install STM32 JTAG drivers
To install the drivers for STM32 JTAG connected targets.
nanoff --installjtagdrivers
Install STM32 DFU drivers
To install the drivers for STM32 DFU connected targets.
nanoff --installdfudrivers
TI CC13x2 usage examples
Update the firmware of a specific TI CC13x2 target
To update the firmware of the TI_CC1352R1_LAUNCHXL target to the latest version.
nanoff --update --target TI_CC1352R1_LAUNCHXL
Install the XDS110 USB drivers required by TI LaunchPad targets
To install the XDS110 USB drivers.
nanoff --installxdsdrivers
Silabs Giant Gecko usage examples
Update the firmware of a specific Silabs target
To update the firmware of the SL_STK3701A target to the latest version.
nanoff --update --target SL_STK3701A
Update the firmware of a Silabs target from a local file
To update the firmware of a Silabs target with a local firmware file (for example from a build). This file has to be a binary file with a valid Booter and CLR from a build. No checks or validations are performed on the file(s) content.
nanoff --update --platform gg11 --binfile "C:\nf-interpreter\build\nanobooter-nanoclr.bin" --address 0x0
Deploy a managed application to a SL_STK3701A target
To deploy a managed application to a SL_STK3701A target, which has the deployment region at 0x000EE000 flash address and reset the MCU after flashing it.
Note: The binary file with the deployment image can be found on the Release or Debug folder of a Visual Studio project after a successful build. This file contains everything that's required to deploy a managed application to a target (meaning application executable and all referenced libraries and assemblies).
nanoff --target SL_STK3701A --deploy --image "E:\GitHub\nf-Samples\samples\Blinky\Blinky\bin\Debug\Blinky.bin" --address 0x000EE000
Update the firmware of a SL_STK3701A along with a managed application
To update the firmware of the SL_STK3701A target to the latest available version, using a J-Link connection, along with a managed application. You have to specify the path to the managed application. This example uses the binary format file that is generated by Visual Studio when building any nanoFramework C# application. Because it's a binary file you have to specify too the flash address of the deployment region (here 0x000EE000, mind the hexadecimal format).
nanoff --update --target SL_STK3701A --binfile "c:\dev\my awesome app\bin\debug\my_awesome_app.bin" --address 0x000EE000
List all Silabs devices available with J-Link connection
This useful to list all Silabs devices that are connected through J-Link.
nanoff --listjlink
Plain connection usage examples
It's possible to update a nano device using the same connection that is used for Visual Studio connection, meaning that no specialized connection is required (like JTAG, or JLink). This is only possible if the device has previously been flashed with a working nanoFramework firmware.
Update the CLR of a nano device
To update the CLR of a nano device connected to a serial port to the latest available version. This will find the latest available firmware for the connected device and will update the CLR.
nanoff --nanodevice --update --serialport COM9
Deploy a managed application
To deploy (or update) a managed application, the path to the managed application has to be provided. This example uses the binary format file that is generated by Visual Studio when building any nanoFramework C# application. Because it's possible to retrieve all the required details from the connected device no other configuration is required.
nanoff --nanodevice --deploy --serialport COM9 --image "c:\dev\my awesome app\bin\debug\my_awesome_app.bin"
Update the CLR of a nano device from a local file
To update the firmware of a nano device with a local firmware file (for example from a build). This file has to be a binary file with a valid nanoCLR from a build. No checks or validations are performed on the file content.
nanoff --nanodevice --update --serialport COM9 --clrfile "C:\nf-interpreter\build\nanoclr.bin"
Get details from a nano device
To get the details of a nano device connected to a serial port.
nanoff --nanodevice --devicedetails --serialport COM9
Common options
Pre-check if target fits connected device
The tool tries to make a best effort sanity check on whether the requested target fits the connected target. Sometimes that's not possible because of the differences and variations on the target names, or lack of details provided by the connected device or even (like with DFU connected devices) because it's not possible to determine exactly what device is connected at all. This doesn't necessarily mean that the firmware wont' work, so take this as an advice only.
To disable this validation add --nofitcheck
option to the command line.
Tool output verbosity
The tool output verbosity can be set through the v|verbosity
option.
This is convenient, for example, if this tool is being used in a automated process where the minimum output is desired to ease processing the return result of the execution. It can be set to:
- q[uiet]
- m[inimal]
- n[ormal]
- d[etailed]
- diag[nostic]
nanoff -v q
List connected nano devices
To get a list of connected nano devices. If more details are required add verbose
option with setting above normal.
nanoff --listdevices [ -v d ]
Output example:
-- Connected .NET nanoFramework devices --
SKY_EEVB_Debug @ COM7
------------------------------------------
Output example with verbose details:
-- 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
------------------------------------------
Finding the device COM port on Windows
You need to know the COM Port attached to your device. Search for Computer Management, select Device Manager then expand Ports (COM & LPT), you will find the COM port of the connected device.
IMPORTANT: you may have to install drivers. Refer to the vendor website or use Windows Update to install the latest version of the drivers.
Finding the device COM port using nanoff
You can use the --listports command with nanoff to list the available COM ports. This method works on all OS. If you run the command first without your device plugged, you'll get a first list. Then plug your device and run the command again. The new COM port showing up is the one from your device!
nanoff --listports
Example of outcomes when there is no device plugged in:
No available COM port
And when you then plug the device and run the command again:
Available COM ports:
COM12
List targets
You can list the supported targets, and their version using the --platform
parameter.
List packages available for ESP32 targets:
nanoff --listtargets --platform esp32
List packages available for STM32 targets:
nanoff --listtargets --platform stm32
If you use the --listtargets
switch in conjunction with --preview
, you'll get the list of available firmware packages that are available with experimental or major feature changes.
Deploy file to device storage
Some devices like ESP32, Orgpal and few others have storage available. Files can be deployed in this storage. You have to use the filedeployment
parameter pointing on a JSON file to deploy files while flashing the device:
nanoff --target XIAO_ESP32C3 --update --masserase --serialport COM21 --filedeployment C:\path\deploy.json
The JSON an optional SerialPort
in case the port to upload the files must be different than the one to flash the device or not specified in the main command line and a mandatory list of Files
entries. Each entry must contains DestinationFilePath
, the destination full path file name and SourceFilePath
to deploy content, otherwise to delete the file, the full path with file name of the source file to be deployed:
{
"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"
}
]
}
In the case you just want to deploy the files without any other operation, you can just specify:
nanoff --filedeployment C:\path\deploy.json
In that case, the SerialPort
must be present in the JSON file.
[!Note] If a file already exists in the storage, it will be replaced by the new one.
If a file does not exist and is requested to be deleted, nothing will happen, a warning will be displayed.
If a file can't be uploaded because of a problem, the deployment of the other files will continue and an error will be displayed.
Clear cache location
If needed one can clear the local cache from the firmware packages that are stored there.
As an additional information the cache location is the directory -nanoFramework\fw_cache
in the user folder.
When this option is included in the command no other options are processed.
nanoff --clearcache
Exit codes
The exit codes can be checked in this source file.
Telemetry
This tool is using anonymous telemetry to help us improve the usage. You can opt out by setting up an environment variable NANOFRAMEWORK_TELEMETRY_OPTOUT
to 1.
The telemetry information is mainly related to the command line arguments, the firmware versions installed and any issue that can occurs during the code execution.
Feedback and documentation
To provide feedback, report issues and finding out how to contribute please refer to the Home repo.
Join our Discord community here.
Credits
The list of contributors to this project can be found at CONTRIBUTORS.
License
The nanoFramework firmware flasher tool is licensed under the MIT license.
Code of Conduct
This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behaviour in our community. For more information see the .NET Foundation Code of Conduct.
.NET Foundation
This project is supported by the .NET Foundation.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
This package has no dependencies.
Version | Downloads | Last updated |
---|---|---|
2.5.99 | 6,538 | 10/10/2024 |
2.5.98 | 855 | 10/9/2024 |
2.5.97 | 396 | 10/9/2024 |
2.5.96 | 2,480 | 9/30/2024 |
2.5.95 | 1,303 | 9/26/2024 |
2.5.94 | 544 | 9/25/2024 |
2.5.90 | 9,631 | 6/26/2024 |
2.5.89 | 608 | 6/24/2024 |
2.5.86 | 1,149 | 6/18/2024 |
2.5.83 | 970 | 6/14/2024 |
2.5.78 | 1,235 | 6/4/2024 |
2.5.77 | 984 | 5/31/2024 |
2.5.74 | 873 | 5/29/2024 |
2.5.73 | 709 | 5/28/2024 |
2.5.67 | 3,697 | 4/28/2024 |
2.5.66 | 806 | 4/26/2024 |
2.5.61 | 4,695 | 4/1/2024 |
2.5.60 | 2,023 | 3/25/2024 |
2.5.59 | 1,934 | 3/21/2024 |
2.5.58 | 6,012 | 1/31/2024 |
2.5.56 | 2,995 | 1/4/2024 |
2.5.54 | 1,562 | 1/2/2024 |
2.5.52 | 2,494 | 12/22/2023 |
2.5.49 | 1,228 | 12/21/2023 |
2.5.46 | 7,948 | 10/27/2023 |
2.5.45 | 1,294 | 10/24/2023 |
2.5.44 | 1,520 | 10/19/2023 |
2.5.43 | 658 | 10/19/2023 |
2.5.38 | 2,979 | 10/9/2023 |
2.5.36 | 7,115 | 8/23/2023 |
2.5.34 | 5,581 | 7/14/2023 |
2.5.33 | 730 | 7/14/2023 |
2.5.32 | 942 | 7/14/2023 |
2.5.28 | 2,729 | 6/28/2023 |
2.5.25 | 877 | 6/27/2023 |
2.5.24 | 1,519 | 6/19/2023 |
2.5.21 | 904 | 6/14/2023 |
2.5.10 | 1,130 | 5/31/2023 |
2.5.3 | 856 | 5/29/2023 |
2.5.2 | 1,146 | 5/12/2023 |
2.5.1 | 2,810 | 4/27/2023 |
2.4.36 | 902 | 4/27/2023 |
2.4.35 | 878 | 4/27/2023 |
2.4.34 | 902 | 4/26/2023 |
2.4.33 | 2,324 | 4/17/2023 |
2.4.31 | 4,931 | 3/15/2023 |
2.4.30 | 3,893 | 2/22/2023 |
2.4.28 | 1,926 | 2/17/2023 |
2.4.24 | 3,119 | 12/19/2022 |
2.4.22 | 1,371 | 12/17/2022 |
2.4.19 | 1,302 | 12/16/2022 |
2.4.14 | 1,227 | 12/13/2022 |
2.4.2 | 1,900 | 11/16/2022 |
2.4.1 | 1,420 | 11/16/2022 |
2.3.12 | 1,653 | 11/9/2022 |
2.3.9 | 2,295 | 9/7/2022 |
2.3.7 | 1,344 | 9/5/2022 |
2.3.4 | 2,926 | 8/25/2022 |
2.3.1 | 1,500 | 8/24/2022 |
2.2.5 | 1,759 | 8/22/2022 |
2.2.2 | 1,370 | 8/22/2022 |
2.2.1 | 1,221 | 8/22/2022 |
2.1.16 | 1,956 | 8/19/2022 |
2.1.15 | 1,198 | 8/19/2022 |
2.1.14 | 1,287 | 8/19/2022 |
2.1.11 | 1,422 | 8/18/2022 |
2.1.7 | 4,832 | 7/14/2022 |
2.1.6 | 1,867 | 7/14/2022 |
2.1.5 | 1,787 | 7/13/2022 |
2.1.2 | 2,478 | 7/6/2022 |
2.0.67 | 2,863 | 6/14/2022 |
2.0.66 | 2,171 | 6/9/2022 |
2.0.65 | 2,350 | 6/1/2022 |
2.0.62 | 3,214 | 5/19/2022 |
2.0.60 | 1,757 | 5/17/2022 |
2.0.58 | 3,632 | 4/27/2022 |
2.0.57 | 2,306 | 4/21/2022 |
2.0.56 | 1,771 | 4/20/2022 |
2.0.55 | 1,996 | 4/18/2022 |
2.0.51 | 2,873 | 4/18/2022 |
2.0.47 | 2,604 | 4/18/2022 |
2.0.44 | 2,600 | 4/14/2022 |
2.0.41 | 3,125 | 3/31/2022 |
2.0.39 | 2,550 | 3/31/2022 |
2.0.34 | 2,852 | 3/8/2022 |
2.0.30 | 2,542 | 2/23/2022 |
2.0.28 | 2,526 | 2/18/2022 |
2.0.26 | 2,460 | 2/18/2022 |
2.0.25 | 2,677 | 2/18/2022 |
2.0.15 | 2,552 | 2/10/2022 |
2.0.9 | 2,464 | 12/27/2021 |
2.0.7 | 1,614 | 12/23/2021 |
2.0.6 | 1,595 | 12/22/2021 |
2.0.5 | 1,481 | 12/17/2021 |
2.0.3 | 1,473 | 12/16/2021 |
1.29.8 | 1,598 | 11/29/2021 |
1.29.5 | 3,311 | 11/26/2021 |
1.29.1 | 1,428 | 11/17/2021 |
1.28.2 | 2,036 | 11/4/2021 |
1.28.1 | 1,518 | 10/28/2021 |
1.27.1 | 1,742 | 10/15/2021 |
1.26.5 | 1,320 | 10/14/2021 |
1.26.4 | 1,604 | 10/7/2021 |
1.26.3 | 2,659 | 10/6/2021 |
1.26.1 | 2,392 | 10/5/2021 |
1.25.4 | 2,614 | 10/5/2021 |
1.25.1 | 1,427 | 8/25/2021 |
1.24.7 | 1,131 | 8/25/2021 |
1.24.6 | 1,220 | 8/25/2021 |
1.24.2 | 1,141 | 8/24/2021 |
1.24.1 | 1,151 | 8/17/2021 |
1.23.3 | 1,153 | 8/16/2021 |
1.23.1 | 1,206 | 8/16/2021 |
1.22.9 | 1,243 | 8/9/2021 |
1.22.7 | 1,320 | 7/21/2021 |
1.22.6 | 1,332 | 7/17/2021 |
1.22.5 | 1,397 | 6/29/2021 |
1.22.4 | 1,135 | 6/25/2021 |
1.22.2 | 1,141 | 6/24/2021 |
1.22.1 | 1,187 | 6/23/2021 |
1.22.0 | 1,230 | 6/23/2021 |
1.20.1 | 777 | 6/22/2021 |
1.20.0-preview.13 | 281 | 6/18/2021 |
1.20.0-preview.12 | 283 | 6/17/2021 |
1.20.0-preview.8 | 321 | 5/10/2021 |
1.19.0 | 1,167 | 3/31/2021 |
1.19.0-preview.1 | 329 | 3/24/2021 |
1.17.0-preview.6 | 286 | 3/19/2021 |
1.16.2 | 856 | 3/15/2021 |
1.16.1-preview.1 | 414 | 12/3/2020 |
1.16.0-preview.3 | 437 | 7/13/2020 |
1.15.0 | 1,606 | 7/13/2020 |
1.14.0 | 1,090 | 7/2/2020 |
1.14.0-preview.9 | 513 | 7/2/2020 |