1SD Pull-up Requirements
2=======================
3
4Espressif hardware products are designed for multiple use cases which may require different pull states on pins. For this reason, the pull state of particular pins on certain products will need to be adjusted to provide the pull-ups required in the SD bus.
5
6SD pull-up requirements apply to cases where {IDF_TARGET_NAME} uses the SPI or SDMMC controller to communicate with SD cards. When an SD card is operating in SPI mode or 1-bit SD mode, the CMD and DATA (DAT0 - DAT3) lines of the SD bus must be pulled up by 10 kOhm resistors. SD cards and SDIO devices should also have pull-ups on all above-mentioned lines (regardless of whether these lines are connected to the host) in order to prevent them from entering a wrong state.
7
8.. only:: esp32
9
10    By default, the MTDI bootstrapping pin is incompatible with the DAT2 line pull-up if the flash voltage is 3.3 V. For more information, see :ref:`mtdi_strapping_pin` below.
11
12.. todo::
13
14   Add a diagram of the Bus lines and pullups
15
16This document has the following structure:
17
18- `Overview of compatibility`_ between the default pull states on pins of Espressif's products and the states required by the SD bus
19- `Solutions`_ - ideas on how to resolve compatibility issues
20- `Related information`_ - other relevant information
21
22
23.. _compatibility_overview_espressif_hw_sdio:
24
25Overview of Compatibility
26-------------------------
27
28This section provides an overview of compatibility issues that might occur when using SDIO (secure digital input output). Since the SD bus needs to be connected to pull-ups, these issues should be resolved regardless of whether they are related to master (host) or slave (device). Each issue has links to its respective solution. A solution for a host and device may differ.
29
30
31Systems on a Chip (SoCs)
32^^^^^^^^^^^^^^^^^^^^^^^^
33
34.. only:: esp32
35
36    - ESP32 (except for D2WD versions, see `ESP32 datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_):
37
38        - :ref:`sd_pull-up_no_pull-ups`
39        - :ref:`strapping_conflicts_dat2` for models with 3.3 V flash chip
40
41    - ESP32-D2WD:
42
43        - :ref:`sd_pull-up_no_pull-ups`
44        - :ref:`no_pull-up_on_gpio12`
45
46.. only:: SOC_SDMMC_USE_GPIO_MATRIX
47
48    {IDF_TARGET_NAME} SDMMC host controller allows using any of GPIOs for any of SD interface signals. However, it is recommended to avoid using strapping GPIOs, GPIOs with internal weak pull-downs and GPIOs commonly used for other purposes to prevent conflicts:
49
50.. only:: esp32s3
51
52    - GPIO0 (strapping pin)
53    - GPIO45, GPIO46 (strapping pins, internal weak pulldown)
54    - GPIO26 - GPIO32 (commonly used for SPI Flash and PSRAM)
55    - GPIO33 - GPIO37 (when using chips and modules with Octal SPI Flash or Octal PSRAM)
56    - GPIO43, GPIO44 (GPIOs used for UART0 by default)
57    - GPIO19, GPIO20 (GPIOs used for USB by default)
58
59
60Systems in Packages (SIP)
61^^^^^^^^^^^^^^^^^^^^^^^^^
62
63.. only:: esp32
64
65    - ESP32-PICO-D4:
66
67        - :ref:`sd_pull-up_no_pull-ups`
68        - :ref:`strapping_conflicts_dat2`
69
70
71Modules
72^^^^^^^
73
74.. only:: esp32
75
76    - ESP32-WROOM-32 Series, including ESP32-WROOM-32, ESP32-WROOM-32D, ESP32-WROOM-32U, and ESP32-SOLO-1
77
78        - :ref:`sd_pull-up_no_pull-ups`
79        - :ref:`strapping_conflicts_dat2`
80
81    - ESP32-WROVER Series, including ESP32-WROVER and ESP32-WROVER-I
82
83        - :ref:`sd_pull-up_no_pull-ups`
84
85    - ESP32-WROVER-B Series, including ESP32-WROVER-B and ESP32-WROVER-IB
86
87        - :ref:`sd_pull-up_no_pull-ups`
88        - :ref:`strapping_conflicts_dat2`
89
90
91.. _sdio_dev_kits:
92
93Development Boards
94^^^^^^^^^^^^^^^^^^
95
96.. only:: esp32
97
98    - ESP32-PICO-KIT, including PICO-KIT v4.1, v4.0, and v3
99
100        - :ref:`sd_pull-up_no_pull-ups`
101        - :ref:`strapping_conflicts_dat2`
102        - :ref:`gpio2_strapping_pin`
103
104    - ESP32-DevKitC, including ESP32-DevKitC v4 and v2
105
106        - :ref:`sd_pull-up_no_pull-ups`
107        - :ref:`strapping_conflicts_dat2`
108        - :ref:`gpio2_strapping_pin`
109
110    - ESP-WROVER-KIT
111
112        - Required pull-ups are provided
113        - :ref:`pull-up_conflicts_on_gpio13` (v4.1, v3, v2, and v1)
114        - :ref:`strapping_conflicts_dat2` (v4.1, v2, and v1)
115        - :ref:`gpio2_strapping_pin` (v2, v1)
116
117        You can determine the version of your ESP23-WROVER-KIT by checking which module is mounted on it:
118
119        - ESP32-WROVER-B on v4.1
120        - ESP32-WROVER on v3
121        - ESP32-WROOM-32 on v1 and v2
122
123    - ESP32-LyraTD-MSC
124
125        - Required pull-ups are provided
126        - :ref:`strapping_conflicts_dat2`
127
128    - ESP32-LyraT
129
130        - Required pull-ups are provided
131        - :ref:`pull-up_conflicts_on_gpio13`
132
133.. only:: esp32s3
134
135    - ESP32-S3-DevKitC-1
136
137        - :ref:`sd_pull-up_no_pull-ups`
138
139    - ESP32-S3-USB-OTG
140
141        - The board may be used in 1-line and 4-line SD mode or SPI mode.
142        - Required pull-ups are provided on GPIOs 33-38.
143
144    - ESP32-S3-EYE
145
146        - The board is limited to 1-line SD mode.
147        - Required pull-ups are provided on GPIOs 38-40.
148
149.. only:: SOC_SDIO_SLAVE_SUPPORTED
150
151    Non-Espressif Hosts
152    ^^^^^^^^^^^^^^^^^^^
153
154    Please make sure that your SDIO host provides necessary pull-ups for all SD bus signals.
155
156
157Solutions
158---------
159
160.. _sd_pull-up_no_pull-ups:
161
162No Pull-ups
163^^^^^^^^^^^
164
165If you use a development board without pull-ups, you can do the following:
166
167- If your host and slave device are on separate boards, replace one of them with a board that has pull-ups. For the list of Espressif's development boards with pull-ups, go to :ref:`sdio_dev_kits`.
168- Attach external pull-ups by connecting each pin which requires a pull-up to VDD via a 10 kOhm resistor.
169
170.. only:: esp32
171
172    .. _pull-up_conflicts_on_gpio13:
173
174    Pull-up Conflicts on GPIO13
175    ^^^^^^^^^^^^^^^^^^^^^^^^^^^
176
177    If DAT3 of your device is not properly pulled up, you have the following options:
178
179    - Use 1-bit SD mode and tie the device's DAT3 to VDD
180    - Use SPI mode
181    - Perform one of the following actions on the GPIO13 pin:
182        - Remove the pull-down resistors
183        - Attach a pull-up resistor of less than 5 kOhm (2 kOhm suggested)
184        - Pull it up or drive it high either by using the host or with 3.3 V on VDD in 1-bit SD mode
185
186
187    .. _strapping_conflicts_dat2:
188
189    Conflicts Between Bootstrap and SDIO on DAT2
190    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
191
192    There is a conflict between the boot strapping requirements of the ESP32 and the SDIO protocol. For details, see :ref:`mtdi_strapping_pin`.
193
194    To resolve the conflict, you have the following options:
195
196    1. (Recommended) Burn the flash voltage selection eFuses. This will permanently configure the internal regulator's output voltage to 3.3 V, and GPIO12 will not be used as a bootstrapping pin. After that, connect a pull-up resistor to GPIO12.
197
198    .. warning::
199
200        Burning eFuses is irreversible! The issue list above might be out of date, so please make sure that the module you are burning has a 3.3 V flash chip by checking the information on http://www.espressif.com/. If you burn the 3.3 V eFuses on a module with a 1.8 V flash chip, the module will stop functioning.
201
202    If you are sure that you need to irreversibly burn eFuses, go to your ESP-IDF directory and run the following command:
203
204    .. code-block:: bash
205
206        components/esptool_py/esptool/espefuse.py set_flash_voltage 3.3V
207
208    This command will burn the `XPD_SDIO_TIEH`, `XPD_SDIO_FORCE`, and `XPD_SDIO_REG` eFuses. After all the three eFuses are burned to value 1, the internal VDD_SDIO flash voltage regulator will be permanently set to 3.3 V. You will see the following log if the burning succeeds:
209
210    .. code-block:: bash
211
212        espefuse.py v2.6
213        Connecting....
214
215        Enable internal flash voltage regulator (VDD_SDIO) to 3.3 V.
216        The following eFuses are burned: XPD_SDIO_FORCE, XPD_SDIO_REG, XPD_SDIO_TIEH.
217        This is an irreversible operation.
218        Type 'BURN' (all capitals) to continue.
219        BURN
220        VDD_SDIO setting complete.
221
222    To check the status of the eFuses, run::
223
224        ``components/esptool_py/esptool/espefuse.py summary``
225
226    If running from an automated flashing script, ``espefuse.py`` has an option ``--do-not-confirm``.
227
228    For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].
229
230    2. **If using 1-bit SD mode or SPI mode**, disconnect the DAT2 pin and make sure it is pulled high. For this, do one the following:
231
232        - Leave the host's DAT2 floating and directly connect the slave's DAT2 to VDD.
233        - For a slave device, build a firmware with the option ``SDIO_SLAVE_FLAG_DAT2_DISABLED`` and re-flash your device. This option will help avoid slave detecting on the DAT2 line. Note that 4-bit SD mode will no longer be supported by the standard Card Common Control Register (CCCR); however, the host will not be aware of that. The use of 4-bit SD mode will have to be disabled on the host's side.
234
235
236    .. _no_pull-up_on_gpio12:
237
238    No Pull-up on GPIO12
239    ^^^^^^^^^^^^^^^^^^^^
240
241    Your module is compatible with the SDIO protocol. Just connect GPIO12 to VDD via a 10 kOhm resistor.
242
243
244    .. _gpio2_strapping_pin:
245
246    Download Mode Not Working (minor issue)
247    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
248
249    When the GPIO2 pin is pulled high in accordance with the SD pull-up requirements, you cannot enter Download mode because GPIO2 is a bootstrapping pin which in this case must be pulled low.
250
251    There are the following solutions:
252
253    - For boards that require shorting the GPIO0 and GPIO2 pins with a jumper, put the jumper in place, and the auto-reset circuit will pull GPIO2 low along with GPIO0 before entering Download mode.
254    - For boards with components attached to their GPIO2 pin (such as pull-down resistors and/or LEDs), check the schematic of your development board for anything connected to GPIO2.
255
256        - **LEDs** would not affect operation in most cases.
257        - **Pull-down resistors** can interfere with DAT0 signals and must be removed.
258
259    If the above solutions do not work for you, please determine if it is the host or slave device that has pull-ups affecting their GPIO2, then locate these pull-ups and remove them.
260
261
262.. _related_info_sdio:
263
264Related Information
265-------------------
266
267.. only:: esp32
268
269    .. _mtdi_strapping_pin:
270
271    MTDI Strapping Pin
272    ^^^^^^^^^^^^^^^^^^
273
274    MTDI (GPIO12) is used as a bootstrapping pin to select the output voltage of an internal regulator (VDD_SDIO) which powers the flash chip. This pin has an internal pull-down, so, if left unconnected, it will read low level at startup, which will lead to selecting the default 3.3 V operation.
275
276    All ESP32-WROVER modules, excluding ESP32-WROVER-B, use 1.8 V flash and have internal pull-ups on GPIO12. Other modules that use 3.3 V flash have no pull-ups on the GPIO12 pin, and this pin is slightly pulled down internally.
277
278    When adding a pull-up to this pin for SD card operation, consider the following:
279
280    - For boards that do not use the internal regulator (VDD_SDIO) to power flash, GPIO12 can be pulled high.
281    - For boards using 1.8 V flash chips, GPIO12 needs to be pulled high at reset. This is fully compatible with the SD card operation.
282    - On boards using the internal regulator and a 3.3 V flash chip, GPIO12 must be pulled low at reset. This is incompatible with the SD card operation. For reference information on compatibility of Espressif's boards with the SD card operation, see :ref:`compatibility_overview_espressif_hw_sdio`.
283
284
285    Internal Pull-ups and Strapping Requirements
286    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
287
288    Using external resistors is always preferable. However, Espressif's products have internal weak pull-up and pull-down resistors which can be enabled and used instead of external ones. Please keep in mind that this solution cannot guarantee reliable SDIO communication.
289
290    With that said, the information about these internal pull-ups and strapping requirements can still be useful. Espressif hardware products have different weak internal pull-ups / pull-downs connected to CMD and DATA pins. The table below shows the default pull-up and pull-down states of the CMD and DATA pins.
291
292    The following abbreviations are used in the table:
293
294    - **WPU**: Weak pull-up inside the SoC
295    - **WPD**: Weak pull-down inside the SoC
296    - **PU**: Pull-up inside Espressif modules but outside the SoC
297
298    .. list-table:: Default pull-up and pull-down states of the CMD and DATA pins
299       :widths: 25 25 25 25
300       :header-rows: 1
301
302       * - GPIO number
303         - Pin Name
304         - Startup State
305         - Strapping Requirement
306       * - **15**
307         - CMD
308         - WPU
309         -
310       * - **2**
311         - DAT0
312         - WPD
313         - Low for Download mode
314       * - **4**
315         - DAT1
316         - WPD
317         -
318       * - **12**
319         - DAT2
320         - PU for 1.8 V flash; WPD for 3.3 V flash
321         - High for 1.8 V flash; Low for 3.3 V flash
322       * - **13**
323         - DAT3
324         - WPU
325         -
326