Spectramax Plate Reader Controller

A Python interface for controlling Molecular Devices SpectraMax plate readers via the SoftMax Pro Software Automation API.

Overview

This project provides a high-level Python wrapper for the SoftMax Pro Automation API, enabling programmatic control of SpectraMax plate readers. It supports both real hardware control and simulation mode for development and testing.

Features

• Plate Reader Control: Open/close drawer, perform UV-Vis reads, set temperature
• Data Management: Save data in multiple formats (.sda, .csv, .xml)
• Event Handling: Asynchronous command completion and error reporting
• Simulation Mode: Test functionality without physical hardware
• Type Safety: Full type hints for better development experience

Requirements

• Python 3.7+
• SoftMax Pro 7.0+ (for real hardware control)
• SoftMax Pro Automation SDK (for real hardware control)

Installation

1. Clone the repository:

git clone <repository-url>
cd Spectramax

2. Install dependencies:

pip install -r requirements.txt

3. For real hardware control, install the SoftMax Pro Automation SDK:
   • Download from Molecular Devices website
   • Install to default location: C:\Program Files (x86)\Molecular Devices\SoftMax Pro 7.0 Automation SDK
   • Update AUTOMATION_SDK_PATH in spectramax.py if needed

Quick Start

from spectramax import Spectramax

# Create controller instance
spectramax = Spectramax()

# Initialize connection
if spectramax.initialize():
    print("Connected successfully!")
    
    # Setup reader (simulation mode)
    spectramax.setup_reader(
        port="Offline",
        instrument="SPECTRAmax M5",
        simulation=True
    )
    
    # Perform operations
    spectramax.open_drawer()
    
    # Always disconnect when done
    spectramax.disconnect()

API Reference

Spectramax Class

Constructor

Spectramax(server: str = "localhost", port: int = 9000)

Methods

initialize() -> bool

Initialize connection to SoftMax Pro software.

Returns: True if connection successful, False otherwise

disconnect()

Disconnect from SoftMax Pro and clean up resources.

setup_reader(port: str, instrument: str, simulation: bool) -> bool

Configure the plate reader.

Parameters:

• port: Communication port (e.g., "COM1" or "Offline")
• instrument: Instrument model name
• simulation: Enable simulation mode

Returns: True if setup successful

open_drawer() -> bool

Open the plate drawer.

Returns: True if operation successful

close_drawer() -> bool

Close the plate drawer.

Returns: True if operation successful

read_UVVis(method: str, results: str) -> bool

Perform a UV-Vis read using the specified method and save results.

Parameters:

• method: File path to the method file (.spr protocol file)
• results: Base file path for results (without extension)

Returns: True if read and save operations successful

Output Files:

• .sda: SoftMax Pro data file
• .csv: CSV export (COLUMNS format)
• .xml: XML export

get_data() -> Optional[str]

Get the current plate data.

Returns: Plate data as tab-delimited string, or None if error

set_temperature(temperature: float) -> bool

Set the incubator temperature.

Parameters:

• temperature: Temperature in Celsius (0 to turn off)

Returns: True if successful

get_instrument_status() -> str

Get current instrument status.

Returns: Current instrument status string

save_data(file_path: str) -> bool

Save the current document.

Parameters:

• file_path: Full path for saving (use .sda extension for data files)

Returns: True if save successful

export_data(file_path: str, format_type: str) -> bool

Export data in specified format.

Parameters:

• file_path: Full path for export
• format_type: Export format ("XML", "PLATE", "COLUMNS", "TIME")

Returns: True if export successful

Usage Examples

Basic UV-Vis Read

from spectramax import Spectramax

spectramax = Spectramax()

try:
    if not spectramax.initialize():
        print("Failed to initialize")
        return
    
    # Setup reader
    spectramax.setup_reader(
        port="Offline",
        instrument="SPECTRAmax M5",
        simulation=True
    )
    
    # Perform UV-Vis read
    method_file = r"C:\Path\To\Your\Method.spr"
    results_base = r"C:\Path\To\Results\experiment_001"
    
    if spectramax.read_UVVis(method_file, results_base):
        print("UV-Vis read completed successfully")
    else:
        print("UV-Vis read failed")
        
finally:
    spectramax.disconnect()

Temperature Control

# Set temperature to 37°C
spectramax.set_temperature(37.0)

# Turn off temperature control
spectramax.set_temperature(0.0)

Data Export

# Export as CSV
spectramax.export_data("data.csv", "COLUMNS")

# Export as XML
spectramax.export_data("data.xml", "XML")

Error Handling

The library provides comprehensive error handling:

• Connection errors are caught and reported
• Command timeouts are handled gracefully
• Event-based error reporting for real-time feedback
• Simulation mode allows testing without hardware

Development

Running Tests

python main.py

Adding New Features

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

Troubleshooting

Common Issues

1. Import Error: Make sure pythonnet is installed
2. SDK Path Error: Verify the SoftMax Pro Automation SDK path
3. Connection Failed: Ensure SoftMax Pro is running and accessible
4. Permission Error: Run as administrator if needed

Simulation Mode

If you don't have access to SoftMax Pro hardware, the library will automatically run in simulation mode, allowing you to test the API without physical equipment.

License

[Add your license information here]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions:

1. Check the troubleshooting section
2. Review the API documentation
3. Open an issue on GitHub

Changelog

Version 1.0.0

• Initial release
• Basic plate reader control functionality
• UV-Vis read support
• Data export capabilities
• Simulation mode support