File-Based Communication Protocol

Understanding how Python communicates with ChemStation is crucial for troubleshooting and advanced usage. This page explains the file-based protocol that enables reliable command execution.

How It Works

The file-based communication protocol is adapted and enhanced from the original concept developed by Alexander Hammer and Hessam Mehr from the Cronin Group. The original implementation can be found at https://github.com/croningp/analyticallabware/tree/master/AnalyticalLabware/devices/Agilent. Our implementation builds upon their foundational work with improvements for CE-specific operations and enhanced reliability.

The protocol creates a reliable bidirectional communication channel between Python and ChemStation by using monitored files as the communication medium. This approach ensures that commands are not lost and responses are properly matched to their originating requests.

Communication Flow

sequenceDiagram
    participant Python
    participant CommandFile
    participant ResponseFile
    participant Macro
    participant ChemStation

    Python->>CommandFile: Write "1 LoadMethod MyMethod.M"
    Macro->>CommandFile: Read command
    Macro->>ChemStation: Execute LoadMethod
    ChemStation-->>Macro: Return result
    Macro->>ResponseFile: Write "1 None"
    Python->>ResponseFile: Read response

The macro runs continuously within ChemStation, monitoring the command file every 200ms for new commands. When a new command is detected (identified by a higher command number than previously processed), the macro executes it through ChemStation's Command Processor and writes the response to the response file.

Command Format

Basic Commands

Commands without return values:

# Python code
api.send("LoadMethod _METHPATH$, MyMethod.M")

# Command file content
123 LoadMethod _METHPATH$, MyMethod.M

# Response file content
123 None

Commands with Return Values

To capture a return value, prefix with response$ =:

# Python code
path = api.send("response$ = _METHPATH$")

# Command file content
124 response$ = _METHPATH$

# Response file content
124 C:\Chem32\1\Methods\CE\

Command Numbering

The protocol uses sequential command numbers to match responses with requests:

Numbers increment from 1 to 256 (configurable)
Automatically wraps around at maximum
Ensures each command gets its correct response
Prevents mixing responses from multiple commands

# Example of command numbering in action
1 response$ = _METHPATH$
2 LoadMethod _METHPATH$, Test.M
3 response$ = VAL$(_MethodOn)
...
256 response$ = ACQSTATUS$
1 response$ = _DATAPATH$  # Wraps around

File Locations

Default file locations:

SIA-CE/
└── ChemstationAPI/
    └── core/
        ├── ChemPyConnect.mac          # Macro file
        └── communication_files/       # Communication directory
            ├── command               # Command file
            └── response              # Response file

Monitoring Communication

Enable Verbose Mode

from ChemstationAPI.core.communication_config import CommunicationConfig

config = CommunicationConfig(verbose=True)
api = ChemstationAPI(config)

# Now all commands and responses are printed
api.send("response$ = _METHPATH$")
# Output:
# Sending command 1: response$ = _METHPATH$
# Received response 1: C:\Chem32\1\Methods\CE\

Error Handling

Timeout Handling

# Increase timeout for long operations
api.send("RunMethod _DATAPATH$,, Sample001", timeout=30.0)

Error Responses

ChemStation errors are detected and raised as exceptions. Here's an example of what happens when you send an invalid command:

try:
    api.send("InvalidCommand parameter")
except ChemstationError as e:
    print(f"Error: {e}")
    # Output: Error: ChemStation command failed: ERROR: The command InvalidCommand failed to execute. Error message: Invalid command syntax

When ChemStation cannot execute a command due to syntax errors, wrong parameters, or system state conflicts, it returns an error message that starts with "ERROR:". The API automatically detects these error responses and raises a ChemstationError exception with the detailed error message from ChemStation.

Common error scenarios: - Invalid command syntax - Wrong parameter types or values - Commands not available in current mode - Instrument state conflicts

Macro Initialization

The ChemStation macro must be running for communication to work:

ChemStation command processor:

macro "C:\path\to\ChemPyConnect.mac"; Python_Run

The macro runs in a continuous loop: 1. Reads command file every 200ms 2. Executes new commands (higher number than last) 3. Writes responses 4. Continues until "Exit" command

Advanced Configuration

Custom Configuration

from ChemstationAPI.core.communication_config import CommunicationConfig

config = CommunicationConfig(
    comm_dir="custom/path",
    max_command_number=1000,
    retry_delay=0.2,
    max_retries=5,
    default_timeout=10.0
)

api = ChemstationAPI(config)

Configuration Options

Parameter	Default	Description
`comm_dir`	`"core/communication_files"`	Communication directory
`max_command_number`	`256`	Maximum before wraparound
`retry_delay`	`0.1`	Seconds between retries
`max_retries`	`10`	Maximum retry attempts
`default_timeout`	`5.0`	Default command timeout
`verbose`	`False`	Enable debug output

Troubleshooting Protocol Issues

No Response Received

Symptoms: TimeoutError after sending command

Check: 1. Is ChemStation macro running? 2. Are file paths correct? 3. Can Python write to communication directory?

Wrong Response Received

Symptoms: Response doesn't match command

Check: 1. Command numbering synchronization 2. Multiple Python instances running? 3. Old responses in response file?

Slow Communication

Symptoms: Commands take long to execute

Solutions: 1. Reduce retry_delay in configuration 2. Check disk performance 3. Ensure antivirus isn't scanning communication files

Understanding the Protocol

The file-based protocol might seem complex, but it's very reliable once properly configured. Most issues come from macro not running or incorrect file paths.