Serve the OTAFIX bootloader factory-erase image

data/maintenanceUf2.json

@@ -15,6 +15,11 @@
         "expectedFirstTargetAddress": 159744
       }
     },
+    "nrf52Bootloader": {
+      "fileName": "meshtastic_factory_erase.uf2",
+      "sha256": "6ef3146505c40079ee9e7e692448e40a793dad636f55d1545063299d28908f0d",
+      "expectedFamilyId": 1296388936
+    },
     "rp2040": {
       "fileName": "pico_erase.uf2",
       "sha256": "08aa7d561e8b8bf2f9b061b3506fb4d8f135e832efe0f3ae978241db2da0c853"

scripts/validate-maintenance-uf2.ts

@@ -22,6 +22,7 @@ interface EraseImageEntry {
   fileName: string;
   sha256: string;
   expectedFirstTargetAddress?: number;
+  expectedFamilyId?: number;
 }
 
 const manifest = JSON.parse(readFileSync(DATA_PATH, "utf8")) as {
@@ -30,6 +31,7 @@ const manifest = JSON.parse(readFileSync(DATA_PATH, "utf8")) as {
   otafixBase: string;
   erase: {
     nrf52: Record<string, EraseImageEntry>;
+    nrf52Bootloader?: EraseImageEntry;
     rp2040: EraseImageEntry;
   };
   otafixByBoardId: Record<string, { otafixBoardSlug: string; sha256: string }>;
@@ -56,6 +58,52 @@ const checkSha256 = (sha256: string, where: string) => {
   }
 };
 
+// --- bootloader-consumed erase image: one UF2 block whose family ID is the whole contract ---
+// The OTAFIX bootloader acts on this file by family ID alone (targetAddr is 0, so the clients'
+// first-target-address check does not apply); a wrong family here would make every device treat
+// it as an ordinary firmware block. Check the header the way the bootloader reads it.
+const UF2_BLOCK_SIZE = 512;
+const UF2_MAGIC0 = 0x0a324655;
+const UF2_MAGIC1 = 0x9e5d5157;
+const UF2_MAGIC_END = 0x0ab16f30;
+const UF2_FLAG_FAMILY_ID_PRESENT = 0x2000;
+
+const checkUf2FamilyBlock = (
+  bytes: Buffer,
+  expectedFamilyId: number,
+  where: string,
+) => {
+  if (bytes.length !== UF2_BLOCK_SIZE) {
+    fail(
+      `${where}: expected exactly one ${UF2_BLOCK_SIZE}-byte UF2 block, got ${bytes.length} bytes`,
+    );
+    return;
+  }
+  const magic0 = bytes.readUInt32LE(0);
+  const magic1 = bytes.readUInt32LE(4);
+  const flags = bytes.readUInt32LE(8);
+  const familyId = bytes.readUInt32LE(28);
+  const magicEnd = bytes.readUInt32LE(508);
+  if (magic0 !== UF2_MAGIC0 || magic1 !== UF2_MAGIC1) {
+    fail(
+      `${where}: bad UF2 start magic 0x${magic0.toString(16)}/0x${magic1.toString(16)}`,
+    );
+  }
+  if (magicEnd !== UF2_MAGIC_END) {
+    fail(`${where}: bad UF2 end magic 0x${magicEnd.toString(16)}`);
+  }
+  if ((flags & UF2_FLAG_FAMILY_ID_PRESENT) === 0) {
+    fail(
+      `${where}: UF2 flags 0x${flags.toString(16)} lack the family-ID-present bit`,
+    );
+  }
+  if (familyId !== expectedFamilyId) {
+    fail(
+      `${where}: UF2 family ID 0x${familyId.toString(16)}, manifest expects 0x${expectedFamilyId.toString(16)}`,
+    );
+  }
+};
+
 // --- erase images: fileName/sha256 shape, and the vendored bytes actually match ---
 const checkEraseEntry = (entry: EraseImageEntry, where: string) => {
   checkFileName(entry.fileName, where);
@@ -68,6 +116,9 @@ const checkEraseEntry = (entry: EraseImageEntry, where: string) => {
         `${where}: vendored ${entry.fileName} hashes to ${actual}, manifest says ${entry.sha256}`,
       );
     }
+    if (entry.expectedFamilyId !== undefined) {
+      checkUf2FamilyBlock(bytes, entry.expectedFamilyId, where);
+    }
   } catch (err) {
     fail(
       `${where}: could not read static/maintenanceUf2/${entry.fileName}: ${(err as Error).message}`,
@@ -80,6 +131,10 @@ for (const [softDevice, entry] of Object.entries(manifest.erase.nrf52)) {
   checkEraseEntry(entry, `erase.nrf52["${softDevice}"]`);
   eraseImageCount++;
 }
+if (manifest.erase.nrf52Bootloader) {
+  checkEraseEntry(manifest.erase.nrf52Bootloader, "erase.nrf52Bootloader");
+  eraseImageCount++;
+}
 checkEraseEntry(manifest.erase.rp2040, "erase.rp2040");
 eraseImageCount++;
 

src/lib/maintenanceUf2.ts

@@ -24,6 +24,9 @@ export interface EraseImageEntry {
   fileName: string;
   sha256: string;
   expectedFirstTargetAddress?: number;
+  // Set only on nrf52Bootloader: the UF2 family ID the bootloader consumes itself. Its block
+  // has targetAddr 0, so clients check this instead of expectedFirstTargetAddress.
+  expectedFamilyId?: number;
 }
 
 export interface OtafixAssetEntry {
@@ -44,6 +47,11 @@ export interface MaintenanceUf2Manifest {
     // all, so it correctly has no sub-key, unlike the old flat {s140_6_1_1, s140_7_3_0, rp2040}
     // shape that mixed a SoftDevice-variant axis with an architecture axis in one object.
     nrf52: Record<string, EraseImageEntry>; // keyed by SoftDeviceVariant.fromWire's input, e.g. "6.1.1"
+    // One board-agnostic file the OTAFIX bootloader consumes itself (UF2 family 0x4D455348,
+    // "MESH"), so it needs no SoftDevice sub-key. Clients gate it on the UF2 drive's INFO_UF2.TXT
+    // carrying a "Factory-Erase:" line naming that family; an older bootloader has no such line
+    // and silently ignores the file, so clients fall back to erase.nrf52 for it.
+    nrf52Bootloader?: EraseImageEntry;
     rp2040: EraseImageEntry;
   };
   otafixByBoardId: Record<string, OtafixAssetEntry>;

static/maintenanceUf2/ATTRIBUTION.md

@@ -5,3 +5,11 @@
 (GPL-3.0-only), vendored here rather than fetched at runtime because that repo cuts no GitHub
 releases. Digests are pinned in `../../data/maintenanceUf2.json` and re-verified by
 `scripts/validate-maintenance-uf2.ts`.
+
+`meshtastic_factory_erase.uf2` is `tools/meshtastic_factory_erase.uf2` from
+[meshtastic/Adafruit_nRF52_Bootloader_OTAFIX](https://github.com/meshtastic/Adafruit_nRF52_Bootloader_OTAFIX)
+(MIT) at commit
+[`c8ccd1d7419fda4c01c30c8a9bf144d30a424c46`](https://github.com/meshtastic/Adafruit_nRF52_Bootloader_OTAFIX/blob/c8ccd1d7419fda4c01c30c8a9bf144d30a424c46/tools/meshtastic_factory_erase.uf2),
+generated there by `tools/make_factory_erase_uf2.py` and shipped as the `meshtastic_factory_erase.uf2`
+asset of release [`0.9.2-OTAFIX2.4`](https://github.com/meshtastic/Adafruit_nRF52_Bootloader_OTAFIX/releases/tag/0.9.2-OTAFIX2.4)
+(same bytes, same digest). Same digest pinning and re-verification as above.