MojoScale Studio Docs
API Reference

sdcard

microSD card storage module.

All modules Open Studio
Studio Docs Storage

import sdcard

The sdcard module reads and writes files on a FAT16/FAT32 microSD card connected over SPI. Use it for data logging, camera images, configuration files, web assets, and offline message storage. ESP32 GPIO is 3.3 V logic. Use a microSD module designed for 3.3 V signals, or one with proper level shifting. SD card operations can block briefly, so avoid running heavy file work inside timing-critical callbacks.

Quick example

import sdcard

card = sdcard.SDCard(cs=5)
card.mount()

card.write_text("/hello.txt", "Hello from MojoScale\n")
print(card.read_text("/hello.txt"))

card.unmount()

import sdcard
import bme280
import system

card = sdcard.SDCard(cs=5)
card.mount()
log = card.open("/environment.csv", "a")

def record():
    reading = bme280.read()
    line = str(system.millis()) + "," + str(reading["temperature"]) + "\n"
    log.write(line)
    log.flush()

system.schedule("sd-log", 5000, 0, -1, record)

importsdcard

microSD card storage module.

The sdcard module reads and writes files on a FAT16/FAT32 microSD card connected over SPI. Use it for data logging, camera images, configuration files, web assets, and offline message storage. ESP32 GPIO is 3.3 V logic. Use a microSD module designed for 3.3 V signals, or one with proper level shifting. SD card operations can block briefly, so avoid running heavy file work inside timing-critical callbacks.

API 25 available

sdcard.SDCard(cs: int, spi: int = None, frequency: int = None, mount_point: str = None) -> sdcard_card

Create a microSD card object.

Creating the object does not mount the card. Call ``mount()`` before file operations. The module uses the configured SPI bus pins when SPI has already been initialized; otherwise it starts the selected SPI bus with board-default pins.

Parameters
Name Type Pass as Required Description
cs int positional or keyword Yes Chip-select GPIO connected to the SD card module.
spi int positional or keyword No Optional SPI bus number. Defaults to 2.
frequency int positional or keyword No Optional SPI clock frequency in hertz. Defaults to 20000000.
mount_point str positional or keyword No Optional internal mount location. Defaults to "/sd".
Returns

sdcard_card sdcard_card object.

sdcard.SDCard().mount() -> bool

Mount the FAT filesystem. Returns True when the card is mounted.

sdcard.SDCard().unmount() -> bool

Flush and unmount the card. Close open files first.

sdcard.SDCard().is_mounted() -> bool

Return whether the card is currently mounted.

sdcard.SDCard().info() -> dict

Return type, size_bytes, used_bytes, free_bytes, mount_point, mounted, cs, spi, frequency, and open_files.

sdcard.SDCard().exists(path) -> bool

Return True when a file or directory exists. Path must start with "/".

Parameters
Name Type Pass as Required Description
path str positional or keyword Yes Required value.

sdcard.SDCard().stat(path) -> dict

Return name, path, type, size, and modified for a file or directory.

Parameters
Name Type Pass as Required Description
path str positional or keyword Yes Required value.

sdcard.SDCard().list(path="/") -> list

Return direct child entries for a directory. This is not recursive.

Parameters
Name Type Pass as Required Description
path str positional or keyword No Optional value. Defaults to "/".

sdcard.SDCard().mkdir(path) -> bool

Create a directory, including missing parent directories.

Parameters
Name Type Pass as Required Description
path str positional or keyword Yes Required value.

sdcard.SDCard().remove(path) -> bool

Delete a file or an empty directory. This is not recursive.

Parameters
Name Type Pass as Required Description
path str positional or keyword Yes Required value.

sdcard.SDCard().rename(source, destination, overwrite=False) -> bool

Rename or move a file or directory on the same card.

Parameters
Name Type Pass as Required Description
source int positional or keyword Yes Required value.
destination int positional or keyword Yes Required value.
overwrite bool positional or keyword No Optional value. Defaults to False.

sdcard.SDCard().open(path, mode="r") -> sdcard_file: Open a file. Modes

"r", "w", "a", "r+", "w+", "a+", plus binary variants.

Parameters
Name Type Pass as Required Description
path str positional or keyword Yes Required value.
mode str positional or keyword No Optional value. Defaults to "r".

sdcard.SDCard().read_text(path, max_bytes=65536) -> str

Read a UTF-8 text file, rejecting files larger than max_bytes.

Parameters
Name Type Pass as Required Description
path str positional or keyword Yes Required value.
max_bytes int positional or keyword No Optional value. Defaults to 65536.

sdcard.SDCard().write_text(path, content) -> bool

Write text, replacing the file contents.

Parameters
Name Type Pass as Required Description
path str positional or keyword Yes Required value.
content any positional or keyword Yes Required value.

sdcard.SDCard().append_text(path, content) -> bool

Append text, creating the file when needed.

Parameters
Name Type Pass as Required Description
path str positional or keyword Yes Required value.
content any positional or keyword Yes Required value.

sdcard.SDCard().close() -> bool

Alias for unmount().

sdcard.SDCard().File Object Methods

sdcard.SDCard().read(size=-1) -> str

Read data from the current position.

Parameters
Name Type Pass as Required Description
size any positional or keyword No Optional value. Defaults to -1.

sdcard.SDCard().readline() -> str

Read one line, or nil at end of file.

sdcard.SDCard().write(data) -> int

Write a string or bytes value and return bytes written.

Parameters
Name Type Pass as Required Description
data any positional or keyword Yes Required value.

sdcard.SDCard().flush() -> bool

Flush buffered data to the card.

sdcard.SDCard().seek(offset, origin="start") -> bool

Move the file position. Origins are "start", "current", and "end".

Parameters
Name Type Pass as Required Description
offset float positional or keyword Yes Required value.
origin any positional or keyword No Optional value. Defaults to "start".

sdcard.SDCard().tell() -> int

Return the current byte position.

sdcard.SDCard().size() -> int

Return the file size in bytes.

sdcard.SDCard().close() -> bool

Flush and close the file.