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. M, R, 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.

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 MOVE or 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.

The usual syntax is to set parameter values with an equal sign, and query them using a question mark. However note that there are separate commands for setting and querying positions.

When a numeric value is expected but omitted then it usually is interpreted as =0; the behavior is near-universal and works for the commonly-used MOVE, MOVREL, and HERE commands. Truncation or rounding of numeric values may occur depending on the command.

Some commands do not require a parameter value (e.g., INFO X) or use the + or - signs (e.g. MC X-).

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 X and Y are typically used for a 2-axis motorized stage, Z and 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> and <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 <CR><LF> only.

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 W <axis>.

When a command is received that the controller cannot interpret, for one reason or another, an error is returned in the following format:

 :N-<error code>

The error codes are as follows:

The most common commands including MOVE, MOVEREL, HERE, and WHERE use axis units, which can be changed using the UM command. However, some commands such as SETUP, SETLOW, and 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.