How to Configure After Changing Removable Elements

A Checklist and User Guide

For Instrument Scientists, Engineers, Technicians

BACKGROUND

DEIMOS has removable elements: slitmasks, filters, and gratings. In the final deployed state, all these elements should be barcoded. The slitmask barcodes can be read by a scanner mounted on the instrument. The other element barcodes can be read by a hand-held gun which will semi-automate the configuration process.

In the short term, however, we have to configure gratings and filter wheels manually.

The dispatcher (Dean's code) knows 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.

Here's the good news: the procedure is quite simple. Type a command, edit a file, type a command, restart the dispatchers and dashboards.

CHECKLIST / HOWTO

Log in to deitrader as kics, in two different xterms: You have to have kics privs to execute this procedure. You have to execute it where the dispatchers are. The dispatchers run on deitrader. You will need two kics xterms for the last step in the procedure.
Go to the directory config in kics' home dir: In other words cd config. You should see three files: confget, confput, and deimot.cfg. If you are paranoid, make a backup copy of the cfg file. You don't have to cd config in both xterms, only one.
confget: This extracts 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).
Use your favourite text editor to edit the new deimot.cfg file: This file is tab-separated. Keep it that way! Follow the instructions in the comment block at the top of the file (a detailed example/walkthrough appears below); if you're changing gratings, remember to edit both appearances of the grating name (see below). Also heed the warnings please.
confput: This script writes your altered data back into the database of dynamic configurations. Due to a peculiarity of "exec" on deitrader which we don't yet understand, this script will pause at one point and ask you to paste a command into your other xterm, wait for it to complete, and then hit return. I hope we'll iron out this wrinkle one of these days. Meanwhile, just follow the instructions and it will work.
Restart the dispatcher(s): deimos restart dispatcher2.1: If you only made changes affecting one dispatcher (i.e. you only changed the dewar filter config and nothing else) then you only need to restart one dispatcher. It is important not to skip this step! If you don't kick the dispatcher it won't notice the new dyna map file. If you aren't sure which dispatcher to restart, restart them both:
deimos restart dispatcher2.1 dispatcher2.2
Restart all dashboards: The dashboards configure their menus at startup time.
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.
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.

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

de@ucolick.org
De Clarke