介绍树莓派（RPi）Pico开发板(或树莓派Pico W无线开发板)与MicroSD卡模块SPI接口技术原理及SPI接口硬件连接的具体步骤，讲述采用MicroPython和SDCard类编制程序读写MicroSD存储卡的方法，给出读写MicroSD存储卡文件的测试程序。
一、所需硬件材料
1.树莓派Pico开发板(或树莓派Pico W无线开发板)×1
2.MicroSD卡模块×1
3.8GB MicroSD卡×1
4.MicroUSB数据线×1
5.面包板×1
6.公对母杜邦线×6
7.MicroSD读卡器(可选)
二、MicroSD卡模块
MicroSD(Micro Secure Digital flash memory)卡也叫TF(Trans Flash memory)卡。图1(a)是一种MicroSD卡模块外观图，该模块提供了SDIO接口方式和SPI接口方式。以SPI接口方式为例，MicroSD 卡模块包括1个用于插入MicroSD卡的卡槽和6根用以与MCU微控制器连接的SPI接口信号：包括MISO、MOSI、SCK 、CS 四根SPI接口引脚，以及VDD电源和GND接地引脚。图1(b)是一种8GB MicroSD存储卡外观图(实践时，可选用2GB~128GB 范围容量的MicroSD存储卡)。

(a) MicroSD卡模块及其引脚配置 (b) MicroSD存储卡
图1 MicroSD卡模块和MicroSD存储卡外观图
三、MicroSD卡模块与树莓派Pico接口
树莓派Pico(RPi Pico)开发板或树莓派Pico W(RPi Pico W)无线开发板扩展硬件接口提供了两个SPI接口–SPI0和SPI1，且SPI接口信号引脚完全兼容。本文仅以RPi Pico的SPI1接口为例进行介绍。
MicroSD 卡模块与RPi Pico开发板SPI1接口连接原理图及外观图如图2所示，硬件具体连接说明如下：
1.将MicroSD卡模块的 MOSI、MISO、SCLK 和 CS 引脚分别 与 RPi Pico的 SPI1 TX(SPI1 MOSI)、SPI1 RX(SPI1 MISO)、SPI1 SCK和 SPI1 CS 引脚连接，这些引脚对应于RPi Pico的SPI1接口信号。SPI1接口信号使用的是RPi Pico的GP10(SPI1 SCK)、GP11(SPI1 TX)、GP12(SPI1 RX)、GP13(SPI1 CS)引脚信号。
2.将MicroSD卡模块的 VCC 和 GND 引脚分别与RPi Pico的 3.3V(3V3 OUT)电源和GND接地引脚连接。

(a) MicroSD卡模块与RPi Pico的SPI接口连接原理图

(b) MicroSD卡模块与RPi Pico的SPI接口连接外观图
图2 MicroSD卡模块与RPi Pico的SPI接口连接
关于RPi Pico开发板（RP2040 MCU）SPI接口技术原理与相关实践，可参考相关技术文献，此处不再赘述。
四、MicroPython的machine模块
MicroPython的machine 模块包含与专用开发板硬件相关的特定功能。machine模块包括控制或管理GPIO、PWM、ADC、UART、SPI、I2C、I2S、Timer、RTC、Watchdog定时器及SD存储卡等硬件相关的类。machine模块的SDcard类(class SDCard)支持读取SD、MicroSD、MMC和eMMC等存储卡。
五、SDCard类
SDCard 类通过指定的SPI接口或SD/MMC SDIO接口访问 SD或MMC存储卡。在 MicroPython语言中使用SDCard类，须先下载sdcard.py程序文件并将其烧写到RPi Pico开发板板载Flash中，然后在MicroPython应用程序中导入sdcard。
sdcard.py程序文件可以从网址 https://github.com/micropython/micropython-lib/blob/master/micropython/drivers/storage/sdcard/sdcard.py或网址 https://github.com/micropython/micropython-infineon/blob/master/drivers/sdcard/sdcard.py下载。
sdcard.py程序清单如下：

from micropython import const
import time


_CMD_TIMEOUT = const(100)

_R1_IDLE_STATE = const(1 << 0)
# R1_ERASE_RESET = const(1 << 1)
_R1_ILLEGAL_COMMAND = const(1 << 2)
# R1_COM_CRC_ERROR = const(1 << 3)
# R1_ERASE_SEQUENCE_ERROR = const(1 << 4)
# R1_ADDRESS_ERROR = const(1 << 5)
# R1_PARAMETER_ERROR = const(1 << 6)
_TOKEN_CMD25 = const(0xFC)
_TOKEN_STOP_TRAN = const(0xFD)
_TOKEN_DATA = const(0xFE)


