class Flash – access to built-in flash storage

The Flash class provides direct, block-level access to the RP2040’s external QSPI flash chip. The driver implements the vfs.AbstractBlockDev interface so it can be passed to vfs.mount() for custom filesystem configurations.

Most scripts persist data through the auto-mounted filesystem at / and never construct Flash directly. Construct one manually when you need to:

  • Mount a non-default filesystem (e.g. wrap with vfs.VfsFat) on a custom partition.

  • Read or write firmware regions or factory-data blocks that aren’t owned by the filesystem.

  • Implement a custom on-flash storage format that bypasses the filesystem layer.

Constructors

class rp2.Flash → Flash

Return the singleton Flash block-device object backed by the RP2040’s QSPI flash chip. The first block exposed is the one immediately after the firmware region, so callers see only the filesystem-eligible area of the chip.

Methods

readblocks(block_num: int, buf: bytearray) → None
readblocks(block_num: int, buf: bytearray, offset: int) → None

Read bytes from the flash into buf. Standard vfs.AbstractBlockDev block-device entry point used by the filesystem layer.

Simple form (readblocks(block_num, buf)): read whole blocks starting at block index block_num. len(buf) must be a multiple of the flash block size.

Extended form (readblocks(block_num, buf, offset)): read len(buf) bytes – not necessarily a whole number of blocks – starting at byte offset within block block_num. Used by littlefs and other byte-addressable filesystems.

writeblocks(block_num: int, buf: bytes) → None
writeblocks(block_num: int, buf: bytes, offset: int) → None

Write bytes from buf to the flash. Standard vfs.AbstractBlockDev block-device entry point used by the filesystem layer.

Simple form (writeblocks(block_num, buf)): write whole blocks starting at block index block_num. len(buf) must be a multiple of the flash block size. Each affected block is erased automatically before being written.

Extended form (writeblocks(block_num, buf, offset)): write len(buf) bytes – not necessarily a whole number of blocks – starting at byte offset within block block_num. No implicit erase is performed – the caller must ensure the affected blocks have been erased via a prior ioctl(6, block_num) call.

ioctl(cmd: int, arg: int) → int | None

Standard vfs.AbstractBlockDev control entry point. Called by the filesystem layer at mount/unmount time and on every sync. Recognised cmd values:

  • 1 – initialise. Returns 0 on success.

  • 2 – deinitialise. Returns 0 on success.

  • 3 – sync pending writes. Returns 0.

  • 4 – return the number of flash blocks visible to the filesystem.

  • 5 – return the block size in bytes (typically the flash sector size, 4096).

  • 6 – erase the block at index arg. Required before using the extended writeblocks form.

  • 7 – return whether the device supports the block erase command (1 on RP2040).

Direct callers normally don’t use this method – the filesystem driver dispatches the standard codes automatically once the Flash is mounted.