diff --git a/.gitlab/ci/target-test.yml b/.gitlab/ci/target-test.yml index c599421399..d861b83c15 100644 --- a/.gitlab/ci/target-test.yml +++ b/.gitlab/ci/target-test.yml @@ -284,6 +284,26 @@ example_test_C3_FLASH_ENC_OTA: - ESP32C3 - Example_Flash_Encryption_OTA_WiFi +example_test_ESP32_SDSPI: + extends: .example_test_esp32_template + tags: + - ESP32 + - UT_T1_SPIMODE + +# uncomment when ESP32S2 & ESP32C3 runners with external SD connected over SPI are available +# ensure the runners have required tags created +# +#example_test_ESP32S2_SDSPI: +# extends: .example_test_esp32s2_template +# tags: +# - ESP32S2 +# - UT_T1_SPIMODE +# +#example_test_ESP32C3_SDSPI: +# extends: .example_test_esp32c3_template +# tags: +# - ESP32C3 +# - UT_T1_SPIMODE .test_app_template: extends: .target_test_job_template diff --git a/examples/storage/sd_card/sd_card_example_test.py b/examples/storage/sd_card/sd_card_example_test.py deleted file mode 100644 index dc380a3d69..0000000000 --- a/examples/storage/sd_card/sd_card_example_test.py +++ /dev/null @@ -1,35 +0,0 @@ -import re - -import ttfw_idf -from tiny_test_fw import Utility - - -@ttfw_idf.idf_example_test(env_tag='UT_T1_SDMODE') -def test_examples_sd_card(env, extra_data): - - dut = env.get_dut('sd_card', 'examples/storage/sd_card') - dut.start_app() - dut.expect('example: Initializing SD card', timeout=20) - peripheral = dut.expect(re.compile(r'example: Using (\w+) peripheral'), timeout=5)[0] - Utility.console_log('peripheral {} detected'.format(peripheral)) - assert peripheral in ('SDMMC', 'SPI') - - # These lines are matched separately because of ASCII color codes in the output - name = dut.expect(re.compile(r'Name: (\w+)'), timeout=5)[0] - _type = dut.expect(re.compile(r'Type: (\S+)'), timeout=5)[0] - speed = dut.expect(re.compile(r'Speed: (\S+)'), timeout=5)[0] - size = dut.expect(re.compile(r'Size: (\S+)'), timeout=5)[0] - - Utility.console_log('Card {} {} {}MHz {} found'.format(name, _type, speed, size)) - - dut.expect_all('Opening file', - 'File written', - 'Renaming file', - 'Reading file', - "Read from file: 'Hello {}!".format(name), - 'Card unmounted', - timeout=5) - - -if __name__ == '__main__': - test_examples_sd_card() diff --git a/examples/storage/sd_card/CMakeLists.txt b/examples/storage/sd_card/sdmmc/CMakeLists.txt similarity index 100% rename from examples/storage/sd_card/CMakeLists.txt rename to examples/storage/sd_card/sdmmc/CMakeLists.txt diff --git a/examples/storage/sd_card/Makefile b/examples/storage/sd_card/sdmmc/Makefile similarity index 100% rename from examples/storage/sd_card/Makefile rename to examples/storage/sd_card/sdmmc/Makefile diff --git a/examples/storage/sd_card/README.md b/examples/storage/sd_card/sdmmc/README.md similarity index 69% rename from examples/storage/sd_card/README.md rename to examples/storage/sd_card/sdmmc/README.md index 3fc1a101e1..290f5e6b27 100644 --- a/examples/storage/sd_card/README.md +++ b/examples/storage/sd_card/sdmmc/README.md @@ -1,4 +1,7 @@ -# SD Card example +| Supported Targets | ESP32| +| ----------------- | ---- | + +# SD Card example (SDMMC) (See the README.md file in the upper level 'examples' directory for more information about examples.) @@ -7,7 +10,7 @@ This example demonstrates how to use an SD card with an ESP device. Example does 1. Use an "all-in-one" `esp_vfs_fat_sdmmc_mount` function to: - initialize SDMMC peripheral, - probe and initialize the card connected to SD/MMC slot 1 (HS2_CMD, HS2_CLK, HS2_D0, HS2_D1, HS2_D2, HS2_D3 lines), - - mount FAT filesystem using FATFS library (and format card, if the filesystem can not be mounted), + - mount FAT filesystem using FATFS library (and format card, if the filesystem cannot be mounted), - register FAT filesystem in VFS, enabling C standard library and POSIX functions to be used. 2. Print information about the card, such as name, type, capacity, and maximum supported frequency. 3. Create a file using `fopen` and write to it using `fprintf`. @@ -16,61 +19,23 @@ This example demonstrates how to use an SD card with an ESP device. Example does This example support SD (SDSC, SDHC, SDXC) cards and eMMC chips. -## Hardware - -### Connections for ESP32 +## Hardware connection This example runs on ESP-WROVER-KIT boards without any extra modifications required, only the SD card needs to be inserted into the slot. Other ESP32 development boards need to be connected to SD card as follows: -ESP32 pin | SD card pin | SPI pin | Notes ---------------|-------------|---------|------------ -GPIO14 (MTMS) | CLK | SCK | 10k pullup in SD mode -GPIO15 (MTDO) | CMD | MOSI | 10k pullup, both in SD and SPI modes -GPIO2 | D0 | MISO | 10k pullup in SD mode, pull low to go into download mode (see Note about GPIO2 below!) -GPIO4 | D1 | N/C | not used in 1-line SD mode; 10k pullup in 4-line SD mode -GPIO12 (MTDI) | D2 | N/C | not used in 1-line SD mode; 10k pullup in 4-line SD mode (see Note about GPIO12 below!) -GPIO13 (MTCK) | D3 | CS | not used in 1-line SD mode, but card's D3 pin must have a 10k pullup -N/C | CD | | optional, not used in the example -N/C | WP | | optional, not used in the example +ESP32 pin | SD card pin | Notes +--------------|-------------|------------ +GPIO14 (MTMS) | CLK | 10k pullup in SD mode +GPIO15 (MTDO) | CMD | 10k pullup in SD mode +GPIO2 | D0 | 10k pullup in SD mode, pull low to go into download mode (see Note about GPIO2 below!) +GPIO4 | D1 | not used in 1-line SD mode; 10k pullup in 4-line SD mode +GPIO12 (MTDI) | D2 | not used in 1-line SD mode; 10k pullup in 4-line SD mode (see Note about GPIO12 below!) +GPIO13 (MTCK) | D3 | not used in 1-line SD mode, but card's D3 pin must have a 10k pullup This example doesn't utilize card detect (CD) and write protect (WP) signals from SD card slot. -With the given pinout for SPI mode, same connections between the SD card and ESP32 can be used to test both SD and SPI modes, provided that the appropriate pullups are in place. -See [the document about pullup requirements](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/sd_pullup_requirements.html) for more details about pullup support and compatibility of modules and development boards. - -In SPI mode, pins can be customized. See the initialization of ``spi_bus_config_t`` and ``sdspi_slot_config_t`` structures in the example code. - -### Connections for ESP32-S2 - -Note that ESP32-S2 doesn't include SD Host peripheral and only supports SD over SPI. Therefore only SCK, MOSI, MISO, CS and ground pins need to be connected. - -ESP32-S2 pin | SD card pin | SPI pin | Notes ---------------|-------------|---------|------------ -GPIO14 | CLK | SCK | 10k pullup -GPIO15 | CMD | MOSI | 10k pullup -GPIO2 | D0 | MISO | 10k pullup -GPIO13 | D3 | CS | 10k pullup -N/C | CD | | optional, not used in the example -N/C | WP | | optional, not used in the example - -In SPI mode, pins can be customized. See the initialization of ``spi_bus_config_t`` and ``sdspi_slot_config_t`` structures in the example code. - -### Connections for ESP32-C3 - -Note that ESP32-C3 doesn't include SD Host peripheral and only supports SD over SPI. Therefore only SCK, MOSI, MISO, CS and ground pins need to be connected. - -ESP32-C3 pin | SD card pin | SPI pin | Notes ---------------|-------------|---------|------------ -GPIO8 | CLK | SCK | 10k pullup -GPIO9 | CMD | MOSI | 10k pullup -GPIO18 | D0 | MISO | 10k pullup -GPIO19 | D3 | CS | 10k pullup -N/C | CD | | optional, not used in the example -N/C | WP | | optional, not used in the example - -In SPI mode, pins can be customized. See the initialization of ``spi_bus_config_t`` and ``sdspi_slot_config_t`` structures in the example code. ### Note about GPIO2 (ESP32 only) @@ -98,9 +63,9 @@ This command will burn the `XPD_SDIO_TIEH`, `XPD_SDIO_FORCE`, and `XPD_SDIO_REG` `espefuse.py` has a `--do-not-confirm` option if running from an automated flashing script. -## How to use example +See [the document about pullup requirements](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/sd_pullup_requirements.html) for more details about pullup support and compatibility of modules and development boards. -SD card can be used in various modes. See below on choosing the mode to be used. +## How to use example ### 4-line and 1-line SD modes @@ -114,10 +79,6 @@ Among other things, this sets `slot_config.width = 0`, which means that SD/MMC d Note that even if card's D3 line is not connected to the ESP32, it still has to be pulled up, otherwise the card will go into SPI protocol mode. -### SPI mode - -By default, the example uses SDMMC Host peripheral to access the card using SD protocol. To use SPI peripheral instead (and SPI protocol), uncomment ``#define USE_SPI_MODE`` line in the example code. - ### Build and flash Build the project and flash it to the board, then run monitor tool to view serial output: @@ -149,17 +110,17 @@ Name: XA0E5 Type: SDHC/SDXC Speed: 20 MHz Size: 61068MB -I (7386) example: Opening file +I (7386) example: Opening file /sdcard/hello.txt I (7396) example: File written -I (7396) example: Renaming file -I (7396) example: Reading file +I (7396) example: Renaming file /sdcard/hello.txt to /sdcard/foo.txt +I (7396) example: Reading file /sdcard/foo.txt I (7396) example: Read from file: 'Hello XA0E5!' I (7396) example: Card unmounted ``` ## Troubleshooting -### Failure to upload the example +### Failure to download the example ``` Connecting........_____....._____....._____....._____....._____....._____....._____ diff --git a/examples/storage/sd_card/main/CMakeLists.txt b/examples/storage/sd_card/sdmmc/main/CMakeLists.txt similarity index 100% rename from examples/storage/sd_card/main/CMakeLists.txt rename to examples/storage/sd_card/sdmmc/main/CMakeLists.txt diff --git a/examples/storage/sd_card/main/Kconfig.projbuild b/examples/storage/sd_card/sdmmc/main/Kconfig.projbuild similarity index 100% rename from examples/storage/sd_card/main/Kconfig.projbuild rename to examples/storage/sd_card/sdmmc/main/Kconfig.projbuild diff --git a/examples/storage/sd_card/main/component.mk b/examples/storage/sd_card/sdmmc/main/component.mk similarity index 100% rename from examples/storage/sd_card/main/component.mk rename to examples/storage/sd_card/sdmmc/main/component.mk diff --git a/examples/storage/sd_card/sdmmc/main/sd_card_example_main.c b/examples/storage/sd_card/sdmmc/main/sd_card_example_main.c new file mode 100644 index 0000000000..7386d154e4 --- /dev/null +++ b/examples/storage/sd_card/sdmmc/main/sd_card_example_main.c @@ -0,0 +1,137 @@ +/* SD card and FAT filesystem example. + This example code is in the Public Domain (or CC0 licensed, at your option.) + + Unless required by applicable law or agreed to in writing, this + software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR + CONDITIONS OF ANY KIND, either express or implied. +*/ + +// This example uses SDMMC peripheral to communicate with SD card. + +#include +#include +#include +#include "esp_vfs_fat.h" +#include "sdmmc_cmd.h" +#include "driver/sdmmc_host.h" + +static const char *TAG = "example"; + +#define MOUNT_POINT "/sdcard" + + +void app_main(void) +{ + esp_err_t ret; + + // Options for mounting the filesystem. + // If format_if_mount_failed is set to true, SD card will be partitioned and + // formatted in case when mounting fails. + esp_vfs_fat_sdmmc_mount_config_t mount_config = { +#ifdef CONFIG_EXAMPLE_FORMAT_IF_MOUNT_FAILED + .format_if_mount_failed = true, +#else + .format_if_mount_failed = false, +#endif // EXAMPLE_FORMAT_IF_MOUNT_FAILED + .max_files = 5, + .allocation_unit_size = 16 * 1024 + }; + sdmmc_card_t *card; + const char mount_point[] = MOUNT_POINT; + ESP_LOGI(TAG, "Initializing SD card"); + + // Use settings defined above to initialize SD card and mount FAT filesystem. + // Note: esp_vfs_fat_sdmmc/sdspi_mount is all-in-one convenience functions. + // Please check its source code and implement error recovery when developing + // production applications. + + ESP_LOGI(TAG, "Using SDMMC peripheral"); + sdmmc_host_t host = SDMMC_HOST_DEFAULT(); + + // This initializes the slot without card detect (CD) and write protect (WP) signals. + // Modify slot_config.gpio_cd and slot_config.gpio_wp if your board has these signals. + sdmmc_slot_config_t slot_config = SDMMC_SLOT_CONFIG_DEFAULT(); + + // To use 1-line SD mode, uncomment the following line: + // slot_config.width = 1; + + // GPIOs 15, 2, 4, 12, 13 should have external 10k pull-ups. + // Internal pull-ups are not sufficient. However, enabling internal pull-ups + // does make a difference some boards, so we do that here. + gpio_set_pull_mode(15, GPIO_PULLUP_ONLY); // CMD, needed in 4- and 1- line modes + gpio_set_pull_mode(2, GPIO_PULLUP_ONLY); // D0, needed in 4- and 1-line modes + gpio_set_pull_mode(4, GPIO_PULLUP_ONLY); // D1, needed in 4-line mode only + gpio_set_pull_mode(12, GPIO_PULLUP_ONLY); // D2, needed in 4-line mode only + gpio_set_pull_mode(13, GPIO_PULLUP_ONLY); // D3, needed in 4- and 1-line modes + + ret = esp_vfs_fat_sdmmc_mount(mount_point, &host, &slot_config, &mount_config, &card); + + if (ret != ESP_OK) { + if (ret == ESP_FAIL) { + ESP_LOGE(TAG, "Failed to mount filesystem. " + "If you want the card to be formatted, set the EXAMPLE_FORMAT_IF_MOUNT_FAILED menuconfig option."); + } else { + ESP_LOGE(TAG, "Failed to initialize the card (%s). " + "Make sure SD card lines have pull-up resistors in place.", esp_err_to_name(ret)); + } + return; + } + + // Card has been initialized, print its properties + sdmmc_card_print_info(stdout, card); + + // Use POSIX and C standard library functions to work with files: + + // First create a file. + const char *file_hello = MOUNT_POINT"/hello.txt"; + + ESP_LOGI(TAG, "Opening file %s", file_hello); + FILE *f = fopen(file_hello, "w"); + if (f == NULL) { + ESP_LOGE(TAG, "Failed to open file for writing"); + return; + } + fprintf(f, "Hello %s!\n", card->cid.name); + fclose(f); + ESP_LOGI(TAG, "File written"); + + const char *file_foo = MOUNT_POINT"/foo.txt"; + + // Check if destination file exists before renaming + struct stat st; + if (stat(file_foo, &st) == 0) { + // Delete it if it exists + unlink(file_foo); + } + + // Rename original file + ESP_LOGI(TAG, "Renaming file %s to %s", file_hello, file_foo); + if (rename(file_hello, file_foo) != 0) { + ESP_LOGE(TAG, "Rename failed"); + return; + } + + // Open renamed file for reading + ESP_LOGI(TAG, "Reading file %s", file_foo); + f = fopen(file_foo, "r"); + if (f == NULL) { + ESP_LOGE(TAG, "Failed to open file for reading"); + return; + } + + // Read a line from file + char line[64]; + fgets(line, sizeof(line), f); + fclose(f); + + // Strip newline + char *pos = strchr(line, '\n'); + if (pos) { + *pos = '\0'; + } + ESP_LOGI(TAG, "Read from file: '%s'", line); + + // All done, unmount partition and disable SDMMC peripheral + esp_vfs_fat_sdcard_unmount(mount_point, card); + ESP_LOGI(TAG, "Card unmounted"); +} diff --git a/examples/storage/sd_card/sdmmc/sd_card_example_test.py b/examples/storage/sd_card/sdmmc/sd_card_example_test.py new file mode 100644 index 0000000000..3e7cc28530 --- /dev/null +++ b/examples/storage/sd_card/sdmmc/sd_card_example_test.py @@ -0,0 +1,33 @@ +import re + +import ttfw_idf +from tiny_test_fw import Utility + + +@ttfw_idf.idf_example_test(env_tag='UT_T1_SDMODE') +def test_examples_sd_card(env, extra_data): # type: (ttfw_idf.Env.Env, None ) -> None + + dut = env.get_dut('sd_card', 'examples/storage/sd_card/sdmmc') + dut.start_app() + dut.expect('example: Initializing SD card', timeout=20) + dut.expect('example: Using SDMMC peripheral', timeout=10) + + # These lines are matched separately because of ASCII color codes in the output + name = dut.expect(re.compile(r'Name: (\w+)'), timeout=10)[0] + _type = dut.expect(re.compile(r'Type: (\S+)'), timeout=10)[0] + speed = dut.expect(re.compile(r'Speed: (\S+)'), timeout=10)[0] + size = dut.expect(re.compile(r'Size: (\S+)'), timeout=10)[0] + + Utility.console_log('Card {} {} {}MHz {} found'.format(name, _type, speed, size)) + + dut.expect_all('Opening file /sdcard/hello.txt', + 'File written', + 'Renaming file /sdcard/hello.txt to /sdcard/foo.txt', + 'Reading file /sdcard/foo.txt', + "Read from file: 'Hello {}!'".format(name), + 'Card unmounted', + timeout=10) + + +if __name__ == '__main__': + test_examples_sd_card() diff --git a/examples/storage/sd_card/sdkconfig.ci b/examples/storage/sd_card/sdmmc/sdkconfig.ci similarity index 100% rename from examples/storage/sd_card/sdkconfig.ci rename to examples/storage/sd_card/sdmmc/sdkconfig.ci diff --git a/examples/storage/sd_card/sdspi/CMakeLists.txt b/examples/storage/sd_card/sdspi/CMakeLists.txt new file mode 100644 index 0000000000..00153c74c9 --- /dev/null +++ b/examples/storage/sd_card/sdspi/CMakeLists.txt @@ -0,0 +1,6 @@ +# The following lines of boilerplate have to be in your project's CMakeLists +# in this exact order for cmake to work correctly +cmake_minimum_required(VERSION 3.5) + +include($ENV{IDF_PATH}/tools/cmake/project.cmake) +project(sd_card) diff --git a/examples/storage/sd_card/sdspi/Makefile b/examples/storage/sd_card/sdspi/Makefile new file mode 100644 index 0000000000..2d047609a9 --- /dev/null +++ b/examples/storage/sd_card/sdspi/Makefile @@ -0,0 +1,8 @@ +# +# This is a project Makefile. It is assumed the directory this Makefile resides in is a +# project subdirectory. +# + +PROJECT_NAME := sd_card + +include $(IDF_PATH)/make/project.mk diff --git a/examples/storage/sd_card/sdspi/README.md b/examples/storage/sd_card/sdspi/README.md new file mode 100644 index 0000000000..bfa49dc053 --- /dev/null +++ b/examples/storage/sd_card/sdspi/README.md @@ -0,0 +1,121 @@ +# SD Card example (SDSPI) + +(See the README.md file in the upper level 'examples' directory for more information about examples.) + +This example demonstrates how to use an SD card with an ESP device. Example does the following steps: + +1. Use an "all-in-one" `esp_vfs_fat_sdspi_mount` function to: + - initialize SDSPI peripheral, + - probe and initialize the card connected to SPI bus (DMA channel 1, MOSI, MISO and CLK lines, chip-specific SPI host id), + - mount FAT filesystem using FATFS library (and format card, if the filesystem cannot be mounted), + - register FAT filesystem in VFS, enabling C standard library and POSIX functions to be used. +2. Print information about the card, such as name, type, capacity, and maximum supported frequency. +3. Create a file using `fopen` and write to it using `fprintf`. +4. Rename the file. Before renaming, check if destination file already exists using `stat` function, and remove it using `unlink` function. +5. Open renamed file for reading, read back the line, and print it to the terminal. + +This example support SD (SDSC, SDHC, SDXC) cards. + +## Hardware + +### Connections for ESP32 and ESP32-S2 + +This example runs on ESP-WROVER-KIT boards without any extra modifications required, only the SD card needs to be inserted into the slot. + +Other ESP32 development boards need to be connected to SD card as follows: + +ESP32(S2) pin | SD card pin | SPI pin | Notes +--------------|-------------|---------|------------ +GPIO2 | D0 | MISO | +GPIO13 (MTCK) | D3 | CS | +GPIO14 (MTMS) | CLK | SCK | +GPIO15 (MTDO) | CMD | MOSI | 10k pullup + +This example doesn't utilize card detect (CD) and write protect (WP) signals from SD card slot. + +In SPI mode, pins can be customized. See the initialization of ``spi_bus_config_t`` and ``sdspi_slot_config_t`` structures in the example code. +Some boards require specific manipulation to enable UART Download mode (GPIO2 low) - eg ESP32-Azure IoT Kit needs KEY_IO0 pressed down for the time of firmware flashing operation (sets IO0 and IO2 low). See troubleshooting section for more details + +It is recommended to get familiar with [the document about pullup requirements](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/sd_pullup_requirements.html) to understand Pullup/down resistor support and compatibility of various ESP modules and development boards. + + +### Connections for ESP32-C3 + +Note that ESP32-C3 doesn't include SD Host peripheral and only supports SD over SPI. Therefore only SCK, MOSI, MISO, CS and ground pins need to be connected. + +ESP32-C3 pin | SD card pin | SPI pin | Notes +--------------|-------------|---------|------------ +GPIO8 | CLK | SCK | +GPIO9 | CMD | MOSI | 10k pullup +GPIO18 | D0 | MISO | +GPIO19 | D3 | CS | + +In SPI mode, pins can be customized. See the initialization of ``spi_bus_config_t`` and ``sdspi_slot_config_t`` structures in the example code. + +### Build and flash + +Build the project and flash it to the board, then run monitor tool to view serial output: + +``` +idf.py -p PORT flash monitor +``` + +(Replace PORT with serial port name.) + +(To exit the serial monitor, type ``Ctrl-]``.) + +See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. + + +## Example output + +Here is an example console output. In this case a 128MB SDSC card was connected, and `EXAMPLE_FORMAT_IF_MOUNT_FAILED` menuconfig option enabled. Card was unformatted, so the initial mount has failed. Card was then partitioned, formatted, and mounted again. + +``` +I (336) example: Initializing SD card +I (336) example: Using SPI peripheral +I (336) gpio: GPIO[13]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0 +W (596) vfs_fat_sdmmc: failed to mount card (13) +W (596) vfs_fat_sdmmc: partitioning card +W (596) vfs_fat_sdmmc: formatting card, allocation unit size=16384 +W (7386) vfs_fat_sdmmc: mounting again +Name: XA0E5 +Type: SDHC/SDXC +Speed: 20 MHz +Size: 61068MB +I (7386) example: Opening file /sdcard/hello.txt +I (7396) example: File written +I (7396) example: Renaming file /sdcard/hello.txt to /sdcard/foo.txt +I (7396) example: Reading file /sdcard/foo.txt +I (7396) example: Read from file: 'Hello XA0E5!' +I (7396) example: Card unmounted +``` + +## Troubleshooting + +### Failure to mount filesystem + +``` +example: Failed to mount filesystem. If you want the card to be formatted, set the EXAMPLE_FORMAT_IF_MOUNT_FAILED menuconfig option. +``` +The example will be able to mount only cards formatted using FAT32 filesystem. If the card is formatted as exFAT or some other filesystem, you have an option to format it in the example code. Enable the `EXAMPLE_FORMAT_IF_MOUNT_FAILED` menuconfig option, then build and flash the example. + + +### Unable to download the example BIN (or serial port not available) +``` +After the first successful flashing of the example firmware, it is not possible to flash again. +(Download mode not activated when running idf.py (==esptool.py) or the board's serial port disappears completely) +``` + +Some boards require specific handling to activate the Download mode after a system reset, due to GPIO2 pin now being used as both SDSPI (MISO) and a bootstrapping signal for enabling UART0 Boot (low). +(For instance, the ESP32-Azure IoT Kit requires KEY_IO0 button remain pressed during whole firmware flashing operation, as it sets both GPIO0 and GPIO2 signals low). +Check you board documentation/schematics for appropriate procedure. + +An attempt to download a new firmware under this conditions may also result in the board's serial port disappearing from your PC device list - rebooting your computer should fix the issue. After your device is back, use + +`esptool --port PORT --before no_reset --baud 115200 --chip esp32 erase_flash` + +to clean your board's flash, then download your firmware properly. + + + \ No newline at end of file diff --git a/examples/storage/sd_card/sdspi/main/CMakeLists.txt b/examples/storage/sd_card/sdspi/main/CMakeLists.txt new file mode 100644 index 0000000000..39630ccc57 --- /dev/null +++ b/examples/storage/sd_card/sdspi/main/CMakeLists.txt @@ -0,0 +1,2 @@ +idf_component_register(SRCS "sd_card_example_main.c" + INCLUDE_DIRS ".") diff --git a/examples/storage/sd_card/sdspi/main/Kconfig.projbuild b/examples/storage/sd_card/sdspi/main/Kconfig.projbuild new file mode 100644 index 0000000000..0a3e447f10 --- /dev/null +++ b/examples/storage/sd_card/sdspi/main/Kconfig.projbuild @@ -0,0 +1,9 @@ +menu "SD Card Example menu" + + config EXAMPLE_FORMAT_IF_MOUNT_FAILED + bool "Format the card if mount failed" + default n + help + If this config item is set, format_if_mount_failed will be set to true and the card will be formatted if + the mount has failed. +endmenu diff --git a/examples/storage/sd_card/sdspi/main/component.mk b/examples/storage/sd_card/sdspi/main/component.mk new file mode 100644 index 0000000000..a98f634eae --- /dev/null +++ b/examples/storage/sd_card/sdspi/main/component.mk @@ -0,0 +1,4 @@ +# +# "main" pseudo-component makefile. +# +# (Uses default behaviour of compiling all source files in directory, adding 'include' to include path.) diff --git a/examples/storage/sd_card/main/sd_card_example_main.c b/examples/storage/sd_card/sdspi/main/sd_card_example_main.c similarity index 57% rename from examples/storage/sd_card/main/sd_card_example_main.c rename to examples/storage/sd_card/sdspi/main/sd_card_example_main.c index 7fa538bbd0..243370c644 100644 --- a/examples/storage/sd_card/main/sd_card_example_main.c +++ b/examples/storage/sd_card/sdspi/main/sd_card_example_main.c @@ -6,55 +6,21 @@ CONDITIONS OF ANY KIND, either express or implied. */ -#include +// This example uses SPI peripheral to communicate with SD card. + #include #include #include -#include "esp_err.h" -#include "esp_log.h" #include "esp_vfs_fat.h" -#include "driver/sdspi_host.h" -#include "driver/spi_common.h" #include "sdmmc_cmd.h" -#include "sdkconfig.h" - -#ifdef CONFIG_IDF_TARGET_ESP32 -#include "driver/sdmmc_host.h" -#endif static const char *TAG = "example"; #define MOUNT_POINT "/sdcard" -// This example can use SDMMC and SPI peripherals to communicate with SD card. -// By default, SDMMC peripheral is used. -// To enable SPI mode, uncomment the following line: - -// #define USE_SPI_MODE - -// ESP32-S2 and ESP32-C3 doesn't have an SD Host peripheral, always use SPI: -#if CONFIG_IDF_TARGET_ESP32S2 ||CONFIG_IDF_TARGET_ESP32C3 -#ifndef USE_SPI_MODE -#define USE_SPI_MODE -#endif // USE_SPI_MODE -// on ESP32-S2, DMA channel must be the same as host id -#define SPI_DMA_CHAN host.slot -#endif //CONFIG_IDF_TARGET_ESP32S2 - -// DMA channel to be used by the SPI peripheral -#ifndef SPI_DMA_CHAN -#define SPI_DMA_CHAN 1 -#endif //SPI_DMA_CHAN - -// When testing SD and SPI modes, keep in mind that once the card has been -// initialized in SPI mode, it can not be reinitialized in SD mode without -// toggling power to the card. - -#ifdef USE_SPI_MODE -// Pin mapping when using SPI mode. -// With this mapping, SD card can be used both in SPI and 1-line SD mode. -// Note that a pull-up on CS line is required in SD mode. +// Pin mapping #if CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S2 + #define PIN_NUM_MISO 2 #define PIN_NUM_MOSI 15 #define PIN_NUM_CLK 14 @@ -67,11 +33,18 @@ static const char *TAG = "example"; #define PIN_NUM_CS 19 #endif //CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S2 -#endif //USE_SPI_MODE + +#if CONFIG_IDF_TARGET_ESP32S2 ||CONFIG_IDF_TARGET_ESP32C3 +#define SPI_DMA_CHAN host.slot +#else +#define SPI_DMA_CHAN 1 +#endif + void app_main(void) { esp_err_t ret; + // Options for mounting the filesystem. // If format_if_mount_failed is set to true, SD card will be partitioned and // formatted in case when mounting fails. @@ -84,7 +57,7 @@ void app_main(void) .max_files = 5, .allocation_unit_size = 16 * 1024 }; - sdmmc_card_t* card; + sdmmc_card_t *card; const char mount_point[] = MOUNT_POINT; ESP_LOGI(TAG, "Initializing SD card"); @@ -92,28 +65,6 @@ void app_main(void) // Note: esp_vfs_fat_sdmmc/sdspi_mount is all-in-one convenience functions. // Please check its source code and implement error recovery when developing // production applications. -#ifndef USE_SPI_MODE - ESP_LOGI(TAG, "Using SDMMC peripheral"); - sdmmc_host_t host = SDMMC_HOST_DEFAULT(); - - // This initializes the slot without card detect (CD) and write protect (WP) signals. - // Modify slot_config.gpio_cd and slot_config.gpio_wp if your board has these signals. - sdmmc_slot_config_t slot_config = SDMMC_SLOT_CONFIG_DEFAULT(); - - // To use 1-line SD mode, uncomment the following line: - // slot_config.width = 1; - - // GPIOs 15, 2, 4, 12, 13 should have external 10k pull-ups. - // Internal pull-ups are not sufficient. However, enabling internal pull-ups - // does make a difference some boards, so we do that here. - gpio_set_pull_mode(15, GPIO_PULLUP_ONLY); // CMD, needed in 4- and 1- line modes - gpio_set_pull_mode(2, GPIO_PULLUP_ONLY); // D0, needed in 4- and 1-line modes - gpio_set_pull_mode(4, GPIO_PULLUP_ONLY); // D1, needed in 4-line mode only - gpio_set_pull_mode(12, GPIO_PULLUP_ONLY); // D2, needed in 4-line mode only - gpio_set_pull_mode(13, GPIO_PULLUP_ONLY); // D3, needed in 4- and 1-line modes - - ret = esp_vfs_fat_sdmmc_mount(mount_point, &host, &slot_config, &mount_config, &card); -#else ESP_LOGI(TAG, "Using SPI peripheral"); sdmmc_host_t host = SDSPI_HOST_DEFAULT(); @@ -138,15 +89,14 @@ void app_main(void) slot_config.host_id = host.slot; ret = esp_vfs_fat_sdspi_mount(mount_point, &host, &slot_config, &mount_config, &card); -#endif //USE_SPI_MODE if (ret != ESP_OK) { if (ret == ESP_FAIL) { ESP_LOGE(TAG, "Failed to mount filesystem. " - "If you want the card to be formatted, set the EXAMPLE_FORMAT_IF_MOUNT_FAILED menuconfig option."); + "If you want the card to be formatted, set the EXAMPLE_FORMAT_IF_MOUNT_FAILED menuconfig option."); } else { ESP_LOGE(TAG, "Failed to initialize the card (%s). " - "Make sure SD card lines have pull-up resistors in place.", esp_err_to_name(ret)); + "Make sure SD card lines have pull-up resistors in place.", esp_err_to_name(ret)); } return; } @@ -155,9 +105,12 @@ void app_main(void) sdmmc_card_print_info(stdout, card); // Use POSIX and C standard library functions to work with files. + // First create a file. - ESP_LOGI(TAG, "Opening file"); - FILE* f = fopen(MOUNT_POINT"/hello.txt", "w"); + const char *file_hello = MOUNT_POINT"/hello.txt"; + + ESP_LOGI(TAG, "Opening file %s", file_hello); + FILE *f = fopen(file_hello, "w"); if (f == NULL) { ESP_LOGE(TAG, "Failed to open file for writing"); return; @@ -166,42 +119,46 @@ void app_main(void) fclose(f); ESP_LOGI(TAG, "File written"); + const char *file_foo = MOUNT_POINT"/foo.txt"; + // Check if destination file exists before renaming struct stat st; - if (stat(MOUNT_POINT"/foo.txt", &st) == 0) { + if (stat(file_foo, &st) == 0) { // Delete it if it exists - unlink(MOUNT_POINT"/foo.txt"); + unlink(file_foo); } // Rename original file - ESP_LOGI(TAG, "Renaming file"); - if (rename(MOUNT_POINT"/hello.txt", MOUNT_POINT"/foo.txt") != 0) { + ESP_LOGI(TAG, "Renaming file %s to %s", file_hello, file_foo); + if (rename(file_hello, file_foo) != 0) { ESP_LOGE(TAG, "Rename failed"); return; } // Open renamed file for reading - ESP_LOGI(TAG, "Reading file"); - f = fopen(MOUNT_POINT"/foo.txt", "r"); + ESP_LOGI(TAG, "Reading file %s", file_foo); + f = fopen(file_foo, "r"); if (f == NULL) { ESP_LOGE(TAG, "Failed to open file for reading"); return; } + + // Read a line from file char line[64]; fgets(line, sizeof(line), f); fclose(f); - // strip newline - char* pos = strchr(line, '\n'); + + // Strip newline + char *pos = strchr(line, '\n'); if (pos) { *pos = '\0'; } ESP_LOGI(TAG, "Read from file: '%s'", line); - // All done, unmount partition and disable SDMMC or SPI peripheral + // All done, unmount partition and disable SPI peripheral esp_vfs_fat_sdcard_unmount(mount_point, card); ESP_LOGI(TAG, "Card unmounted"); -#ifdef USE_SPI_MODE + //deinitialize the bus after all devices are removed spi_bus_free(host.slot); -#endif } diff --git a/examples/storage/sd_card/sdspi/sd_card_example_test.py b/examples/storage/sd_card/sdspi/sd_card_example_test.py new file mode 100644 index 0000000000..0438eb105e --- /dev/null +++ b/examples/storage/sd_card/sdspi/sd_card_example_test.py @@ -0,0 +1,33 @@ +import re + +import ttfw_idf +from tiny_test_fw import Utility + + +@ttfw_idf.idf_example_test(env_tag='UT_T1_SPIMODE') +def test_examples_sd_card(env, extra_data): # type: (ttfw_idf.Env.Env, None ) -> None + + dut = env.get_dut('sd_card', 'examples/storage/sd_card/sdspi') + dut.start_app() + dut.expect('example: Initializing SD card', timeout=20) + dut.expect('example: Using SPI peripheral', timeout=20) + + # These lines are matched separately because of ASCII color codes in the output + name = dut.expect(re.compile(r'Name: (\w+)'), timeout=20)[0] + _type = dut.expect(re.compile(r'Type: (\S+)'), timeout=20)[0] + speed = dut.expect(re.compile(r'Speed: (\S+)'), timeout=20)[0] + size = dut.expect(re.compile(r'Size: (\S+)'), timeout=20)[0] + + Utility.console_log('Card {} {} {}MHz {} found'.format(name, _type, speed, size)) + + dut.expect_all('Opening file /sdcard/hello.txt', + 'File written', + 'Renaming file /sdcard/hello.txt to /sdcard/foo.txt', + 'Reading file /sdcard/foo.txt', + "Read from file: 'Hello {}!'".format(name), + 'Card unmounted', + timeout=20) + + +if __name__ == '__main__': + test_examples_sd_card() diff --git a/examples/storage/sd_card/sdspi/sdkconfig.ci b/examples/storage/sd_card/sdspi/sdkconfig.ci new file mode 100644 index 0000000000..7847e636ee --- /dev/null +++ b/examples/storage/sd_card/sdspi/sdkconfig.ci @@ -0,0 +1 @@ +CONFIG_EXAMPLE_FORMAT_IF_MOUNT_FAILED=y