class SDCard:
    def __init__(self, spi, cs, baudrate=1320000):
        self.spi = spi
        self.cs = cs

        self.cmdbuf = bytearray(6)
        self.dummybuf = bytearray(512)
        self.tokenbuf = bytearray(1)
        for i in range(512):
            self.dummybuf[i] = 0xFF
        self.dummybuf_memoryview = memoryview(self.dummybuf)

        # initialise the card
        self.init_card(baudrate)

    def init_spi(self, baudrate):
        try:
            master = self.spi.MASTER
        except AttributeError:
            # on ESP8266
            self.spi.init(baudrate=baudrate, phase=0, polarity=0)
        else:
            # on pyboard
            self.spi.init(master, baudrate=baudrate, phase=0, polarity=0)

    def init_card(self, baudrate):
        # init CS pin
        self.cs.init(self.cs.OUT, value=1)

        # init SPI bus; use low data rate for initialisation
        self.init_spi(100000)

        # clock card at least 100 cycles with cs high
        for i in range(16):
            self.spi.write(b"\xff")

        # CMD0: init card; should return _R1_IDLE_STATE (allow 5 attempts)
        for _ in range(5):
            if self.cmd(0, 0, 0x95) == _R1_IDLE_STATE:
                break
        else:
            raise OSError("no SD card")

        # CMD8: determine card version
        r = self.cmd(8, 0x01AA, 0x87, 4)
        if r == _R1_IDLE_STATE:
            self.init_card_v2()
        elif r == (_R1_IDLE_STATE | _R1_ILLEGAL_COMMAND):
            self.init_card_v1()
        else:
            raise OSError("couldn't determine SD card version")

        # get the number of sectors
        # CMD9: response R2 (R1 byte + 16-byte block read)
        if self.cmd(9, 0, 0, 0, False) != 0:
            raise OSError("no response from SD card")
        csd = bytearray(16)
        self.readinto(csd)
        if csd[0] & 0xC0 == 0x40:  # CSD version 2.0
            self.sectors = ((csd[8] << 8 | csd[9]) + 1) * 1024
        elif csd[0] & 0xC0 == 0x00:  # CSD version 1.0 (old, <=2GB)
            c_size = (csd[6] & 0b11) << 10 | csd[7] << 2 | csd[8] >> 6
            c_size_mult = (csd[9] & 0b11) << 1 | csd[10] >> 7
            read_bl_len = csd[5] & 0b1111
            capacity = (c_size + 1) * (2 ** (c_size_mult + 2)) * (2**read_bl_len)
            self.sectors = capacity // 512
        else:
            raise OSError("SD card CSD format not supported")
        # print('sectors', self.sectors)

        # CMD16: set block length to 512 bytes
        if self.cmd(16, 512, 0) != 0:
            raise OSError("can't set 512 block size")

        # set to high data rate now that it's initialised
        self.init_spi(baudrate)

    def init_card_v1(self):
        for i in range(_CMD_TIMEOUT):
            time.sleep_ms(50)
            self.cmd(55, 0, 0)
            if self.cmd(41, 0, 0) == 0:
                # SDSC card, uses byte addressing in read/write/erase commands
                self.cdv = 512
                # print("[SDCard] v1 card")
                return
        raise OSError("timeout waiting for v1 card")

    def init_card_v2(self):
        for i in range(_CMD_TIMEOUT):
            time.sleep_ms(50)
            self.cmd(58, 0, 0, 4)
            self.cmd(55, 0, 0)
            if self.cmd(41, 0x40000000, 0) == 0:
                self.cmd(58, 0, 0, -4)  # 4-byte response, negative means keep the first byte
                ocr = self.tokenbuf[0]  # get first byte of response, which is OCR
                if not ocr & 0x40:
                    # SDSC card, uses byte addressing in read/write/erase commands
                    self.cdv = 512
                else:
                    # SDHC/SDXC card, uses block addressing in read/write/erase commands
                    self.cdv = 1
                # print("[SDCard] v2 card")
                return
        raise OSError("timeout waiting for v2 card")

    def cmd(self, cmd, arg, crc, final=0, release=True, skip1=False):
        self.cs(0)

        # create and send the command
        buf = self.cmdbuf
        buf[0] = 0x40 | cmd
        buf[1] = arg >> 24
        buf[2] = arg >> 16
        buf[3] = arg >> 8
        buf[4] = arg
        buf[5] = crc
        self.spi.write(buf)

        if skip1:
            self.spi.readinto(self.tokenbuf, 0xFF)

        # wait for the response (response[7] == 0)
        for i in range(_CMD_TIMEOUT):
            self.spi.readinto(self.tokenbuf, 0xFF)
            response = self.tokenbuf[0]
            if not (response & 0x80):
                # this could be a big-endian integer that we are getting here
                # if final<0 then store the first byte to tokenbuf and discard the rest
                if final < 0:
                    self.spi.readinto(self.tokenbuf, 0xFF)
                    final = -1 - final
                for j in range(final):
                    self.spi.write(b"\xff")
                if release:
                    self.cs(1)
                    self.spi.write(b"\xff")
                return response

        # timeout
        self.cs(1)
        self.spi.write(b"\xff")
        return -1

    def readinto(self, buf):
        self.cs(0)

        # read until start byte (0xff)
        for i in range(_CMD_TIMEOUT):
            self.spi.readinto(self.tokenbuf, 0xFF)
            if self.tokenbuf[0] == _TOKEN_DATA:
                break
            time.sleep_ms(1)
        else:
            self.cs(1)
            raise OSError("timeout waiting for response")

        # read data
        mv = self.dummybuf_memoryview
        if len(buf) != len(mv):
            mv = mv[: len(buf)]
        self.spi.write_readinto(mv, buf)

        # read checksum
        self.spi.write(b"\xff")
        self.spi.write(b"\xff")

        self.cs(1)
        self.spi.write(b"\xff")

    def write(self, token, buf):
        self.cs(0)

        # send: start of block, data, checksum
        self.spi.read(1, token)
        self.spi.write(buf)
        self.spi.write(b"\xff")
        self.spi.write(b"\xff")

        # check the response
        if (self.spi.read(1, 0xFF)[0] & 0x1F) != 0x05:
            self.cs(1)
            self.spi.write(b"\xff")
            return

        # wait for write to finish
        while self.spi.read(1, 0xFF)[0] == 0:
            pass

        self.cs(1)
        self.spi.write(b"\xff")

    def write_token(self, token):
        self.cs(0)
        self.spi.read(1, token)
        self.spi.write(b"\xff")
        # wait for write to finish
        while self.spi.read(1, 0xFF)[0] == 0x00:
            pass

        self.cs(1)
        self.spi.write(b"\xff")

    def readblocks(self, block_num, buf):
        # workaround for shared bus, required for (at least) some Kingston
        # devices, ensure MOSI is high before starting transaction
        self.spi.write(b"\xff")

        nblocks = len(buf) // 512
        assert nblocks and not len(buf) % 512, "Buffer length is invalid"
        if nblocks == 1:
            # CMD17: set read address for single block
            if self.cmd(17, block_num * self.cdv, 0, release=False) != 0:
                # release the card
                self.cs(1)
                raise OSError(5)  # EIO
            # receive the data and release card
            self.readinto(buf)
        else:
            # CMD18: set read address for multiple blocks
            if self.cmd(18, block_num * self.cdv, 0, release=False) != 0:
                # release the card
                self.cs(1)
                raise OSError(5)  # EIO
            offset = 0
            mv = memoryview(buf)
            while nblocks:
                # receive the data and release card
                self.readinto(mv[offset : offset + 512])
                offset += 512
                nblocks -= 1
            if self.cmd(12, 0, 0xFF, skip1=True):
                raise OSError(5)  # EIO

    def writeblocks(self, block_num, buf):
        # workaround for shared bus, required for (at least) some Kingston
        # devices, ensure MOSI is high before starting transaction
        self.spi.write(b"\xff")

        nblocks, err = divmod(len(buf), 512)
        assert nblocks and not err, "Buffer length is invalid"
        if nblocks == 1:
            # CMD24: set write address for single block
            if self.cmd(24, block_num * self.cdv, 0) != 0:
                raise OSError(5)  # EIO

            # send the data
            self.write(_TOKEN_DATA, buf)
        else:
            # CMD25: set write address for first block
            if self.cmd(25, block_num * self.cdv, 0) != 0:
                raise OSError(5)  # EIO
            # send the data
            offset = 0
            mv = memoryview(buf)
            while nblocks:
                self.write(_TOKEN_CMD25, mv[offset : offset + 512])
                offset += 512
                nblocks -= 1
            self.write_token(_TOKEN_STOP_TRAN)

    def ioctl(self, op, arg):
        if op == 4:  # get number of blocks
            return self.sectors
        if op == 5:  # get block size in bytes
            return 512

