From 6077d1715013dac50b54d8321a7a0f51db34aa5c Mon Sep 17 00:00:00 2001 From: Nicko van Someren Date: Fri, 31 May 2019 01:04:32 -0600 Subject: [PATCH] docs/machine: Add initial docs for new machine.SDCard class. --- docs/library/machine.SD.rst | 4 +- docs/library/machine.SDCard.rst | 122 ++++++++++++++++++++++++++++++++ docs/library/machine.rst | 1 + 3 files changed, 125 insertions(+), 2 deletions(-) create mode 100644 docs/library/machine.SDCard.rst diff --git a/docs/library/machine.SD.rst b/docs/library/machine.SD.rst index 9c58e73545..d985db231a 100644 --- a/docs/library/machine.SD.rst +++ b/docs/library/machine.SD.rst @@ -1,8 +1,8 @@ .. currentmodule:: machine .. _machine.SD: -class SD -- secure digital memory card -====================================== +class SD -- secure digital memory card (cc3200 port only) +========================================================= .. warning:: diff --git a/docs/library/machine.SDCard.rst b/docs/library/machine.SDCard.rst new file mode 100644 index 0000000000..34bb2e48bf --- /dev/null +++ b/docs/library/machine.SDCard.rst @@ -0,0 +1,122 @@ +.. currentmodule:: machine +.. _machine.SDCard: + +class SDCard -- secure digital memory card +========================================== + +SD cards are one of the most common small form factor removable storage media. +SD cards come in a variety of sizes and phsyical form factors. MMC cards are +similar removable storage devices while eMMC devices are electically similar +storage devices designed to be embedded into other systems. All three form +share a common protocol for communication with their host system and high-level +support looks the same for them all. As such in MicroPython they are implemented +in a single class called :class:`machine.SDCard` . + +Both SD and MMC interfaces support being accessed with a variety of bus widths. +When being accessed with a 1-bit wide interface they can be accessed using the +SPI protocol. Different MicroPython hardware platforms support different widths +and pin configurations but for most platforms there is a standard configuation +for any given hardware. In general constructing an `SDCard`` object with without +passing any parameters will initialise the interface to the default card slot +for the current hardware. The arguments listed below represent the common +arguments that might need to be set in order to use either a non-stanard slot +or a non-standard pin assignment. The exact subset of arguments suported will +vary from platform to platform. + +.. class:: SDCard(slot=1, width=1, cd=None, wp=None, sck=None, miso=None, mosi=None, cs=None) + + This class provides access to SD or MMC storage cards using either + a dedicated SD/MMC interface hardware or through an SPI channel. + The class implements the block protocol defined by :class:`uos.AbstractBlockDev`. + This allows the mounting of an SD card to be as simple as:: + + uos.mount(storage.SDCard(), "/sd") + + The constrcutor takes the following paramters: + + - *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. + + - *cd* can be used to specify a card-detect pin. + + - *wp* can be used to specify a write-protect pin. + + - *sck* can be used to specify an SPI clock pin. + + - *miso* can be used to specify an SPI miso pin. + + - *mosi* can be used to specify an SPI mosi pin. + + - *cs* can be used to specify an SPI chip select pin. + +Implementation-specific details +------------------------------- + +Different implementations of the ``SDCard`` class on different hardware support +varying subsets of the options above. + +PyBoard +``````` + +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 + ====== ====== ====== ====== ====== + +cc3200 +`````` + +You can set the pins used for SPI access by passing a tuple as the +*pins* argument. + +*Note:* The current cc3200 SD card implementation names the this class +:class:`machine.SD` rather than :class:`machine.SDCard` . diff --git a/docs/library/machine.rst b/docs/library/machine.rst index a7b5957761..8cc5efe593 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -168,3 +168,4 @@ Classes machine.Timer.rst machine.WDT.rst machine.SD.rst + machine.SDCard.rst