filesystems
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 (SD Card).
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 supportvia menuconfig.
The settings are also valid for SD Card 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.
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.
| ESP32 pin | SD name | SD pin | µSD pin | SPI pin | Notes |
|---|---|---|---|---|---|
| GPIO14 (MTMS) | CLK | 5 | 5 | SCK | 10k pullup in SD mode |
| GPIO15 (MTDO) | CMD / DI | 2 | 3 | MOSI | 10k pullup, both in SD and SPI modes |
| GPIO2 | DAT0 / DO | 7 | 7 | MISO | 10k pullup in SD mode (Note) |
| GPIO4 | DAT1 | 8 | 8 | N/C | not used in 1-line SD mode; 10k pullup in 4-line SD mode |
| GPIO12 (MTDI) | DAT2 | 9 | 1 | N/C | not used in 1-line SD mode; 10k pullup in 4-line SD mode (Note) |
| GPIO13 (MTCK) | DAT3 | 1 | 2 | CS | not used in 1-line SD mode, card's DAT3 pin must have a 10k pullup |
| N/C | CD | Card Detect, optional, not used by driver | |||
| N/C | WP | Write Protect, optional, not used by driver | |||
| VDD (3.3V) | VDD | 4 | 4 | ||
| GND | GND VSS VSS1,VSS2 |
3&6 | 6 |
SD card pinout / µSD card 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 agpio_pullup_en(GPIO_NUM_12);call. This is handled by SD Card 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
GPIO2 pin is used as a bootstrapping pin, and should be low to enter UART download mode.
One way to do this is to connect GPIO0 and GPIO2 using a jumper, and then the auto-reset circuit on most development boards will pull GPIO2 low along with GPIO0, when entering download mode.
Some boards have pulldown and/or LED on GPIO2. LED is usually ok, but pulldown will interfere with D0 signals and must be removed. Check the schematic of your development board for anything connected to GPIO2.
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 SD Card, the sd card interface can be configured using the following method:
For mode argument use one of the constants uos.SDMODE_1LINE, uos.SDMODE_4LINE or uos.SDMODE_SPI
If SPI mode is selected, clk, mosi, miso, cs arguments are mandatory, optionally spihost can be set to VSPI_HOST (2, default) or HSPI_HOST (1).
The default SPI speed is 20 MHz (this results in reported SD card speed of 25 MHz which is in fact number of bytes per second, the card reported speed is always 25 or 50 MHz).
On some boards that speed is to high for reliable communication with the sd card (this is the case with Adafruit Feather wing).
The different SPI speed can be selected using the maxspeed argument. Allowed values are 8 ~ 40, the speed in MHz.
In 1LINE and 4LINE SD mode use maxspeed=40 to enable SDCard Hi-speed mode (40MHz clock, 50 MB/s).
If this method is not executed, sd card interface will be configured according to the defaults configured via menuconfig.
# SD Card configuration for M5Stack
uos.sdconfig(uos.SDMODE_SPI, clk=18, mosi=23, miso=19, cs=4)
# SD Card configuration for Adafruit Feather wing
uos.sdconfig(uos.SDMODE_SPI, clk=5, mosi=18, miso=19, cs=14, maxspeed=16)
>>> 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
>>> When building/flashing file system image always use the the same flash and file system related BUILD.sh options as for building the firmware.
It is recommended to flash the file system image first, than to flash the firmware.
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/internalfs_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/internalfs_image.img to ESP32
You must manualy copy the created FS image from build directory to components/spiffs_image/internalfs_image.img
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 FatFS into components/internalfs_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/internalfs_image/internalfs_image.img to ESP32
You must manualy copy the created FS image from build directory to components/spiffs_image/internalfs_image.img
Prepared image file can be flashed to ESP32, if not flashed, filesystem will be formated after first boot.
LittleFS image can be prepared on host and flashed to ESP32:
Copy the files to be included on LittleFS into components/internalfs_image/image/ directory. Subdirectories can also be added.
Execute:
./BUILD.sh makelfsfs
to create FatFS image in build directory without flashing to ESP32
Execute:
./BUILD.sh flashlfsfs
to create FatFS image in build directory and flash it to ESP32
Execute:
./BUILD.sh copylfsfs
to flash the default FatFS image components/fatfs_image/internalfs_image.img to ESP32
You must manualy copy the created FS image from build directory to components/spiffs_image/internalfs_image.img
