The MX MarCCD interface program 'goniostat' provides a way for the MarCCD detector control system to access beamline provided services. The primary uses of 'goniostat' are to provide a way for MarCCD to control a goniostat not made by MarUSA and a way for MarCCD to control the beamline X-ray wavelength. The MX 'goniostat' program has been tested so far in three configurations: 1. Using SER-CAT's APS sector 22-ID goniostat system. 2. Using the goniostat that comes with an ADSC Quantum 210 detector. 3. Using a standard MarDTB base for only wavelength control. MarCCD is configured to use 'goniostat' for external control in the configuration file /home/marccd/configuration/marccd_site. For versions of MarCCD built since Fall 2002, the use of 'goniostat' is enabled by a line in that file that looks like goniostat_software_command "/opt/mx/bin/goniostat -V --" Older versions of MarCCD use the directive 'goniostat_external_command' rather than 'goniostat_software_command'. MarCCD is configured to send goniostat move requests to 'goniostat' rather than a Mar supplied base by specifying that the 'goniostat_type' is 'Software' rather than 'mardtb'. Bear in mind that the MarCCD software provided by MarUSA is constantly being improved, so you should check with MarUSA for the details on how to enable external control with your version of MarCCD. The command line arguments for 'goniostat' are as follows: Usage: /opt/mx/bin/goniostat [-hV] [-f file] [-L file] -- command -h print this help message -V verbose mode -q quiet (for timing tests) -f file initialize MX from the specified database file -L file log output to file -- terminates the list of options where command is one of: marccd_move_abs motor_name destination speed [repeats...] marccd_shutter {open|close} marccd_query record_name marccd_set_abs motor_name position (currently disabled) marccd_exposure motor_name angle_range seconds expose_flag By default, 'goniostat' looks for its MX database in the file /opt/mx/etc/goniostat.dat. It can be told to look in a different location by use of the '-f' flag shown above. WARNING: You must always place the string '--' before the command argument so that the getopt() function used by 'goniostat' knows that there are no option flags after that point on the command line. Otherwise, 'goniostat' may think that '-90' in a command like /opt/mx/bin/goniostat marccd_move_abs phi -90.5 1 is actually a option flag '9' with a value '0.5' rather than the position you want to move phi to. Command descriptions: marccd_move_abs This command is used to move one or more motors controlled by the 'goniostat' program. For example, the command /opt/mx/bin/goniostat -- marccd_move_abs phi 90 1 tells 'goniostat' to move the phi axis to 90 degrees. The argument '1' is a requested speed which is currently ignored by 'goniostat'. For multiple motors, the pattern of command line arguments repeats. Thus, a command like /opt/mx/bin/goniostat -- marccd_move_abs kappa 5 1 omega 10 1 phi 30 1 would tell 'goniostat' to move the kappa axis to 5 degrees, the omega axis to 10 degrees, and the phi axis to 30 degrees. marccd_shutter This commands the goniostat to open or close. A command of the form /opt/mx/bin/goniostat -- marccd_shutter open tells the shutter to open, while /opt/mx/bin/goniostat -- marccd_shutter close tells the shutter to close. The MX database for 'goniostat' must include an MX relay record named 'shutter' for this command to work. marccd_query This command may be used to ask for the position of a motor or the status of the shutter. For example, if the command /opt/mx/bin/goniostat -- marccd_query lambda returns the string 1.05, this means that the X-ray wavelength of the monochromator is currently at 1.05 angstroms. Similarly, /opt/mx/bin/goniostat -- marccd_query shutter will return 1 if the shutter is open, and 0 if the shutter is closed. marccd_set_abs This is a placeholder for a command to redefine the position of a motor. This is intentionally disabled for now. marccd_exposure This command is used to command the beamline goniostat to perform the synchronized motions and shutter commands required to take a frame with the CCD detector. For example, a command like /opt/mx/bin/goniostat -- marccd_exposure omega 0.5 0.2 1 tells 'goniostat' to move omega 0.5 degrees relative to the current position in 0.2 seconds during the taking of the CCD frame. The value '1' tells 'goniostat' to open the shutter. If you want to take a still, this can be done by setting the angle range to 0 which looks like /opt/mx/bin/goniostat -- marccd_exposure omega 0 0 1 Performance: Current versions of MarCCD insist on starting a new copy of the external program for each command sent. In addition, during a data run, it also insists on sending move commands to all motors that it knows how to move even if MarCCD has previously commanded the motor to be at this position. For example, if external control of the beamline wavelength has been enabled and MarCCD commands the monochromator to move to 1.1 angstroms for the first frame, it insists on sending a new move command to move to 1.1 angstroms on every frame of the data run. All this means that the external program 'goniostat' must be careful to minimize the overhead required to start it up and run. One strategy that has proven useful has been to give 'goniostat' its own dedicated MX server to connect to and then put in /opt/mx/etc/goniostat.dat the absolute minimum number of records required by the 'goniostat' program. This way the overhead is required to set up the initial connections to the real hardware is performed only once when the dedicated MX server for 'goniostat' is started, while the database for 'goniostat' itself only contains a small set of MX network records which take relatively little time to be initialized. Another important thing one should do is configure the motor records in /opt/mx/etc/goniostat.dat to have non-zero deadbands. That way, if MarCCD commands the wavelength to move to 1.1 angstroms and 'goniostat' determines that the wavelength is already at 1.1 angstroms, then no move command is sent to the real hardware. Exposures: 'goniostat' can handle most operations required by MarCCD using generic MX records. However, the 'marccd_exposure' command must be tailored to the particular goniostat hardware. The choice of goniostat hardware is configured in /opt/mx/etc/goniostat.dat by the use of an inline string record called 'exposure_type'. At present, there are three supported values for the 'exposure_type' variable, namely, 'dummy, 'sercat' and 'adsc'. Bear in mind that if you are using a Mar provided goniostat and are only using the MX 'goniostat' program for monochromator wavelength control, then you do not need to define an 'exposure_type' record. Two of the three exposure types require additional records to be present in the /opt/mx/etc/goniostat.dat database. These are as follows: 'dummy' - This exposure type pretends to perform an exposure by sleeping for the expected number of seconds. This is normally only useful if you do not yet have code written to handle exposures for your goniostat and want to test the rest of the system. No additional MX records are required. 'sercat' - This exposure type handles the PMAC based goniostat control system used by SER-CAT's APS sector 22-ID beamline. For this case, you must include an additional string record called 'remote_pmac' to specify which PMAC is controlling the exposure. This looks like exposure_type variable inline string "" "" 1 80 sercat remote_pmac variable inline string "" "" 1 80 myserver:pmac_name where 'myserver' is the name of the MX server that controls this PMAC as specified in /opt/mx/etc/goniostat.dat, while 'pmac_name' is the name of the 'pmac' record as specified in the MX database for 'myserver' on the remote machine. 'adsc' - This exposure type handles triggering an exposure using the Compumotor 6K based goniostat provided with an ADSC Quantum 210. This requires two additional records called 'remote_6k' and 'remote_rs232' which look like exposure_type variable inline string "" "" 1 80 adsc remote_6k variable inline string "" "" 1 80 myserver:6k_name remote_rs232 interface rs232 network_rs232 "" "" 9600 8 N 1 N 0 0 myserver 6k_rs232 The 'remote_6k' record works like the 'remote_pmac' record described above, while the 'remote_rs232' record is an MX network RS-232 record connected to the RS-232 record '6k_rs232' in the MX server called 'myserver'. Contact information: If you have any problems with this program, please contact the author, William Lavender, at the email address lavender@agni.phys.iit.edu.