Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:UF2

From ReverseEngineering.wiki
Format
On this wiki Facts · Code · Notes · Topics

Microsoft's USB Flashing Format: a file of 512-byte blocks (magic 0x0A324655 / 0x9E5D5157, end magic 0x0AB16F30) each carrying up to 476 bytes of payload and a target flash address, used by drag-and-drop bootloaders of RP2040, SAMD, nRF52, ESP32 and others; a family id says which chip.

Overview

A .uf2 file is a sequence of independent 512-byte blocks, all little endian, so a bootloader exposing a USB mass-storage disk can write each block as it arrives, in any order. To recover a raw image, concatenate payloads at their target addresses.

Block layout

See the struct fact on this page: 32-byte header (magicStart0 0x0A324655 which is the text "UF2\n", magicStart1 0x9E5D5157, flags, targetAddr, payloadSize, blockNo, numBlocks, and a final 32-bit word that is the family id when flag 0x2000 is set, or fileSize when flag 0x1000 is set), 476 bytes of data, and magicEnd 0x0AB16F30. Payloads are typically 256 bytes.

Flags

0x1 not-main-flash (comment block, do not flash), 0x1000 file container, 0x2000 familyID present, 0x4000 MD5 checksum present (last 24 bytes of the data area: start address, length, MD5; used by ESP32), 0x8000 extension tags present, placed right after the payload (tags: 0x9fc7bc firmware version semver, 0x650d9d device description, 0x0be9f7 page size, 0xb46db0 SHA-2 of firmware, 0xc8a729 device type id).

Family ids

The repository publishes utils/uf2families.json (78 entries at the pinned commit): 0xe48bff56 RP2040, 0x1c5f21b0 ESP32, 0xbfdd4eee ESP32-S2, 0xc47e5767 ESP32-S3, 0xd42ba06c ESP32-C3, 0x68ed2b88 SAMD21, 0x55114460 SAMD51, 0xada52840 nRF52840, 0x57755a57 STM32F4, 0x5ee21072 STM32F1, 0x6db66082 STM32H7 and more. See the enum fact.

Related

UF2 images contain Cortex-M images for several families: Platform:ARM Cortex-M; ESP32 payloads are Format:ESP32 application image. esptool can write UF2 (uf2_writer.py).

Code & repositories

  • https://github.com/microsoft/uf2 @ 90e9741f217f5a40c98ba74d663e408041037578 · license: MIT (read from LICENSE.txt; GitHub's detector did not classify it)
    UF2 specification, uf2.h and the family id list (utils/uf2families.json).
    Tested on: source read, not run: read · checked 2026-10-18; last activity 2026-09-23
  • https://github.com/espressif/esptool @ af1ed10290e6328416cf8c73076bba15b459cbb2 · license: GPL-2.0
    esptool: image parsing and writing (bin_image.py), chip ids, app descriptor parser, UF2 writer.
    Tested on: source read, not run: read · checked 2026-10-18; last activity 2026-10-15; Note: the latest release ships binaries; the wiki links only the source, never the binaries