MCP Fiducials Commands

The MCP keeps two values for each fiducial on each axis; the `correct' value, and the value of the encoder the last time that the fiducial was crossed. The `correct' values are kept in non-volatile shared memory on the MCP, and may be loaded from files on the unix host.

Overview of Fiducials

When an axis crosses a fiducial mark, two things happen in hardware:
  • A signal is sent to the MEI to latch all the axes, i.e. read the positions of all the encoders (two per axis). The MEI remembers these positions until they've been read and the board is explicitly reset.
  • The systran DIO316 board in the MCP VME crate is told to generate an interrupt for the MCP, telling it which axes were crossed. This interrupt is then disabled for all axes. A message is then sent to the tLatch MCP task telling it which axes have seen a fiducial crossing. tLatch then decides which fiducial is crossed; for the rotator this is easy as the distance between any two consecutive marks on the optical tape identifies the fiducial. For the azimuth the MCP reads a barcode; for altitude it uses the clinometer. Note that this identification in azimuth and altitude is carried out when the interrupt is recieved, not when the fiducial is crossed. When the tLatch task receives the message it reads the position of the indicated axes, then resets the MEI and reenables interrupts.

    A consequence of this architecture is that while a fiducial crossing is being processed on one axis, fiducial crossings on the other axes are ignored. This is unfortunate but necessary --- the MEI is unable to latch the different axes separately, so the MCP is unable to read the position of the second fiducial. It would be possible to generate a warning, but doing so would significantly complicate the code.

    `MS' Commands

    All fiducial commands start MS.; this stands for MagnetoSensor, and reflects this history of the APO 3.5m.

    The full command set is as follows; only MS.ON and MS.OFF are generated by the TCC; for a discussion see documentation of Axis Controller commands

    CORRECT
    Apply an arbitrarily large correction to an axis.
    MS.MAP.DUMP
    Not implemented; see MS.WRITE.
    MS.MAP.LOAD
    Not implemented; see MS.READ.
    MS.OFF
    Stop correcting an axis's position; the opposite of MS.ON.
    MS.ON
    Start correcting an axis's position; the opposite of MS.OFF.
    MS.MAX
    Set the maximum correction that MS.ON is allowed to apply
    MS.READ
    Read the fiducial positions from a file on the unix host.
    MS.SET
    Equivalent to SET.FIDUCIAL
    MS.WRITE
    Write the current fiducial table to a file.
    SET.FIDUCIAL
    Tell the MEI where an axis is.

    CORRECT

    CORRECT is equivalent to a MS.ON/MS.OFF pair of commands, with the exception that an arbitrarily large correction is allowed.

    MS.MAP.DUMP

    Not implemented; see MS.WRITE.

    MS.MAP.LOAD

    Not implemented; see MS.READ.

    MS.OFF [DT]

    Turn off MS.ON, that is, stop updating the encoders every time that a fiducial is crossed. If the time delay dt is specified, only disable updates after dt seconds.

    MS.ON

    After an MS.ON command is received for a given axis, and until a MS.OFF is seen (or takes effect if a delay is specified), the encoders for that axis are corrected each time that a fiducial is crossed.

    More precisely, the MCP maintains a table of the `true' position of each fiducial, and notes the difference between this position and the encoder reading each time a fiducial is crossed; when requested MS.ON is active, the encoder is adjusted to make this error zero. It would be possible to use the history of errors for a given axis to estimate the error, but at present this is not done.

    A SET_FIDUCIAL_ERROR entry is written the the mcpFiducials-mjd.dat file every time that the encoders are updated.

    Because the MEI supports no atomic `update this axis' command, the correction is applied in software; all positions that are sent to or received from the MEI are corrected by the appropriate amount. Only when the axis is given an INIT command is the encoder actually updated.

    MS.MAX max

    Set the maximum correction that MS.ON can make to max. If a larger correction is requested an error message is written to murmur (unless max is zero), and the correction is not applied. Furthermore, no further corrections are permitted for that axis until after an INIT, and the ms_on_correction_too_large bit is set in the axis status word.

    You should use the CORRECT command to apply arbitrarily large corrections to an axis.

    MS.READ file

    Read the positions of the fiducials from file, as if they had just been crossed.

    Note that this doesn't make them the `correct' values; to do that you must use the MS.DEFINE.

    Any lines starting # are comments and are ignored, with the exception of a line that looks like # type fiducials; type may be azimuth, altitude, or rotator. If this line is seen, the axis type must agree with the current axis.

    Data lines are of the form

      7           0 +- -9999.000000 0           0 +- -9999.000000 0
      8   100167224 +- 0.000000 1       100167224 +- 0.000000 1
    
    where the first integer is the fiducial index; the next the value for encoder1 for that fiducial, followed by its error; then the number of points that were averaged together to derive the value; then the corresponding values for the second encoder. Only the fiducial number and the two positions are used, except that the special error value -9999 is used to label a missing value.

    When you switch to a new version of the MCP (using switchMCP) the fiducial tables in the new version are installed in /p/mcpbase; they are downloaded to the MCP itself at boot time.

    MS.WRITE file

    Write the fiducial table to file. Only useful if you're not sure what's currently loaded into the MCP.

    The format is:

    #
    # rotator fiducials
    #
    # Creator:             rhl
    # Time:                Fri Nov 02 09:36:47 MST 2001
    # Input file:          /mcptpm/52159/mcpFiducials-52159.dat
    # Scales:              0.021315785186278132  0.021315786787577316
    # Canonical fiducial:  78
    # Arguments:           -mjd 52159 -rot -time0 999838149 -time1 999841558 -canon -reset -scale -table rot.dat
    #
    # Fiducial Encoder1 +- error  npoint  Encoder2 +- error  npoint
    ...
    4          59366318 +-   4.6   6      59366599 +-   1.2   6
    5          58565519 +-   4.7   6      58565809 +-   0.9   6
    ...
    
    An error of -9999 is used to indicate that a value is missing.

    The iop command readMcpFiducials is used to produce fiducial tables, e.g.

    readMcpFiducials -mjd 52193 -alt -canon -reset -scale -table alt.dat \
    					-time0 1002767494 -time1 1002768300
    readMcpFiducials -mjd 52193 -az -canon -reset -scale -table az.dat \
    					-time0 1002759866 -time1 1002763821
    readMcpFiducials -mjd 52159 -rot -canon -reset -scale -table rot.dat \
    					-time0 999838149 -time1 999841558
    

    SET.FIDUCIAL

    Update the MEI's idea of the position of a given axis by the MCP's current value for the error on that axis; the MCP's software error is set to zero.

    A SET_FIDUCIAL_ERROR entry is written the the mcpFiducials-mjd.dat file every time that the encoders are updated.

    Fiducial Log Files

    Most actions connected with the fiducial system are logged to a Yanny `Parameter'-format file in /mcptpm/mjd/mcpFiducials-mjd.dat where mjd is the current SDSS-modified Modified Julian Day.

    The typedefs in the file are:

    ALT_FIDUCIAL
    An altitude fiducial has been crossed. The fiducial index, the `correct' positions of both encoders, two measured encoder positions, the velocity, and the clinometer reading converted to an elevation are logged.
    AZ_FIDUCIAL
    The fiducial index, the `correct' positions of both encoders, two measured encoder positions, the and the velocity are logged.
    ROT_FIDUCIAL
    The fiducial index (negative if the index is one of the intermediate dithered values), the `correct' positions of both encoders, two encoder readings, velocity, and the position of the previous fiducial crossed are logged.
    DEFINE_FIDUCIALS
    A MS.DEFINE command has been issued; which axis was affected is logged.
    START_FIDUCIAL
    The fiducials task in the MCP has restarted; this almost certainly means that the MCP has been rebooted.
    UPDATE_ENCODER
    The MEI's idea of the position of the axis has been reset, and the MCP's software error cleared. The axis, current position, and applied offset are logged.
    SET_FIDUCIAL_ERROR
    The MCP's idea of the encoder error in this axis has been updated. The axis and new error are logged.
    DISABLE_MS_CORRECTION
    The TCC has requested the MCP to disable MS.ON updates to the encoder positions as too large a correction (or too many large corrections) have been requested. The time, axis, and offending correction are logged.
    MS_ON
    The TCC has sent the MCP an MS.ON command. The time and axis are logged.
    MS_OFF
    The TCC has sent the MCP an MS.OFF command. The time and axis are logged.

    IOP Commands to Manipulate mcpFiducial Files

    There are a number (well, one is a number) of commands in iop to manipulate and analyse the mcpFiducials files that the MCP writes:
    plotMcpFiducials
    Read and analyze an mcpFiducials file e.g.
     plotMcpFiducials -mjd 51799 \\
           -alt -y pos1 -x time -reset -canon -scale -table stdout
    
    The file (by default the current one) is read, and the readings of the specified encoder for the specified axis are analysed.

    A complete list of options is available via plotMcpFiducials -help

    If you specify -x and -y a plot of x v. y is generated; useful choices for x are fididx (fiducial index), time, or index; you will usually want to use pos1 or pos2 for y. Unless you specify -absolute, the value for each encoder will have a mean value subtracted; exactly how that mean is determined is described in the next paragraph.

    If you specify -x time all the times will have a suitable offset subtracted from them (it's given in the axis label). If you choose -x index the x-axis will be the rank of the measurement's timestamps (i.e. the array index), starting at 0. There are a number of flags to control how the mean value for each fiducial is determined:

    -absolute
    Don't subtract any mean; use raw values
    -canonical
    Adjust the value of the `canonical' fiducial to have the `canonical' value; currently these are:
    Azimuth 33 31016188
    Altitude 1 3825222
    Rotator 83 40168185
    -error
    Use the position in the fiducial table as the `mean' value, so what's plotted is the error relative to the fiducial table. There's also an option -fiducialtable to specify which fiducial table should be used (e.g. -error -fiducialtable /p/mcp/mcpVersion/%s.dat, where %s will be replaced by e.g. "rot"; -fiducialtable mcpVersion is also permitted) If you don't specify a table the one current when the data was taken will be used.
    -reset
    The middle encoder encountered in each sweep in the axis position is found (averaged over sweeps), and matters are arranged so that that encoder has the same value for every sweep; this is used to take out secular changes (and is not needed for the instrument rotator).
    -scale
    Estimate the scale (in arcsec/tick), and ensure that if an fiducial's present in the table twice, once wrapped and once not, the two entries always differ by the same amount (360*60*60/scale)

    The value that -scale prints out is exactly the value that should be in the file mcp/mcp-new/axis.h.

    For axes that don't wrap (i.e. altitude) the relative scale is still correct; the numbers in the fiducial table are -(range in encoder counts) seen on the two encoders. Implies the -absolute flag.

    -time0
    Discard all measurements taken before time t0. If t0 is less than the first time stamp in the file, it'll be interpreted as being relative to the starting time subtracted from all times when they're plotted (see above).
    -time1
    Discard all measurements taken after t1; see -time0 for the meaning of small values of t1.
    -updown
    Analyse the encoder positions measured when the telescope was moving up and down (or clockwise and anticlockwise) separately. The mean `up' and `down' values are then averaged together.

    Optionally, a fiducial table in the correct format for MS.READ can be generated (using the -table flag).

    mcpFiducialsPlots
    Make complete (?) sets of plots for a given axis, either to the screen or to a set of files.