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.

nanoff install flash

Install path issues

[!CAUTION] 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:

ESP32
STM32
TI CC13x2
Silabs Giant Gecko
Plain connection usage examples
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 ***

[!WARNING] 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

Skip backing up configuration partition

To skip backing up the configuration partition when updating the firmware of an ESP32 target connected to COM31.

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

NanoFirmwareFlasher

Install / Use

README