Motor Program Summary

Starting the program

The motor program is invoked by simply typing motor at a Unix shell prompt or in a DOS command window under Microsoft Windows . Motor should immediately display a version number and after a little while a motor> command prompt.

Exiting the program

Type exit or quit at the motor> command prompt.

Online help.

Typing help at the motor> command prompt gives a brief description of all the available commands. Typing the first word of each command will give a more detailed description of that command.

Controlling motors

For move,mrel, and mjog below, hitting almost any key (for example, the return key or the space bar) while a move is in progress will abort the move.
show motors - shows the positions of all motors.
show motor motor_name - shows the status of an individual motor in more detail.

move motor_name position - moves the motor motor_name to the absolute position position expressed in engineering units. mabs is an alias for move.
mrel motor_name distance - moves the motor motor_name by the distance distance relative to the current position expressed in engineering units.

The following two commands only work for motor controllers that allow direct access to step or tick counts.
move motor_name steps step_position - moves the motor motor_name to the position step_position expressed in motor steps or encoder ticks.
mrel motor_name steps relative_steps - moves the motor motor_name by the distance relative_steps relative to the current position expressed in step or tick counts.

mjog motor_name jog_size or
mjog motor_name steps jog_step_size - allows the repeated jogging of motor_name by jog_size or by jog_step_size. This is done via single keystroke commands: + (the plus key) and - (the minus key) move up or down 1 jog distance; > (the greater-than key) and < (the less-than key) move up or down 10 jog distances. No backlash correction is performed.

stop motor_name or abort motor_name - stops the motion of a currently moving motor.

home motor_name direction - performs a home search on the specified motor. If direction > 0, the home search will be in the positive direction. if direction < 0, the home search will be in the negative direction. If direction == 0, a motor driver dependent operation will be performed.

set motor motor_name position new_position or
set motor motor_name position steps new_step_position - redefines the current position of motor_name to be the requested position.

set motor motor_name backlash new_position or
set motor motor_name backlash steps new_step_position - changes the backlash correction for motor_name. Set the backlash correction to 0 to suppress backlash corrections.

set motor motor_name positive_limit new_position or
set motor motor_name positive_limit steps new_step_position - redefines the positive limit of travel for motor motor_name.

set motor motor_name negative_limit new_position or
set motor motor_name negative_limit steps new_step_position - redefines the negative limit of travel for motor motor_name.

set motor motor_name zero - sets the current motor position to be zero. Used for controllers like Newport MM4000s which do not allow the current position to be set to an arbitrary value, but which do allow the current position to be set to zero.
Scanning is broken up into two parts: setting up and manipulating scan records and actually running the scan.

Setting up scans

show scans - shows a summary of all currently existing scan records.
show scan scan_name - shows an individual scan in more detail.

setup scan scan_name - sets up a new scan called scan_name. The user is first asked to select a scan type. Then, the user is prompted for various scan parameters which vary from scan type to scan type, typically including names of motor(s) to scan, scaler(s) to use for readout, scan ranges, integration times, data file type, plot variables, etc. If scan_name matches a preexisting scan name, that previous scan will be overwritten. If it matches the name of any other preexisting MX device or record, the name will be rejected. Scan setup can be aborted part way through by typing ctrl-D.

modify scan scan_name - modifies a preexisting scan. The prompts are identical to setup scan, but the previous values for the scan record are shown as defaults. If modify scan is aborted part way through, the previous contents of scan_name are no longer available.

copy scan old_scan_name new_scan_name - can be used to make a copy of a preexisting scan record. This command allows the creation of modified versions of old scans without destroying the old scan. The normal procedure is to run copy scan to make a duplicate of the old scan under a new name and then run modify scan to change the scan parameters for the new copy. copy scan has no prompts.

delete scan scan_name - deletes all traces of the scan called scan_name.

load scans savefile_name - loads MX scan records from the specified save file. Any already existing scans with the same name as a scan in the save file will be overwritten.

save scans savefile_name - saves all MX scan records to the specified save file.

Running scans

scan scan_name - runs the scan named scan_name. While the scan is in progress, hitting the 'p' key will cause the scan to be paused. Hitting any other key will abort the scan. When a scan is paused, you can type 'a' to abort the scan or 'c' to continue the scan.

Scaler control

show scalers - shows a summary of all the scalers in the system.
show scaler scaler_name - shows more complete information about the specified scaler.
count counting_time scaler1 [scaler2 [scaler3 ...]]] - this command performs a measurement using the named scalers for the given counting time in seconds. In actuality, any device that MX treats as an input device like analog or digital inputs can be used instead of a scaler.
measure dark_currents [ measurement_time [ number_of_measurements ]] - measures dark currents for all scalers This is used to allow for automatic subtraction of dark currents during all scaler measurements. Be sure that the X-ray shutters are closed before doing this.
set field scaler_name.dark_current value - changes the subtracted dark current value to the specified value.
set field scaler_name.subtract_dark_current value - turn on or off the subtraction of dark current values depending on whether value is set to 1 for on or 0 for off.

A couple of commands are specific to autoscaling scaler records:

