This section is intended to quickly bring the users up to speed on the most common serial commands. Find separately an index of all commands and a compiled list of commands; separate documentation for each command are linked there.
There is a separate page detailing the communication details (also includes notes on various software that can be used to send serial commands directly or indirectly including Python, Julia, Micro-Manager, LabView, etc). Serial commands are not case-sensitive. For commands that require a numeric input, if none is specified then the value is taken to be 0.
The most common commands are identical across both the MS-2000/RM-2000 controller and the TG-1000 “Tiger” controller. Any “axis-specific” commands that specifies a physical axis that the command applies to will be identical (e.g.
W for absolute and relative moves along with position query) along with the busy query
/. Commands that use a letter to specify what the setting is (e.g.
TTL X sets TTL input mode and
TTL Y sets TTL output mode) are slightly different on Tiger in that the card address must be prepended. There is a full description of TG-1000 and MS-2000’s instruction set differences.
Note that ASI filter wheels have a completely separate command set described in the filter wheel documentation. along with a different serial terminator. Also see the documentation for TG-1000 filter wheel communication.
|Full name||Short name||Use||Default units||Specify axis or address?||Example|
| || ||Initiates move to absolute position||10ths of microns||Axis||
| || ||Initiates move a specified distance from current position||10ths of microns||Axis||
| || ||Queries the absolute position of the axis||10ths of microns||Axis||
| || ||Sets the origin of the coordinate system for the specified axis||10ths of microns||Axis||
| || ||Queries status of all axes on controller (MS-2000) or on card (TG-1000 if address is specified)||-||Address optionally (TG-1000 only)||
| || || When used with ||-||Axis||
The controller’s instruction set is implemented using the following general syntax. Details are given on the page of each command.
<command name> (<axis letter> [=<value>] | [?] | [+] | [-])* <Carriage Return>
The COMMAND is a string of ASCII characters such as
HOME, which must be followed by a space. All commands are case insensitive. Most commands have abbreviated names that help cut down on typing time and serial bus traffic.
Next comes one or more sets of strings that contain an axis name. When setting a value the axis name is followed immediately by an equal sign and the corresponding value. Decimal values are expressed in the US/UK convention with a period symbol '.' for the decimal point, and without any commas ',' or other delimeters. Each axis must be separated from the one before by one blank space. One or more axes may be specified on a single command line. An axis symbol typed without an
= assignment is usually assumed to mean
=0 (the behavior isn’t universal but it works for the commonly-used
MOVREL commands). Truncation or rounding of values may occur depending on the command. Set parameter values with an equal sign, and query them using a question mark. Some commands do not require a parameter value (e.g.,
INFO X) or use the
- signs (e.g.
The axis name is a single character. All 26 alphabet characters A-Z can potentially be used as axis names, and the special character
* means “all axes” (not including filterwheels) in recent Tiger firmware. Axis letters
Y are typically used for a 2-axis motorized stage,
F are commonly used for focus axes, and
A-D are the default letters for micro-mirror scanner axes. Filter Wheels are designated by numbers, TG-1000 can accommodate up to 10 wheels numbered 0-9.
For Tiger only: When
[Addr#] appears in the format, then the intended card address must be prepended to the serial command, as the command is Card-Addressed.
… indicates more arguments can be sent with the same command.
All commands are completed with a Carriage Return (ASCII hex code:
0D). The controllers receive ASCII characters one at a time and place them into their memory buffer. With the exception of single hex code commands like the tilde
~ and halt
/, the controller will not process a command in the memory buffer until the Carriage Return
<CR> has been received.
Upon receiving a Carriage Return <CR>, the Controller will process the command stored in its command buffer, clear the command buffer, and return a reply.
When a command is recognized, the controller will send back a colon
: (hex code: 3A) to show that it is processing the command. When processing of the command is complete, an answer is returned with any requested information, typically beginning with the letter
A. In some cases, the answer part of the reply is delayed until the completion of the command. The reply is terminated by a carriage return and a linefeed character
<CR><LF>. In the examples below, the
<CR> <LF> are implied. This programming manual gives examples in the MS-2000 reply syntax unless otherwise specified.
Typed commands are in THIS TYPEFACE Controller replies are in THIS TYPEFACE
MOVE X=1234 Z=1234.5 <CR> :A <CR><LF> MOVE X Y Z <CR> :A <CR><LF> WHERE X <CR> :A 0 <CR><LF> MOVE X=4 Y=3 Z=1.5 <CR> :A <CR><LF> WHERE X Y Z <CR> :A 4 3 1.5 <CR><LF> WHERE Z Y X <CR> :A 4 3 1.5 <CR><LF>
The TG-1000 has two reply syntaxes; the active one is set using the VB F command. The default syntax is backwards compatible with the MS-2000 controller, including all the quirks and inconsistencies between commands. The Tiger syntax is more self-consistent and in some cases more explanatory (e.g. with
WHERE), but is not backwards compatible. Choice of reply syntax is completely arbitrary and does not affect operation.
In the Tiger syntax no :A is sent back. Furthermore, whenever an axis position or command value is returned (i.e. whenever the command is a query), the axis letter is always specified. Consequently, when no information needs to be sent back and there is no error the controller simply replies with
The above examples in Tiger reply syntax are as follows:
MOVE X=1234 Z=1234.5 <CR> <CR><LF> MOVE X Y Z <CR> <CR><LF> WHERE X<CR> X=0 <CR><LF> MOVE X=4 Y=3 Z=1.5 <CR> <CR><LF> WHERE X Y Z <CR> X=4 Y=3 Z=1.5 <CR><LF> WHERE Z Y X <CR> Y=4 Y=3 Z=1.5 <CR><LF>
Most commands used to set parameter values – for example the setting
S for maximum speed or
B for backlash move distance – can be queried for the current values using the question-mark syntax: CMND X? Y? Z? F?. The controller will respond with CMND’s current settings, e.g. :A X=0 Y=1 Z=10 F=2. The exact details of the reply syntax depend on the exact command but are self-evident when you try it.
This feature is most useful when using a terminal program to change controller parameters to verify that you have made the changes that you think you did, or to check present settings.
Note that the position query
W is a command by itself and does not use the question-mark syntax; simply use
When a command is received that the controller cannot interpret, for one reason or another, an error is returned in the following format:
The error codes are as follows:
|Command Syntax Error Codes|
|:N-1||Unknown Command (not issued in TG-1000)|
|:N-2||Unrecognized Axis Parameter (valid axes are dependent on the controller)|
|:N-3||Missing Parameters (command received requires an axis parameter such as
|:N-4||Parameter Out of Range|
|:N-6||Undefined Error (command is incorrect, but for none of the above reasons)|
|:N-7||Invalid Card Address|
|:N-8 … :N-10||Reserved|
|:N-11 … :N-20||Reserved For Filterwheel|
|:N-21||Serial Command Halted (by the HALT command)|
|:N-30 … :N-39||Reserved|
The most common commands including
WHERE use axis units, which can be changed using the
UM command. However, some commands such as
PCROS use units of millimeter (mm), and the documentation page for the command specifies the unit. By default, axis units where position is given in distance (e.g. for motorized stages and piezo stages) are represented in 0.1um increments, or 10,000 units per millimeter of travel. For mirror scanner axes, default axis units are 0.001 degrees (uncalibrated), or 1000 units per degree of travel. When a time is required, the unit is generally milliseconds. Some commands use integer codes or other input units as described in the per-command documentation.