Use serial only instead of USB MSC for CIRCUITPY access

[makermelissa]

I would make the workflow much easier if we could only rely on the serial connection. This would make it so much easier to rename folders and use features like that. The main issue (and the reason it is the way it is now) is that I believe the file system is not writeable when the CIRCUITPY drive is present to avoid writing conflicts. We may be able to get around this by asking the user to eject the drive, and then writing

import storage
storage.disable_usb_drive()

to boot.py and and resetting. It could programmatically be removed from boot.py to re-enable the CIRCUITPY drive. Perhaps there is a way to just programmatically eject it, though I'm not seeing a way currently.

[makermelissa]

It looks like storage.remount() may eject the drive automatically, so that's a great option.

[dhalbert]

You cannot do remount.storage() when USB is active:

Adafruit CircuitPython 10.0.1 on 2025-10-09; Adafruit Metro RP2350 with rp2350b
>>> 
>>> import storage
>>> storage.remount("/")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
RuntimeError: Cannot remount path when visible via USB.

[dhalbert]

I would make the workflow much easier if we could only rely on the serial connection. This would make it so much easier to rename folders and use features like that. The main issue (and the reason it is the way it is now) is that I believe the file system is not writeable when the CIRCUITPY drive is present to avoid writing conflicts.

This is the way Thonny works. Is it easier because there would be only one path in the editor for file access, or because you don't have to give the browser permission to write the drive, or some other reason?

The MicroPython folks have mostly given up on USB access to the filesystem. They use LittleFS for some boards, and don't expose a USB drive. So they rely on tools like mpremote to do file manipulation and reading/writing.

Thonny can get into a bad state sometimes and require resetting. Writing boot.py might interfere with other things the user has in boot.py, such as HID device description. I am wondering if it would help to be able to hard-reset into "CIRCUITPY is writeable by Python" mode instead of messing with boot.py.

[makermelissa]

Thanks for looking into that Dan.

Is it easier because there would be only one path in the editor for file access, or because you don't have to give the browser permission to write the drive, or some other reason?

Both because it would only need one path and because of some feature limitations of the FileSystem API.

I am wondering if it would help to be able to hard-reset into "CIRCUITPY is writeable by Python" mode instead of messing with boot.py.

Yeah, that may be the only good option. I'm assuming you mean both the CIRCUITPY drive as well by remounting the storage without read_only and having disable_concurrent_write_protection also set.

[dhalbert]

'm assuming you mean both the CIRCUITPY drive as well by remounting the storage without read_only and having disable_concurrent_write_protection also set.

readonly=False, but doing disable_concurrent_write_protection=True would make the drive susceptible to corruption by writes from the host, so I think we should avoid that.

This would be another RunMode for microcontroller.on_next_reset(). It would be something like WRITABLE_CIRCUITPY. But maybe it should be SAFE_MODE_WRITABLE_CIRCUITPY, so that you can edit boot.py safely, and not have code.py start either after the reset. We'll need to think about that.

[makermelissa]

This is sounding good. Some thing to keep in mind:

• We would like a way for users to be able to run their code. Another reset might be needed (unless safe mode allows running code via REPL).
• Another good option may be a mode that places it in serial only without mounting the CIRCUITPY drive on next reboot.
• If this is a new feature, we would need a way to query the microcontroller to see if the reset mode exists. Perhaps just the version would be enough or maybe there's already a way that I'm not thinking of.

[dhalbert]

This is sounding good. Some thing to keep in mind:

• We would like a way for users to be able to run their code. Another reset might be needed (unless safe mode allows running code via REPL).

You could just do import code.py. I think Thonny does not actually run code.py or main.py at all: it sends the contents to the REPL or something like that.

• Another good option may be a mode that places it in serial only without mounting the CIRCUITPY drive on next reboot.

I like that: it's even simpler.

• If this is a new feature, we would need a way to query the microcontroller to see if the reset mode exists. Perhaps just the version would be enough or maybe there's already a way that I'm not thinking of.

You can just check the attributes of microcontroller.ResetReason:

>>> import microcontroller
>>> dir(microcontroller.ResetReason)
['__class__', '__name__', 'BROWNOUT', 'DEEP_SLEEP_ALARM', 'POWER_ON', 'RESCUE_DEBUG', 'RESET_PIN', 'SOFTWARE', 'UNKNOWN', 'WATCHDOG', '__bases__', '__dict__']
>>> hasattr(microcontroller.ResetReason, "POWER_ON")
True

[tannewt]

You could just do import code.py. I think Thonny does not actually run code.py or main.py at all: it sends the contents to the REPL or something like that.

I don't like doing this because it does guarantee you start in the same state.

I do think trying to add a hot reload mode could be cool. hot reload is where the changed portions of the code are reloaded but the other state is kept. I don't know how it is done though.

• Another good option may be a mode that places it in serial only without mounting the CIRCUITPY drive on next reboot.

I like that: it's even simpler.

I think adding a reboot mode that makes CIRCUITPY writable would be fine. However, let's acknowledge that it prevents the coder from using other tools (like cli circup or claude code) concurrently with the web editor.

[dhalbert]

I have another idea about this, which is to make storage.disable_usb_drive() be usable after USB starts. Turning that on after enumeration would make the MSC device report "Not Ready". E.g. https://community.st.com/stm32-mcus-products-25/how-can-i-temporalily-detach-reattach-the-msc-only-portion-of-a-composite-usb-msc-hid-device-from-the-device-itself-71347. It would still work as now when done before enumeration.

This is a bit dangerous if the host is in process with something, but that is already the case if we force a hard reset to change modes. We could add a required argument. The implementation could also wait some length of time with no host MSC writes before reporting Not Ready, like auto-reload does.

This discussion would be better held in https://github.com/adafruit/circuitpython/. EDIT: I've opened adafruit/circuitpython#11091 for that.

[makermelissa]

@dhalbert the changes for this have been merged into code-beta.circuitpython.org if you'd like to give it a try.

[dhalbert]

@dhalbert the changes for this have been merged into code-beta.circuitpython.org if you'd like to give it a try.

Great!