Broaden read-only filesystem messaging to cover non-host-mounted cases (refs #460)#506
Merged
makermelissa merged 1 commit intoJun 5, 2026
Conversation
The current dialog asserts that a host computer has CIRCUITPY mounted over USB, but that isn't always the cause. CircuitPython firmware holds the block device locked whenever USB Mass Storage is enabled on the board (the default for most boards), even on a power-only USB connection or a wall adapter that never completes SCSI enumeration. Users reproducing on a board connected only to a USB power source — no host, no Finder eject involved — were getting a dialog telling them to disconnect a host that wasn't there, which read as a bug. This commit: - Rewords the connect-time read-only notice to point at USB Mass Storage being *enabled*, not 'released'. - Rewords the save-failure dialog and the underlying ProtocolError hint to describe the read-only state in terms of the firmware's USB MSC mode rather than asserting host involvement. - Adds a 'heads up' note explaining that disabling USB MSC in boot.py hides CIRCUITPY from a host computer too, and mentions the common boot.py-button-gate pattern so users juggling Mu and web workflow understand the tradeoff before they edit boot.py. - Keeps the macOS Finder-eject caveat where it still applies. The detection logic (409/500 on /fs/ PUT tagged as writeProtected) is unchanged; this is a messaging fix only.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Refs #460 — the read-only filesystem dialog from PR #498 misdiagnoses
a real-world case the original reporter flagged: a board connected
to a USB power-only source (no host has CIRCUITPY mounted)
still hits the dialog and is told to disconnect a host that isn't
there.
This PR is a messaging fix only — the detection logic is
unchanged. It does not close #460; the underlying
"board-side filesystem stays locked while USB MSC is enabled even
when no host is using it" behavior is a firmware-side concern that
will be tracked separately.
What changed
js/script.jsConnect-time read-only notice:
Save-failure dialog:
Reordered the fix list (boot.py disable comes first now, because
the alternate "just unplug USB" remedy only helps the smaller
subset of users where a host actually has it mounted), and added
a heads-up paragraph:
That note is the missing piece for the dual-workflow case the
original reporter (#460) called out: they work on the same project
both at the bench (Mu over USB) and deployed (web workflow), and
the previous dialog's only fix recommendation forced them to pick one.
js/common/web-file-transfer.jsThe
_writeProtectedError().hintstring (used as the fallbackwhen the editor doesn't render the dialog itself) is updated to
match the new framing — points at USB MSC being enabled, doesn't
assert host involvement.
Why not just close #460 with this?
The dialog is now accurate, but the underlying board behavior
(filesystem stays write-protected while USB MSC is enabled, even
on power-only connections) is still surprising and arguably wrong
on hardware that never sees a real host. Investigating whether
the CircuitPython firmware should release the lock when no host
has done a real
WRITE10in some window, or expose a cooperative"yield to web workflow" mechanism, is its own piece of work and
belongs in adafruit/circuitpython.
That follow-up will be tracked separately; #460 stays open as
the umbrella.
Testing
node --checkon both edited files passes.npm run build(vite) passes clean.branches, no API surface change.
Refs
the first place — that logic is preserved verbatim).