thorlabs_apt_device.devices.aptdevice module

class thorlabs_apt_device.devices.aptdevice.APTDevice(serial_port=None, vid=None, pid=None, manufacturer=None, product=None, serial_number=None, location=None, controller=EndPoint.RACK, bays=(EndPoint.BAY0,), channels=(1,), status_updates='none')[source]

Bases: object

Initialise and open serial device for the ThorLabs APT controller.

If the serial_port parameter is None (default), then an attempt to detect an APT device will be performed. The first device found will be initialised. If multiple devices are present on the system, then the use of the serial_number parameter will specify a particular device by its serial number. This is a regular expression match, for example serial_number="83" would match devices with serial numbers starting with 83, while serial_number=".*83$" would match devices ending in 83.

Status updates can be obtained automatically from the device by setting status_updates="auto", which will request the controller to send regular updates, as well as sending the required “keepalive” acknowledgement messages to maintain the connection to the controller. In this case, ensure the keepalive_message property is set correctly for the controller.

To instead query the device for status updates on a regular basis, set status_updates="polled", in which case ensure the update_message property is set correctly for the controller.

The default setting of status_updates="none" will mean that no status updates will be performed, leaving the task up to sub-classes to implement.

Parameters:

  • serial_port – Serial port device the device is connected to.

  • 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).

  • controller – The destination EndPoint for the controller.

  • bays – Tuple of EndPoint(s) for the populated controller bays.

  • channels – Tuple of indices (1-based) for the controller bay’s channels.

  • status_updates – Set to "auto", "polled" or "none".

close()[source]

Close the serial connection to the ThorLabs APT controller.

identify(channel=0)[source]

Flash the device’s front panel LEDs to identify the unit.

For some single-channel USB controlled devices channel=None is used, which sends the identify command to the USB controller EndPoint. On devices which are considered “rack” controllers (including single-channel “rack” units such as the BBD201), the channel parameter will actually refer to the card bay. There are likely other types of units (though currently untested) which have a single “bay” with multiple channels, and then the channel parameter would refer to the actual channel index of the controller card.

Parameters:

channel – Index (0-based) of controller bay channel to send the command.

register_error_callback(callback_function)[source]

Register a function to be called in the case of an error being reported by the device.

The function passed in should have the signature callback_function(source, msgid, code, notes), where source is the enums.EndPoint where the message originated, msgid is the type of message which triggered the error (or 0 if unknown or a spontaneous error), code is a numerical error code and notes is a string description.

Params callback_function:

Function to call in case of device error.

unregister_error_callback(callback_function)[source]

Unregister a previously registered error callback function.

The function passed in should have been previously registered using register_error_callback().

Params callback_function:

Function to unregister.

bays

Tuple of ID codes for the controller’s card bay EndPoint(s).

channels

Tuple of indexes for the the channels in card bays.

controller

ID code for the controller message EndPoint.

keepalive_interval

Time interval between sending of keepalive messages, in seconds.

keepalive_message

Function to generate the keepalive message which are sent at regular intervals when status updates are configured as "auto". Examples are mot_ack_dcstatusupdate, pz_ack_pzstatusupdate, pzmot_ack_statusupdate or similar from thorlabs_apt_device.protocol.functions, and are device specific.

read_interval

Time to wait between read attempts on the serial port, in seconds.

update_interval

Time interval between sending of status update requests, in seconds. Note that this is in fact the delay to use after completing a previous status update, thus a value of 0.01 s does not mean that status updates will be performed 100 times a second, depending on the time it takes to complete a command, or the presence of other commands on the message queue.

update_message

Function to generate the status update request message which are sent at regular intervals when status updates are configured as "polled". Examples are mot_req_statusupdate, mot_req_dcstatusupdate, mot_req_statusbits, rack_req_statusbits, la_req_statusupdate or similar from thorlabs_apt_device.protocol.functions, and are device specific.

thorlabs_apt_device.devices.aptdevice.find_device(vid=None, pid=None, manufacturer=None, product=None, serial_number=None, location=None)[source]

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 Thorlabs APT 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=1659. 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.

Note that the APT protocol documentation lists formats for device serial numbers. For example, a TDC001 “DC Driver T-Cube” should have serial numbers starting with “83”.

Be aware that different operating systems may return different data for the various fields, which can complicate matching.

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_apt_device.devices.aptdevice.list_devices()[source]

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 APTDevice class to identify and select a specific serial device.

Returns:

String listing all serial devices and their details.