ESP-IDF Programming Guide Choose target... Choose version... Get Started API Reference Hardware Reference API Guides Security Guides Migration Guides Libraries and Frameworks Contributions Guide ESP-IDF Versions Resources Copyrights and Licenses About Switch Between Languages ESP-IDF Programming Guide ESP-IDF Programming Guide Edit on GitHub ESP-IDF Programming Guide [中文] This is the documentation for Espressif IoT Development Framework (esp-idf). ESP-IDF is the official development framework for the ESP32, ESP32-S, ESP32-C, ESP32-H and ESP32-P Series SoCs. This document describes using ESP-IDF with the ESP32 SoC. To switch to a different SoC target, choose target from the dropdown in the upper left. Get Started API Reference API Guides Was this page helpful? Thank you! We received your feedback. If you have any comments, fill in Espressif Documentation Feedback Form. We value your feedback. Let us know how we can improve this page by filling in Espressif Documentation Feedback Form. Next © Copyright 2016 - 2026, Espressif Systems (Shanghai) Co., Ltd. Built with Sphinx using a theme based on Read the Docs Sphinx Theme. Download HTML ESP-IDF Programming Guide Choose target... Choose version... Get Started API Reference Hardware Reference Technical Reference Manual (PDF) Chip Datasheet (PDF) Hardware Design Guidelines SoC Errata Chip Variants Modules Development Boards Espressif KiCad Library ESP Product Selector Regulatory Certificates Chip Series Comparison User Forum (Hardware) API Guides Security Guides Migration Guides Libraries and Frameworks Contributions Guide ESP-IDF Versions Resources Copyrights and Licenses About Switch Between Languages ESP-IDF Programming Guide Hardware Reference Edit on GitHub Hardware Reference [中文] Technical Reference Manual (PDF) Chip Datasheet (PDF) Hardware Design Guidelines SoC Errata Chip Variants Modules Development Boards Espressif KiCad Library ESP Product Selector Regulatory Certificates Chip Series Comparison User Forum (Hardware) Was this page helpful? Thank you! We received your feedback. If you have any comments, fill in Espressif Documentation Feedback Form. We value your feedback. Let us know how we can improve this page by filling in Espressif Documentation Feedback Form. Previous Next © Copyright 2016 - 2026, Espressif Systems (Shanghai) Co., Ltd. Built with Sphinx using a theme based on Read the Docs Sphinx Theme. Download HTML ESP-IDF Programming Guide Choose target... Choose version... Get Started API Reference Hardware Reference API Guides Application Level Tracing Library Application Startup Flow Bluetooth® Architecture Bluetooth® Classic Bluetooth® Low Energy ESP-BLE-MESH Bootloader Build System Build System v2 RF Coexistence C Support C Version Unsupported C Features Nested Function Pointers C++ Support Code Quality Core Dump Current Consumption Measurement of Modules Deep-sleep Wake Stubs Error Handling ESP-WIFI-MESH Support for External RAM Fatal Errors File System Considerations Hardware Abstraction High Priority Interrupts JTAG Debugging Project Configuration Linker Script Generation Low Power Modes lwIP Memory Types OpenThread Partition Tables Performance Reproducible Builds RF Calibration Standard I/O and Console Output Thread Local Storage Tools Unit Testing in ESP32 Running ESP-IDF Applications on Host Wi-Fi Driver Wi-Fi Security Wi-Fi Expansion PHY Security Guides Migration Guides Libraries and Frameworks Contributions Guide ESP-IDF Versions Resources Copyrights and Licenses About Switch Between Languages ESP-IDF Programming Guide API Guides C Support Edit on GitHub C Support [中文] ESP-IDF is primarily written in C and provides C APIs. ESP-IDF can use one of the following C Standard Library implementations: Picolibc (default) Newlib (enabled with CONFIG_LIBC_NEWLIB Kconfig option) The Picolibc version is specified in esp_libc/sbom_picolibc.yml and the Newlib version in esp_libc/sbom_newlibc.yml. In general, all C features supported by the compiler (currently GCC) can be used in ESP-IDF, unless otherwise noted in Unsupported C Features below. C Version GNU dialect of ISO C23 (--std=gnu23) is the current default C version in ESP-IDF. To compile the source code of a certain component using a different language standard, set the desired compiler flag in the component's CMakeLists.txt file: idf_component_register( ... ) target_compile_options(${COMPONENT_LIB} PRIVATE -std=gnu11) If the public header files of the component also need to be compiled with the same language standard, replace the flag PRIVATE with PUBLIC. Unsupported C Features The following features are not supported in ESP-IDF. Nested Function Pointers The GNU dialect of ISO C23 supports nested functions. However, ESP-IDF does not support referencing nested functions as pointers. This is due to the fact that the GCC compiler generates a trampoline (i.e., small piece of executable code) on the stack when a pointer to a nested function is referenced. ESP-IDF does not permit executing code from a stack, thus use of pointers to nested functions is not supported. Was this page helpful? Thank you! We received your feedback. If you have any comments, fill in Espressif Documentation Feedback Form. We value your feedback. Let us know how we can improve this page by filling in Espressif Documentation Feedback Form. Previous Next © Copyright 2016 - 2026, Espressif Systems (Shanghai) Co., Ltd. Built with Sphinx using a theme based on Read the Docs Sphinx Theme. Download HTML ESP-IDF Programming Guide Choose target... Choose version... Get Started API Reference API Conventions Application Protocols Bluetooth® API Error Codes Reference Networking APIs Peripherals API Analog to Digital Converter (ADC) Clock Tree Digital To Analog Converter (DAC) GPIO & RTC GPIO General Purpose Timer (GPTimer) Inter-Integrated Circuit (I2C) Inter-IC Sound (I2S) LCD LED Control (LEDC) Motor Control Pulse Width Modulator (MCPWM) Pulse Counter (PCNT) Remote Control Transceiver (RMT) SD Pull-up Requirements SDMMC Host Driver SD SPI Host Driver Overview How to Use Other Details Related Docs API Reference SDIO Card Slave Driver Sigma-Delta Modulation (SDM) SPI Flash API SPI Master Driver SPI Slave Driver Capacitive Touch Sensor Two-Wire Automotive Interface (TWAI) Universal Asynchronous Receiver/Transmitter (UART) Provisioning API Storage API System API Configuration Options Reference Hardware Reference API Guides Security Guides Migration Guides Libraries and Frameworks Contributions Guide ESP-IDF Versions Resources Copyrights and Licenses About Switch Between Languages ESP-IDF Programming Guide API Reference Peripherals API SD SPI Host Driver Sharing the SPI Bus Among SD Cards and Other SPI Devices Edit on GitHub Sharing the SPI Bus Among SD Cards and Other SPI Devices [中文] The SD card has an SPI mode, enabling it to function as an SPI device, but there are some restrictions that we need to pay attention to. Pin Loading of Other Devices When adding more devices onto the same bus, the overall pin loading increases. The loading consists of AC loading (pin capacitor) and DC loading (pull-ups). AC Loading SD cards, designed for high-speed communications, have small pin capacitors (AC loading) to work until 50 MHz. However, the other attached devices will increase the pin's AC loading. Heavy AC loading of a pin may prevent the pin from being toggled quickly. By using an oscilloscope, you will see the edges of the pin become smoother, i.e., the gradient of the edge is smaller. The setup timing requirements of an SD card may be violated when the card is connected to a bus with a high AC load. Even worse, high AC loads may cause the SD card and other SPI devices to fail to properly resolve clock signals from the host, affecting communication stability. This issue may be more obvious if other attached devices are not designed to work at the same frequency as the SD card, because they may have larger pin capacitors. The larger the pin capacity, the greater the pin response time, the smaller the max frequency the SD bus can work. To see if your pin AC loading is too heavy, you can try the following tests: Terminology: launch edge: at which clock edge the data starts to toggle; latch edge: at which clock edge the data is supposed to be sampled by the receiver. For SD card, it is the rising edge. Use an oscilloscope to see the clock and compare the data line to the clock. If you see the clock is not fast enough, e.g., the rising/falling edge is longer than 1/4 of the clock cycle, it means the clock is skewed too much. If you see the data line unstable before the latch edge of the clock, it means the load of the data line is too large. You may also observe the corresponding phenomenon that data delayed largely from the launching edge of the clock with logic analyzers. But it is not as obvious as with an oscilloscope. Try to use a slower clock frequency. If the lower frequency can work while the higher frequency cannot, it is an indication that the AC loading on the pins is too large. If the AC loading of the pins is too large, you can either use other faster devices with lower pin load or slow down the clock speed. DC Loading The pull-ups required by SD cards are usually around 10 kOhm to 50 kOhm, which may be too strong for some other SPI devices. Check the specification of your device about its DC output current, it should be larger than 700 μA, otherwise, the device output may not be read correctly. Initialization Sequence Note If you see any problem in the following steps, please make sure the timing is correct first. You can try to slow down the clock speed, such as setting SDMMC_FREQ_PROBING to 400 kHz for SD card, to avoid the influence of pin AC loading, as discussed in the previous section. When using an SD card with other SPI devices on the same SPI bus, due to the restrictions of the SD card startup flow, the following initialization sequence should be followed. Refer to storage/sd_card for further details. Initialize