User Tools

Site Tools


command_quick_start

Quick Start on Serial Commands

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 softwares that can be used to send serial commands directly or indirectly). 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.

Most common commands

Full name Short name Use Default units Specify axis or address? Example
MOVE M Initiates move to absolute position 10ths of microns Axis M X=10000 moves to position 1.000 mm per current origin
MOVREL R Initiates move a specified distance from current position 10ths of microns Axis R X=-1000 moves 100um in negative direction
WHERE W Queries the absolute position of the axis 10ths of microns Axis W X returns :A 1000 if the absolute position is 100um relative to the origin
HERE H Sets the origin of the coordinate system for the specified axis 10ths of microns Axis H X sets the current position of the X axis to be 0
STATUS / Queries status of all axes on controller (MS-2000) or on card (TG-1000 if address is specified) - Address optionally (TG-1000 only) / returns N if no axis is busy or B if one is
RDSTAT RS When used with ? qualifier, queries status specified axis - Axis RS X? returns N if X axis is busy or B if it is

Command Syntax

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. 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 MOVE and 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 + 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.

Reply Syntax

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.

MS-2000 Reply Syntax

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.

Examples
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>

Tiger Reply Syntax

The TG-1000 has two reply syntaxes; the active one is set using the [commands:vb|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>
: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>

Query of Parameters

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

Command Syntax Error Codes

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:

: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 x=1234)
:N-4 Parameter Out of Range
:N-5 Operation failed
: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

A Note Regarding Units

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 always use units of mm. 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.

Address: 29391 W Enid Rd. Eugene, OR 97402, USA | Phone: +1 (541) 461-8181
command_quick_start.txt · Last modified: 2021/09/23 17:15 (external edit)