Skip to main content

Syncing with Computer

USBFS (USB File System) provides a convenient way to transfer files between your computer and Spectranext over USB-C. Files uploaded via USBFS are stored in the RAM filesystem and can be accessed from Spectrum programs using the XFS filesystem. This is essential for development workflows where you edit code on your computer and test on the Spectrum.

Overview​

USBFS provides:

  • File Transfer: Upload/download files over USB to RAM filesystem
  • Directory Operations: List, create, delete directories
  • File Management: Move, rename, delete files
  • XFS Integration: Files uploaded via USBFS are accessible from Spectrum using XFS
  • Development Workflow: Edit on PC, upload via USBFS, access via XFS on Spectrum

Setup​

  1. Connect USB-C: Connect Spectranext to your computer
  2. Source SDK: see Syncing With Computer

Basic Commands​

List Files​

xfs-ls [path]

Examples:

xfs-ls              # List root

Download File​

xfs-get <remote> <local>

Example:

xfs-get program.tap ./program.tap

Upload File​

xfs-put <local> <remote>

Example:

xfs-put ./game.tap game.tap

Move/Rename File​

xfs-mv <old> <new>

Example:

xfs-mv temp.txt final.txt

Delete File​

xfs-rm <path>

Example:

xfs-rm oldfile.txt

Create Directory​

xfs-mkdir <path>

Example:

xfs-mkdir /ram/games

Remove Directory​

xfs-rmdir <path>

Example:

xfs-rmdir games

Reboot ZX Spectrum​

xfs-reboot

This command triggers a hardware reset of the ZX Spectrum. Useful after uploading files or making configuration changes that require a reboot.

Example:

xfs-reboot

Note: The command sends an OK response before triggering the reset, so the connection will be lost immediately after.

Development Workflow​

Typical Workflow​

  1. Edit on Computer: Write/modify code on your PC
  2. Compile: Build your program (e.g., with z88dk)
  3. Upload to RAM: Use xfs-put to upload files to RAM filesystem
  4. Mount XFS: On Spectrum, mount XFS filesystem: %mount 0, "xfs://ram/" (or configure to have that on every boot)
  5. Access Files: Use standard Spectranet commands (%load, %cat, %open, etc.) to access uploaded files
  6. Test on Spectrum: Load and test your program
  7. Iterate: Repeat as needed

Note: Files uploaded via USBFS are stored in the RAM filesystem. To access them from Spectrum programs, you must mount XFS first. See the XFS Filesystem documentation for details on mounting and accessing files.

Example Script​

#!/bin/bash
# Build and upload script

# Compile
zcc +zx -o program.tap program.c

# Upload to RAM filesystem (accessible via XFS)
xfs-put program.tap program.tap

# Files are now available on Spectrum after mounting XFS:
# %mount 0, "xfs://ram/"
# %load "program.tap"
xfs-reboot

Important: After uploading files via USBFS, mount XFS on Spectrum to access them. See XFS Filesystem for mounting instructions.

Automated Workflow​

You can integrate USBFS into your build system:

upload: program.tap
	xfs-put program.tap program.tap
	# Files uploaded to RAM filesystem, accessible via XFS

test: upload
	# Trigger test on Spectrum (after mounting XFS)

Note: Remember to mount XFS on Spectrum (%mount 0, "xfs://ram/") before accessing uploaded files. See XFS Filesystem for details.

Python API​

For advanced usage, you can use the Python API directly:

from tools.xfs import XFSConnection

# Connect
conn = XFSConnection()

# List files in RAM filesystem
entries = conn.ls("/")
for entry_type, name, size in entries:
    print(f"{entry_type} {name} {size}")

# Upload file to RAM filesystem (accessible via XFS)
conn.put("./local.txt", "remote.txt")

# Download file from RAM filesystem
conn.get("remote.txt", "./local.txt")

# Delete file
conn.rm("remote.txt")

# Reboot ZX Spectrum
conn.reboot()

Note: Files uploaded via USBFS are stored in the RAM filesystem. Access them from Spectrum programs by mounting XFS (%mount 0, "xfs://ram/"). See XFS Filesystem for accessing files from Spectrum.

Protocol Details​

File Upload​

Upload process:

  1. Send PUT <path> <size>\n command
  2. Send binary file data immediately after
  3. Receive OK\n or ERR <code> <message>\n response

File Download​

Download process:

  1. Send GET <path>\n command
  2. Receive OK <size>\n response
  3. Read <size> bytes of binary data

Directory Listing​

Listing process:

  1. Send LS <path>\n command
  2. Receive OK\n response
  3. Receive lines: [D|F] <name> <size>\n
  4. Empty line indicates end

Best Practices​

File Organization​

  1. Use RAM for testing: Fast and automatically cleared
  2. Use Flash for releases: Persistent storage
  3. Organize by project: Create directories per project
  4. Keep names short: Spectrum has filename limitations

Transfer Efficiency​

  1. Batch operations: Group file operations
  2. Use RAM first: Test in RAM before committing to flash
  3. Compress when possible: Smaller files transfer faster
  4. Monitor progress: Watch transfer progress

Error Handling​

  1. Check responses: Verify operations succeeded
  2. Handle errors: Check error codes
  3. Retry on failure: Network issues may cause failures
  4. Verify transfers: Check file sizes after transfer

Troubleshooting​

Connection Issues​

If USBFS doesn't connect:

  • Verify USB-C cable supports data
  • Check device is powered on
  • Try different USB port
  • Verify second CDC interface is available

Transfer Failures​

If transfers fail:

  • Check file paths are correct
  • Verify sufficient space available
  • Check file permissions
  • Review error messages

Slow Transfers​

If transfers are slow:

  • USBFS uses 115200 baud (~11KB/s)
  • Large files take time
  • Use progress indicators
  • Consider TNFS for very large files

Advanced Usage​

Custom Tools​

You can create custom tools using the Python API:

#!/usr/bin/env python3
import sys
from tools.usbfs import USBFSConnection

def main():
    conn = USBFSConnection()
    
    if sys.argv[1] == "sync":
        # Sync directory
        local_dir = sys.argv[2]
        remote_dir = sys.argv[3]
        # ... sync logic ...
    
    elif sys.argv[1] == "backup":
        # Backup all files
        # ... backup logic ...

if __name__ == "__main__":
    main()

Integration with IDEs​

You can integrate USBFS with development environments:

  • VS Code: Tasks for upload/download
  • Makefiles: Build targets for transfer
  • Scripts: Automated deployment

Limitations​

  • Transfer Speed: ~11KB/s over USB serial
  • File Size: Limited by available RAM/flash
  • Concurrent Operations: One operation at a time
  • Network Required: USBFS uses USB, not network

USBFS Protocol​

USBFS uses a simple text-based protocol over a second CDC (USB serial) interface:

Commands​

  • LS <path> - List directory
  • GET <path> - Download file
  • PUT <path> <size> - Upload file
  • MV <old> <new> - Move/rename file
  • RM <path> - Delete file
  • MKDIR <path> - Create directory
  • RMDIR <path> - Remove directory
  • STATUS - Check connection status
  • REBOOT - Trigger ZX Spectrum hardware reset

Responses​

  • OK - Success
  • OK <value> - Success with value (e.g., file size)
  • ERR <code> <message> - Error with code and message

Next Steps​