Skip to main content

Syncing with Computer

Spectranext includes an onboard XFS filesystem directly on the cartridge, providing local storage that doesn't require a network connection. You can upload files directly to the cartridge from your computer, and then access them from Spectrum programs by mounting the XFS filesystem. This provides a simple, convenient way to transfer files for development workflows.

The local filesystem has two layers:

  • 4MB temporary RAM storage for quick upload-test-replace iterations and scratch files used by programs.
  • 4MB overlayed flash storage for files and directories you commit so they survive power loss.

Overview​

Spectranext provides multiple ways to upload files to the cartridge's onboard XFS filesystem:

  1. Web File Browser: Access the file manager at device.spectranext.net (recommended)
  2. SPX Command-Line Tool: Upload/download files via spx command

All methods upload files to the cartridge's RAM layer first, which can then be accessed from Spectrum programs by mounting the XFS filesystem: %mount "xfs://ram/". Files are stored directly on the cartridge, making them immediately available without requiring a network connection or TNFS server. If you want a file or directory to persist, commit it to flash from the Browser or with spx commit.

Development Workflow​

Method 1: Web File Browser​

The easiest way to manage files on your Spectranext cartridge is through the web-based file browser:

  1. Open the File Browser: Navigate to device.spectranext.net in your web browser
  2. Connect to Device: Click the "Connect" button and select your Spectranext device from the USB device picker (the device named "spectranext")
  3. Manage Files: Once connected, you can:
    • Browse the local XFS filesystem
    • Upload files via drag-and-drop
    • Download files
    • Create/delete directories
    • View text file contents
    • Commit selected files or directories to flash
    • Refresh the file list

The file browser uses the Web Serial API to communicate directly with your Spectranext device via USB CDC. Files uploaded via the browser are immediately stored in temporary RAM and can be accessed after mounting XFS on Spectrum. To make selected files permanent, click the disk icon labelled Commit To Flash. Committed items are shown as stored in flash and remain available after power loss.

Browser Compatibility: The Web Serial API is supported in Chromium-based browsers (Chrome, Edge, Opera). Firefox and Safari do not currently support Web Serial API.

Method 2: SPX Command-Line Tools​

Note on accessing SPX

In order for spx tools to work, add spectranext-sdk/bin folder to your PATH. Installation script helps you do that.

Working with FuseX Emulator

The SPX command-line tools and SDK operations work with both physical Spectranext hardware and the FuseX emulator. When using FuseX, the spx tool will connect via TCP instead of USB. This allows you to develop and test your programs entirely in the emulator before deploying to physical hardware.

The web file browser (Method 1) only works with physical hardware via USB CDC.

The SDK provides spx command-line tool for programmatic file transfer:

# List files in XFS, including ram/committed storage state
spx ls

# Upload a file
spx put localfile.bin /remotefile.bin

# Download a file
spx get /remotefile.bin localfile.bin

# Create directory
spx mkdir /mydir

# Move/rename file
spx mv /oldname.bin /newname.bin

# Delete file
spx rm /file.bin

# Commit a file or directory to flash
spx commit /file.bin

# Remove directory
spx rmdir /mydir

# Trigger ZX Spectrum reboot
spx reboot

# Configure autoboot from xfs://ram/ and reboot
spx autoboot

The spx tool connects via USB CDC for physical hardware (or TCP for FuseX emulator) and works directly with the cartridge's onboard XFS filesystem. Files uploaded via spx put go to temporary RAM and are immediately available on the cartridge/emulator. Use spx commit <path> when you want that file or directory copied into the overlayed flash filesystem.

Next Steps​