Lightfall

A modern, unified control system for synchrotron lightsource facilities that provides facility-wide consistency with beamline-specific customization.

Overview

Lightfall is designed for the Advanced Light Source (ALS) facility, providing:

• Unified Interface: Consistent look-and-feel across beamlines with skinnable themes
• API-First Architecture: Modular, extensible design enabling automation and integration
• LLM/AI Integration: Claude-powered chatbot for natural language control and assistance
• FAIR-Compliant Data Management: Integration with Tiled for data cataloging and access
• Secure Remote Operations: Full remote operation capability with fine-grained access control

Features

User Interface

• Progressive disclosure: user panels with expert panels behind authorization
• Scripting panel with Jupyter-lab style interface
• LLM panel for controlling panels via natural language
• GUI Builder for drag-and-drop interface creation
• Persistent user preferences saved across sessions

Device Management

• Centralized device catalog with lifecycle tracking
• Real-time monitoring via EPICS Channel Access
• Version-controlled device configurations
• Rich high-level controls integrated into workflows

Data Acquisition

• Bluesky-based acquisition engine
• Flexible signal/stream selection with real-time visualization
• Interactive, pausable, restartable acquisition
• Automatic data persistence to Tiled catalog

Data Browser

• Browse and search data stored in Tiled server
• Filter by date range, plan type, exit status
• Pagination for large datasets
• Click/double-click signals for integration with analysis tools

Installation

pip install lightfall

Development Installation

# Clone the repository
git clone https://github.com/als-controls/lightfall.git
cd lightfall

# Create and activate virtual environment
python -m venv .venv
.venv\Scripts\activate  # Windows
# or
source .venv/bin/activate  # Unix

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Lightfall depends on lightfall-utils (installed from PyPI like any other dependency). To co-develop both packages, install a sibling checkout in editable mode on top:

git clone https://github.com/als-controls/lightfall-utils.git ../lightfall-utils
pip install -e ../lightfall-utils

Running the Application

lightfall

Configuration

Lightfall uses a layered configuration system:

1. System defaults - Built-in defaults
2. Site configuration - Facility-wide settings
3. User preferences - Personal customizations

Configuration files are stored in:

• Windows: %APPDATA%\lightfall\
• Linux/Mac: ~/.config/lightfall/

Architecture

Lightfall is built on:

• PySide6 - Qt for Python GUI framework
• Bluesky - Data acquisition framework
• Ophyd - Device abstraction layer
• Tiled - Data catalog and access
• EPICS - Control system communication

Plugin System

Lightfall supports plugins for:

• Panels - Custom UI panels
• Settings - Preference pages
• Status Bar - Status indicators
• Engines - Acquisition backends
• Plans - Scan procedures

Development

Running Tests

pytest

Code Quality

# Linting
ruff check src tests

# Type checking
mypy src

Project Structure

lightfall/
├── src/lightfall/
│   ├── acquire/        # Data acquisition engine (Bluesky RunEngine, plans)
│   ├── auth/           # Authentication & authorization
│   ├── claude/         # Embedded Claude agent integration
│   ├── config/         # Configuration management
│   ├── core/           # Core application classes
│   ├── devices/        # Device catalog & backends
│   ├── epics/          # EPICS (caproto) widgets & helpers
│   ├── exporter/       # Data exporter CLI
│   ├── ipc/            # Inter-process communication (NATS)
│   ├── logbook/        # Logbook client
│   ├── pipelines/      # Pipeline client
│   ├── plugins/        # Plugin system
│   ├── services/       # Application services (Tiled, CA tunnel, etc.)
│   ├── settings/       # User-portable settings client
│   ├── ui/             # User interface
│   │   ├── panels/     # Panel implementations
│   │   ├── widgets/    # Reusable widgets
│   │   ├── preferences/  # Settings UI
│   │   └── theme/      # Theming system
│   ├── utils/          # Utilities
│   └── visualization/  # Plotting & live visualization
└── tests/              # Test suite