measure autoscale autoscale_scaler_name [ measurement_time [ number_of_measurements ]] - measure the dark currents for autoscale_scaler_name for each of the gain or filter settings available to it. This command must be run separately for each autoscaling scaler you are using.
set autoscale scaler_name low_limit high_limit low_deadband high_deadband - sets low and high thresholds and deadbands for autoscaling of amplifier gain or filter settings for an autoscaling scaler.
Scalers may be read out repeatedly by Only the first two options will display a graph of the measured scaler values.

Amplifier control

show amplifiers - shows a summary of all the amplifiers in the system.
show amplifier amplifier_name - shows more complete information about the specified amplifier.
set amplifier amplifier_name gain gain_value - sets the gain of the specified amplifier. The gain_value must be specified as a multiplier, for example 1e-4, rather than a gain range like 4.
set amplifier amplifier_name offset offset_value - sets the offset of the output voltage of the specified amplifier.
set amplifier amplifier_name time_constant time_constant_value - sets the filter time constant for the amplifier. The time_constant_value must be specified in seconds.

Relay, shutter, and filter control

show relays - shows a summary of all the relays in the system.
show relay relay_name - shows more complete information about the specified relay.
open shutter_name - opens the specified shutter.
close shutter_name - closes the specified shutter.
insert filter_name - inserts the specified filter.
remove filter_name - removes the specified filter.
Note that insert is actually an alias for close and remove is actually an alias for open.

Multichannel analyzer control from scans

Multichannel analyzers (MCAs) may be specified as scan input devices when a scan is being set up or modified. When an MCA is listed as a scan input device, the MCA spectrum at each point is written out to a separate datafile instead of being inserted as a column in the output datafile.

The filename for this spectrum file is derived from the filename of the primary scan file as follows:

  1. If the primary scan file's name has no extension, the MCA spectrum filename is created by appending a measurement number as an extension. For example, the first MCA spectrum file for scan datafile junk would be junk.001.
  2. If the primary scan file's name does have an extension, the extension is moved before the period, is separated from the previous base name by an underscore and the measurement number is appended as an extension. For example, the first MCA spectrum file for scan datafile junk.out would be junk_out.001. Similarly, the first MCA spectrum file for scan datafile junk.004 would be junk_004.001.

Related MX drivers

There are three MX driver types that can also put MCA related data in a scan datafile:
mca_channel - a pseudoscaler that returns the counts in the specified MCA channel.
mca_roi_integral - a pseudoscaler that returns the integrated counts in the MCA region of interest.
mca_alt_time - a pseudoscaler that returns either the accumulated real time, the accumulated live time, or the accumulated time that is complementary to the time used to gate on the MCA timer.
These drivers must be configured into the local MX database to be used.

Controlling multichannel analyzers directly

There is also a set of commands for directly controlling MCAs from the motor command line. If neither real nor live is specified in the commands below, the default is live time.
mca mca_name count [ real | live ] counting_time - commands the MCA to count for the specified number of seconds and displays the spectrum as a plot on the screen.
mca mca_name rawcount [ real | live ] counting_time - commands the MCA to count for the specified number of seconds just like count does, but displays the MCA spectrum as text numbers rather than as a plot.
mca mca_name start [ real | live ] [counting_time] - commands the MCA to start counting for the specified number of seconds or indefinitely if no counting time was specified. The start command returns immediately after starting the counting rather than waiting for the counting to finish.
mca mca_name stop - stops the MCA if it was counting.
mca mca_name clear - clears to zero the spectrum in the MCA.
mca mca_name read - reads the spectrum currently in the MCA and displays it as a plot on the screen.
mca mca_name rawread - reads the spectrum currently in the MCA and displays it as a list of text numbers.
mca mca_name save savefile_name - saves the MCA spectrum to the file savefile_name.
mca mca_name get roi - gets the high and low channel numbers of the MCA's current region of interest (ROI).
mca mca_name get integral - gets the integral of the counts in the MCA's current region of interest.
mca mca_name get num_channels - gets the current number of channels in the MCA spectrum.
mca mca_name get channel channel_number - gets the number of counts in the specified MCA channel channel_number.
mca mca_name get real_time - gets the accumulated MCA real time in seconds.
mca mca_name get live_time - gets the accumulated MCA live time in seconds.
mca mca_name set roi low_channel high_channel - sets the region of interest limits to the specified low and high channel numbers.
mca mca_name set num_channels number_of_channels - sets the current number of channels in the MCA spectrum.

Multichannel analyzer control from scans

MX has a quick scan type called mcs_scan which is designed around the use of multichannel scalers for the acquisition of data. This is the recommended way of using MCSs from scans.

Controlling multichannel scalers directly

