pyThorlabsElliptec

pyThorlabsElliptec is a Python library/GUI interface to control Thorlabs Elliptec piezo motors. The package is composed of two parts: a low-level driver to perform basic operations, and a high-level GUI, written with PyQt5, which can be easily embedded into other GUIs. The low-level driver is a wrapper of the thorlabs_elliptec library, with a few tweaks for device discovery and error handling.

The interface can work either as a stand-alone application, or as a module of ergastirio.

Table of Contents

• Installation
• Usage via the low-level driver
  • Creating a driver instance
  • Properties
  • Other attributes
  • Methods
  • Direction constants
  • Examples
• Usage as a stand-alone GUI interface
• Embed the GUI within another GUI

Installation

1. Install the package via pip:

pip install pyThorlabsElliptec

2. Install the thorlabs_elliptec library:

pip install thorlabs-elliptec

No additional DLLs or vendor software are required. The Elliptec controller communicates over USB-serial (virtual COM port), which is handled automatically by thorlabs_elliptec.

These two steps are enough to use the low-level driver. To use the GUI, install the additional dependencies listed in requirements.txt:

pip install abstract_instrument_interface>=0.10
pip install "PyQt5>=5.15.6"
pip install pyqtgraph
pip install numpy

Usage via the low-level driver

pyThorlabsElliptec can be used to control a device from the command line or from your Python script.

The class pyThorlabsElliptec wraps the connected device's low-level ELLx object (defined in thorlabs_elliptec) and exposes the subset of its properties and methods needed to find, connect to, and operate a stage. A full list of properties, attributes, and methods is available below. Note: the documentation below was partially compiled with the help of Claude — mistakes are possible.

Creating a driver instance

pyThorlabsElliptec(virtual=False)

Properties

The following are implemented as Python @property. Reading or setting either of these requires a device to be connected; otherwise, accessing them raises an AttributeError (no underlying ELLx object has been created yet).

Other attributes

Methods

Direction constants

move_jog() uses integer direction codes. These are defined at the module level in main.py:

from pyThorlabsElliptec.main import MOVE_FWD, MOVE_REV

Examples

from pyThorlabsElliptec.driver import pyThorlabsElliptec
from pyThorlabsElliptec.main import MOVE_FWD
import time

instrument = pyThorlabsElliptec()
available_devices = instrument.list_devices()   # Scan for Elliptec devices
print(available_devices)
# e.g. [['COM3', 0x1313, 0x804A, 'ELL14K00000001']]

device_addr = [available_devices[0][1], available_devices[0][2]]  # [vid, pid]
instrument.connect_device(device_addr=device_addr)

instrument.move_home()                          # Start homing (non-blocking)
while instrument.is_in_motion:                  # Poll until homing is done
    time.sleep(0.1)

instrument.position = 45                        # Start a non-blocking absolute move to 45°
while instrument.is_in_motion:
    time.sleep(0.1)
print(instrument.position)

instrument.jog_step_size = 5                    # Set the jog step size to 5°
instrument.move_jog(MOVE_FWD)                   # Jog forward by 5°
while instrument.is_in_motion:
    time.sleep(0.1)

instrument.disconnect_device()

Usage as a stand-alone GUI interface

The installation sets up an entry point for the GUI. Just type:

pyThorlabsElliptec

in the command prompt to start the GUI. The GUI will automatically scan for connected Elliptec devices on startup. Select the device from the drop-down menu and click Connect.

Embed the GUI within another GUI

The GUI controller can be easily integrated within a larger graphical interface, as shown in the example below.

import PyQt5.QtWidgets as Qt
import pyThorlabsElliptec

app = Qt.QApplication([])
window = Qt.QWidget()

# The GUI needs to be contained inside a widget object
widget_containing_interface_GUI = Qt.QWidget()
widget_containing_interface_GUI.setStyleSheet(
    ".QWidget {
"
    "border: 1px solid black;
"
    "border-radius: 4px;
"
    "}"
)

# Create the interface object for the motor
Interface = pyThorlabsElliptec.interface(app=app, virtual=False)
Interface.verbose = False  # set the verbosity of the interface logger to False
# At any time during the software execution, the position read by the instrument can be
# accessed via Interface.output['Position']. One can also connect a callback to be called
# automatically whenever the position is updated:
#
#       Interface.sig_update_position.connect(foo)
#
# Every time the position is read from the instrument, foo(new_position) is called.

# Create the GUI for the motor
view = pyThorlabsElliptec.gui(interface=Interface, parent=widget_containing_interface_GUI)

# Create additional GUI elements
gridlayoutwidget = Qt.QWidget()
gridlayout = Qt.QGridLayout()
gridlayout.addWidget(Qt.QLabel("Additional GUI 1"), 0, 0)
gridlayout.addWidget(Qt.QLabel("Additional GUI 2"), 1, 0)
gridlayout.addWidget(Qt.QLabel("Additional GUI 3"), 0, 1)
gridlayout.addWidget(Qt.QLabel("Additional GUI 4"), 1, 1)
gridlayoutwidget.setLayout(gridlayout)

layout = Qt.QVBoxLayout()
layout.addWidget(widget_containing_interface_GUI)
layout.addWidget(gridlayoutwidget)
layout.addStretch(1)
window.setLayout(layout)

window.show()
app.exec()  # Start the event loop.