feature(sdcard_example): Add SD Card operating with ESP-Hosted example

- Added an example showing the SD Card operating with ESP-Hosted on a ESP32-P4, using SDIO as ESP-Hosted transport.
- Add dummy init and deinit function for host of the SD card

Co-authored-by: yanke <yanke2@espressif.com>

Author: 2 people

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.6.5
+
+### Features
+
+- Add example showing concurrent use of a SD Card and ESP-Hosted.
+
 ## 2.6.4
 
 - Fix the esp_wifi_deinit() call from host

examples/host_sdcard_with_hosted/CMakeLists.txt

@@ -0,0 +1,9 @@
+# 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.22)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+# "Trim" the build. Include the minimal set of components, main, and anything it depends on.
+idf_build_set_property(MINIMAL_BUILD ON)
+
+project(sd_card)

examples/host_sdcard_with_hosted/README.md

@@ -0,0 +1,164 @@
+| Supported Hosts | ESP32-P4 | ESP32-S3 |
+|-----------------|----------|----------|
+
+# SD Card (SDMMC) with ESP-Hosted example
+
+> [!IMPORTANT]
+> The ESP-IDF `master` branch has an issue that prevents the SD card and ESP-Hosted from working together when both are using SDMMC. See [ESP-IDF Issue 16233](https://github.com/espressif/esp-idf/issues/16233) for more information. This code contains a workaround for this issue.
+
+This example demonstrates how to use an SD card on an ESP32-P4 dev board when ESP-Hosted is using SDIO to communicate with the on-board ESP32-C6. It has been modified from the standard [ESP-IDF SD Card example](https://github.com/espressif/esp-idf/tree/master/examples/storage/sd_card/sdmmc).
+
+This example does the following steps:
+
+1. Initialise ESP-Hosted and Wi-Fi
+1. Use an "all-in-one" `esp_vfs_fat_sdmmc_mount` function to:
+    - initialize SDMMC peripheral,
+    - probe and initialize an SD card,
+    - mount FAT filesystem using FATFS library
+    - register FAT filesystem in VFS, enabling C standard library and POSIX functions to be used.
+1. Print information about the card, such as name, type, capacity, and maximum supported frequency.
+1. Perform a Wi-Fi Scan
+1. Create a file using `fopen` and write to it using `fprintf`.
+1. Rename the file. Before renaming, check if destination file already exists using `stat` function, and remove it using `unlink` function.
+1. Open renamed file for reading, read back the line, and print it to the terminal.
+1. Perform another Wi-Fi Scan
+
+This example supports SD (SDSC, SDHC, SDXC) cards and eMMC chips.
+
+## Hardware
+
+This example requires an ESP32-P4 development board with an SD card slot and an SD card. On this board, the SD card slot is assigned to SDMMC Slot 0, while the on-board ESP32-C6 is connected to the ESP32-P4 on SDMMC Slot 1.
+
+Although it is possible to connect an SD card breakout adapter, keep in mind that connections using breakout cables are often unreliable and have poor signal integrity. You may need to use lower clock frequency when working with SD card breakout adapters.
+
+This example doesn't utilize card detect (CD) and write protect (WP) signals from SD card slot.
+
+### Pin assignments for SDMMC Slot 0 on ESP32-P4
+
+On ESP32-P4, SDMMC Slot 0 GPIO pins cannot be customized. The GPIO assigned in the example should not be modified.
+
+The table below lists the default pin assignments.
+
+ESP32-P4 pin  | SD card pin | Notes
+--------------|-------------|------------
+GPIO43        | CLK         | 10k pullup
+GPIO44        | CMD         | 10k pullup
+GPIO39        | D0          | 10k pullup
+GPIO40        | D1          | not used in 1-line SD mode; 10k pullup in 4-line mode
+GPIO41        | D2          | not used in 1-line SD mode; 10k pullup in 4-line mode
+GPIO42        | D3          | not used in 1-line SD mode, but card's D3 pin must have a 10k pullup
+
+### 4-line and 1-line SD modes
+
+By default, this example uses 4 line SD mode, utilizing 6 pins: CLK, CMD, D0 - D3. It is possible to use 1-line mode (CLK, CMD, D0) by changing "SD/MMC bus width" in the example configuration menu (see `CONFIG_EXAMPLE_SDMMC_BUS_WIDTH_1`).
+
+Note that even if card's D3 line is not connected to the ESP chip, it still has to be pulled up, otherwise the card will go into SPI protocol mode.
+
+## How to use example
+
+### 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
+
+A Wi-Fi Scan is performed before and after accessing the SD Card. This shows that both SDMMC Slots work as expected.
+
+```
+I (2103) transport: Received INIT event from ESP32 peripheral
+I (2103) transport: EVENT: 12
+I (2113) transport: Identified slave [esp32c6]
+I (2113) transport: EVENT: 11
+I (2113) transport: capabilities: 0xd
+I (2123) transport: Features supported are:
+I (2123) transport:      * WLAN
+I (2123) transport:        - HCI over SDIO
+I (2133) transport:        - BLE only
+I (2133) transport: EVENT: 13
+I (2133) transport: ESP board type is : 13
+
+I (2143) transport: Base transport is set-up, TRANSPORT_TX_ACTIVE
+I (2143) H_API: Transport active
+I (2143) transport: Slave chip Id[12]
+I (2153) transport: raw_tp_dir[-], flow_ctrl: low[60] high[80]
+I (2153) transport: transport_delayed_init
+I (2163) esp_cli: Remove any existing deep_sleep cmd in cli
+I (2163) esp_cli: Registering command: crash
+I (2173) esp_cli: Registering command: reboot
+I (2173) esp_cli: Registering command: mem-dump
+I (2173) esp_cli: Registering command: task-dump
+I (2183) esp_cli: Registering command: cpu-dump
+I (2183) esp_cli: Registering command: heap-trace
+I (2193) esp_cli: Registering command: sock-dump
+I (2193) esp_cli: Registering command: host-power-save
+I (2203) hci_stub_drv: Host BT Support: Disabled
+I (2203) H_SDIO_DRV: Received INIT event
+I (2203) H_SDIO_DRV: Event type: 0x22
+I (2213) H_SDIO_DRV: Write thread started
+I (2643) example: Initializing SD card
+I (2643) example: Using SDMMC peripheral
+W (2643) ldo: The voltage value 0 is out of the recommended range [500, 2700]
+I (2643) RPC_WRAP: ESP Event: wifi station started
+I (2653) RPC_WRAP: ESP Event: wifi station started
+I (2743) example: Mounting filesystem
+I (2743) sdmmc_periph: sdmmc_host_init: SDMMC host already initialized, skipping init flow
+I (2953) example: Filesystem mounted
+I (2953) example: Doing Wi-Fi Scan
+I (3653) rpc_req: Scan start Req
+
+W (3653) rpc_rsp: Hosted RPC_Resp [0x21a], uid [4], resp code [12298]
+I (6183) RPC_WRAP: ESP Event: StaScanDone
+I (6203) example: Total APs scanned = 11, actual AP number ap_info holds = 10
+Name: SD16G
+Type: SDHC
+Speed: 40.00 MHz (limit: 40.00 MHz)
+Size: 14868MB
+CSD: ver=2, sector_size=512, capacity=30449664 read_bl_len=9
+SSR: bus_width=4
+I (6213) example: Opening file /sdcard/hello.txt
+I (6303) example: File written
+I (6323) example: Renaming file /sdcard/hello.txt to /sdcard/foo.txt
+I (6333) example: Reading file /sdcard/foo.txt
+I (6333) example: Read from file: 'Hello SD16G!'
+I (6333) example: Opening file /sdcard/nihao.txt
+I (6353) example: File written
+I (6353) example: Reading file /sdcard/nihao.txt
+I (6363) example: Read from file: 'Nihao SD16G!'
+I (6363) example: Card unmounted
+I (6363) example: Doing another Wi-Fi Scan
+I (6363) rpc_req: Scan start Req
+
+I (8863) RPC_WRAP: ESP Event: StaScanDone
+I (8883) example: Total APs scanned = 11, actual AP number ap_info holds = 10
+I (8883) main_task: Returned from app_main()
+
+Done
+```
+
+## Troubleshooting
+
+### Card fails to initialize with `sdmmc_init_sd_scr: send_scr (1) returned 0x107` error
+
+Check connections between the card and the ESP32. For example, if you have disconnected GPIO2 to work around the flashing issue, connect it back and reset the ESP32 (using a button on the development board, or by pressing Ctrl-T Ctrl-R in IDF Monitor).
+
+### Card fails to initialize with `sdmmc_check_scr: send_scr returned 0xffffffff` error
+
+Connections between the card and the ESP32 are too long for the frequency used. Try using shorter connections, or try reducing the clock speed of SD interface.
+
+### Failure to mount filesystem
+
+```
+example: Failed to mount filesystem.
+```
+The example will be able to mount only cards formatted using FAT32 filesystem.

examples/host_sdcard_with_hosted/main/CMakeLists.txt

@@ -0,0 +1,14 @@
+set(srcs "sd_card_example_main.c"
+    "sd_card_functions.c"
+    "esp_hosted_wifi.c")
+
+idf_component_register(SRCS ${srcs}
+                       INCLUDE_DIRS "."
+                       REQUIRES fatfs esp_wifi
+                       WHOLE_ARCHIVE)
+
+if(NOT CONFIG_SOC_SDMMC_HOST_SUPPORTED)
+    fail_at_build_time(sdmmc ""
+                             "Only ESP32, ESP32-S3, ESP32-P4 targets are supported."
+                             "Please refer README.md for more details")
+endif()

examples/host_sdcard_with_hosted/main/Kconfig.projbuild

@@ -0,0 +1,92 @@
+menu "SD/MMC Example Configuration"
+
+    config EXAMPLE_SDMMC_SLOT_RANGE_MAX
+	    int
+		default 0 if IDF_TARGET_ESP32P4
+		default 1 if IDF_TARGET_ESP32S3
+
+    config EXAMPLE_SDMMC_SLOT
+        int "SD/MMC slot to use"
+        default 0
+		range 0 EXAMPLE_SDMMC_SLOT_RANGE_MAX
+        help
+            Select the slot to use
+            For ESP32-P4, only Slot 0 for SD Card is available as ESP-Hosted uses Slot 1
+
+    choice EXAMPLE_SDMMC_BUS_WIDTH
+        prompt "SD/MMC bus width"
+        default EXAMPLE_SDMMC_BUS_WIDTH_4
+        help
+            Select the bus width of SD or MMC interface.
+            Note that even if 1 line mode is used, D3 pin of the SD card must have a pull-up resistor connected.
+            Otherwise the card may enter SPI mode, the only way to recover from which is to cycle power to the card.
+
+        config EXAMPLE_SDMMC_BUS_WIDTH_4
+            bool "4 lines (D0 - D3)"
+
+        config EXAMPLE_SDMMC_BUS_WIDTH_1
+            bool "1 line (D0)"
+    endchoice
+
+    config EXAMPLE_PIN_CARD_POWER_RESET
+        int
+        depends on SOC_SDMMC_IO_POWER_EXTERNAL
+        prompt "Card Power Reset"
+        default 45
+
+    config EXAMPLE_PIN_CMD
+        int
+        prompt "CMD GPIO number" if SOC_SDMMC_USE_GPIO_MATRIX
+        default 35 if IDF_TARGET_ESP32S3
+        range 44 44 if IDF_TARGET_ESP32P4
+
+    config EXAMPLE_PIN_CLK
+        int
+        prompt "CLK GPIO number" if SOC_SDMMC_USE_GPIO_MATRIX
+        default 36 if IDF_TARGET_ESP32S3
+        range 43 43 if IDF_TARGET_ESP32P4
+
+    config EXAMPLE_PIN_D0
+        int
+        prompt "D0 GPIO number" if SOC_SDMMC_USE_GPIO_MATRIX
+        default 37 if IDF_TARGET_ESP32S3
+        range 39 39 if IDF_TARGET_ESP32P4
+
+    if EXAMPLE_SDMMC_BUS_WIDTH_4
+
+        config EXAMPLE_PIN_D1
+            int
+            prompt "D1 GPIO number" if SOC_SDMMC_USE_GPIO_MATRIX
+            default 38 if IDF_TARGET_ESP32S3
+            range 40 40 if IDF_TARGET_ESP32P4
+
+        config EXAMPLE_PIN_D2
+            int
+            prompt "D2 GPIO number" if SOC_SDMMC_USE_GPIO_MATRIX
+            default 33 if IDF_TARGET_ESP32S3
+            range 41 41 if IDF_TARGET_ESP32P4
+
+        config EXAMPLE_PIN_D3
+            int
+            prompt "D3 GPIO number" if SOC_SDMMC_USE_GPIO_MATRIX
+            default 34 if IDF_TARGET_ESP32S3
+            range 42 42 if IDF_TARGET_ESP32P4
+
+    endif  # EXAMPLE_SDMMC_BUS_WIDTH_4
+
+    config EXAMPLE_SD_PWR_CTRL_LDO_INTERNAL_IO
+        depends on SOC_SDMMC_IO_POWER_EXTERNAL
+        bool "SD power supply comes from internal LDO IO (READ HELP!)"
+        default y
+        help
+            Only needed when the SD card is connected to specific IO pins which can be used for high-speed SDMMC.
+            Please read the schematic first and check if the SD VDD is connected to any internal LDO output.
+            Unselect this option if the SD card is powered by an external power supply.
+
+    config EXAMPLE_SD_PWR_CTRL_LDO_IO_ID
+        depends on SOC_SDMMC_IO_POWER_EXTERNAL && EXAMPLE_SD_PWR_CTRL_LDO_INTERNAL_IO
+        int "LDO ID"
+        default 4 if IDF_TARGET_ESP32P4
+        help
+            Please read the schematic first and input your LDO ID.
+endmenu

examples/host_sdcard_with_hosted/main/esp_hosted_wifi.c

@@ -0,0 +1,45 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+/**
+ * ESP-Hosted Wi-Fi Functions for SD Card Example
+ */
+#include <string.h>
+
+#include "esp_check.h"
+#include "esp_log.h"
+#include "esp_wifi.h"
+
+#include "esp_hosted_wifi.h"
+
+static const char *TAG = "sd_card_wifi";
+
+void init_wifi(void)
+{
+    ESP_ERROR_CHECK(esp_netif_init());
+    ESP_ERROR_CHECK(esp_event_loop_create_default());
+    esp_netif_t *sta_netif = esp_netif_create_default_wifi_sta();
+    assert(sta_netif);
+
+    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
+    ESP_ERROR_CHECK(esp_wifi_init(&cfg));
+
+    ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA));
+    ESP_ERROR_CHECK(esp_wifi_start());
+}
+
+void do_wifi_scan(void)
+{
+    uint16_t number = 10;
+    wifi_ap_record_t ap_info[number];
+    uint16_t ap_count = 0;
+    memset(ap_info, 0, sizeof(ap_info));
+
+    esp_wifi_scan_start(NULL, true);
+
+    ESP_ERROR_CHECK(esp_wifi_scan_get_ap_num(&ap_count));
+    ESP_ERROR_CHECK(esp_wifi_scan_get_ap_records(&number, ap_info));
+    ESP_LOGI(TAG, "Total APs scanned = %u, actual AP number ap_info holds = %u", ap_count, number);
+}

examples/host_sdcard_with_hosted/main/esp_hosted_wifi.h

@@ -0,0 +1,12 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+#ifndef __ESP_HOSTED_WIFI_H__
+#define __ESP_HOSTED_WIFI_H__
+
+void init_wifi(void);
+void do_wifi_scan(void);
+
+#endif

examples/host_sdcard_with_hosted/main/idf_component.yml

@@ -0,0 +1,9 @@
+dependencies:
+  espressif/esp_wifi_remote:
+    version: "*"
+    rules:
+      - if: "target in [esp32p4]"
+  espressif/esp_hosted:
+    version: "*"
+    rules:
+      - if: "target in [esp32p4]"

examples/host_sdcard_with_hosted/main/sd_card_example_common.h

@@ -0,0 +1,14 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+#ifndef __SD_CARD_EXAMPLE_COMMON_H__
+#define __SD_CARD_EXAMPLE_COMMON_H__
+
+#define EXAMPLE_MAX_CHAR_SIZE    64
+
+// enable this to perform Wi-Fi functions in example
+#define EXAMPLE_USE_WIFI 1
+
+#endif