RPi Pico WAV Player SD Card Interface and Supported File Systems

The RPi Pico WAV Player uses the SPI 0 peripheral for SD card communication and supports FAT12, FAT16, FAT32, and EXFAT file systems via the FatFs library.

The elehobica/rpi_pico_wav_player project implements a WAV audio player for the Raspberry Pi Pico that relies on standard SD card storage. Understanding the SD card interface and supported file systems is essential for hardware integration and preparing storage media correctly.

SPI Interface Configuration

The player accesses the micro-SD card through the SPI 0 peripheral using a hardware SPI configuration. In lib/file_menu/file_menu_FatFs.c, the pico_fatfs wrapper configures the SPI bus with board-default pins before initializing the FatFs library (v0.90).

// lib/file_menu/file_menu_FatFs.c – SPI configuration for the SD card
pico_fatfs_spi_config_t config = {
    spi0,                     // <-- SPI 0 is used
    CLK_SLOW_DEFAULT,
    40 * MHZ,
    PIN_SPI0_MISO_DEFAULT,   // default MISO pin
    PIN_SPI0_CS_DEFAULT,     // default CS   pin
    PIN_SPI0_SCK_DEFAULT,    // default SCK  pin
    PIN_SPI0_MOSI_DEFAULT,   // default MOSI pin
    true                     // use internal pull-up
};
pico_fatfs_set_config(&config);

The SPI bus operates at up to 40 MHz for high-speed data transfer, with slower clock speeds used during initialization.

Supported File Systems

The player relies on the FatFs library to handle SD card file systems. During startup in src/UIMode.cpp, the code mounts the card and detects the file system type, storing it in vars->fs_type.

The supported file systems are explicitly enumerated in the source:

// src/UIMode.cpp – recognised FatFs types
const char* fs_type_str[5] = {
    "NOT_MOUNTED",    // 0
    "FAT12",          // 1
    "FAT16",          // 2
    "FAT32",          // 3
    "EXFAT"           // 4
};

Thus, the RPi Pico WAV Player supports FAT12, FAT16, FAT32, and EXFAT partitions. If the card cannot be mounted, the UI reports "No SD Card Found!" or "SD Card Read Error!".

Implementation Details

Mounting and File System Detection

The initialization sequence uses file_menu_init() from lib/file_menu/file_menu_FatFs.h to configure the SPI bus and mount the volume. The function returns the detected file system type via a pointer parameter:

#include "file_menu_FatFs.h"
#include "ff.h"
#include <cstdio>

void mount_and_report() {
    uint8_t fs_type = 0;
    FRESULT fr = file_menu_init(&fs_type);   // initialise SPI and mount

    if (fr != FR_OK) {
        printf("Failed to mount SD card (error %d)\n", fr);
        return;
    }

    const char* fs_names[5] = {"NOT_MOUNTED","FAT12","FAT16","FAT32","EXFAT"};
    printf("SD Card File System = %s\r\n", fs_names[fs_type]);
}

EXFAT Workaround

The source code includes a specific workaround for EXFAT partitions due to a known FatFs bug when handling the ".." directory entry. In src/UIMode.cpp, when navigating up a directory on an EXFAT volume, the code re-opens the root directory and replays the directory stack rather than relying on the standard parent directory reference.

Summary

• SD Card Interface: SPI 0 peripheral via the pico_fatfs wrapper, operating at up to 40 MHz with board-default pin assignments.
• Supported File Systems: FAT12, FAT16, FAT32, and EXFAT (detected automatically by FatFs v0.90).
• Key Implementation Files: lib/file_menu/file_menu_FatFs.c for SPI configuration, src/UIMode.cpp for mounting and file system detection.
• Special Handling: EXFAT volumes include a workaround for FatFs parent-directory navigation bugs.

Frequently Asked Questions

What SPI peripheral does the RPi Pico WAV Player use for SD cards?

The player uses SPI 0 (spi0) as configured in lib/file_menu/file_menu_FatFs.c. The wrapper sets the default MISO, MOSI, SCK, and CS pins for the Raspberry Pi Pico board definition, enabling hardware SPI communication at up to 40 MHz.

Does the player support SDXC cards formatted with EXFAT?

Yes. The player supports EXFAT file systems, which are commonly used on SDXC cards larger than 32 GB. The FatFs library detects EXFAT volumes automatically, though the code in src/UIMode.cpp includes a specific workaround for a known FatFs bug when handling parent directory ("..") entries on EXFAT partitions.

Why does the code include a special case for EXFAT navigation?

The special handling addresses a known FatFs bug where the ".." directory entry does not function correctly on EXFAT volumes. When the user navigates up a directory on an EXFAT card, the code in src/UIMode.cpp re-opens the root directory and replays the directory stack rather than using the standard parent directory reference, ensuring reliable navigation.

What file systems are supported besides EXFAT?

The player supports the full range of legacy FAT formats detected by FatFs: FAT12, FAT16, and FAT32. These are automatically identified during the mount process in src/UIMode.cpp, where the fs_type variable stores the detected format as an integer corresponding to the file system type strings defined in the source code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}