Skip to content

filesystems

Jump to bottom
Boris Lovosevic edited this page Mar 21, 2018 · 18 revisions

File systems used in this MicroPython implementation

This implementation of MicroPython uses native esp-idf support for file systems and esp-idf VFS.

Two file systems are implemented: internal (Flash file system) and external (SDCard).

Internal file system

The type and size of the Flash file system can be configured before the build using menuconfig
→ MicroPython → File systems.

  • Three file system types are available: SPIFFS, FatFS and LittleFS.
    FatFS uses esp-idf wear leveling
  • Maximum number of opened files can be configured from menuconfig
  • Start address in Flash and file system size are configured automatically from BUILD.sh based on Flash size, partition layout and command line options
  • If using FatFS, Code Page, Long file name support and max long file name length can be configured in
    → Component config → FAT Filesystem support via menuconfig.
    The settings are also valid for SDCard file system (which must be FAT32).

Internal file system is mounted automatically at boot in /flash directory and cannot be unmounted (it is automatically unmounted before reset or deepsleep).

If the internal file system is not formated, it will be formated automatically on first boot and boot.py file will be created.

External file system

SD card can be configured via menuconfig (→ MicroPython → SD Card configuration).

SD card can be connected in SD mode (1-line or 4-line) or in SPI mode.

In SD mode the dedicated sdio pins must be used.
In SPI mode the default pins used for MOSI, MISO, SCK and CS can be selected via menuconfig.
The pins can also be configured from MicroPython, before mount, using the uos.sdconfig method.

SDCard connection to ESP32

ESP32 pin SD name SD pin uSD pin SPI pin Notes
GPIO14 (MTMS) CLK 5 5 SCK 10k pullup in SD mode
GPIO15 (MTDO) CMD 2 3 MOSI 10k pullup, both in SD and SPI modes
GPIO2 D0 7 7 MISO 10k pullup in SD mode,
pull low to go into download mode
GPIO4 D1 8 8 N/C not used in 1-line SD mode;
10k pullup in 4-line SD mode
GPIO12 (MTDI) D2 9 1 N/C not used in 1-line SD mode;
10k pullup in 4-line SD mode (Note)
GPIO13 (MTCK) D3 1 2 CS not used in 1-line SD mode,
card's D3 pin must have a 10k pullup
N/C CD optional, not used
N/C WP optional, not used
VDD 3.3V VSS 4 4
GND GND GND 3&6 6

SDcard pinout / uSDcard pinout (Contacts view):

Note:
GPIO12 (MTDI) is used as a bootstrapping pin to select output voltage of an internal regulator which powers the flash chip (VDD_SDIO). This pin has an internal pulldown so if left unconnected it will read low at reset (selecting default 3.3V operation).
When adding a pullup to this pin for SD card operation, consider the following:

  • For boards which don't use the internal regulator (VDD_SDIO) to power the flash, GPIO12 can be pulled high.
  • For boards which use 1.8V flash chip (e.g. WROVER), GPIO12 needs to be pulled high at reset.
    This is fully compatible with SD card operation.
  • On boards which use the internal regulator and a 3.3V flash chip (e.g. ESP-WROOM-32), GPIO12 must be low at reset.
    This is incompatible with SD card operation.
    In most cases, external pullup can be omitted and an internal pullup can be enabled using a gpio_pullup_en(GPIO_NUM_12); call. This is handled by SDCard driver.

    Another option is to burn the flash voltage selection efuses.
    This will permanently select 3.3V output voltage for the internal regulator, and GPIO12 will not be used as a bootstrapping pin.
    Then it is safe to connect a pullup resistor to GPIO12.
    This option is suggested for production use.
    <esp-idf_path>/components/esptool_py/esptool/espefuse.py set_flash_voltage 3.3V

SD card must be formated to FAT32 format before it can be used in MicroPython. At the moment there is no option to format SD card from MicroPython.

External file system can be mounted/unmounted using the following functions from uos module:

Method Notes
uos.mountsd([chdir]) Initialize SD card and mount file system on /sd directory. If optional argument chdir is set to True, directory is changed to /sd after successful mount
uos.umountsd() Unmount SD card. Directory is changed to /flash after successful unmount

Before mounting the SDCard, the sdcard interface can be configured using the following method:

uos.sdconfig(mode [,clk, mosi, miso, cs])

For mode argument use one of the constants uos.1LINE, uos.4LINE or uos.SPI

If SPI mode is selected, clk, mosi, miso, cs arguments are mandatory.

If this method is not executed, sdcard interface will be configured according to the defaults configured via menuconfig

# SDCard configuration for M5Stack
uos.sdconfig(uos.SDMODE_SPI, clk=18, mosi=23, miso=19, cs=4)
# SDCard configuration for Adafruit Feather wing
uos.sdconfig(uos.SDMODE_SPI, clk=5, mosi=18, miso=19, cs=14)
>>> os.mountsd()
---------------------
 Mode: SPI
 Name: SU08G
 Type: SDHC/SDXC
Speed: default speed (25 MHz)
 Size: 7580 MB
  CSD: ver=1, sector_size=512, capacity=15523840 read_bl_len=9
  SCR: sd_spec=2, bus_width=5

>>>



Using prepared file system images

At the moment, there is no support for creating and flashing file system images for LittleFS

Using prepared SPIFFS image

Prepared image file can be flashed to ESP32, if not flashed, filesystem will be formated after first boot.

SFPIFFS image can be prepared on host and flashed to ESP32:

Copy the files to be included on spiffs into components/spiffs_image/image/ directory. Subdirectories can also be added.

Execute: ./BUILD.sh makefs to create spiffs image in build directory without flashing to ESP32

Execute: ./BUILD.sh flashfs to create spiffs image in build directory and flash it to ESP32

Execute: ./BUILD.sh copyfs to flash the default spiffs image components/spiffs_image/spiffs_image.img to ESP32

Using prepared FatFS image

Prepared image file can be flashed to ESP32, if not flashed, filesystem will be formated after first boot.

FatFS image can be prepared on host and flashed to ESP32:

Copy the files to be included on spiffs into components/fatfs_image/image/ directory. Subdirectories can also be added.

Execute: ./BUILD.sh makefatfs to create FatFS image in build directory without flashing to ESP32

Execute: ./BUILD.sh flashfatfs to create FatFS image in build directory and flash it to ESP32

Execute: ./BUILD.sh copyfatfs to flash the default FatFS image components/fatfs_image/fatfs_image.img to ESP32

Content

Building

Downloads

Modules

Frozen Modules

Python Examples

Clone this wiki locally