Thanks to ChatGPT for help with this…
Ah, CircuitPython. A delightful platform that turns "playing with microcontrollers" into an accessible and joyful experience. But every so often, you hit a problem that makes you scratch your head and say, "Wait, what?" Today, we’re diving into one such scenario: disabling USB mass storage, and (more importantly) restoring it without bricking yourself into a corner. Let's dig in!
Why Disable USB Mass Storage?
Good question! CircuitPython presents itself to your computer as a USB drive (the iconic CIRCUITPY
), which makes transferring code files a breeze. However, there are times when you need the microcontroller itself to have exclusive write access to the filesystem—perhaps to log data or update files without interference from your computer. For this, we can disable USB mass storage in the boot.py
file.
But what happens if you decide, "No, wait, I do want my CIRCUITPY
drive back?" Worry not! With the power of the REPL (and a pinch of Pythonic magic), you can re-enable mass storage mode. Let’s see how.
Step 1: Disabling USB Mass Storage
First, create a boot.py
file with the following content:
import storage
import usb_cdc
# Disable USB mass storage
storage.disable_usb_drive()
# Keep USB REPL enabled to allow deploying files via REPL tools
usb_cdc.enable(console=True, data=True)
# Remount the filesystem so CircuitPython code can write to it
storage.remount("/", readonly=False)
When this code runs on boot, the CIRCUITPY
drive will no longer appear on your computer. But don’t panic! Your device is still alive and kicking, and you can access it through the REPL (Read-Eval-Print Loop).
Important: The boot.py
file runs before code.py
, and it’s where you set up USB behavior. Always keep this distinction in mind.
Step 2: Accessing the REPL
Even with USB mass storage disabled, the REPL remains accessible via the USB serial interface. Here’s how to connect:
Open a Serial Terminal: Use a tool like Mu Editor, Thonny, or even mpremote
.
On Linux/macOS: Use screen
(e.g., screen /dev/ttyACM0 115200
).
On Windows: Use a terminal program like PuTTY.
Press Enter: Once connected, hit Enter to activate the REPL.
Start Typing Python Code: You’re now in the CircuitPython shell, ready to command your device!
Step 3: Restoring USB Mass Storage
From the REPL, you can modify or delete the offending boot.py
file to restore USB mass storage functionality.
Here’s how to rename it (so you can keep it as a backup):
import os
# Rename boot.py to boot_backup.py
os.rename("boot.py", "boot_backup.py")
Alternatively, if you’re feeling bold, you can delete it entirely:
import os
# Delete boot.py
os.remove("boot.py")
Once you’ve made the change, reboot your device:
import microcontroller
# Reboot the board
microcontroller.reset()
And just like that, the CIRCUITPY
drive will reappear! Congratulations, you’ve regained control.
Pro Tips
Test Before You Commit: Before adding storage.disable_usb_drive()
to your boot.py
, ensure you’re comfortable using the REPL and os
commands.
Keep Backups Handy: Always back up critical files before experimenting. If you’re locked out, you’ll need to reflash CircuitPython to recover.
Use Safe Mode: Double-press the reset button to enter safe mode, which bypasses boot.py
and lets you recover from mistakes.
Wrapping Up
Disabling USB mass storage can seem scary at first, but with a bit of planning (and the magic of the REPL), it’s a totally reversible process. Now you can take full control of your CircuitPython projects without fear of getting stuck.
As always, happy hacking!