Multichannel scalers may also be controlled directly from the motor command line:
mcs mcs_name count measurement_time  num_measurements - commands the MCS to take the specified number of measurements with each data point taken for the specified measurement time. The results are displayed as a plot on the screen.
mcs mcs_name rawcount measurement_time  num_measurements - commands the MCS to take the specified number of measurements with each data point taken for the specified measurement time. The results are displayed as text numbers rather than as a plot.
mcs mcs_name start [ measurement_time  num_measurements ] - commands the MCS to take the specified number of measurements with each data point taken for the specified measurement time. The start command returns immediately after starting the counting rather than waiting for the counting to finish. If a measurement time and number of measurements is not specified, the MCS uses the values set with the set commands below.
mcs mcs_name stop - stops the MCS if it was counting.
mcs mcs_name clear - clears to zero the spectrum in the MCS.
mcs mcs_name readall - reads all the measurements for all the scalers in the MCS and display them as a plot on the screen.
mcs mcs_name rawreadall - reads all the measurements for all the scalers in the MCS and display them as text numbers.
mcs mcs_name read channel_number - reads all the measurements for the specified scaler channel number and displays them as a plot on the screen.
mcs mcs_name rawread channel_number - reads all the measurements for the specified scaler channel number and displays them as text numbers.
mcs mcs_name measurement measurement_number - reads all the scaler counts for the specified measurement number and displays them as text numbers.
mcs mcs_name saveall savefile_name - saves the counts from all scalers and measurements to the specified save file.
mcs mcs_name save channel_number savefile_name - saves the counts from the specified scaler channel for all measurements to the specified save file.
mcs mcs_name get measurement_time - gets the currently programmed measurement time from the MCS.
mcs mcs_name set measurement_time measurement_time sets the currently programmed measurement time to the specified time in seconds.
mcs mcs_name get num_measurements - gets the currently programmed number of measurements from the MCS.
mcs mcs_name set num_measurements number_of measurements - sets the currently programmed number of measurements to the specified number.

Execute scripts or external commands

! external_command_line or system external_command_line - runs an external Unix command line. Command arguments and redirection of input and output are available. Examples: ! vi test.file or ! ls > output.file.

@ script_name or exec script_name - executes a list of motor commands from the file called script_name.

& program_name or take program_name - runs an external program. The standard output of the external program is redirected so that it is interpreted as a series of commands to the motor program. Similarly, most of the output from motor is redirected back to the standard input of the external command.

Motor program flag variables

set plot on - enables the display of plots during scans. This is the default.
set plot off - disables the display of plots during scans.
set plot nowait - enables the display of plots during a scan, but does not require the user to hit a key at the end of the scan to exit the plot. This is intended for use in command scripts that run many scans in a row.
show plot - displays the status of the plot enable flag.
The particular kind of plot used and the particular functions plotted for a given scan are specified in the individual scan record and are set by the user in either setup scan or modify scan.
set header on - enables prompting for changes to datafile header text lines. This is the default.
set header off - disables prompting for changes to datafile header text lines.
show header - displays the status of the header prompt enable flag.

set overwrite on - allows scans to overwrite pre-existing datafiles if there is a filename conflict.
set overwrite off - prompts the user for permission to overwrite pre-existing datafiles if there is a filename conflict. This is the default.
show overwrite - displays the status of the datafile overwrite flag.

Database variables

Database variables are MX records that do not have any hardware associated with them. They are used for recording things like the monochromator crystal d-spacing, the currently used X-ray absorption edge energy, data file header text, and so forth.

Three motor commands are used with database variables:

show variables - shows the values of all current database variables.
show variable variable_name - shows more information about a particular database variable.
set variable variable_name value1 [value2 [value3 ...]] - sets the current value of the specified database variable.

Generic record interface

The following commands should work for most record types:
resynchronize record_name - If the communication between MX and a hardware controller has failed, this command may be able to reestablish communication. This command is not implemented for all record types and is not always successful. Note: sometimes resynchronizing more than once can help.

set device record_name values - sends the specified value to the specified record. This command is primarily used to set the values of DAC and digital output records.

show records - shows the entire list of database records in the motor program.
show record record_name - shows more detail about a given record.
showall record record_name - shows details for all record fields in a record. This command just shows the current contents of the fields and does not refresh their values from the actual hardware.

set field record_name.field_name - sets the value of a given field in an MX record. Unrestricted use of this command is to be discouraged since you can completely scramble motor's copy of the MX database if you change the wrong field. Don't use this command unless you really know what you are doing.

Other commands.

cd directory-name - allows motor's current directory to be changed. Datafiles are written to the current directory unless the datafile specification includes a directory name. Please note that prefixing cd with an exclamation point as in ! cd will not work.

show interfaces, show devices, show variables, show servers, show amplifiers, show adcs, show dacs, show dinputs, show doutputs, show mcas, show mcses, show motors, show relays, show scalers, show timers - These commands list the status of particular classes of devices. They do not show anything that cannot be shown by show records or show record.

show history - lists previous commands that have been executed.
show version - shows the version number of MX for the copy of motor you are running.
set debug debug_level - controls the amount of internal debugging output that is generated by MX and motor. Higher values of debug_level will generate more debugging output. This command is normally used only for debugging the internal operation of MX and motor. The default debug level is 0.
This document is current as of MX version 0.27.3.
Last modified by lavender@metis.imca.aps.anl.gov on May 14, 2001.