thorlabs_elliptec package

exception thorlabs_elliptec.ELLError(status: ELLStatus = ELLStatus.UNKNOWN)

Bases: Exception

Exception class to indicate an error with the Elliptec device.

The optional parameter is an instance of ELLStatus to describe the error type.

An instance of this exception may be raised from movement commands (e.g. move_absolute(), move_relative(), home()) when used in synchronous mode by passing blocking=True. When using (the default, non-blocking) asynchronous mode, an exception may be raised from is_moving() or wait() if the raise_errors=True parameter is passed.

Parameters:

status – ELLStatus object to describe the error.

status

A instance of ELLStatus which describes the error.

class thorlabs_elliptec.ELLStatus(*values)

Bases: IntEnum

Status codes and descriptions returned by Thorlabs Elliptec devices.

These codes are the same as documented in the communications protocol document from Thorlabs.

BUSY = 9

COMMAND_NOT_SUPPORTED = 3

COMM_TIMEOUT = 1

INIT_ERROR = 7

MECH_TIMEOUT = 2

MODULE_ISOLATED = 5

MODULE_NOT_ISOLATED = 6

MOTOR_ERROR = 11

OK = 0

OUT_OF_RANGE = 12

OVER_CURRENT = 13

SENSOR_ERROR = 10

THERMAL_ERROR = 8

UNKNOWN = 14

VALUE_OUT_OF_RANGE = 4

property description

Get a string representation of this status code.

class thorlabs_elliptec.ELLx(serial_port=None, x: int = None, device_serial: str = None, device_id: int = 0, **kwargs)

Bases: object

Generic class to interact with the Thorlabs Elliptec series of devices.

The serial_port parameter may be a system-specific string (eg. "/dev/ttyUSB0", "COM12") or a serial.tools.list_ports_common.ListPortInfo instance. If the serial_port parameter is None (default), then an attempt to detect a serial device will be performed. The first device found will be initialised. If multiple serial devices are present on the system, then the use of the the additional keyword arguments can be used to select a specific device. The keyword arguments the same as those used for find_device().

The multi-drop feature of the ELLx devices may be used by specifying an existing instance of an ELLx class as the serial_port parameter. The serial port device initialised by the existing instance will be shared with the newly created one.

The default parameter of x=None will result in the specific model of ELLx device to be automatically detected. If a number is specified (eg. x=20 for an ELL20), then an exception will be raised if the detected model number does not match.

The default parameter of device_serial=None will use any detected device, regardless of its serial number. If a device serial string is specified, an exception will be raised if the detected serial number does not match.

The Elliptec devices support a “multi drop” bus arrangement on the serial port lines, which allows control of multiple devices over a single serial link. The device_id parameter should correspond to the device ID number programmed into the device. For single devices on a serial port, the default of 0 is probably correct. Changing a device ID through this library is not currently supported. Use a serial terminal program (e.g. minicom or putty) to connect to a device and issue the “change address” command. For example, 0ca1 will change the device ID from 0 to 1. The “save user data” (us) command might also be needed to make the address change permanent. See the Thorlabs documentation on the Elliptec serial communication protocol for more details.

The remaining keyword arguments are passed onto find_device() for selection of a specific serial port device.

Parameters:

• serial_port – Serial port device the device is connected to, or another instance of the ELLx class.

• x – The required “x” in the detected ELLx model number.

• device_serial – Serial number required of the detected device.

• device_id – Numeric ID to use during serial communications with device.

• vid – Serial port numerical USB vendor ID to match.

• pid – Serial port numerical USB product ID to match.

• manufacturer – Serial port regular expression to match to a device manufacturer string.

• product – Serial port regular expression to match to a device product string.

• serial_number – Serial port regular expression to match to a device serial number.

• location – Serial port regular expression to match to a device physical location.

close() → None

Close the serial connection to the ELLx device.

Note that this method returns immediately, and the halting of communications and closing of the serial port is performed in a background thread. This means the serial port may not actually be closed yet when this method returns.

Further, if the multi-drop feature of the ELLx devices is used, the serial port will only be closed if no other devices remain open which are sharing the same serial port device.

get_position() → float

Return the current position of the ELLx device, in real device units.

Returns:

Position in real device units.

get_position_raw() → int

Return the current position of the ELLx device, in raw encoder counts.

Returns:

Position in raw encoder counts.

home(direction: int = 0, blocking: bool = False) → None

Move to device to the home position.

The direction of movement (e.g. for rotational stages) can be configured using the direction parameter. This parameter should be 0 or 1, but True or False are also valid.

The default behaviour is for this method to return immediately, without waiting for the operation to complete (or to detect any movement errors). To instead wait for the operation to finish, set the parameter blocking=True. If a movement error occurs, an ELLError will be raised.

Parameters:

• direction – Direction to move.

• blocking – Wait for operation to complete.

is_moving(raise_errors: bool = False) → bool

Test if the device is currently performing a move operation.

