UF2 Image and Bootloader

RE: UF2 Image and Bootloader

Apofis — Thu, 05 Feb 2026 00:47:55 GMT

Hi,

Did the settings above solved your problems? If so, could you precise which type of build configuration do you use (board/variant/sys_build)? Did you updated the Bootloader?

RE: UF2 Image and Bootloader

Garag — Sat, 27 Sep 2025 11:03:28 GMT

Hi,

thank you for your detailed description. I had problems with a Pro Micro nrf52840 board. For my board i have to use the following settings in the prj.conf file:

CONFIG_BUILD_OUTPUT_UF2=y
CONFIG_FLASH_LOAD_OFFSET=0x1000

Maybe you can try CONFIG_FLASH_LOAD_OFFSET instead of CONFIG_ROM_START_OFFSET.

RE: UF2 Image and Bootloader

douglas.malnati — Mon, 06 Mar 2023 18:04:35 GMT

Ok I have worked out how to do it, and will update this thread with more detailed answers for the sake of the community.

If you want to be able to upload zephyr firmware as a UF2 file to a USB drive, using the Adafruit bootloader, do this.

I'm using WSL2 (linux) and a jlink programmer so those are the instructions I'll provide. I'm using the feather nrf52840 so I'll use that also, but the bootloader supports lots of boards.

1. Get the Adafruit bootloader

$ git clone https://github.com/adafruit/Adafruit_nRF52_Bootloader
$ cd Adafruit_nRF52_Bootloader

2. Build and flash the bootloader

$ make BOARD=feather_nrf52840_express flash
Flashing: feather_nrf52840_express_bootloader-0.6.4-dirty_nosd.hex
nrfjprog --program _build/build-feather_nrf52840_express/feather_nrf52840_express_bootloader-0.6.4-dirty_nosd.hex --sectoranduicrerase -f nrf52 --reset
Parsing image file.
WARNING: A programming operation has been performed without --verify.
WARNING: Programming can fail without error.
Applying system reset.
Run.

You should see a new USB flash drive appear in explorer

3. Change your prj.conf to include UF2 output and a rom start offset of 0x1000, corresponding to the Adafruit bootloader expectations.

CONFIG_BUILD_OUTPUT_UF2=y
CONFIG_ROM_START_OFFSET=0x1000

4. Build pristine. Notice a UF2 file is output. The flash output file size is also 4k smaller than before (accounting for the lost space due to the offset).

[276/276] Linking CXX executable zephyr/zephyr.elf
Memory region         Used Size  Region Size  %age Used
           FLASH:      493704 B         1 MB     47.08%
            SRAM:      123736 B       256 KB     47.20%
        IDT_LIST:          0 GB         2 KB      0.00%
Converting to uf2, output size: 987648, start address: 0x0
Wrote 987648 bytes to zephyr.uf2

5. Open explorer to the build output files of your application, which is <appname>/build/zephyr, and look for the zephyr.uf2 file.

6. Drag/drop the zephyr.uf2 file onto the flash drive that appeared before. It may take a moment of copying, but then the flash drive will vanish and your code will begin to run as normal.

7. Double-click the reset button to get back into the USB drive for drag/drop upgrade.

Note - I've found that with the CONFIG_ROM_START_OFFSET parameter set, I can no longer "flash" directly from VSCode. It kind of just bricks the device. Commenting out that parameter during rapid code/flash/test iterations is probably the way to go. I'll put the bootloader on there when I'm done.

RE: UF2 Image and Bootloader

douglas.malnati — Mon, 06 Mar 2023 16:34:35 GMT

Specifically, it looks like these params were introduced in 2021

https://github.com/zephyrproject-rtos/zephyr/pull/31066

It's Zephr parameters, right?

RE: UF2 Image and Bootloader

douglas.malnati — Mon, 06 Mar 2023 16:22:51 GMT

Hi, I don't really understand, Adafruit didn't introduce those prj.conf parameters, those are part of Zephyr. Why don't you know what they do?

I can't ask Adafruit, they have told me already they don't provide support.

But again, these are Zephyr (and therefore Nordic) parameters. How am I supposed to understand how they work if you don't know?

RE: UF2 Image and Bootloader

Sigurd Hellesvik — Mon, 06 Mar 2023 11:32:16 GMT

Hi,

The bootloaders we officially support for nRF Connect SDK is listed at Bootloaders and Device Firmware Updates.

UF2 is not one of those, so the support I can give for this will be limited. For better support, I suggest that you contact Adafruit support.

From my general bootloader knowledge:

An application does not need to know about the bootloader. The bootloader will begin at address 0x0 and then point to where the application starts from.
For other similar cases, it has been enough to build the application with CONFIG_FLASH_LOAD_OFFSET. The bootloader should be configured to point to an address for an application. Make sure the flash offset is the same as this one.

Using CONFIG_FLASH_LOAD_OFFSET is only relevant if you build the bootloader separately from the application.
So I guess that if you use CONFIG_BUILD_OUTPUT_UF2, the offset might be handled automatically.

[quote user=""]CONFIG_BOOTLOADER_MCUBOOT[/quote]

It should be "no". If you do not need MCUboot, do not use MCUboot.

[quote user=""]CONFIG_ROM_START_OFFSET[/quote]

I have not heard about this before. So I would guess that you do not need it.

[quote user=""]

CONFIG_BUILD_OUTPUT_UF2 - allows automatic building of a zephyr.uf2 file in the build directory. I enabled this, should I? I do see zephyr.uf2 produced as part of the build.

CONFIG_BOOTLOADER_BOSSA - Select the Adafruit UF2 variant of the BOSSA bootloader - not sure what this does. Should I set this?

CONFIG_BOOTLOADER_BOSSA_ADAFRUIT_UF2 - "Select the Adafruit UF2 variant of the BOSSA bootloader" Not really sure what this does. Should I set this?

CONFIG_BUILD_OUTPUT_UF2_FAMILY_ID - "UF2 bootloaders only accept UF2 files with a matching family ID" For the nRF52840, I believe the right value is "0xADA52840". I think I should set this.

[/quote]

I do not know about UF2-specific configurations. Ask Adafruit about those.

Regards,
Sigurd Hellesvik