除此之外，还必须导入os模块和machine模块。
必须导入的一些模块语句如下：

import uos
import machine
import sdcard

SDCard类的SD对象需使用构造器进行初始化，SDCard类的构造器调用格式如下：

class machine.SDCard(slot=1, width=1, cd=None, wp=None, sck=None, miso=None, mosi=None, cs=None, freq=20000000)

构造器参数说明：
•slot: 选择一个可用SPI/SDIO接口或使用默认接口
•width: 选择SD/MMC接口的总线宽度（对于SD/MicroSD卡适配器，宽度为“1”；一般不需要显式指定，除非SD卡硬件可以访问存储卡的并行接口)
•cd: 指定SD卡检测引脚
•wp: 指定写保护引脚
•sck: 指定SPI CLK引脚
•miso: 指定SPI MISO引脚
•mosi: 指定SPI MOSI引脚
•cs: 指定SPI CS片选引脚
•freq: 选择 SD/MMC 接口工作频率(单位：Hz)
RPi Pico开发板扩展硬件接口提供了两个SPI接口：SPI0和SPI1。
以RPi Pico开发板SPI1接口连接MicroSD卡模块为例，假设SPI1接口信号使用上面介绍的GP10~GP13端口(GP10: SPI1 SCK; GP11: SPI1 TX/SPI1 MOSI; GP12: SPI1 RX/ SPI1 MISO; GP13: SPI1 CS)，启动SD卡对象语句序列如下：

