`emmcio` – Block device access to the on-board eMMC

The emmcio module exposes an eMMC chip as a block device. It provides no filesystem of its own: to read files, hand an EMMC object to storage.VfsFat and mount it.

Available on these boards

Teenage Engineering SP-1

class emmcio.EMMC(*, clock: microcontroller.Pin, command: microcontroller.Pin, data: microcontroller.Pin, reset: microcontroller.Pin | None = None, vccq: microcontroller.Pin | None = None, high_speed: bool = False, write_enabled: bool = False)

eMMC as a block device

Power up the card and make it ready for block access.

Only one EMMC object may exist at a time. Call deinit(), or use the object as a context manager, to release the card and its pins.

Parameters:

clock (Pin) – the card’s CLK pin
command (Pin) – the card’s CMD pin
data (Pin) – the card’s DAT0 pin. The bus is 1-bit, so this is a single pin.
reset (Pin) – the card’s RST_n pin, if the board wires one
vccq (Pin) – a pin gating the card’s I/O rail, if the board has one
high_speed (bool) – Run the bus at its faster clock rate. Raises an OSError if the card will not make the switch.
write_enabled (bool) – Allow writeblocks(). When False, the object is read-only and every write path refuses.

Raises:

ValueError – if the pins are unusable or already in use, or if the card is owned by the USB drive.
OSError – if the card does not come up. emmcio failure: n names the MMC command that did not answer (8 being the extended CSD), and high_speed failure: n how far the switch got: 0 the card does not advertise 52 MHz, 1 no CMD6 response, 2 the card never released DAT0, 3 it never came back to the transfer state, 4 the EXT_CSD readback did not take, 5 the 32 MHz smoke test failed, 7 the card rejected HS_TIMING.

Mount the card’s filesystem:

import board
import emmcio
import storage

emmc = emmcio.EMMC(
    clock=board.EMMC_CLK,
    command=board.EMMC_CMD,
    data=board.EMMC_DAT0,
    reset=board.EMMC_RESET,
    vccq=board.EMMC_VCCQ,
    high_speed=True,
    write_enabled=True,
)
storage.mount(storage.VfsFat(emmc), "/sd")

deinit() → None: Release the card and the pins it uses. Any further use of this object raises a ValueError.

__enter__() → EMMC: No-op used by Context Managers.

__exit__() → None: Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.

readblocks(start_block: int, buf: circuitpython_typing.WriteableBuffer) → None

Read into buf starting at start_block.

Parameters:

start_block (int) – the first block to read
buf (WriteableBuffer) – a buffer whose length is a non-zero multiple of block_size

Raises:

ValueError – if buf is the wrong length, or the requested blocks run past the end of the card.
OSError – if the card fails to deliver the data.

writeblocks(start_block: int, buf: circuitpython_typing.ReadableBuffer) → None

Write buf to the card starting at start_block.

Parameters:

start_block (int) – the first block to write
buf (ReadableBuffer) – a buffer whose length is a non-zero multiple of block_size

Raises:

RuntimeError – if this object was not constructed with write_enabled=True.
ValueError – if buf is the wrong length, or the requested blocks run past the end of the card.
OSError – if the write fails.

ioctl(op: int, arg: int) → int | None: Perform a block-device control operation, as required by the block-device protocol. Returns None for operations this device does not implement.

read_ext_csd() → bytes: Read the card’s 512-byte extended CSD register.

status() → int: Read the card’s 32-bit status register.

count: int: The number of blocks on the card.

block_size: int: The size of one block, in bytes.

cid: bytes: The card’s 16-byte identification register.

write_enabled: bool: Whether writeblocks() is permitted on this object.

high_speed: bool: Whether the card is running at its faster clock rate.

frequency: int: The bus clock rate in Hz.

emmcio – Block device access to the on-board eMMC

`emmcio` – Block device access to the on-board eMMC