By default, if a movement error occurs, this method will ignore the fault and simply return False. To instead raise an ELLError exception, set the parameter raise_errors=True.

Parameters:

raise_errors – Raise an ELLError if movement failed.

Returns:

True if device is currently moving.

move_absolute(position: float, blocking: bool = False) → None

Move the device to an absolute position, specified in real device units.

The default behaviour is for this method to return immediately, without waiting for the operation to complete (or to detect any movement errors). To instead wait for the operation to finish, set the parameter blocking=True. If a movement error occurs, an ELLError will be raised.

Parameters:

• position – Position to move to, in real device units.

• blocking – Wait for operation to complete.

move_absolute_raw(counts: int, blocking: bool = False) → None

Move the device to an absolute position, specified in raw encoder counts.

The default behaviour is for this method to return immediately, without waiting for the operation to complete (or to detect any movement errors). To instead wait for the operation to finish, set the parameter blocking=True. If a movement error occurs, an ELLError will be raised.

Parameters:

• counts – Position to move to, in raw encoder counts.

• blocking – Wait for operation to complete.

move_relative(amount: float, blocking: bool = False) → None

Move the device by a relative amount, specified in real device units.

The default behaviour is for this method to return immediately, without waiting for the operation to complete (or to detect any movement errors). To instead wait for the operation to finish, set the parameter blocking=True. If a movement error occurs, an ELLError will be raised.

Parameters:

• amount – Amount to move by, in real device units.

• blocking – Wait for operation to complete.

move_relative_raw(counts: int, blocking: bool = False) → None

Move the device by a relative amount, specified in raw encoder counts.

The default behaviour is for this method to return immediately, without waiting for the operation to complete (or to detect any movement errors). To instead wait for the operation to finish, set the parameter blocking=True. If a movement error occurs, an ELLError will be raised.

Parameters:

• counts – Amount to move by, in raw encoder counts.

• blocking – Wait for operation to complete.

wait(raise_errors: bool = False) → None

Block until any current movement is completed.

By default, if a movement error occurs, this method will ignore the fault and return silently. To instead raise an ELLError exception, set the parameter raise_errors=True.

Parameters:

raise_errors – Raise an ELLError if movement failed.

property device_id: int

Numeric ID of the device used during communications.

property firmware_version: str

Firmware version installed on the device.

property model_number: str

Model number of the device.

Metric thread versions will include their “/M” suffix. Example model numbers are "ELL14/M" or "ELL18".

port_lock_timeout

Time in seconds to wait for the lock on the serial port device when shared with other devices in a multi-drop configuration.

property port_name: str

Serial port device name.

The naming is dependent on the underlying operating system, for example "/dev/ttyUSB1" on Linux or "COM5" on Windows.

property serial_number: str

Serial number of the device.

property status

Current state of the ELLx device. The return type is in instance of the ELLStatus enum.

property status_poll_interval: float

Time between polling for status updates, in seconds. Default is 0.1 seconds.

property thread_type: str

Thread type of mountings on the device ("metric" or "imperial").

property travel: int

Maximum travel distance/angle of device.

property units: str

A string representation of the units for the device’s movement type.

For linear stages this will be "mm", or "°" for rotation stages.

property year: int

Manufacturing year of the device.

thorlabs_elliptec.find_device(vid: int = None, pid: int = None, manufacturer: str = None, product: str = None, serial_number: str = None, location: str = None)

Search attached serial ports for a specific device.

The first device found matching the criteria will be returned. Because there is no consistent way to identify serial devices, the default parameters do not specify any selection criteria, and thus the first serial port will be returned. A specific device should be selected using a unique combination of the parameters.

The USB vendor (vid) and product (pid) IDs are exact matches to the numerical values, for example vid=0x067b or vid=0x2303. The remaining parameters are strings specifying a regular expression match to the corresponding field. For example serial_number="83" would match devices with serial numbers starting with 83, while serial_number=".*83$" would match devices ending in 83. A value of None means that the parameter should not be considered, however an empty string value ("") is subtly different, requiring the field to be present, but then matching any value.

Be aware that different operating systems may return different data for the various fields, which can complicate matching when attempting to write cross-platform code.

To see a list of serial ports and the relevant data fields:

Parameters:

• vid – Numerical USB vendor ID to match.

• pid – Numerical USB product ID to match.

• manufacturer – Regular expression to match to a device manufacturer string.

• product – Regular expression to match to a device product string.

• serial_number – Regular expression to match to a device serial number.

• location – Regular expression to match to a device physical location (eg. USB port).

Returns:

First ListPortInfo device which matches given criteria.

thorlabs_elliptec.list_devices() → str

Return a string listing all detected serial devices and any associated identifying properties.

The manufacturer, product, vendor ID (vid), product ID (pid), serial number, and physical device location are provided. These can be used as parameters to find_device() or the constructor of a device class to identify and select a specific serial device.

Returns:

String listing all serial devices and their details.