spi = SPI(1, sck=Pin(10), mosi=Pin(11), miso=Pin(12))
cs = Pin(13)
sd = sdcard.SDCard(spi, cs)

六、os/uos模块
MicroPython os/uos模块提供了对文件系统访问和挂载的功能。下面是访问MicroSD 卡的几个常用os对象的方法。
1.os.VfsFat()
os.VfsFat()方法创建使用 FAT 文件系统格式的文件系统对象。块设备实现块协议，提供FAT文件系统存储。 本质上，os.VfsFat()方法使设备能够支持 MicroPython文件系统。 物理硬件由文件系统类表示。 当使用 os.VfsFat()方法创建对象时，表示使用FAT文件系统，我们可以用下面的os.mount()方法挂载该对象。
2.os.mount()
os.mount()方法将指定的文件系统对象挂载到由字符串参数指定的虚拟文件系统位置。文件系统对象可以是具有 mount() 方法的虚拟对象或块设备。 若是块设备，则自动检测文件系统类型；否则，将抛出异常。
指定位置的字符串可以是“/”以便将文件系统对象挂载在根目录下，或者是“/”将其挂载在根目录下的子目录中。 os.mount()方法有3个参数：文件系统对象、指定位置的字符串和只读参数。如果只读参考为“True”，则文件系统以只读方式挂载。 如果指定位置已挂载，则会抛出OSError(EPERM)。
3.os.listdir()
如果调用os.listdir()方法不带参数，表示将列出当前目录；否则，列出指定的目录。
4.os.umount()
os.umount()方法用于“卸载”文件系统。位置可以是所命名挂载位置的字符串，也可以是事先安装的文件系统对象。在卸载过程中，将调用文件系统对象的os.umount()方法。
下面是 MicroSD卡 FAT文件系统的示例程序，它将文件系统对象挂载到内存中。

vfs = os.VfsFat(sd)
os.mount(vfs, “/fc”)
print(“文件系统检测”)
print(os.listdir(“/fc”))

七、MicroSD存储卡文件操作
1.创建文本文件
将纯文本文件添加到 MicroSD 存储卡十分简单。我们可以在MicroSD卡上创建多个纯文本文件，创建时只需指定该文本文件的路径字符串即可。
下面是在MicroSD 卡上创建一个“log.txt”文件名的纯文本文件：
fn =“/fc/log.txt”
2.写入单个块
单个块是指一行文本。必须使用字符串变量指定文件，用open()方法打开指定的文件路径才可以写入块，“w”参数是以写入方式打开文件。通过调用write()方法来写入单个块。
下面是在 MicroSD 卡的文本文件中写入单个块的代码示例：

fn = “/fc/one-line-log.txt”
print()
print(“写单个块”)
with open(fn, “w”) as f:
            n = f.write(“abcdefgh\n”)  # 单个块
            print(n, “字节被写入”)

3.读取单个块
读取文件须调用open()方法打开字符串变量指定的文件，并将文件打开方式指定为“r”。 通过调用read()方法读取文件。
下面是从MicroSD卡读取文本文件的代码示例：

