ghosty 0.1.2

Wrapper for the Table Stable Ltd. Ghost Software

Ghosty - GHOST Brillouin Spectrometer Control

Python interface for controlling the GHOST Brillouin spectrometer software via TCP/IP communication.

Features

• Asynchronous control interface for the GHOST spectrometer
• Automatic timing calculations based on clock frequency
• Robust acquisition with timeout handling and retry logic
• Acquisition timing logging
• Working directory management
• Comprehensive error handling and recovery
• Support for both standard (4 kHz) and high-speed (10 kHz) modes

Installation

From Git Repository

1. Clone the repository:

git clone https://github.com/timm-landes/ghosty.git
cd ghosty

2. Create and activate a virtual environment (recommended):

python -m venv venv
# On Windows:
.\venv\Scripts\activate
# On Linux/Mac:
source venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Install in development mode:

pip install -e .

Quick Start

import asyncio
from ghosty import BrillouinSpectrometer

async def main():
    # Create spectrometer instance (4 kHz standard mode)
    spec = BrillouinSpectrometer(clock_frequency_khz=4)
    
    try:
        # Initialize connection
        await spec.initialize()
        
        # Set working directory
        await spec.set_working_directory("C:/Data")
        
        # Acquire data
        await spec.acquire_and_save(cycles=10, fname="spectrum.DAT")
        
    finally:
        # Clean up
        await spec.close()

asyncio.run(main())

Operating Modes

Standard Mode (4 kHz)

• Uses full 2048 MCA channels
• Scan time: ~512 ms
• Total cycle time: ~615 ms (scan + retract)

High-Speed Mode (10 kHz)

• Uses 512 MCA channels
• Scan time: ~205 ms
• Total cycle time: ~250 ms (scan + retract)
• Requires hardware modifications

Communication Protocol

The GHOST software uses a TCP/IP protocol with the following specifications:

• Port: 4000 (default)
• Encoding: UTF-8
• Command termination: \r\n (CR+LF)
• Maximum command length: 80 characters
• Default timeout: 5 seconds

Key Components

BrillouinSpectrometer

High-level interface providing:

• Connection management
• Acquisition control
• Timing calculations
• Error handling
• Status monitoring

TcpIpController

Low-level communication handling:

• TCP/IP connection management
• Command sending/receiving
• Protocol implementation
• Basic error checking

Command Reference

Available commands through the TcpIpController:

Command	Description	Response Expected
OBSERVE	Start observation	No
STATUS	Get system status	Yes
START n	Start n acquisition cycles	No
STOP	Stop acquisition	No
SAVE name	Save data to file	No
DELETE	Clear data buffer	No
WDIR path	Set working directory	No

Timing Details

Timing calculations are based on the spectrometer's clock frequency:

cycle_time_ms = (2460 / clock_frequency) * 1000

Safety margins:

• Minimum wait: 60% of theoretical time
• Timeout: theoretical time + 10 cycles
• Status confirmation: 2 consecutive IDLE states

Error Handling

The library implements multiple layers of error handling:

1. Connection-level errors
2. Command validation
3. Response verification
4. Timeout protection
5. Status monitoring
6. Resource cleanup

Logging

Uses loguru for comprehensive logging:

• Debug level: Command details
• Info level: Operation status
• Warning level: Timing issues
• Error level: Operation failures
• Trace level: Detailed status

Requirements

• Python ≤ 3.12.9 (for telnetlib) or telnetlib3 when using Python ≥ 3.13
• asyncio
• loguru

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - See LICENSE file for details

Acknowledgments

Based on the GHOST spectrometer software communication protocol.

Development Setup

For development work:

1. Clone the repository as described above
2. Install development dependencies:

pip install -r requirements.txt

3. Setup pre-commit hooks:

pre-commit install

Repository

The project is hosted on GitLab at the University of Hannover: https://gitlab.uni-hannover.de/phytophotonics/ghosty (internal use) and publically available hosted at GitHub: https://github.com/timm-landes/ghosty

Authors

Project Lead:

• Timm Landes
  • Leibniz University Hannover
  • Email: [e-mail]
  • ORCID: https://orcid.org/0000-0001-8953-3003

Contributors:

• Dag Heinemann
  • Leibniz University Hannover
  • Email: [e-mail]
  • ORCID: https://orcid.org/0000-0003-3506-1762

Citing Ghosty

If you use Ghosty in your research, please cite it as follows:

BibTeX

@software{ghosty2024,
  author       = {Landes, Timm and Heinemann, Dag},
  title        = {Ghosty: A Python Interface for GHOST Brillouin Spectrometer Control},
  year         = {2025},
  version      = {0.1.1},
  url          = {https://gitlab.uni-hannover.de/phytophotonics/ghosty},
  institution  = {Leibniz University Hannover}
}

APA Style

Landes, T., & Heinemann, D. (2025). Ghosty: A Python Interface for GHOST Brillouin 
Spectrometer Control (Version 0.1.1) [Computer software]. 
Leibniz University Hannover. https://gitlab.uni-hannover.de/phytophotonics/ghosty

Related Publications

If applicable, please also cite the following related publications:

Landes, T., Khanal, B.P., Bethge, H.L. et al. Micromechanical behavior of the apple fruit cuticle investigated by Brillouin light scattering microscopy. Commun Biol 8, 174 (2025). https://doi.org/10.1038/s42003-025-07555-5