Attempt a workaround for the bad response issue

See microbit-foundation/python-editor-v3#89

Ultimately this needs a fix in DAPLink to clear the queue on reset but that
won't have much impact on existing devices.

Author: microbit-matt-hillsdon

lib/usb-device-wrapper.ts

@@ -96,7 +96,7 @@ export class DAPWrapper {
       this.initialConnectionComplete = true;
     }
 
-    await this.daplink.connect();
+    await this.connectDaplink();
     await this.cortexM.connect();
 
     this.logging.event({
@@ -154,6 +154,90 @@ export class DAPWrapper {
     throw lastError;
   }
 
+  /**
+   * Drain any stale responses from the USB buffer.
+   * Sends a known command (DAP_INFO) and keeps reading until we get the
+   * matching response. This recovers from the state where a previous session
+   * was closed mid-serial-read, leaving stale responses in the device's
+   * USB buffer that break subsequent connections.
+   *
+   * See: https://github.com/microbit-foundation/python-editor-v3/issues/89
+   */
+  private async drainStaleResponses(): Promise<void> {
+    // DAPLink's DAP_PACKET_COUNT is 5-8 for micro:bit variants.
+    // In practice, only 1-2 stale responses are typical (from interrupted serial read).
+    // Use a value slightly above the max buffer size as a safety margin.
+    const maxAttempts = 10;
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      // DAP_INFO is a safe, read-only command that always succeeds
+      const packet = [DapCmd.DAP_INFO, 0x01];
+      await this.transport.write(Uint8Array.from(packet).buffer);
+
+      const response = await this.transport.read();
+      const responseBytes = new Uint8Array(response.buffer);
+
+      if (responseBytes[0] === DapCmd.DAP_INFO) {
+        // This is the response to our first DAP_INFO (from attempt 0).
+        // We sent additional DAP_INFO commands in subsequent attempts while
+        // reading stale responses - read out those responses too.
+        for (let i = 0; i < attempt; i++) {
+          await this.transport.read();
+        }
+        this.logging.log(
+          `USB buffer drain: synchronized after ${attempt} stale response(s)`,
+        );
+        return;
+      }
+      this.logging.log(
+        `USB buffer drain: discarded stale response 0x${responseBytes[0].toString(16)}`,
+      );
+    }
+
+    this.logging.log(
+      "USB buffer drain: warning - could not fully synchronize after max attempts",
+    );
+  }
+
+  /**
+   * Connect daplink, handling stale USB responses from a previous session.
+   * See: https://github.com/microbit-foundation/python-editor-v3/issues/89
+   */
+  private async connectDaplink(maxRetries = 3): Promise<void> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        if (attempt > 0) {
+          this.logging.log(
+            `Connection retry attempt ${attempt + 1}/${maxRetries}`,
+          );
+          await this.drainStaleResponses();
+        }
+
+        await this.daplink.connect();
+        return;
+      } catch (e) {
+        // https://github.com/ARMmbed/dapjs/blob/master/src/proxy/cmsis-dap.ts#L178
+        if (e instanceof Error && /^Bad response for /.test(e.message)) {
+          lastError = e;
+          this.logging.log(`Bad response error during connect: ${e.message}`);
+
+          try {
+            await this.transport.close();
+          } catch {
+            // Ignore close errors
+          }
+          await this.transport.open();
+          continue;
+        }
+        throw e;
+      }
+    }
+
+    throw lastError || new Error("Connection failed after retries");
+  }
+
   async startSerial(listener: (data: string) => void): Promise<void> {
     const currentBaud = await this.daplink.getSerialBaudrate();
     if (currentBaud !== 115200) {

lib/usb.ts

@@ -142,62 +142,6 @@ class MicrobitWebUSBConnectionImpl
   };
 
   private flashing: boolean = false;
-  private disconnectAfterFlash: boolean = false;
-  private visibilityReconnect: boolean = false;
-  private visibilityChangeListener = () => {
-    if (document.visibilityState === "visible") {
-      if (
-        this.visibilityReconnect &&
-        this.status !== ConnectionStatus.CONNECTED
-      ) {
-        this.disconnectAfterFlash = false;
-        this.visibilityReconnect = false;
-        if (!this.flashing) {
-          this.log("Reconnecting visible tab");
-          this.connect();
-        }
-      }
-    } else {
-      if (!this.unloading && this.status === ConnectionStatus.CONNECTED) {
-        if (!this.flashing) {
-          this.log("Disconnecting hidden tab");
-          this.disconnect().then(() => {
-            this.visibilityReconnect = true;
-          });
-        } else {
-          this.log("Scheduling disconnect of hidden tab for after flash");
-          this.disconnectAfterFlash = true;
-        }
-      }
-    }
-  };
-
-  private unloading = false;
-
-  private beforeUnloadListener = () => {
-    // If serial is in progress when the page unloads with V1 DAPLink 0254 or V2 0255
-    // then it'll fail to reconnect with mismatched command/response errors.
-    // Try hard to disconnect as a workaround.
-    // https://github.com/microbit-foundation/python-editor-v3/issues/89
-    this.unloading = true;
-    this.stopSerialInternal();
-    // The user might stay on the page if they have unsaved changes and there's another beforeunload listener.
-    window.addEventListener(
-      "focus",
-      () => {
-        const assumePageIsStayingOpenDelay = 1000;
-        setTimeout(() => {
-          if (this.status === ConnectionStatus.CONNECTED) {
-            this.unloading = false;
-            if (this.addedListeners.serialdata) {
-              this.startSerialInternal();
-            }
-          }
-        }, assumePageIsStayingOpenDelay);
-      },
-      { once: true },
-    );
-  };
 
   private logging: Logging;
   private deviceSelectionMode: DeviceSelectionMode;
@@ -221,30 +165,12 @@ class MicrobitWebUSBConnectionImpl
     if (navigator.usb) {
       navigator.usb.addEventListener("disconnect", this.handleDisconnect);
     }
-    if (typeof window !== "undefined") {
-      window.addEventListener("beforeunload", this.beforeUnloadListener);
-      if (window.document) {
-        window.document.addEventListener(
-          "visibilitychange",
-          this.visibilityChangeListener,
-        );
-      }
-    }
   }
 
   dispose() {
     if (navigator.usb) {
       navigator.usb.removeEventListener("disconnect", this.handleDisconnect);
     }
-    if (typeof window !== "undefined") {
-      window.removeEventListener("beforeunload", this.beforeUnloadListener);
-      if (window.document) {
-        window.document.removeEventListener(
-          "visibilitychange",
-          this.visibilityChangeListener,
-        );
-      }
-    }
   }
 
   setRequestDeviceExclusionFilters(exclusionFilters: USBDeviceFilter[]) {
@@ -331,18 +257,11 @@ class MicrobitWebUSBConnectionImpl
     } finally {
       progress(undefined, wasPartial);
 
-      if (this.disconnectAfterFlash) {
-        this.log("Disconnecting after flash due to tab visibility");
-        this.disconnectAfterFlash = false;
-        await this.disconnect();
-        this.visibilityReconnect = true;
-      } else {
-        if (this.addedListeners.serialdata) {
-          this.log("Reinstating serial after flash");
-          if (this.connection.daplink) {
-            await this.connection.daplink.connect();
-            await this.startSerialInternal();
-          }
+      if (this.addedListeners.serialdata) {
+        this.log("Reinstating serial after flash");
+        if (this.connection.daplink) {
+          await this.connection.daplink.connect();
+          await this.startSerialInternal();
         }
       }
     }
@@ -408,7 +327,6 @@ class MicrobitWebUSBConnectionImpl
 
   private setStatus(newStatus: ConnectionStatus) {
     this.status = newStatus;
-    this.visibilityReconnect = false;
     this.log("USB connection status " + newStatus);
     this.dispatchTypedEvent("status", new ConnectionStatusEvent(newStatus));
   }