An interactive command-line shell for exploring the P2 SD card filesystem driver. Supports both DOS-style (dir, type, del) and Unix-style (ls, cat, rm) commands.
Who this is for: the user — an interactive shell for exploring the driver by hand. Focused copy-paste examples are in
src/EXAMPLES/; standalone tools are insrc/UTILS/; developer probes are indiagnostic-tests/.
| File | Description |
|---|---|
SD_demo_shell.spin2 |
Main shell application |
isp_serial_singleton.spin2 |
Serial terminal driver (singleton, shared across cogs) |
The shell also uses micro_sd_fat32_fs.spin2 and isp_mem_strings.spin2 from the parent
directory (included via -I ..), and isp_fsck_utility.spin2 and isp_format_utility.spin2
from src/UTILS/ (included via -I ../UTILS) to back the fsck, audit and format
commands. isp_mem_strings.spin2 is shared with the utilities, so it lives at src/ rather
than here.
- pnut-ts and pnut-term-ts - See detailed installation instructions for macOS, Windows, and Linux/RPi
- Parallax Propeller 2 (P2 Edge or P2 board with microSD add-on) connected via USB
From this DEMO/ directory:
pnut-ts -I .. -I ../UTILS SD_demo_shell.spin2
pnut-term-ts -r SD_demo_shell.binThe -I .. flag tells the compiler to find micro_sd_fat32_fs.spin2 in the parent directory;
-I ../UTILS finds the fsck and format libraries. Both are required — the shell will not
compile without them.
Important: Do NOT use the -d (debug) flag when compiling the demo shell. The debug runtime emits cog-start frames on pin 62 that corrupt the serial output when the SD worker cog starts mid-session (e.g., during mount). The demo shell uses isp_serial_singleton.spin2 for all terminal I/O, not the debug system.
Connect a serial terminal to the P2 programming port:
- Baud rate: 2,000,000 (2 Mbit)
- Data format: 8N1
- Terminal type: PST (Parallax Serial Terminal) compatible
- Flow control: None
The shell uses PST control characters for screen clearing (CLS = 16) and cursor control.
When the shell starts, it clears the screen and displays a welcome banner:
P2 SD Card Filesystem Shell
- type 'help' for commands
The prompt shows the current directory and mount status:
SD:/> _ (mounted, at root)
SD:/MYDIR> _ (mounted, in MYDIR)
SD:(unmounted)> _ (card not mounted)
The SD card must be mounted before any filesystem operations:
SD:(unmounted)> mount
Mounting SD card...
Mounted successfully
Card: PNY SD16G (16 GB)
SPI: 25000000 Hz
Free: 15.9 GB
SD:/>
SD:/> dir
Directory of /
Attr Modified Size Name
---- ---------------- -------- --------------------------------
D--- 2026-03-17 10:00 <DIR> MYDIR
---- 2026-03-17 14:30 1234 README.TXT
---- 2026-03-15 09:15 65536 DATA.BIN
3 file(s), 66770 bytes
SD:/> cd MYDIR
SD:/MYDIR> dir
Directory of /MYDIR
Attr Modified Size Name
---- ---------------- -------- --------------------------------
---- 2026-03-17 14:30 512 NOTES.TXT
1 file(s), 512 bytes
SD:/MYDIR> cd /
SD:/>
SD:/> type README.TXT
Hello from the P2 SD card driver!
This is a demo text file.
[58 bytes]
SD:/> hexdump DATA.BIN
00000000 48 65 6c 6c 6f 20 57 6f 72 6c 64 21 0d 0a 00 00 |Hello World!....|
... (truncated at 512 bytes)
SD:/> copy README.TXT BACKUP.TXT
Copied 58 bytes to BACKUP.TXT
SD:/> ren BACKUP.TXT SAVED.TXT
Renamed 'BACKUP.TXT' to 'SAVED.TXT'
SD:/> touch EMPTY.TXT
Created: EMPTY.TXT
SD:/> mkdir NEWDIR
Created directory: NEWDIR
SD:/> del EMPTY.TXT
Deleted: EMPTY.TXT
SD:/> stats
Volume label: P2FMTER
Free space: 15.9 GB (31199056 sectors)
Cluster size: 16 sectors (8192 bytes)
SD:/> card
Manufacturer: PNY (0x27)
Product: SD16G
Revision: 2.0
Serial: 0x0BADCAFE
Date: 06/2023
SD:/> version
SD Card Driver - Iron Sheep Productions
SPI Frequency: 25000000 Hz
SD:/> date
2009-01-27 07:00:00
SD:/> date 2026 3 17 14 30 0
Date set: 2026-03-17 14:30:00
Audit - read-only filesystem integrity check. FSCK - filesystem check and repair.
Both commands delegate to the same four-pass engine the standalone utilities use
(isp_fsck_utility), so their output is identical to it. The canonical,
capture-stamped transcript lives in
DOCs/SD-CARD-UTILITIES.md — see the
SD_FAT32_audit and SD_FAT32_fsck sections.
fsck prompts for confirmation before writing:
SD:/> fsck
WARNING: FSCK will modify the SD card to fix errors.
Continue? (Y/N): y
Benchmark - read-only throughput measurement. Timings vary by card; run it on yours rather than relying on the figures below.
SD:/> bench
Initializing card...
=== Read-Only Throughput Benchmark ===
Card: 7431 MB, SPI: 25000000 Hz
Test area: sectors 1000+
Single-sector (100 reads)... 123 ms, 415 KB/s
Multi-sector x8 (100 reads)... 89 ms, 573 KB/s
Multi-sector x32 (25 reads)... 71 ms, 720 KB/s
| Command | Description |
|---|---|
demo |
Create sample files for testing |
cls / clear |
Clear the terminal screen |
help |
Show all available commands |
| Command | Aliases | Description |
|---|---|---|
mount |
Mount the SD card | |
unmount |
eject |
Safely unmount the SD card |
dir |
ls |
List directory contents |
cd <path> |
Change directory (cd .., cd /, cd SUBDIR) |
|
pwd |
Print current working directory |
| Command | Aliases | Description |
|---|---|---|
type <file> |
cat |
Display text file contents |
hexdump <file> |
hd |
Display file in hex dump format |
copy <src> <dst> |
cp |
Copy a file |
ren <old> <new> |
mv |
Rename a file or directory |
del <file> |
rm |
Delete a file |
touch <file> |
Create an empty file | |
mkdir <dir> |
Create a new directory | |
rmdir <dir> |
Remove an empty directory |
| Command | Aliases | Description |
|---|---|---|
stats |
info |
Show filesystem statistics |
card |
cid |
Show card identification (CID register) |
version |
Show driver version and SPI frequency | |
date |
Show current date/time | |
date YYYY MM DD HH MM SS |
Set date/time for file timestamps |
| Command | Aliases | Description |
|---|---|---|
audit |
Read-only filesystem integrity check | |
fsck |
Filesystem check and repair (prompts before modifying) | |
bench |
benchmark, perf |
Read throughput benchmark |
The microSD add-on board connects to any 8-pin header group on the P2. Pins are defined as offsets from the base pin of the group:
| Offset | Signal | Description |
|---|---|---|
| +5 | CLK (SCK) | Serial Clock |
| +4 | CS (DAT3) | Chip Select |
| +3 | MOSI (CMD) | Master Out, Slave In |
| +2 | MISO (DAT0) | Master In, Slave Out |
| +1 | Insert Detect | Active low when card inserted (not used by driver) |
The default configuration uses base pin 56 (P2 Edge Module):
CON
SD_BASE = 56
SD_SCK = SD_BASE + 5 ' P61 - Serial Clock
SD_CS = SD_BASE + 4 ' P60 - Chip Select
SD_MOSI = SD_BASE + 3 ' P59 - Master Out Slave In
SD_MISO = SD_BASE + 2 ' P58 - Master In Slave Out
To use a different 8-pin group, change SD_BASE in the CON section of SD_demo_shell.spin2.
The demo shell runs as a single-cog application:
- Main loop - reads commands from serial, parses tokens, dispatches to handlers
- SD card driver - runs its own worker cog for SPI operations (started on
mount) - Serial driver - singleton serial terminal on the programming port (P62/P63)
The shell maintains its own current working directory string (cwd) for the prompt display, synchronized with the driver's per-cog CWD via changeDirectory().
Part of the P2 microSD FAT32 Filesystem project — Iron Sheep Productions