Communicating with the AOC

gpilib began as a way to interface with the AOC, so this part of the code base retains the most legacy code and practices. The code has been systematically updated to use more and more of the routines employed by the TLC and Instrument Sequencer for AOC control, while retaining the old functionality in parallel. This makes some of the code quite difficult to parse, so be very careful when editing to ensure that you are working on the intended logical branch of the code.

Socket or RPC

IDL communication with the AOC can be achieved in one of two ways:

1. Direct read/write to the AOC realtime socket.
2. Via Remote Procedure Calls (RPC).

The second method is the default, as it represent normal GPI operation. The first method is still available as it is useful for debugging. In both cases AOC commands are (eventually) sent to the AOC socket. A full list of these can be found in the AOC ICD at:

http://dms.hia.nrc.ca/view.php?fDocumentId=3379

From IDL, commands are sent via the function rtc_issue_command. The method used to send the call is determined by common block variable gpi_noaocksocket (see Common Blocks). See the description of procedure start_us_up below for more details.

Direct Socket Communication

In direct socket communication, the AOC realtime socket is opened and assigned to variable unit in IDL common block aocIF. All communication is done via functions and procedures in gpilib/rtc/aoc_socket_functions.pro. These include

Function	Description
aocsocket_help	Print information about socket functions.
aocsocket_open	Open realtime socket to AOC and assign to file unit in variable unit.
aocsocket_write	Write byte string to socket.
aocsocket_readline	Read from socket until encountering end of line, and return buffer.
aocsocket_waitcommand	Read from socket until command completion has been acknowledged, or error occurs.
aocsocket_close	Close the file unit connected to the socket.

These commands are all used by higher level functions and typically do not need to be called directly when using direct socket communication.

AOC RPC

The default method of accessing the AOC is the same on used with the other subsytem - RPC calls. These are done via the gpAocRpcClientTester binary. For more information, see TLC Binaries.

Because the codebase to interact with the AOC grew out of direct socket communication, high level IDL code utilizes AOC socket functions, which must be translated before sending via RPC. This is done with the function aoc2rpc. While this function translates the majority of AOC commands, there are a few rarely called ones which do not have translations. Therefore, there is an alternate option: aocrpc_passthru, which passes command directly to the socket, with no translation or error-checking by the RPC.

Note

aoc2rpc.pro is merely a translator. It does not issue any commands. It is called by rtc_issue_command.pro when gpi_noaocsocket is equal to 1.

Session Locking

To further decrease the probability of user collision, a lock file are generated when an IDL session communicates with the AOC. The file, .idllock is written to the AOC config directory. It is added and removed automatically by the startup and shutdown scripts described in the next section, but can also be toggled manually via the scripts lock_aoc and free_aoc.

Startup and Shutdown

start_us_up

Before communicating with the AOC via IDL, it is necessary to run the startup script start_us_up. This has the primary purpose of populating gpi_globals (see Common Blocks), but also moves mechanisms to their last stored states and prepares the system for closing the AO loops.

Warning

While start_us_up moves mechanisms, it does not check whether they are powered on. The AOC also does not check whether its control surfaces are powered. It is up to you to ensure that everything that needs it has power. This can be achieved automatically with the use of ult_sysalign, which is the preferred method of calling start_us_up.

While start_us_up overwrites the majority of gpi_globals variables that it sets, two variables in the common block are sticky (whatever value they have when start_us_up is called remains):

• gpi_noaocsocket If 1, RPC communication is used, if 0, direct socket communication. This should never be changed without restarting the session.
• gpi_verbose When set to 1, all AOC communications will be printed to the IDL session. This can be toggled at any point in the session (assuming the common_block has been loaded).

When called, start_us_up executes the following sequence:

• If the working directory is not /home/LAB/IDL/gpilib, IDL switches to there. Before returning, the original working directory is restored.
• Populates all common block variables with their default values.
• Checks for an existing lock file and generates one as needed.
• If using RPC communication, sends AOC command setDebug -1 to prevent extra information from being written to the socket (this causes the RPC server to die.) If using direct communication, send commands setDebug -2 and setDebug 1, which causes filenames for dumpData products to be written out via the socket.
• Connects to the socket and checks connection.
• Enables AOC error logging.
• Runs rtc_standard_settings and tlc_standard_settings which puts mechanisms in the last recorded positions for the current mode (see below).
• Checks AOC disk usage.

Some useful flags for start_us_up are:

• \noaoc Populate the common block but do not open AOC communication or move mechanisms
• \grabsocket Use direct communication (defaults to RPC)
• \datum_all Send DATUM commands to all of the Track assembly, the ASU, the FPM, the PPM, the AO PnCs, the CAL PnCs, the AOWFS Filter, and the SF.

Operating Modes

start_us_up supports three operating modes, accessed by adding a keyword to the call. These are: \mode_ao, \mode_cal, and \mode_ifs. These modes allow for different sets of mechanism positions to be stored so one can quickly switch between different alignments. The default mode is \mode_ifs. The choice of mode affects what file is read when any of the mechanism control functions are called with a \def flag. Values are stored in the IDL private path (common block variable gpi_idl_private_datapath) and are written and read by functions gpilib/config/save_default_* and gpilib/config/load_default_*. The functions are:

Function	Description and Units
laod/save_best_tt	AO tip/tilt mirror zeroing values (mas)
load/save_default_inputfold	Inputfold centering (mm)
load/save_default_sfpos	Spatial Filter stage position (mm)
load/save_default_pnc_pc	AO PnC mirror pointing, centering and focus (mas, mm, mm)
load/save_default_cal_pnc_pc	CAL PnC mirror pointing, centering and focus (mas, mm, mm)

Note

CAL PnC mirror default value function can accept lyot keyword, specifying which Lyot stop is in use. This allows us to store different centering positions for the different stops.

shut_us_down

The shut_us_down procedure removes and AOC lock files, and puts the system in a standardized shutdown state: All shutters are closed, any AO reference offsets are zeroed, CAL Tip/Tilt biases are zeroed, all loops are opened, all mirrors have zero volts applied, the ASU is extracted, and power is turned off to the Woofer, Tweeter, AO Tip/Tilt mirrors and the supercontinuum source. If keyword /sc_on is set, the supercontinuum is set to zero power and maximum attenuation, but its powerbar remains on.