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.

Onboard writable storage 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.

On hardware with USB host support, a connected USB drive also appears in the local filesystem and takes priority over onboard storage. New files and uploads go to that drive while it is available.

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

Uploaded files are immediately available from Spectrum programs through %mount "xfs://ram/". Without a USB drive, uploads go to temporary RAM; commit them to flash from the Browser or with spx commit to keep them after power loss. With a USB drive available, uploads go to the drive and are already persistent.

Development Workflow​

Method 1: Web File Browser​

The device web tool includes a file browser and terminal. You can connect over USB or Wi-Fi.

Connect over USB​

  1. Open the File Browser: Navigate to device.spectranext.net in your web browser
  2. Connect to Device: Choose USB serial, 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 USB connection uses the browser's Web Serial API. To make RAM 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.

Connect over Wi-Fi​

  1. Connect Spectranext to your Wi-Fi network and put your computer on the same local network.
  2. Find Spectranext's IP address in its network configuration or your router's connected-device list.
  3. Open http://<device-IP>/ in your browser, replacing <device-IP> with that address—for example, http://192.168.1.42/.

Spectranext serves its own copy of the web tool and connects to that device automatically. You can browse, upload, download, and manage files, or open the terminal, without a USB cable to your computer. This is especially useful when the USB-C port is being used for a storage drive.

Use the device's HTTP address for this connection. The public HTTPS site is the convenient entry point for USB access; the device-hosted page provides the direct local Wi-Fi connection.

USB storage and ejection​

USB files appear alongside onboard files in the browser and are marked as USB storage. While a drive is available, new uploads go to it. These files persist on the drive without committing them to flash.

Before unplugging a drive, finish transfers and close any files your Spectrum programs are using, then click USB EJECT. Wait for the confirmation that the drive can be removed safely. See USB storage for mounting and loading files from BASIC.

Terminal​

Click the terminal area to open the device console. The terminal uses the selected connection; other tools cannot use that connection at the same time. Refresh the page to release it when finished.

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 device-hosted Wi-Fi web tool described above is provided by physical Spectranext hardware.

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 with the default XFS filesystem. Files uploaded via spx put go to temporary RAM unless a USB drive is available. Use spx commit <path> to copy a RAM file or directory into the overlayed flash filesystem; files on USB already persist on that drive.

Next Steps​