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.

  • The file system can be formated as spiffs or FatFS. FatFS uses esp-idf wear leveling
  • Start address in Flash, file system size, maximum number of opened files can be configured
  • 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.
    This setting is also valid for SDCard file system.

Internal file system is mounted automatically at boot in /flash directory and cannot be unmounted.
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 fixed pins must be used.
In SPI mode the pins used for MOSI, MISO, SCK and CS can be selected via menuconfig

Using SDCard in SPI mode is not recommended.
There are known issues when using SDCard in SPI mode and Display module at the same time.


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 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 argumnts 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)



Using prepared file system images

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