From bff739348e9500f317b926699f67a7971840021c Mon Sep 17 00:00:00 2001
From: mestrode <35630715+mestrode@users.noreply.github.com>
Date: Wed, 11 Mar 2026 00:05:40 +0100
Subject: [PATCH] Update README with block number handling details

Clarified handling of block numbers and total blocks in UF2 files, including rules for resetting block numbers and concatenating files with different family IDs.
---
 README.md | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 7a60bf5..5cee9b9 100644
--- a/README.md
+++ b/README.md
@@ -87,12 +87,9 @@ board family isn't listed here, pick a new family ID at random. It's good
 to also send a PR here, so your family can be listed.
 
 If the `familyID` doesn't match, the bootloader should disregard the
-entire block, including `blockNo` and `numBlocks` fields.
+entire block.
 In particular, writing a full UF2 file with non-matching `familyID`
 should not reset the board.
-This also allows for several files with different `familyID` to be
-simply concatenated together, and the whole resulting file to be copied
-to the device with only one actually being written to flash.
 
 #### Picking numbers at random
 
@@ -107,6 +104,14 @@ This procedure was unfortunately not used for the SAMD51 and NRF52840 below.
 
 The current master list of family IDs is maintained in a [JSON file](utils/uf2families.json).
 
+### BlockNo and Total Blocks
+
+`blockNo` must be sequencial and smaller then `numBlocks`.
+
+The `blockNo` is permitted to reset to `0` if also `familyId` changes. However,
+`numBlocks` must remain consistent; a new value is only permitted during the
+reset of `blockNo`.
+
 ### Rationale
 
 The magic number at the end is meant to mitigate partial block writes.
@@ -124,12 +129,16 @@ supported in future, as well as for simplicity. Little endian is used, as most
 microcontrollers are little endian. 8 bit microcontrollers can choose to just
 use the first 16 bits of various header fields.
 
-The total number of blocks in the file and the sequential block number make it
+The total number of blocks in the file (per `familyId`) and the sequential block number make it
 easy for the bootloader to detect that all blocks have been transferred. It
 requires one bit of memory per block (eg., on SAMD21G18A it's 128 bytes).
 Alternatively, the bootloader might ignore that and just implement a reset
 after say 1 second break in incoming UF2 blocks.
 
+To concatenate multiple UF2 files with varying `familyId`, the `blockNo` and
+`numBlocks` may reset. Consequently, the concatenated UF2 file can be copied
+to the device, and only one file will be actually written to the flash.
+
 ### Payload sizes
 
 The number of data bytes is configurable and depends on the size of