During the development of eSlide, we had to develop some general-purpose modules based on the ImageJ image processing software, the most (perhaps) useful of which being a plugin for managing a serial controlled microscope stage.

A first version, based on Sun's Javacomm, is available here; however, we recently rewritten from scratch all, starting from the open source RxTx library. An additional property of the new version is the possibility of controlling the stage through macros. As a side effect, we are going to release also a general-purpose SerialPlugin.

We developed it in two versions, corresponding to the controllers we own; however, we are going to release also the sources, to help other people to adapt it to other stages. If you do so, please contact us to share your work.


Packages have been updated on 19 April, 2006 (before there was a mistake in the LSTEP version).

The IJStage software


  1. As a first step, go to the RxTx web site and download the package (v2.1, for use withOUT Sun's CommAPI, i.e., namespace gnu.io). Follow directions for installation as you find in the package. We lost some time installing on MacOSX, due to incorrect permissions; this page helped us.
  2. Put the stage library (either PriorOptiscan_RXTX.jar or LStep_RXTX.jar) into the Java extensions directory (ext/ under jre in both Linux and Windows, /Library/Java/Extensions in MacOSX). There you will find also RxTx files. If you are using the ImageJ package including JRE, you have to use that extensions directory.
  3. Put the stage plugin directory (either IJStage-Prior or IJStage-LSTEP) into the plugins directory. Inside there is also the properties file containing connections parameters. In principle, parameters are correct for connection, but you may have to change the port name.



Each package has its own sources, with you can find in the source directory. Stage libraries are provided in the form of NetBeans projects. However, you can easily extract sources to be used with another IDE.

Serial plugin

The serial plugin has been developed with two aims: to provide a quick way for managing a serial connection from ImageJ macros, and a a programming sample for managing a serial connection when developing plugins. So, all sources are inside the same file, in order to make it compilable directly from ImageJ.

The serial plugin is also based on RxTx. To install it, you just need Rxtx, and then compile the SerialPlugin from ImageJ.

The IJSerial plugin

This ImageJ plugin allows to send and receive strings through a serial port. It is based on the RxTx library.


  1. create a directory named "Serial" inside the Plugins directory of ImageJ;
  2. put serial_plugin.java and initDevice.properties into that directory;
  3. from ImageJ, compile and run the plugin.

Alternativey, you can just put the compiled serial_plugin.class file into the same directory.

In case of communication problems, check the serial port name in the properties file, and eventually even the other parameters.


You can launch the IJSerial plugin in two ways:

Hardware tips

The LSTEP controller

LSTEP may understand two command protocols, one based on registers and one on commands. Our implementation is based on the latter. In order to check the controller and set up the correct language, the WinCommander software from Märzhäuser should be used.

USB to serial adapters

IJStage has been tested with embedded serial ports and also a couple of USB to serial adapters. On MacOSX we tested the Keyspan USB Twin Serial Adapter. On Windows XP, Linux (Ubuntu, Debian) and Macosx 10.4.2 we also successfully tried the Manhattan USB to serial converter, with drivers available at the producer' web site (though not needed for Linux with 2.6 kernel).

When using serial adapters, a possible source of trouble is the port name, mainly on unix-based systems. You can use a terminal software to check it (e.g., HyperTerminal on Windows, GTKTerm on Linux, QuickTerm on MacOSX).

Developing other plugins

If you want to develop a plugin for a different controller, you have to do at least two steps:

It's better to start from the LSTEP version, which is more complete. In fact, some commands may return results, some others not: in the latter case, if you wait for an answer, communication is blocked. As LSTEP has both possibilities, you will find both kinds of commands, while the Prior controller always answers, so we used always the same kind of serial communication. 


The first step is to obtain documentation on the stage protocol. Usually, each command is constituted by some string, followed by parameters.

Then you may experiment with the protocol, in order to understand its functioning, using a terminal emulator (i.e., HyperTerminal on Windows). This way you will be able to discover correct serial parameters (flow control, speed, parity bits, etc) and verify commands. After that, you should be able to modify the Java code with the right parameters.

An intermediate step could be to create a macro version of the plugin, by using the IJSerial plugin. This plugin just implements serial communications, so you can use it to deliver strings to the controller through a macro. However, developing the library and the java plugin allows you to obtain a more complete system, which can be also used in other java programs (for which only the java library is needed). In fact, we used our libraries in a system for complete slide acquisition.


As is, the library just implements basic movement features of a stage. If you have to control other kind of movements (i.e., objective revolver), you may add methods to the library classes, and you have then to implement the corresponding part in the plugin.

Another limit, specific to the plugin, is the fact that it opens and closes the serial communication at each command. This because we didn't find a way to give persistence to the serial communication object. However, this is not a limit for the Java library, which can be used also in other software.


IJStage and IJSerial in all their versions are released under the GPL license.


You can contact us at ijstage at eslide.net.