[WEBUSB] Connection breaks

[fabianhugo]

Describe the bug

In certain situations the WEBUSB connection somewhat crashes and a download of the program is only possible after a new manual coupling action. The known situations currently are:

• saving project settings
• adding an extension to the program
• clicking the "add blocks" button when Jacdac modules are connected

These action have in common that they seem to do an internal reload of makecode in the background.
That the connection breaks can be seen by missing USB icon next to the download button, interestingly the tab still shows a WEBUSB connection.

To Reproduce

1. Go to makecode.calliope.cc, connect device, establish WEBUSB connection
   Do one of the following:
2. Click on project settings and save
3. Click on extension, add any extension
4. Add jacdac extension, connect jacdac module, click add
   Then:
   The WEBUSB connection of makecode is lost, while the WEBUSB connection of the browser inside the tab seems to be intact.

Expected behavior
WEBUSB should remain connected, pressing download should trigger a transfer of the program.

[fabianhugo]

Update July 2025:
The problem persists and can be narrowed down a bit. The following video shows the behaviour, the USB icon of the tab persists while the USB icon of makecode vanishes. If a user would press download in this state, the coupling dialogue pops up, leading to connection errors.

mkcusb.mp4

New information:

The problem has something to do with the hardware selection, which Makecode Calliope has, but Makecode micro:bit does not use. If the following line of pxtarget.json is removed, the problem does not appear anymore.
"dynamicBoardDefinition": true,
But also the hardware selection does not work anymore, so this is not a fix.

So something seems to disconnect webusb for makecode when extensions are added or a hardware selection is done.

@abchatra Do you have any idea where this could come from?

Edit: There was reference to code, that was actually custom for testing purposes.

[fabianhugo]

So what seems to happen is:
The dynamicBoardDefinition:true flag triggers a more reload of the project when an extension is added, compared to makecode microbit, where the dynamicBoardDefinition flag is not set. This can probably be reasoned by the arcade and maker makecode editors, where the different hardware options actually differ more in the underlying code stack.
And during the project reload it comes to a mismatch between the browser's USB connection state and the Makecode application's USB connection state. The browser shows it is still connected by the tiny usb icon in the corresponding tab while makecode thinks the connection is not there. Makecode tries to reestablish the connection, which can be seen by the USB icon popping up briefly, but it then disappears. This might be caused by a race condition or state inconsistency.

One possible fix is to add a usb reset after adding extension as soon as the webusb peripheral is not busy anymore. This can e.g. be implemented in pxt-core v11.4.16 in the file webapp/src/app.tsx in line 1726:

// Force WebUSB reconnection when dynamic board definition might have changed
if (pxt.appTarget.simulator?.dynamicBoardDefinition && pxt.usb.isEnabled) {
    setTimeout(async () => {
        try {
            const forceReset = (pxt.usb as any).forceResetAsync;
            if (forceReset) {
                await forceReset();
            } else {
                await pxt.usb.reconnectAsync();
            }
        } catch (e) {
            // Silently handle reconnection errors
        }
    }, 1000);
}

[fabianhugo]

The fix / workaround can be tried using this branch: https://github.com/fabianhugo/pxt/tree/webusbfix1_resetafter1s.

[fabianhugo]

The workaround that handles the reconnect within pxt-calliope can be found here:
https://github.com/calliope-edu/pxt-calliope/tree/webusb_fix