tools/elf2uf2: addition of new PROGRAMMER for RPi-pico

[krzysztof-cabaj]

Contribution description

Currently, RPi-pico (at least RP2-B1 series) cannot be successfully flashed using uf2conv programmer.

Suggested in the online documentation for RPi-pico board command:

make BOARD=rpi-pico PROGRAMMER=uf2conv flash

... did not work. The program is compiled and copied to the UF2 removable media (flash disk), but the board is not programmed. More details are described in the Issue #15822.

This PR adds new PROGRAMMER elf2uf2, which allows flashing RPi-pico boards using UF2 removable media (flash disk). Provided changes add conversion tool from elf file to UF2 format (using elf2uf2 tool from pico-SDK) as well as needed changes to makefiles and addition of new ones if required.

Testing procedure

• press BOOTSEL button on RPi-pico board,
• connect RPi-pico to USB port, and wait for UF2 removable flash,
• go to examples/blinky directory,
• use command:

UPDATE !!!
Because elf2uf2 PROGRAMMER due to problems with uf2conv was moved as default programmer, option PROGRAMMER=elf2uf2 is not needed.

make BOARD=rpi-pico flash

• The board should be programmed, automatically reset, and the LED on the RPi-pico board should blink.

Issues/PRs references

Issue #15822.

[maribu]

Works like a charm. Care to apply the following changes?

diff --git a/dist/tools/elf2uf2/elf2uf2.sh b/dist/tools/elf2uf2/elf2uf2.sh
index 1aa53692e0..874dcf0043 100755
--- a/dist/tools/elf2uf2/elf2uf2.sh
+++ b/dist/tools/elf2uf2/elf2uf2.sh
@@ -1,8 +1,11 @@
 #!/bin/sh
 
-# $1 contains $(RIOTTOOLS) from makefile
-# $2 contains generated elf file - $FLASHFILE from makefile
+# $1 contains generated elf file - $FLASHFILE from makefile
 
-"$1/elf2uf2/elf2uf2" "$2" NEW.UF2
+ELFFILE="$1"
+U2FFILE="${U2FFILE:-${ELFFILE%%.elf}.u2f}"
+ELF2UF2_MOUNT_PATH="${ELF2UF2_MOUNT_PATH:-/media/$USER/RPI-RP2}"
 
-mv NEW.UF2 "/media/$USER/RPI-RP2/"
+"$(dirname "$0")"/elf2uf2 "$ELFFILE" "$U2FFILE"
+
+cp "$U2FFILE" "$ELF2UF2_MOUNT_PATH"
diff --git a/makefiles/tools/elf2uf2.inc.mk b/makefiles/tools/elf2uf2.inc.mk
index 72311e8078..085ee8ff40 100644
--- a/makefiles/tools/elf2uf2.inc.mk
+++ b/makefiles/tools/elf2uf2.inc.mk
@@ -1,9 +1,8 @@
-
 FLASHER ?= $(RIOTTOOLS)/elf2uf2/elf2uf2.sh
 
 FLASHFILE ?= $(ELFFILE)
 
-FFLAGS ?= $(RIOTTOOLS) $(FLASHFILE)
+FFLAGS ?= $(FLASHFILE)
 
 #yes elf2uf2 not elf2uf2.sh
 #the first should be downloaded from git and build

I contains the following changes:

1. The script determines the path to elf2uf2 automatically, so the path to $(RIOTTOOLS) doesn't need to be provided as argument. This makes it easier to use the script as standalone tool
2. The path to the mounted drive can be overwritten by an environment variable. This makes it easier to adapt the flashing to work stations with different setups
3. The uf2 file is placed next to the elf file by default (again, path can be overwritten by environment variable). If the flashing fails, right now a NEW.uf2 file is left in the application folder. With that, it is placed in bin/<board>/<appname>.uf2 by default, so that it gets cleaned up automatically with make clean even when flashing fails.

[krzysztof-cabaj]

Remarks updated in the code (two small fixes: u2f -> to uf2 in file extension and in variable name U2FFILE -> UF2FILE), squshed and commited ... of course before tested on real hardware :D .

[maribu]

Looks good to me. Would you mind to update the documentation? E.g. something along the lines of this:

diff --git a/boards/rpi-pico/doc.txt b/boards/rpi-pico/doc.txt
index 956f592d06..9e966671a2 100644
--- a/boards/rpi-pico/doc.txt
+++ b/boards/rpi-pico/doc.txt
@@ -59,6 +59,22 @@ supported.
 
 ## Flashing the Board
 
+### Flashing the Board Using the Bootloader
+
+Connect the device to your Micro-USB cable while the button (labeled `BOOTSEL`
+on the silkscreen of the PCB) is pressed to enter the bootloader. The pico
+will present itself as a storage medium to the system, to which a UF2 file
+can be copied perform the flashing of the device. This can be automated by
+running:
+
+```
+make BOARD=rpi-pico flash
+```
+
+If the storage is not automatically mounted to `/media/<USER_NAME>/RPI-RP2`,
+you can overwrite the path by exporting the shell environment variable
+`ELF2UF2_MOUNT_PATH`.
+
 ### Flashing the Board Using OpenOCD
 
 Currently (June 2021), only two methods for debugging via OpenOCD are supported:
@@ -76,7 +92,7 @@ formatted drive the bootloader provides. Once this drive is unmounted again, thi
 the Raspberry Pi Pico showing up as CMSIS-DAP debugger. Afterwards run:
 
 ```
-make BOARD=rpi-pico flash
+make BOARD=rpi-pico PROGRAMMER=openocd flash
 ```
 
 @warning    The `rpi-pico` virtual debugger is not persistent and needs to be "flashed" into RAM
@@ -87,15 +103,6 @@ make BOARD=rpi-pico flash
             The OpenOCD fork of the Raspberry Pi foundation is incompatible with OpenOCD
             configuration provided, so please stick with upstream OpenOCD.
 
-### Flashing the Board Using the Bootloader
-
-Connect the device to your Micro-USB cable while the button (labeled `BOOTSEL` on the silkscreen
-of the PCB) is pressed to enter the bootloader. Afterwards run:
-
-```
-make BOARD=rpi-pico PROGRAMMER=uf2conv flash
-```
-
 ### Flashing the Board Using J-Link
 
 Connect the Board to an Segger J-Link debugger, e.g. the EDU mini debugger is relatively affordable,

[krzysztof-cabaj]

Documentation updated accordingly to the remarks.

I added two changes:

• Move elf2uf2 flashing option to the top - as this currently is default method,
• Minor changes in openocd flashing - which now is not default flashing method.

[maribu]

Thanks for fixing the flashing of the rpi pico!

[krzysztof-cabaj]

No problem.