Crate rs1541

rs1541

Rust bindings and helper functions for accessing Commodore disk drives.

Overview

This crate provides idiomatic Rust interfaces allowing easy control of Commodore disk drives (like the 1541) using modern USB devices such as the XUM1541. Thread-safe access is provided through protected mutex handles enables safe usage in multi-threaded and async applications.

The primary object is Cbm.

Features

• RAII-based driver management - no manual open/close needed
• Thread-safe access for multi-threaded and async applications
• Ergonomic error handling using Rust’s Result type
• Directory parsing with structured data types
• Strong typing for CBM-specific concepts (error codes, status messages, etc.)

Quick Start

use rs1541::Cbm;
use std::error::Error;

fn main() -> Result<(), Box<dyn Error>> {
    // Driver automatically opens on creation and closes on drop
    let cbm = Cbm::new(None, None)?;

    // Get drive information
    let id = cbm.identify(8)?;
    println!("Drive type at device 8: {}", id);

    // Check drive status
    let status = cbm.get_status(8)?;
    println!("Drive status: {}", status);

    // Read directory
    let dir = cbm.dir(8, None)?;
    println!("Directory listing:\n{}", dir);

    Ok(())
}

Requirements

• Rust installed on your system
• XUM1541 (or compatible) USB device
• Appropriate permissions to access the USB device

Error Handling

All operations that could fail return a Result type. Specific error conditions are represented by the Error type, which wraps both XUM1541 errors and drive-specific error codes.

Re-exports

pub use cbm::Cbm;

pub use cbmtype::CbmDeviceInfo;

pub use cbmtype::CbmDeviceType;

pub use cbmtype::CbmErrorNumber;

pub use cbmtype::CbmErrorNumberOk;

pub use cbmtype::CbmOperation;

pub use cbmtype::CbmOperationType;

pub use cbmtype::CbmStatus;

pub use cbmtype::DosVersion;

pub use channel::CbmChannel;

pub use channel::CbmChannelManager;

pub use channel::CbmChannelPurpose;

pub use channel::CBM_CHANNEL_CTRL;

pub use channel::CBM_CHANNEL_LOAD;

pub use disk::CbmDirListing;

pub use disk::CbmDiskHeader;

pub use disk::CbmFileEntry;

pub use disk::CbmFileType;

pub use drive::CbmDriveUnit;

pub use error::DeviceError;

pub use error::Error;

pub use string::AsciiString;

pub use string::CbmString;

pub use string::PetsciiString;

pub use util::ascii_str_to_petscii;

pub use util::ascii_to_petscii;

pub use util::petscii_str_to_ascii;

pub use util::petscii_to_ascii;

pub use validate::validate_device;

pub use validate::DeviceValidation;

Modules

cbm

A Rust interface for interacting with Commodore disk drives.

cbmtype

channel

disk

Contains types and functions for working with Commodore files and directories

drive

error

string

util

validate

Structs

DeviceChannel

Struct holding device and channel numbers. Used by crate::Bus functions which require the device and channel to be specified.

RemoteUsbDevice

UsbDevice

Device represents the physical XUM1541 USB adapter.

Enums

DeviceAccessError

Used to differentiate between different types of problems accessing the XUM1541 device

Xum1541Error

Error type for the xum1541 crate

Constants

DEFAULT_DEVICE_NUM

Default device number for Commodore disk drives

DEFAULT_REMOTE_ADDR

DEFAULT_REMOTE_PORT

DEVICE_MAX_NUM

Maximum Commodore disk drive device number - derived from the maximum number which can be set, with software, on the 1571

DEVICE_MIN_NUM

Minimum (and default) Commodore disk drive device number. Devices lower tha 8 are reserved for other device types, such as printers and tape drives, and built in devices like keyboard and screen

XUM1541_PRODUCT_ID

USB Product ID for an XUM1541 dvice

XUM1541_VENDOR_ID

USB Vendor ID for an XUM1541 device

Traits

Device

The core Device trait, which allows Device to be mocked out for testing