diff options
Diffstat (limited to 'docs/library')
| -rw-r--r-- | docs/library/machine.SDCard.rst | 161 |
1 files changed, 112 insertions, 49 deletions
diff --git a/docs/library/machine.SDCard.rst b/docs/library/machine.SDCard.rst index e4bb25dfc..62da8c3c2 100644 --- a/docs/library/machine.SDCard.rst +++ b/docs/library/machine.SDCard.rst @@ -23,7 +23,8 @@ arguments that might need to be set in order to use either a non-standard slot or a non-standard pin assignment. The exact subset of arguments supported will vary from platform to platform. -.. class:: SDCard(slot=1, width=1, cd=None, wp=None, sck=None, miso=None, mosi=None, cs=None, freq=20000000) +.. class:: SDCard(slot=1, width=1, cd=None, wp=None, sck=None, miso=None, mosi=None, + cs=None, cmd=None, data=None, freq=20000000) This class provides access to SD or MMC storage cards using either a dedicated SD/MMC interface hardware or through an SPI channel. @@ -37,7 +38,8 @@ vary from platform to platform. - *slot* selects which of the available interfaces to use. Leaving this unset will select the default interface. - - *width* selects the bus width for the SD/MMC interface. + - *width* selects the bus width for the SD/MMC interface. This many data + pins must be connected to the SD card. - *cd* can be used to specify a card-detect pin. @@ -51,7 +53,14 @@ vary from platform to platform. - *cs* can be used to specify an SPI chip select pin. - - *freq* selects the SD/MMC interface frequency in Hz (only supported on the ESP32). + The following additional parameters are only present on ESP32 port: + + - *cmd* can be used to specify the SD CMD pin (ESP32-S3 only). + + - *data* can be used to specify a list or tuple of SD data bus pins + (ESP32-S3 only). + + - *freq* selects the SD/MMC interface frequency in Hz. Implementation-specific details ------------------------------- @@ -67,52 +76,106 @@ The standard PyBoard has just one slot. No arguments are necessary or supported. ESP32 ````` -The ESP32 provides two channels of SD/MMC hardware and also supports -access to SD Cards through either of the two SPI ports that are -generally available to the user. As a result the *slot* argument can -take a value between 0 and 3, inclusive. Slots 0 and 1 use the -built-in SD/MMC hardware while slots 2 and 3 use the SPI ports. Slot 0 -supports 1, 4 or 8-bit wide access while slot 1 supports 1 or 4-bit -access; the SPI slots only support 1-bit access. - - .. note:: Slot 0 is used to communicate with on-board flash memory - on most ESP32 modules and so will be unavailable to the - user. - - .. note:: Most ESP32 modules that provide an SD card slot using the - dedicated hardware only wire up 1 data pin, so the default - value for *width* is 1. - -The pins used by the dedicated SD/MMC hardware are fixed. The pins -used by the SPI hardware can be reassigned. - - .. note:: If any of the SPI signals are remapped then all of the SPI - signals will pass through a GPIO multiplexer unit which - can limit the performance of high frequency signals. Since - the normal operating speed for SD cards is 40MHz this can - cause problems on some cards. - -The default (and preferred) pin assignment are as follows: - - ====== ====== ====== ====== ====== - Slot 0 1 2 3 - ------ ------ ------ ------ ------ - Signal Pin Pin Pin Pin - ====== ====== ====== ====== ====== - sck 6 14 18 14 - cmd 11 15 - cs 5 15 - miso 19 12 - mosi 23 13 - D0 7 2 - D1 8 4 - D2 9 12 - D3 10 13 - D4 16 - D5 17 - D6 5 - D7 18 - ====== ====== ====== ====== ====== +SD cards support access in both SD/MMC mode and the simpler (but slower) SPI +mode. ESP32 and ESP32-S3 chips can access SD cards using either mode. SPI mode +makes use of a `SPI` host peripheral, which cannot concurrently be used for +something else. + +The ``slot`` argument determines which mode is used. Different values are +available on different chips: + +====== ================= ============ ======================== +Slot Supported chips Mode Supported data width +====== ================= ============ ======================== +0 ESP32-S3 SD/MMC 1, 4, or 8 bits. +1 ESP32, ESP32-S3 SD/MMC 1 or 4 bits. +2 ESP32, ESP32-S3 `SPI` (id=1) 1 bit. +3 ESP32, ESP32-S3 `SPI` (id=0) 1 bit. +====== ================= ============ ======================== + +.. note:: On the original ESP32, SDMMC slot 0 is unavailable as its pins are + used to communicate with on-board flash memory. + +.. note:: Most ESP32 modules that provide an SD card slot using the + dedicated hardware only wire up 1 data pin, so the default + value for ``width`` is 1. + +Additional details depend on which ESP32 family chip is in use: + +Original ESP32 +~~~~~~~~~~~~~~ + +Pin assignments in SD/MMC mode are fixed on the original ESP32. When accessing a +card in SPI mode, pins can be set to different values in the constructor. + +The default pin assignments are as follows: + + ====== ====== ====== ====== ============ + Slot 1 2 3 Can be set + ------ ------ ------ ------ ------------ + Signal Pin Pin Pin + ====== ====== ====== ====== ============ + CLK 14 No + CMD 15 No + D0 2 No + D1 4 No + D2 12 No + D3 13 No + sck 18 14 Yes + cs 5 15 Yes + miso 19 12 Yes + mosi 23 13 Yes + ====== ====== ====== ====== ============ + +The ``cd`` and ``wp`` pins are not fixed in either mode and default to disabled, unless set. + +ESP32-S3 +~~~~~~~~ + +The ESP32-S3 chip allows pins to be set to different values for both SD/MMC and +SPI mode access. + +If not set, default pin assignments are as follows: + + ======== ====== ====== ====== ====== + Slot 0 1 2 3 + -------- ------ ------ ------ ------ + Signal Pin Pin Pin Pin + ======== ====== ====== ====== ====== + CLK 14 14 + CMD 15 15 + D0 2 2 + D1 4 4 + D2 12 12 + D3 13 13 + D4 33* + D5 34* + D6 35* + D7 36* + sck 37* 14 + cs 34* 13 + miso 37* 2 + mosi 35* 15 + ======== ====== ====== ====== ====== + +.. note:: Slots 0 and 1 cannot both be in use at the same time. + +.. note:: Pins marked with an asterisk * in the table must be changed from the + default if the ESP32-S3 board is configured for Octal SPI Flash or + PSRAM. + +To access a card in SD/MMC mode, set ``slot`` parameter value 0 or 1 and +parameters ``sck`` (for CLK), ``cmd`` and ``data`` as needed to assign pins. If +the ``data`` argument is passed then it should be a list or tuple of data pins +or pin numbers with length equal to the ``width`` argument. For example:: + + sd = SDCard(slot=0, width=4, sck=8, cmd=9, data=(10, 11, 12, 13)) + +To access a card in SPI mode, set ``slot`` parameter value 2 or 3 and pass +parameters ``sck``, ``cs``, ``miso``, ``mosi`` as needed to assign pins. + +In either mode the ``cd`` and ``wp`` pins default to disabled, unless set in the +constructor. cc3200 `````` |