top bar


Revision as of 11:22, 29 September 2011 by Nenad (Talk | contribs)

Summary: Thorlabs Device Adapter Library

Summary:XY Stage (brushless DC motor), Z Stage (Piezo), both using controller BBD 102
Author:Nenad Amodaj and Thorlabs Inc
Platforms:All platforms (uses serial port)
Devices:XYStage, PiezoZStage
Example Config File:Media:MMConfig_Thorlabs.cfg

XY Stage

XY stage device adapter that works with BBD 102 brushless DC motor contoroller[1] and supports high speed motorized scanning stage MLS 203 [2].


This adapter requires only a serial serial port (RS-232). One port should be reserved for this stage and initialized with the following parameters:

BaudRate: 115200

Handshaking: Off

Parity: None

StopBits: 1

(all other micro-manager port parameters can be left with defaults)

The only parameter that is required for configuration of the stage is the name of the serial port (e.g. COM2) attached to the controller. If the port was correctly set and connected in the previous step, micro-manager will load the stage adapter at startup. In Device Property Browser (menu: Tools | Device Property Browser...) the stage appears as:

Property Browser 2011-03-25 16-03-56.png

Using the stage

The stage uses absolute XY coordinates and any positions recorded in micro-manager will always correspond to the same physical location. However, because of this feature, each time we power-up this stage needs to be "homed" before sending any commands. If we try to move it before homing, error message will pop up. Homing is not automatic on startup because during this procedure stage moves to its limits and in may cause one of the objectives to hit the stage frame, if the objective turret is left high enough. This is an issue with any XY stage and the user always needs to make sure that objective turret is in the safe position before homing.

Home procedure

The stage needs to be homed once after each power-up. Homing is not necessary if we just exit and re-start the software without powering down. There are three alternative ways to home the stage. Choose one of the following:

Calibrate command

Open Stage Position List dialog and press "Calibrate" button (menu: Tools | XY List...).


Copy the following script, paste it into the Script Editor (menu: Tools | Script Panel...) and press "Run" button.

// home XY Stage
gui.message("Homing started...");
xyStage = mmc.getXYStageDevice();
x = mmc.getXPosition(xyStage);
y = mmc.getYPosition(xyStage);
gui.message("Done! Home position [um]: " + x + ", " + y);

This script can be saved and stored in the Script-Shortcut list for future use.

Special micro-manager startup script

To automate the process of homing so that you get prompted for it each time you start micro-manager you can use startup scripts. Startup script must reside in the root directory of the micro-manager software and its name is specified in the Options dialog (menu: Tools | Options...). Add the following code to the existing startup script (or create a new one):

// startup script to home Thorlabs BBD102 XY stage
import ij.gui.GenericDialog;

GenericDialog dlg = new GenericDialog("HOME command - XY Stage", null);
msg = "WARNING!!! The XY stage is about to move."
      + "Make sure objectives are out of the way."
      + "If you are in doubt about what to do Cancel this command!";
if (dlg.wasCanceled())
	return false;

gui.message("Homing started...");
xyStage = mmc.getXYStageDevice();
x = mmc.getXPosition(xyStage);
y = mmc.getYPosition(xyStage);
gui.message("Done! Home position [um]: " + x + ", " + y);

Each time you start micro-manager the script will be automatically executed and you will be prompted to home the stage and warned to move objectives to the safe position.

Adjusting motion parameters

The stage adapter lets us adjust velocity and acceleration to match our application. If you use default values for velocity and acceleration, no further actions are necessary. However if you change velocity/acceleration to slow down the stage, you may run into problems with micro-manager timeouts.

The default timeout interval for micro-manager is 5 seconds. If any of the move commands takes more than 5 seconds (or whatever you have set instead) to complete, micro-manager will time out you will get an error message to that effect. If you get timeout error messages on lengthy move commands, try changing the micro-manager timeout interval to 10 seconds or more. To change timeout interval open Device Property Browser (menu: Tools | Device Property Browser...) and set the desired value both for the Core-TimeoutMs and XYStage-MoveTimeoutMs properties.

Note that change in the Property Browser is not permanent. If you exit the application and re-start these values will return to their defaults. To make settings permanent use System/Startup configuration preset mechanism in micro-mananger. Consult micro-manager documentation for more information.

Testing and automation

For verification and testing of the stage we can load test configuration file Media:MMConfig_Thorlabs.cfg. This configuration file contains XYStage tied to the com port and a couple of device simulators (demo adapters) acting as demo camera and focus stage. The configuration probably won't work right away because the COM port on your system may be different. To edit the port information use Hardware Configuration Wizard (menu: Tools) as with any other device.

After the configuration loaded without errors we can use the following script to test the stage:

// Exercise XY stage
import java.text.DecimalFormat;

// obtain xy stage name
xyStage = mmc.getXYStageDevice();


// report starting position
x = mmc.getXPosition(xyStage);
y = mmc.getYPosition(xyStage);
gui.message("Starting position [um]: " + x + ", " + y);

// define test points in um
ArrayList xPos = new ArrayList();
ArrayList yPos = new ArrayList();



DecimalFormat FMT2 = new DecimalFormat("#0.0");

for (int i=0; i<xPos.size(); i++) {
	start = System.currentTimeMillis();
	mmc.setXYPosition(xyStage, (double)xPos.get(i), (double)yPos.get(i));
	end = System.currentTimeMillis();
	gui.message("Reached point " + i 
                    + " at (" + xPos.get(i) + "," + yPos.get(i) + ")"
                    + " in " + (end-start) + " ms");

	x = mmc.getXPosition(xyStage);
	y = mmc.getYPosition(xyStage);
	gui.message("Current position [um]: " + FMT2.format(x) + ", " + FMT2.format(y));

Running this script in the Script Panel (menu: Tools | Script Panel...) should produce the following output:

Starting position [um]: 70000.0, 18000.0
bsh % 
Reached point 0 at (0.0,0.0) in 1000 ms
bsh % 
Current position [um]: -0.2, -0.0
bsh % 
Reached point 1 at (5000.0,30000.0) in 594 ms
bsh % 
Current position [um]: 5000.2, 30000.4
bsh % 
Reached point 2 at (70000.0,18000.0) in 922 ms
bsh % 
Current position [um]: 69999.8, 18000.0
bsh % 

If this script does not generate any errors the stage is working properly. Timing on your system may be different, depending on the motion parameteres.

© Micro-Manager : Vale Lab, UCSF 2006-2011 | All Rights Reserved | Contact