@microbit/microbit-connection 0.9.0-apps.alpha.8 → 1.0.0-beta.0

package/build/esm/{usb-partial-flashing.js → usb/partial-flashing.js}

@@ -37,19 +37,13 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-/**
- * Implementation of partial flashing for the micro:bit.
- *
- * Latest Microsoft implementation is here:
- * https://github.com/microsoft/pxt-microbit/blob/master/editor/flash.ts
- */
-// dapjs import faff needed for Vitest https://github.com/ARMmbed/dapjs/issues/118
-import * as dapjs from "dapjs";
-const { DAPLink: DAPLinkValue } = dapjs;
-import { withTimeout, TimeoutError } from "./async-util.js";
-import { CoreRegister, onlyChanged, pageAlignBlocks, read32FromUInt8Array, } from "./usb-partial-flashing-utils.js";
-import { ProgressStage } from "./device.js";
+import { waitFor } from "./arm-debug.js";
+import { ProgressStage } from "../device.js";
+import { truncateHexAfterEof } from "../hex-util.js";
 import MemoryMap from "nrf-intel-hex";
+import { CoreRegister } from "./cortex-m.js";
+import { dapLinkFlash } from "./daplink.js";
+import { onlyChanged, pageAlignBlocks, read32FromUInt8Array, } from "./partial-flashing-utils.js";
 // Source code for binaries in can be found at https://github.com/microsoft/pxt-microbit/blob/dec5b8ce72d5c2b4b0b20aafefce7474a6f0c7b2/external/sha/source/main.c
 // Drawn from https://github.com/microsoft/pxt-microbit/blob/dec5b8ce72d5c2b4b0b20aafefce7474a6f0c7b2/editor/extension.tsx#L243
 // Update from https://github.com/microsoft/pxt-microbit/commit/a35057717222b8e48335144f497b55e29e9b0f25
@@ -80,18 +74,31 @@ const membase = 0x20000000;
 const loadAddr = membase;
 const dataAddr = 0x20002000;
 const stackAddr = 0x20001000;