fn = “/fc/one-line-log.txt”
print()
print(“读取单个块”)
with open(fn, “r”) as f:
            result = f.read()
            print(len(result2), “字节被读取”)
            print()
            print(result)

4.写入多个块
在文本文件中写入多个块与写入单个块类似，只是写入的字符串对象包含多行文本。
下面是在MicroSD卡上的文本文件中写入多个块的代码示例：

line = “ABCDEFGHIJKLMNOPQRSTUVWXYZ\n”
lines = line * 200  # 5400个字符
fn = “/fc/multi-line-log.txt”
print()
print(“写入多上块”)
with open(fn, “w”) as f:
            n = f.write(lines)
            print(n, “字节被写入”)

5.读取多个块
在文本文件中读取多个块（多行读取方式）与读取单个块（单行读取方式）类似。
下面是从MicroSD卡读取多块文本文件的代码示例：

fn = “/fc/multi-line-log.txt”
print()
print(“读取多个块”)
with open(fn, “r”) as f:
            result = f.read()
            print(len(result2), “字节被读取”)
            print()
            print(result)

八、MicroSD卡存储测试
MicroSD卡存储测试程序(程序文件名为“tfcard_test.py”)清单如下：

# Filename: tfcard_test.py
import uos  # os/uos
import machine
import sdcard
from machine import SPI, Pin

spi = SPI(1, sck=Pin(10), mosi=Pin(11), miso=Pin(12))
cs = Pin(13)
sd = sdcard.SDCard(spi, cs)

# 挂载文件到sd
uos.mount(sd,"/sd")
# 列出MicroSD/TF卡中的目录文件
print(uos.listdir('/sd'))

# 写文件测试
f = open('/sd/test.txt','w',encoding='utf-8')
f.write('MicroSD/TF存储卡访问测试！')
f.close()

# 读文件测试
f = open('/sd/test.txt','r')
print(f.read())
f.close()

MicroSD卡存储测试步骤归纳如下：
Step 1：下载并烧写RPi Pico MicroPython固件到RPi Pico开发板，具体方法可参考文献[1]或文献[2]。
Step 2：准备一块FAT32文件格式化好的MicroSD(TF)存储卡{若存储卡为非FAT32文件格式，可将MicroSD(TF)卡插入到MicroSD读卡器；MicroSD读卡器接入电脑USB口后，使用FAT32文件格式对MicroSD卡进行格式化}。
Step 3：将MicroSD卡插入MicroSD卡模块的卡槽中。
Step 4：按照图2所示的MicroSD卡模块与RPi Pico的SPI接口连接原理图和外观图连接MicroSD卡模块与RPi Pico开发板。
Step 4：将连接电脑与RPi Pico开发板的Micro USB线接入RPi Pico开发板和电脑USB口。
Step 5：运行Thonny IDE，点击[Tools]→[Options…]打开Thonny options对话框，在对话框中分别选择[MicroPython(Raspberry Pi Pico)]和RPi Pico开发板所使用端口Port的USB串行设备，如图3所示。

图3 Thonny options对话框RPi Pico开发板相关设置
Step 6：复制粘贴上面的“sdcard.py”程序到Thonny编辑器窗口，点击选择[File]→[Save as…]打开Where to save to?对话框，选择[Raspberry Pi Pico]后将程序以“sdcard.py”程序名烧写到RPi Pico开发板。
Step 7：新建一个编辑窗口，复制粘贴上面的“tfcard_test.py”程序到编辑器窗口，点击选择[File]→[Save as…]打开Where to save to?对话框，选择[Raspberry Pi Pico]后将程序以“tfcard_test.py程序名烧写到RPi Pico开发板，如图４所示。

图4 RPi Pico开发板存储的程序文件
Step 8：点击 [View]，选中 [Files]，可看到RPi Pico开发板中的两个程序文件，如图５所示。

图5 Thonny [Files]标签窗口显示RPi Pico开发板中的程序文件
Step 9：选中Thonny中“tfcard_test.py”程序所在的编辑器窗口，点击图６Thonny中的运行按钮(红色框)执行程序，Thonny Shell窗口将显示MicroSD卡上的目录文件信息及读取前面写入到”test.txt“文件中的“MicroSD/TF存储卡访问测试！”字符串。

图６ MicroSD存储卡读写测试

参考文献：
[1]袁志勇.《AI嵌入式系统技术与实践-基于树莓派RP2040和MicroPython》. 北京: 北京航空航天大学出版社, 2023年4月。
[2] Raspberry Pi Pico实践系列1-Windows环境下树莓派Pico迷你开发板MicroPython快速上手实践