Summary

ESI has removable elements in the triple wheel: slits, filters, and decker/blockers. When these are changed, the software must be notified of the changes.

Background

The ESI 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 koki as kics. You must have kics privs to execute this procedure. You must execute it where the dispatchers are. The dispatchers run on koki.
  2. cd to ~kics/config. Among the many files these should be three required files: confget, confput, and esi.cfg. If you are paranoid, make a backup copy of the cfg file via
    	cp esi.cfg esi.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 esi.cfg (that's why a paranoid person would make a backup copy).
  4. Edit esi.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. Enter ./confput, which writes your altered data back into the database of dynamic configurations and also generates a new version of the important file $KROOT/data/esi/dyna/mapRON.cfg which lists the defined positions on each stage and is read by the dispatchers on startup.
  6. Restart the dispatchers. Log into koki as user esieng and issue the following command:
    	esi restart dispatcher2.0 dispatcher2.1
    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 esi dwfilnam=Coffee without getting an error.

    Another thing you can do to confirm (for the brave and bold): go to /u/kroot/data/esi/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 esi.cfg file:
# DWFIL
# (dynamically configured)
esi  DWFIL   0       1       Filter1
esi  DWFIL   142857  2       Clear
esi  DWFIL   285714  3       Filter3
esi  DWFIL   428571  4       Filter4
esi  DWFIL   571429  5       Empty
esi  DWFIL   714286  6       Filter6
esi  DWFIL   857143  7       Filter7
# (factory defaults)
# esi        DWFIL   0       1       Filter #1
# esi        DWFIL   142857  2       Filter #2
# esi        DWFIL   285714  3       Filter #3
# esi        DWFIL   428571  4       Filter #4
# esi        DWFIL   571429  5       Filter #5
# esi        DWFIL   714286  6       Filter #6
# esi        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)
esi  GRSEL   10000   1       NonOp
esi  GRSEL   -9323100        2       Mirror
esi  GRSEL   -4228176        3       900line
esi  GRSEL   128228  4       1200line
# (factory defaults)
# esi        GRSEL   10000   1       Grating_1
# esi        GRSEL   -9323055        2       Mirror
# esi        GRSEL   -4218400        3       Grating_3
# esi        GRSEL   126012  4       Grating_4
#

[...]

# GRATE
# (dynamically configured)
esi  GRATE   1       1       NonOp
esi  GRATE   2       2       Mirror
esi  GRATE   3       3       900line
esi  GRATE   4       4       1200line
# (factory defaults)
# esi        GRATE   1       1       Grating_1
# esi        GRATE   2       2       Mirror
# esi        GRATE   3       3       Grating_3
# esi        GRATE   4       4       Grating_4

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.