Summary

DEIMOS has removable elements: slitmasks, filters, and gratings. The standard changeout procedure involves using a barcode scanner to read barcode labels on an individual element. If for some reason this does not work (e.g., barcode scanner is broken) then the reconfiguration can be completed manually using the following procedure.

Background

The DEIMOS dispatchers (motor control software) know the Raw, Ordinal, and Name values for each of N positions on a filter wheel. It also knows the Names that go with the Positions for the compound grating select/clamp stage. This knowledge is compiled in.

To "teach" the dispatcher new maps (either new raw positions or new names for existing positions) you need to feed it a "dyna map" file, which is generated from data in the database. Our dispatchers are configured to read this file at startup time, overriding their default (compiled-in) information with information from the file (which came from the database).

The observer GUI uses information directly from the database to configure its menus for filter wheels, grating select, etc. -- otherwise the menus would show the same choices that are compiled into the dispatcher.

The bottom line is that if you don't update the database to reflect the new configuration, the dispatcher won't know about the new filter, grating, or whatever positions; and the automatically-genned dashboard menus will be all wrong.

Procedure

  1. Log in to keamano as kics. You must have kics privs to execute this procedure. You must execute it where the dispatchers are. The dispatchers run on keamano.
  2. cd to ~kics/config. Among the many files these should be three required files: confget, confput, and deimot.cfg. If you are paranoid, make a backup copy of the cfg file via 
    	cp deimot.cfg deimot.cfg.YYYYMMMDD
  3. Run confget. Typing confget will extract the current dynamic configuration settings into a plain text file. There will be some debug messages which you can safely ignore. The result should be a new file deimot.cfg (that's why a paranoid person would make a backup copy).
  4. Edit deimot.cfg. Use your favorite text editor (emacs, vi, etc.) to edit the file as needed. Note: This file is tab-separated. Keep it that way! Follow the instructions in the comment block at the top of the file.
  5. Run confput. This script writes your altered data back into the database of dynamic configurations.
  6. Restart the dispatchers. Issue the following command: 
    	deimos restart dispatcher2.1 dispatcher2.2
    This step is essential! If you don't kick the dispatchers they won't notice the new dyna map file.
  7. Restart all dashboard GUIs. The dashboards configure their menus at startup time, so they must be killed and restarted in order to sense the changes.
  8. Sanity check (for the paranoid). You may want to confirm that you can move to, e.g. a new named position -- if you have just put in a filter called Coffee, make sure you can modify -s deimot dwfilnam=Coffee without getting an error.

    Another thing you can do to confirm (for the brave and bold): go to /local/kroot/data/deimot/dyna and look at the file mapRON.cfg. This is the dyna map file itself. Its touch date should be "just a minute or two ago" because it should be your creation. Note: NEVER, NEVER, NEVER yield to the temptation to edit this file directly! If you do, you will cause the dispatcher to be out of synch with the dashboards. This can result in some very startling effects.

Sample confio File Edits

Here's a chunk of the cfg file. 
# DWFIL
# (dynamically configured)
deimot  DWFIL   0       1       Filter1
deimot  DWFIL   142857  2       Clear
deimot  DWFIL   285714  3       Filter3
deimot  DWFIL   428571  4       Filter4
deimot  DWFIL   571429  5       Empty
deimot  DWFIL   714286  6       Filter6
deimot  DWFIL   857143  7       Filter7
# (factory defaults)
# deimot        DWFIL   0       1       Filter #1
# deimot        DWFIL   142857  2       Filter #2
# deimot        DWFIL   285714  3       Filter #3
# deimot        DWFIL   428571  4       Filter #4
# deimot        DWFIL   571429  5       Filter #5
# deimot        DWFIL   714286  6       Filter #6
# deimot        DWFIL   857143  7       Filter #7
If you read the comments at the top of the file (you did read all the comments, right?) you will know that the commented-out lines are the default (compiled-in) values, and the uncommented lines are your own (dynamic) values.

If you want to add a new filter at position 6, you would simply use your text editor to change the name "Filter6" to the name of your new filter, and then save/exit.

If you are moving grating cells around it is slightly more complicated. The grating stage (GRATExxx keyword) is actually two stages, a linear motion stage and a clamping mechanism. GRATEPOS and GRSELNAM are more or less equivalent: for consistency and to avoid confusion, GRSEL has to know the same named positions as GRATE. Therefore there are two blocks of text to edit for this stage, if you want to do it right. 

# GRSEL
# (dynamically configured)
deimot  GRSEL   10000   1       NonOp
deimot  GRSEL   -9323100        2       Mirror
deimot  GRSEL   -4228176        3       900line
deimot  GRSEL   128228  4       1200line
# (factory defaults)
# deimot        GRSEL   10000   1       Grating_1
# deimot        GRSEL   -9323055        2       Mirror
# deimot        GRSEL   -4218400        3       Grating_3
# deimot        GRSEL   126012  4       Grating_4
#

[...]

# GRATE
# (dynamically configured)
deimot  GRATE   1       1       NonOp
deimot  GRATE   2       2       Mirror
deimot  GRATE   3       3       900line
deimot  GRATE   4       4       1200line
# (factory defaults)
# deimot        GRATE   1       1       Grating_1
# deimot        GRATE   2       2       Mirror
# deimot        GRATE   3       3       Grating_3
# deimot        GRATE   4       4       Grating_4
Usually we're swapping the 1200 line and 900 line gratings between slider 3 and slider 4. Just change 900 to 1200 and 1200 to 900 in both locations, then save/exit.

What if there are no uncommented lines for this stage -- i.e. you are the first on your block to populate a filter wheel with real filters? Easy. Copy/paste the commented lines to duplicate them. Uncomment the duplicate copy. Get rid of any positions that you don't want to see in menus. Change the names of those you do want to see, to reflect the actual filters now installed.

Warnings

The Surgeon General has determined that it's very bad for everyone's mental health when the ordinal positions of DC stages get messed up. Therefore, unless you really know what you are doing, please don't touch the raw or ordinal positions in the config file; restrict yourself to the names of the positions.

If you mess up the file unintentionally (an editor mishap) don't panic, just quit without saving and start over. If it's too late for that, then just run confget again and start over. As long as you haven't run confput, nothing has happened that anyone else can see.

Don't imagine that you have to add to the cfg file every unload position, home position, etc. -- those are not dynamic, and they will always be compiled in to the dispatcher and available to engineering GUIs. Restrict yourself to naming the positions that observers actually see in menus and scripts.