# RPi Pico WAV Player SD Card Interface and Supported File Systems

> Discover the RPi Pico WAV Player's SPI 0 SD card interface. Learn about its support for FAT12, FAT16, FAT32, and exFAT file systems using the FatFs library.

- Repository: [Elehobica/rpi_pico_wav_player](https://github.com/elehobica/rpi_pico_wav_player)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/elehobica/rpi_pico_wav_player/blob/main/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).

```cpp
// 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`](https://github.com/elehobica/rpi_pico_wav_player/blob/main/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:

```cpp
// 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`](https://github.com/elehobica/rpi_pico_wav_player/blob/main/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:

```cpp
#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`](https://github.com/elehobica/rpi_pico_wav_player/blob/main/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`](https://github.com/elehobica/rpi_pico_wav_player/blob/main/lib/file_menu/file_menu_FatFs.c) for SPI configuration, [`src/UIMode.cpp`](https://github.com/elehobica/rpi_pico_wav_player/blob/main/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`](https://github.com/elehobica/rpi_pico_wav_player/blob/main/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`](https://github.com/elehobica/rpi_pico_wav_player/blob/main/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`](https://github.com/elehobica/rpi_pico_wav_player/blob/main/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`](https://github.com/elehobica/rpi_pico_wav_player/blob/main/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.