close
Skip to content

Detect read-only BLE filesystem via write probe (workaround for #376)#479

Closed
makermelissa-piclaw wants to merge 1 commit intocircuitpython:mainfrom
makermelissa-piclaw:fix/376-readonly-detection-workaround
Closed

Detect read-only BLE filesystem via write probe (workaround for #376)#479
makermelissa-piclaw wants to merge 1 commit intocircuitpython:mainfrom
makermelissa-piclaw:fix/376-readonly-detection-workaround

Conversation

@makermelissa-piclaw
Copy link
Copy Markdown
Contributor

Fixes #376 (workaround).

Problem

When CIRCUITPY is mounted read-only (USB MSC owns the filesystem), BLE file operations from the web editor fail silently — no error dialog, just unhelpful console errors and broken Save As / Upload / Rename / Move flows.

The web editor already has the plumbing for this case: fileHelper.readOnly(), the _readOnlyMode flag in the file dialog, and disabled Save As / Save+Run buttons in script.js. The probe is just short-circuited with an early return false, which is why it never fires.

The original detection relied on the firmware returning STATUS_ERROR_READONLY (0x05). Recent CircuitPython collapses that into the generic STATUS_ERROR (0x02) on some code paths (see adafruit/circuitpython#10972), so even bringing the old probe back wouldn't be enough to distinguish read-only from other errors purely by status code.

Fix

Drop the early return false and use a status-code-agnostic probe: attempt to write a hidden zero-byte file (/._ble_readonly_check) at the root and treat any failure as read-only. Cleanup of the probe file is best-effort and only attempted when the write succeeded.

This works on both old (0x05) and new (0x02) firmware, since it doesn't care which error code we got — only whether the write completed.

Effect

Once the probe correctly returns true:

  • script.js: checkReadOnly() shows the existing warning: "Warning: File System is in read only mode. Disable the USB drive to allow write access."
  • Save As and Save+Run buttons get disabled
  • In the file dialog, Upload / New Folder / Rename / Move / Delete are all disabled by the existing _readOnlyMode guards

Verification

  • npm run build clean (vite v8.0.10, 52 modules, ~2.7s)
  • Probe is hidden filename (._ prefix), zero bytes, deleted immediately on success
  • Probe path is the root /, which is always valid on CircuitPython, so no false positives from "Invalid Path"

Notes

  • This is a client-side workaround. The real firmware fix (restore STATUS_ERROR_READONLY on read-only operations) is tracked in adafruit/circuitpython#10972. Even after that lands, this probe is still useful — it doesn't depend on a specific firmware version.
  • Single file changed: js/common/ble-file-transfer.js (+19 / -6).

…rkaround)

The firmware status code for a read-only filesystem regressed from
STATUS_ERROR_READONLY (0x05) to a generic STATUS_ERROR (0x02) on some
code paths in recent CircuitPython (see circuitpython#376 and
adafruit/circuitpython#10972), so the previous status-code-based
detection no longer triggers.

Re-enable the readOnly() probe in the BLE FileTransferClient wrapper:
attempt to write a hidden zero-byte file at the root and treat any
failure as read-only. This is firmware-status-code agnostic, so it
works on both old and new CircuitPython. Cleanup of the probe file is
best-effort.

With the probe live, the existing file-dialog and Save As / Save+Run
disabling logic in file_dialog.js and script.js takes effect again,
giving the user a proper warning and disabled controls when the FS is
read-only.
@makermelissa-piclaw
Copy link
Copy Markdown
Contributor Author

Closing per discussion: rather than ship a client-side workaround for the readonly-FS misreport, we'll wait for the firmware fix in adafruit/circuitpython#10972 so the FAT layer reflects live USB host state. Leaving the code editor in its current state.

The companion read-side helpers (getRuntimeStatus / getReadOnlyReason) drafted on adafruit/circuitpython-repl-js are also being shelved for the same reason — diagnostic value isn't worth the API surface if we're not acting on it.

@makermelissa-piclaw makermelissa-piclaw deleted the fix/376-readonly-detection-workaround branch April 29, 2026 21:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

BLE not detecting Read-only FS

1 participant