+// UICR (User Information Configuration Registers) — non-volatile registers
+// for chip config (bootloader address, NFC pin mode, etc). Bits can only be
+// cleared (1→0); restoring a bit to 1 requires erasing the entire UICR region.
+// https://docs.nordicsemi.com/bundle/ps_nrf52833/page/uicr.html
+const UICR_BASE = 0x10001000;
+const UICR_LIMIT = 0x10002000;
+// nRF52 NVMC registers for UICR erase/write
+const NVMC_CONFIG = 0x4001e504;
+const NVMC_ERASEUICR = 0x4001e514;
+const NVMC_READY = 0x4001e400;
+const NVMC_CONFIG_WEN = 1; // Write enable
+const NVMC_CONFIG_EEN = 2; // Erase enable
+const NVMC_CONFIG_REN = 0; // Read only
 /**
- * Uses a DAPWrapper to flash the micro:bit.
+ * Uses a USBDeviceWrapper to flash the micro:bit.
  *
- * Intented to be used for a single flash with a pre-connected DAPWrapper.
+ * Intended to be used for a single flash with a pre-connected USBDeviceWrapper.
  */
 export class PartialFlashing {
-    constructor(dapwrapper, logging, boardVersion) {
-        Object.defineProperty(this, "dapwrapper", {
+    constructor(device, logging, boardVersion, pageSize, numPages) {
+        Object.defineProperty(this, "device", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: dapwrapper
+            value: device
         });
         Object.defineProperty(this, "logging", {
             enumerable: true,
@@ -105,6 +112,18 @@ export class PartialFlashing {
             writable: true,
             value: boardVersion
         });
+        Object.defineProperty(this, "pageSize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: pageSize
+        });
+        Object.defineProperty(this, "numPages", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: numPages
+        });
     }
     log(v) {
         this.logging.log(v);
@@ -112,36 +131,34 @@ export class PartialFlashing {
     // Runs the checksum algorithm on the micro:bit's whole flash memory, and returns the results.
     // Drawn from https://github.com/microsoft/pxt-microbit/blob/dec5b8ce72d5c2b4b0b20aafefce7474a6f0c7b2/editor/extension.tsx#L365
     async getFlashChecksumsAsync() {
-        await this.dapwrapper.executeAsync(loadAddr, computeChecksums2, stackAddr, loadAddr + 1, 0xffffffff, dataAddr, 0, this.dapwrapper.pageSize, this.dapwrapper.numPages);
-        return this.dapwrapper.readBlockAsync(dataAddr, this.dapwrapper.numPages * 2);
+        await this.device.cortexM.execute(loadAddr, computeChecksums2, stackAddr, loadAddr + 1, 0xffffffff, dataAddr, 0, this.pageSize, this.numPages);
+        return this.device.adi.readBlock(dataAddr, this.numPages * 2);
     }
     // Runs the code on the micro:bit to copy a single page of data from RAM address addr to the ROM address specified by the page.
     // Does not wait for execution to halt.
     // Drawn from https://github.com/microsoft/pxt-microbit/blob/dec5b8ce72d5c2b4b0b20aafefce7474a6f0c7b2/editor/extension.tsx#L340
     async runFlash(page, addr) {
-        await this.dapwrapper.cortexM.halt(true);
-        await Promise.all([
-            this.dapwrapper.cortexM.writeCoreRegister(CoreRegister.PC, loadAddr + 4 + 1),
-            this.dapwrapper.cortexM.writeCoreRegister(CoreRegister.LR, loadAddr + 1),
-            this.dapwrapper.cortexM.writeCoreRegister(CoreRegister.SP, stackAddr),
-            this.dapwrapper.cortexM.writeCoreRegister(0, page.targetAddr),
-            this.dapwrapper.cortexM.writeCoreRegister(1, addr),
-            this.dapwrapper.cortexM.writeCoreRegister(2, this.dapwrapper.pageSize >> 2),
-        ]);
-        return this.dapwrapper.cortexM.resume(false);
+        await this.device.cortexM.halt(true);
+        await this.device.cortexM.writeCoreRegister(CoreRegister.PC, loadAddr + 4 + 1);
+        await this.device.cortexM.writeCoreRegister(CoreRegister.LR, loadAddr + 1);
+        await this.device.cortexM.writeCoreRegister(CoreRegister.SP, stackAddr);
+        await this.device.cortexM.writeCoreRegister(0, page.targetAddr);
+        await this.device.cortexM.writeCoreRegister(1, addr);
+        await this.device.cortexM.writeCoreRegister(2, this.pageSize >> 2);
+        return this.device.cortexM.resume(false);
     }
     // Write a single page of data to micro:bit ROM by writing it to micro:bit RAM and copying to ROM.
     // Drawn from https://github.com/microsoft/pxt-microbit/blob/dec5b8ce72d5c2b4b0b20aafefce7474a6f0c7b2/editor/extension.tsx#L385
     async partialFlashPageAsync(page, nextPage, i) {
-        // TODO: This short-circuits UICR, do we need to update this?
+        // UICR pages are handled separately by checkUicr/repairUicr.
         if (page.targetAddr >= 0x10000000) {
             return;
         }
         // Use two slots in RAM to allow parallelisation of the following two tasks.
         // 1. DAPjs writes a page to one slot.
         // 2. flashPageBIN copies a page to flash from the other slot.
-        let thisAddr = i & 1 ? dataAddr : dataAddr + this.dapwrapper.pageSize;
-        let nextAddr = i & 1 ? dataAddr + this.dapwrapper.pageSize : dataAddr;
+        let thisAddr = i & 1 ? dataAddr : dataAddr + this.pageSize;
+        let nextAddr = i & 1 ? dataAddr + this.pageSize : dataAddr;
         // Write first page to slot in RAM.
         // All subsequent pages will have already been written to RAM.
         if (i === 0) {
@@ -149,19 +166,20 @@ export class PartialFlashing {
             for (let j = 0; j < page.data.length; j += 4) {
                 u32data[j >> 2] = read32FromUInt8Array(page.data, j);
             }
-            await this.dapwrapper.writeBlockAsync(thisAddr, u32data);
+            await this.device.adi.writeBlock(thisAddr, u32data);
         }
         await this.runFlash(page, thisAddr);
         // Write next page to micro:bit RAM if it exists.
         if (nextPage) {
             let buf = new Uint32Array(nextPage.data.buffer);
-            await this.dapwrapper.writeBlockAsync(nextAddr, buf);
+            await this.device.adi.writeBlock(nextAddr, buf);
         }
-        return this.dapwrapper.waitForHalt();
+        return this.device.cortexM.waitForHalt();
     }
     // Write pages of data to micro:bit ROM.
     async partialFlashCoreAsync(pages, updateProgress) {
         this.log("Partial flash");
+        await this.device.adi.writeBlock(loadAddr, flashPageBIN);
         for (let i = 0; i < pages.length; ++i) {
             updateProgress(ProgressStage.PartialFlashing, i / pages.length);
             await this.partialFlashPageAsync(pages[i], pages[i + 1], i);
@@ -172,13 +190,13 @@ export class PartialFlashing {
     // Falls back to a full flash if partial flashing fails.
     // Drawn from https://github.com/microsoft/pxt-microbit/blob/dec5b8ce72d5c2b4b0b20aafefce7474a6f0c7b2/editor/extension.tsx#L335
     async partialFlashAsync(data, updateProgress) {
-        const flashBytes = this.convertDataToPaddedBytes(data);
+        const memoryMap = this.toMemoryMap(data);
+        const { flashBytes, uicrEntries } = this.extractFlashAndUicr(memoryMap);
         const checksums = await this.getFlashChecksumsAsync();
-        await this.dapwrapper.writeBlockAsync(loadAddr, flashPageBIN);
-        let aligned = pageAlignBlocks(flashBytes, 0, this.dapwrapper.pageSize);
+        let aligned = pageAlignBlocks(flashBytes, 0, this.pageSize);
         const totalPages = aligned.length;
         this.log("Total pages: " + totalPages);
-        aligned = onlyChanged(aligned, checksums, this.dapwrapper.pageSize);
+        aligned = onlyChanged(aligned, checksums, this.pageSize);
         this.log("Changed pages: " + aligned.length);
         let partial;
         if (aligned.length > totalPages / 2) {
@@ -189,6 +207,10 @@ export class PartialFlashing {
             catch (e) {
                 this.log(e);
                 this.log("Full flash failed, attempting partial flash.");
+                // FLASH_CLOSE (called during full flash cleanup) disables SWD,
+                // so we must reconnect before partial flash can use it.
+                await this.device.adi.reinit();
+                await this.device.cortexM.reset(true);
                 await this.partialFlashCoreAsync(aligned, updateProgress);
                 partial = true;
             }
@@ -205,108 +227,145 @@ export class PartialFlashing {
                 partial = false;
             }
         }
-        try {
-            await this.dapwrapper.reset();
-        }
-        catch (e) {
-            // Allow errors on resetting, user can always manually reset if necessary.
+        // After partial flash, check UICR. Full flash writes UICR as part of
+        // the hex stream so doesn't need this.
+        if (partial && uicrEntries.length > 0) {
+            partial = await this.ensureUicr(data, uicrEntries, updateProgress);
         }
         this.log("Flashing complete");
         return partial;
     }
-    // Perform full flash of micro:bit's ROM using daplink.
+    // Perform full flash of micro:bit's ROM using DAPLink vendor commands.
     async fullFlashAsync(data, updateProgress) {
         this.log("Full flash");
         const fullFlashProgress = (progress) => {
             updateProgress(ProgressStage.FullFlashing, progress);
         };
-        this.dapwrapper.daplink.on(DAPLinkValue.EVENT_PROGRESS, fullFlashProgress);
-        try {
-            data = this.convertDataToHexString(data);
-            await this.dapwrapper.transport.open();
-            await this.dapwrapper.daplink.flash(new TextEncoder().encode(data));
-            this.logging.event({
-                type: "WebUSB-info",
-                message: "full-flash-successful",
-            });
-        }
-        finally {
-            this.dapwrapper.daplink.removeListener(DAPLinkValue.EVENT_PROGRESS, fullFlashProgress);
-        }
+        const hexData = this.convertDataToHexString(data);
+        await dapLinkFlash(this.device.adi, new TextEncoder().encode(hexData), fullFlashProgress);
+        this.logging.event({
+            type: "WebUSB-info",
+            message: "full-flash-successful",
+        });
     }
     // Flash the micro:bit's ROM with the provided image, resetting the micro:bit first.
     // Drawn from https://github.com/microsoft/pxt-microbit/blob/dec5b8ce72d5c2b4b0b20aafefce7474a6f0c7b2/editor/extension.tsx#L439
     async flashAsync(data, updateProgress) {
-        let resetPromise = (async () => {
-            // Reset micro:bit to ensure interface responds correctly.
-            this.log("Begin reset");
-            try {
-                await this.dapwrapper.reset(true);
-            }
-            catch (e) {
-                this.log("Retrying reset");
-                await this.dapwrapper.reconnectAsync();
-                await this.dapwrapper.reset(true);
-            }
-        })();
+        // Reset into halted state so partial flash can execute code from a clean
+        // state.
+        this.log("Begin reset");
         try {
-            try {
-                await withTimeout(resetPromise, 1000);
-                this.log("Begin flashing");
-                return await this.partialFlashAsync(data, updateProgress);
-            }
-            catch (e) {
-                if (e instanceof TimeoutError) {
-                    this.log("Resetting micro:bit timed out");
-                    this.log("Partial flashing failed. Attempting full flash");
-                    this.logging.event({
-                        type: "WebUSB-info",
-                        message: "flash-failed/attempting-full-flash",
-                    });
-                    await this.fullFlashAsync(data, updateProgress);
-                    return false;
-                }
-                else {
-                    throw e;
-                }
-            }
+            await this.device.cortexM.reset(true);
         }
-        finally {
-            // NB cannot return Promises above!
-            await this.dapwrapper.disconnectAsync();
+        catch (e) {
+            this.log("Retrying reset");
+            await this.device.reconnect();
+            await this.device.cortexM.reset(true);
         }
+        this.log("Begin flashing");
+        return this.partialFlashAsync(data, updateProgress);
     }
     convertDataToHexString(data) {
         if (typeof data === "string") {
             return data;
         }
         if (data instanceof Uint8Array) {
-            return this.paddedBytesToHexString(data);
+            return MemoryMap.fromPaddedUint8Array(data).asHexString();
         }
         return data.asHexString();
     }
-    convertDataToPaddedBytes(data) {
-        if (data instanceof Uint8Array) {
-            return data;
-        }
+    /**
+     * Parse the flash data into a MemoryMap (if not already one).
+     */
+    toMemoryMap(data) {
         if (typeof data === "string") {
-            return this.hexStringToPaddedBytes(data);
+            return MemoryMap.fromHex(truncateHexAfterEof(data));
         }
-        return this.memoryMapToPaddedBytes(data);
-    }
-    hexStringToPaddedBytes(hex) {
-        const m = MemoryMap.fromHex(hex);
-        return this.memoryMapToPaddedBytes(m);
-    }
-    paddedBytesToHexString(data) {
-        return MemoryMap.fromPaddedUint8Array(data).asHexString();
+        if (data instanceof Uint8Array) {
+            return MemoryMap.fromPaddedUint8Array(data);
+        }
+        return data;
     }
-    memoryMapToPaddedBytes(memoryMap) {
+    /**
+     * Extract padded flash bytes (main flash only) and UICR entries from a
+     * MemoryMap. Parses the data once for both.
+     */
+    extractFlashAndUicr(memoryMap) {
         const flashSize = {
             V1: 256 * 1024,
             V2: 512 * 1024,
         }[this.boardVersion];
-        return memoryMap.slicePad(0, flashSize);
+        const flashBytes = memoryMap.slicePad(0, flashSize);
+        const uicrEntries = [];
+        for (const [addr, block] of memoryMap) {
+            if (addr < UICR_BASE || addr >= UICR_LIMIT)
+                continue;
+            for (let i = 0; i < block.length; i += 4) {
+                uicrEntries.push({
+                    address: addr + i,
+                    value: read32FromUInt8Array(block, i),
+                });
+            }
+        }
+        return { flashBytes, uicrEntries };
+    }
+    /**
+     * Check UICR and repair if needed after a partial flash.
+     *
+     * UICR bits can only be cleared (1→0) without erasing. If all mismatched
+     * bits only need 1→0, we can write directly on both V1 and V2.
+     * If any bit needs 0→1, an erase is required first:
+     *  - V2: erase via NVMC.ERASEUICR, then write
+     *  - V1: no independent UICR erase, fall back to full flash
+     *
+     * Returns true if we stayed on the partial flash path, false if we had
+     * to fall back to full flash.
+     */
+    async ensureUicr(data, entries, updateProgress) {
+        let needsErase = false;
+        let hasMismatch = false;
+        for (const { address, value } of entries) {
+            const actual = await this.device.adi.readMem32(address);
+            if (actual === value)
+                continue;
+            hasMismatch = true;
+            // Check if any bit needs to go from 0→1 (requires erase)
+            const canWriteInPlace = (actual & value) >>> 0 === value >>> 0;
+            this.log(`UICR mismatch at 0x${address.toString(16)}: ` +
+                `device=0x${(actual >>> 0).toString(16)} ` +
+                `expected=0x${(value >>> 0).toString(16)}` +
+                (canWriteInPlace ? "" : " (needs erase)"));
+            if (!canWriteInPlace) {
+                needsErase = true;
+            }
+        }
+        if (!hasMismatch) {
+            return true;
+        }
+        if (needsErase && this.boardVersion === "V1") {
+            // V1 has no ERASEUICR — must do a full flash (chip erase).
+            this.log("UICR requires erase on V1, falling back to full flash.");
+            await this.fullFlashAsync(data, updateProgress);
+            return false;
+        }
+        const waitNvmcReady = () => waitFor(async () => ((await this.device.adi.readMem32(NVMC_READY)) & 1) === 1, 10_000, 5);
+        if (needsErase) {
+            // V2: erase UICR via dedicated NVMC register
+            this.log("Erasing UICR");
+            await this.device.adi.writeMem32(NVMC_CONFIG, NVMC_CONFIG_EEN);
+            await this.device.adi.writeMem32(NVMC_ERASEUICR, 1);
+            await waitNvmcReady();
+        }
+        // Write UICR words
+        this.log("Writing UICR");
+        await this.device.adi.writeMem32(NVMC_CONFIG, NVMC_CONFIG_WEN);
+        for (const { address, value } of entries) {
+            await this.device.adi.writeMem32(address, value);
+            await waitNvmcReady();
+        }
+        await this.device.adi.writeMem32(NVMC_CONFIG, NVMC_CONFIG_REN);
+        this.log("UICR repair complete");
+        return true;
     }
 }
-//# sourceMappingURL=usb-partial-flashing.js.map
+//# sourceMappingURL=partial-flashing.js.map

package/build/esm/usb/partial-flashing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"partial-flashing.js","sourceRoot":"","sources":["../../../src/usb/partial-flashing.ts"],"names":[],"mappings":"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"}

package/build/esm/usb/promise-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promise-queue.js","sourceRoot":"","sources":["../../../src/usb/promise-queue.ts"],"names":[],"mappings":"AAcA,MAAM,OAAO,YAAY;IAKvB,YAAY,UAAmB,EAAE;QAJzB;;;;mBAAgB,KAAK;WAAC;QACtB;;;;mBAA6B,EAAE;WAAC;QAChC;;;;;WAA4C;QAGlD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;OAKG;IACI,GAAG,CAAI,MAAwB;QACpC,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,MAAM,KAAK,GAAkB;gBAC3B,OAAO;gBACP,MAAM;gBACN,MAAM;aACP,CAAC;YACF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACf,KAAK,IAAI,CAAC,YAAY,EAAE,CAAC;YAC3B,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,YAAY;QACxB,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QACpC,IAAI,SAAS,EAAE,CAAC;YACd,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACtB,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO;QACT,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC;YACH,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;QAClB,OAAO,IAAI,CAAC,YAAY,EAAE,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,SAAsB;QACjC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAClB,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;YACpB,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QACxB,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/build/esm/usb/serial-events.d.ts

@@ -0,0 +1,16 @@
+export interface SerialData {
+    data: string;
+}
+export interface SerialConnectionEventMap {
+    /** Fired when serial data is received from the micro:bit. */
+    serialdata: SerialData;
+    /**
+     * Fired when the serial session ends, indicating that subsequent serial
+     * output may be from a different program (e.g. after flashing or a full
+     * disconnect). Consumers typically use this to clear the terminal.
+     *
+     * Not fired when the connection is paused (tab hidden) because the same
+     * program continues running and serial resumes when the tab becomes visible.
+     */
+    serialreset: void;
+}

package/build/esm/usb/serial-events.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=serial-events.js.map

package/build/esm/usb/serial-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial-events.js","sourceRoot":"","sources":["../../../src/usb/serial-events.ts"],"names":[],"mappings":""}

package/build/esm/usb/transport.d.ts

@@ -0,0 +1,42 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * Derived from dapjs (https://github.com/ARMmbed/dapjs) which is
+ * Copyright (c) Arm Limited 2018
+ * Copyright (c) Microsoft Corporation
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * See arm-debug.ts for the full dapjs license.
+ *
+ * WebUSB transport layer. Handles opening/closing the USB interface,
+ * finding the correct CMSIS-DAP endpoints, and reading/writing raw packets.
+ *
+ * This is the lowest layer in the USB stack, sitting beneath the CMSIS-DAP
+ * protocol layer. It knows nothing about DAP commands — it just moves
+ * fixed-size packets between the host and the USB device.
+ *
+ * micro:bit V2 uses CMSIS-DAP v2 (bulk endpoints). micro:bit V1 uses
+ * CMSIS-DAP v1 (HID) which has no bulk endpoints — we fall back to
+ * control transfers (SET_REPORT/GET_REPORT) in that case.
+ */
+export declare const PACKET_SIZE = 64;
+export interface Transport {
+    readonly isOpen: boolean;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    read(): Promise<DataView>;
+    write(data: Uint8Array): Promise<void>;
+}
+export declare class UsbTransport implements Transport {
+    private device;
+    private interfaceNumber?;
+    private endpointIn?;
+    private endpointOut?;
+    constructor(device: USBDevice);
+    get isOpen(): boolean;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    read(): Promise<DataView>;
+    write(data: Uint8Array): Promise<void>;
+}

package/build/esm/usb/transport.js

@@ -0,0 +1,151 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * Derived from dapjs (https://github.com/ARMmbed/dapjs) which is
+ * Copyright (c) Arm Limited 2018
+ * Copyright (c) Microsoft Corporation
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * See arm-debug.ts for the full dapjs license.
+ *
+ * WebUSB transport layer. Handles opening/closing the USB interface,
+ * finding the correct CMSIS-DAP endpoints, and reading/writing raw packets.
+ *
+ * This is the lowest layer in the USB stack, sitting beneath the CMSIS-DAP
+ * protocol layer. It knows nothing about DAP commands — it just moves
+ * fixed-size packets between the host and the USB device.
+ *
+ * micro:bit V2 uses CMSIS-DAP v2 (bulk endpoints). micro:bit V1 uses
+ * CMSIS-DAP v1 (HID) which has no bulk endpoints — we fall back to
+ * control transfers (SET_REPORT/GET_REPORT) in that case.
+ */
+import { DeviceError } from "../device.js";
+// WebUSB interface class for CMSIS-DAP
+const CMSIS_DAP_INTERFACE_CLASS = 0xff;
+// HID report types for control transfer fallback (CMSIS-DAP v1 / no bulk endpoints)
+const GET_REPORT = 0x01;
+const SET_REPORT = 0x09;
+const OUT_REPORT = 0x200;
+const IN_REPORT = 0x100;
+export const PACKET_SIZE = 64;
+export class UsbTransport {
+    constructor(device) {
+        Object.defineProperty(this, "device", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: device
+        });
+        Object.defineProperty(this, "interfaceNumber", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "endpointIn", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "endpointOut", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+    }
+    get isOpen() {
+        return this.interfaceNumber !== undefined;
+    }
+    async open() {
+        if (this.isOpen)
+            return;
+        await this.device.open();
+        await this.device.selectConfiguration(1);
+        const interfaces = this.device.configuration.interfaces.filter((iface) => iface.alternates[0].interfaceClass === CMSIS_DAP_INTERFACE_CLASS);
+        if (!interfaces.length) {
+            throw new DeviceError({
+                code: "firmware-update-required",
+                message: "No valid interfaces found.",
+            });
+        }
+        // Prefer interface with bulk endpoints (CMSIS-DAP v2).
+        // Fall back to an interface without endpoints (CMSIS-DAP v1 / HID),
+        // which will use control transfers instead.
+        const selectedInterface = interfaces.find((iface) => iface.alternates[0].endpoints.length > 0) ??
+            interfaces[0];
+        this.interfaceNumber = selectedInterface.interfaceNumber;
+        const endpoints = selectedInterface.alternates[0].endpoints;
+        this.endpointIn = undefined;
+        this.endpointOut = undefined;
+        for (const endpoint of endpoints) {
+            if (endpoint.direction === "in" && !this.endpointIn)
+                this.endpointIn = endpoint;
+            else if (endpoint.direction === "out" && !this.endpointOut)
+                this.endpointOut = endpoint;
+        }
+        await this.device.claimInterface(this.interfaceNumber);
+    }
+    async close() {
+        this.interfaceNumber = undefined;
+        this.endpointIn = undefined;
+        this.endpointOut = undefined;
+        await this.device.close();
+    }
+    async read() {
+        if (this.interfaceNumber === undefined) {
+            throw new DeviceError({
+                code: "connection-error",
+                message: "No device opened",
+            });
+        }
+        let result;
+        if (this.endpointIn) {
+            result = await this.device.transferIn(this.endpointIn.endpointNumber, PACKET_SIZE);
+        }
+        else {
+            // Control transfer fallback for interfaces without bulk endpoints
+            result = await this.device.controlTransferIn({
+                requestType: "class",
+                recipient: "interface",
+                request: GET_REPORT,
+                value: IN_REPORT,
+                index: this.interfaceNumber,
+            }, PACKET_SIZE);
+        }
+        if (result.status !== "ok" || !result.data) {
+            throw new DeviceError({
+                code: "connection-error",
+                message: "USB read failed",
+            });
+        }
+        return result.data;
+    }
+    async write(data) {
+        if (this.interfaceNumber === undefined) {
+            throw new DeviceError({
+                code: "connection-error",
+                message: "No device opened",
+            });
+        }
+        // Always pad to PACKET_SIZE (required for HID control transfer fallback)
+        const buffer = new Uint8Array(PACKET_SIZE);
+        buffer.set(data.subarray(0, PACKET_SIZE));
+        if (this.endpointOut) {
+            await this.device.transferOut(this.endpointOut.endpointNumber, buffer);
+        }
+        else {
+            // Control transfer fallback for interfaces without bulk endpoints
+            await this.device.controlTransferOut({
+                requestType: "class",
+                recipient: "interface",
+                request: SET_REPORT,
+                value: OUT_REPORT,
+                index: this.interfaceNumber,
+            }, buffer);
+        }
+    }
+}
+//# sourceMappingURL=transport.js.map

package/build/esm/usb/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../../src/usb/transport.ts"],"names":[],"mappings":"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"}