There are essentially four commands for controlling motors. Two of those commands work with keywords and two of them work directly with the Animatics motor controllers command language. The following is a synopsis of the commands which are discussed in detail below.

mm camraw=20000     mm writes to keywords
sm camraw           sm reads keywords
tm 1 AMPS=75        tm writes Animatics commands
am 1 RAMPS          am reads a single Amimatics status value

See analogous Lakeshore and DGH commands.

Reading/Writing Keywords

The commands affecting keywords are the observatory wide standard commands which allow one to read and write keyword values. The write command is modify and the read command is show.

The use of show and modify requires one to specify a 'service'. In the case of NIRC2, example commands would be:

modify -s nirc2 camraw=2000 
show -s nirc2 camraw

Unix aliases have been created for show and modify as shortcuts, so the examples can be simplified to:

mm camraw=2000 
sm camraw

For trouble shooting tips, click here.

The followin is an example of how to run these commands in a script:

#!/bin/csh -f
#
#   test slm by moving through range 10 times
#
logger -p local0.debug " ---------starting slm test ---------"
foreach i ( 1 2 3 4 5 6 7 8 9 10 )
  echo -------- iteration $i -----------------
  echo moving slm to 0 ...
  mm slmraw=0
  echo moving slm 499999 ...
  mm slmraw=499999
end

Mechanism Keyword Suffixes

The list of mechanism keywords is quite extensive. One can visualize the keywords, in most cases, as a composite of a mechanism prefix and a command suffix. A complete discussion of the mechanism keywords can be found in the design book. However, a quick synopsis is that for each mechanism the following command suffixes exist:

INIT   setups of motor control params; must be done after power 
       cycling and/or resetting a motor; when read, returns true
       if init has been completed and false otherwise

HOME   causes a motor to perform its homing procedure; when read, 
       returns true if homing has been completed 

RAW    mechanism's position in encoder counts

DELTA  offsets a mechanism in encoder counts; write only

BRAKES sets/releases brakes; write only

ENABLE enables/disables motor power (servo); write only

MTR    mechanism's associated motor number

INFO   returns a list of all discrete positions and names 
       associated with those positions for a mechanism

SIM    controls mechanism simulation

RESET  causes a motor controller to reset; init is necessary 
       afterwards

STOP   decelerates a moving motor; note that the backlash removal 
       will still occur so multiple stops are often necessary

KILL   instantly stops a moving motor; suffers from the same 
       backlash removal problem as stop

NUM    mechanism's position as an ordinal numbers; returns -1 if 
       the encoder value does not correspond with a known position

NAME   mechanism's position by name where a name is associated 
       with a specific ordinal position; if the encoder value does
       not correspond with a known ordinal position then the 
       mechanism's name keyword is set to 'unknown'

DIST/ANGL mechanism's position in engineering units, typically
       in millimeters (sliders) or degrees (wheels)

IDLE   indicates whether or not a mechanism is idle/not moving;
       read only

RDY    ready status; idle and at the last demanded position;
       read only

STAT   current state (idle, moving, ...); read only

TARG/TRGT current destination as a named position; is set to 'undefined' 
       if the encoder value does no correspond to an ordinal position;
       read only

DEST   current destination in encoder counts; read only

LMTORIDE allows one to override a mechanism's travel limits

MAXPE  sets a mechanism's maximum allowed postion error

MAXPOS negative software travel limit; read only 

MINPOS positiive software travel limit; read only)

ACCEL  allows setting motor acceleration; write only

AMPS   allows setting motor current; write only 

BLASH  allows setting backlash correction in encoder counts;
       write only

VEL    allows setting maximum motor velocity; write only
    

Reading/Writing Motor Controller Parameters

The commands for interfacing to the Animatics motor controllers are askmotor and tellmotor. The aliases for these are, respectively, am and tm.

The difference between askmotor and tellmotor is that askmotor waits for a motor response and, hence, would be used for reading current motor controller values (eg. RP, RA, Rg, Rh, RAMPS, ...).

To use these commands one must specify a motor number followed by a string comprising of an Animatics command. One can specify multiple Animatics commands if they are all enclosed in a single set of double quotes. Be aware that askmotor will only wait for a single response, so a string consisting of multiple commands should only contain a single query command. Also be aware that command strings are not parsed/inspected but are sent exactly as typed, hence, case is important.

am 1 RP            returns motor 1's current position
am 2 RE            returns motor 2's max allowed position error
am 2 Re            returns motor 2's variable 'e' value
am 3 "AMPS=50 RA"  sets motor 3's max current and returns it's 
                   current max acceleration value

tm 4 "g=1 RUN"     causes motor 4 to execute it's init subroutine
tm 4 "g=4 RUN"     causes motor 4 to execute it's homing subroutine
tm 4 "d=2000 g=2 RUN" this sequence would set motor 4's destination
                   to 2000 and cause it to execute its move subroutine 
tm 5 V=128000      sets motor 5's maximum allowed velocity
    

Motor Controller Variable Usage

The Animatics motor controllers provide for ten variables (a-j). Some of the variables are monitored by the higher level mechanism software but, in general, the variables are used internally within the low-level motor controller subroutines.

One can get the value of any variable with the askmotor command (described above) in conjunction with the Animatics 'R' command (eg. am 1 Ra).

The variables are used as follows :

a    is set to 1 in the init subroutine and indicates that the
     init subroutine has been run since the last power-cycle
     or reset

b    is set to the backlash correction value

c    move settling time after which the brakes are set

d    the move destination whether absolute or relative

e    maximum allowed position error 

f    maximum allowed velocity

g    used to specify which subroutine to execute on the next RUN;
     note that the 'g' values do not necessarily correspond 
     one-to-one with the subroutine numbers

h    is set to 1 at the end of the homing subroutine and is used
     to determine if the motor has been homed since the last reset
     or power-cycle

i    an offset to the homed index mark which is an adjustment to
     the origin (O) command

j    a temporary variable currently only used at the end of homing
     in conjunction with the 'i' variable
    

Motor Controller Subroutines

There are three programs that are downloaded into the Animatics motor controllers. The shutter has a unique Animatics program because its control parameters are significantly different. The pupil rotator has a unique program as well, mainly as its motion subroutines do not require use of the brakes or backlash correction. The other nine motors all have the same motor program.

There are seven subroutines in the common motor program. They are:

C1    is the init subroutine which sets up the motors dynamics

C2    is the motion subroutine which moves to some absolute 
      position and performs a backlash correction. Note that brakes 
      are released before the move commences and set after the
      move completes

C3    is the homing routine which moves negative until the travel
      limit switch is encountered and then locates the first
      index mark in the positive direction

C4    is a motion subroutine which does not perform backlash 
      correction (not used operationally)

C5    is the homing subroutine for the shutter (may be removed 
      from the common program sometime)

C6    is a motion subroutine for relative moves with backlash
      correction (not used operationally)

C7    is a motion subroutine for relative moves without 
      backlash correction (not used operationally)