Chapter 1
Introduction

At present, this manual is incomplete and is a work in progress.

Chapter 2
Records

General description of records go here.

Chapter 3
Motors

All motor records in MX support a common set of operations that are described in this chapter. We describe first the set of record fields found in the record description string in an MX database file for a motor.

Motor records are divided into two subclasses, namely, stepper and analog motors. The two classes are distinguished by the format of the numbers used to communicate with the underlying controller. Motor controllers for which positions, speeds, etc. are specified in integer units (steps or encoder ticks) are called stepper motors by MX motor support. Motor controllers for which positions, speeds, etc. are specified in floating point units are called analog motors by MX motor support.

3.1 Record Fields in the Record Description

The following fields must be included in the record description for a record in an MX database file. They must appear in the order presented below.

The disabled motor record was chosen for this example since it has no type-specific fields.

3.2 Motor Controllers

MX currently supports a wide variety of motor controllers.

3.2.1 APS Insertion Device

3.2.2 Bruker D8

3.2.3 Compumotor 6K and 6000 Series Motor Controllers

This set of drivers supports both the Compumotor 6000 and 6K series of controllers from the Compumotor division of Parker Hannifin. Several different MX drivers are associated with this type of controller. They are:

• compumotor_int - An interface driver that manages all of the Compumotor controllers attached to a particular serial port or Ethernet connection.
• compumotor - The basic motor driver for Compumotor controllers.
• compumotor_trans - A motor driver for controlling several motors of a specific Compumotor controller as a group. This driver is capable of simultaneous starts.
• compumotor_lin - A predecessor to the compumotor_trans driver.

So far these drivers have been tested with both the 6K and Zeta 6104 controllers.

compumotor_int

Not yet written.

compumotor

Go to the MX Motor Driver Support page for the common motor record description fields. For the compumotor driver, the following driver specific fields are present:

Notes

• The MX drivers assume that daisy-chained controllers are numbered from 1 to N where N is the number of controllers. This may be done via the ADDR command as described in the 6000 and 6K Command Reference manuals. For more information look at the sections named RS-232C Daisy-Chaining and RS-485 Multi-Drop in the Compumotor 6000 or 6K Programmer’s Guide.
• If you use the ethernet port on a 6K controller, you will need to use the ’tcp232’ RS-232 interface type and specify the port number to connect to as 502. There is not a lot of experience with controlling the 6K this way, so there may be lurking bugs related to the socket I/O.

  Warning: The port number seems to have changed for more recent 6K controllers. Using a packet sniffer while the vendor supplied code for Windows is running should be able to determine the correct port number.

• The MX Compumotor drivers make certain assumptions about the internal configuration of Compumotor controllers. The following figure shows an example startup script for Compmotor controllers that is compatible with MX.

  ---

  ; This command script is to be downloaded into a Compumotor 6000 or 6K   ; controller in order to set up the controller to be compatible with MX.   ; The script sets up a startup command program to be executed by the   ; Compumotor controller at power-on.  The commands for ERRLVL, EOT, and MA   ; _must_ be set as shown below or else the MX driver will not work.   ; If you need other commands to set motor parameters, network addresses,   ; and so forth, add them to the commands listed below.   ;   ; Please note that if you use ECHO1, you must add the 0x2 echo on flag to   ; the compumotor_int record that defines the connection to the interface.   ; This lets the driver know that it needs to discard echoed characters.   ;   ; For a single controller, it is better to set ECHO0 since that will   ; eliminate the overhead of discarding the characters.  However, in a   ; multidrop daisy chain configuration, ECHO1 _must_ _be_ _set_ since the   ; controllers rely on the echoing to send the command on to the next   ; controller in the daisy chain.  If ECHO0 is set in a daisy chain   ; configuration, the configuration will mostly work but will randomly   ; lock up from time to time, so don't do it.   ;   ; William Lavender -- Last modified April 27, 2002   ;   DEF mstart   ERRLVL1          ; Have the controller generate a minimum amount of output.   EOT13,10,0       ; Want all output lines to have the same line terminators.   MA1              ; Use absolute mode for positioning.   LH0              ; Disable limits (for testing only!)   ENC0             ; Use motor step mode ( or set ENC1 for encoder step mode ).   ECHO1            ; Enable command echoing.   END Figure 3.1: Recommended STARTP program for MX controlled Compumotor motors.

  ---

  The MX drivers will not operate correctly if the variables ERRLVL, EOT, and MA are not set as shown. Also note that the setting shown for EOT means that the ’rs232’ driver must be configured with the read and write terminators set to 0x0d0a. In addition, the setting ECHO1 is required in order for multi-drop installations to function correctly. For a single controller, you may use ECHO0 which will the amount of serial I/O required.

Bugs

At present, Zeta 6104s occasionally stop communicating with the MX driver. The exact circumstances under which this occurs is not entirely clear. However, since most of our Compumotor usage is migrating towards the 6K series, the need to fix this issue may become less important.

3.2.4 DAC Motor

3.2.5 Delta Tau PMAC

The PMAC series of motor controllers is manufactured by Delta Tau Data Systems of Chatsworth, CA. PMAC motor controllers are definitely the most powerful motor controllers supported by MX. However, they are also the most complicated to setup and program of all the controllers supported by MX, so they may not be the best choice for simple applications.

The MX PMAC drivers are designed to be easily adaptable to any model of PMAC motor controller. However, so far the drivers have been mostly used with the Turbo PMAC series of controllers. The drivers listed below currently all operate via PMAC ASCII communication interfaces of various types.

MX has a large number of drivers for interacting with PMAC motor controllers:

MX PMAC drivers

pmac

- Pmac interface records are used to control one or more PMAC motor controllers attached to a given external interface. An example pmac record looks like

pmac1 interface generic pmac "" "" rs232 pmac1_rs232 1

which describes a single PMAC motor controller attached to MX RS-232 record pmac1_rs232.

Field Name	Field Type	Number of Dimensions	Sizes	Description
See Common record field definitions
port_type_name	string	1	80	A string such as rs232 that describes the type of PMAC interface this is. See below for more information.
port_args	string	1	80	This contains port type specific information such as the name of an RS-232 port record. See below for more information.
num_cards	int	0	0	The number of individual PMAC controllers attached to this interface. In most cases this will be 1. However, for a controller attached to a multidrop connection such as RS-485, this will be the number of controllers attached to the multidrop.

PMAC ASCII command interfaces are accessible via a variety of different mechanisms such as RS-422, Ethernet, USB, VME, etc. Since the information needed to describe the interface can vary widely from interface type to interface type, the information needed to the interface is specified in a string called port_args. The currently defined port types are:

port_type_name	port_args
rs232	The name of the MX RS-232/422/485 record that this PMAC interface is attached to, such as pmac1_rs232 in the example above.
epics_ect	This port type uses the string command and response interfaces provided with the EPICS PMAC software written by Tom Coleman of the Argonne National Laboratory ECT group. This port type uses EPICS process variable names that are constructed by appending “StrCmd” or “StrRsp” to the names. Thus, if the port args were “S18ID”, then the EPICS process variables used by this interface would be S18IDStrCmd.VAL and S18IDStrRsp.VAL.
	Note: There is an alternate set of MX EPICS drivers called pmac_tc_motor and pmac_bio_motor that is described elsewhere in this manual.

Note: It is anticipated that ethernet and maybe usb port types will be added at some point in the future.

pmac_motor

- A pmac_motor record refers to one particular motor in a PMAC motor controller. The motor is controlled mostly via PMAC “jog” mode commands except for certain features not available via jog commands.

An example pmac_motor record looks like

theta device motor pmac_motor "" "" 0 0 -10000000 10000000 0 -1 -1   0.05 0 um pmac1 0 4

which describes a motor called theta which belongs to controller 0, axis 4 of PMAC interface pmac1. The example motor uses a scale factor of 0.05 -meters per step and raw motion limits of ± 10000000 steps.

Field Name	Field Type	Number of Dimensions	Sizes	Description
See Common motor field definitions
pmac_record	record	0	0	Name of the PMAC interface record that controls this motor.
card_number	int	0	0	Card number of the PMAC card that controls this motor. For PMACs that are not in a multi-drop configuration, the card number will normally be 0.
motor_number	int	0	0	The PMAC axis number for this specific motor.

pmac_cs_axis

- A pmac_cs_axis record makes use of a specified coordinate system axis for a coordinate system defined in a PMAC controller. PMAC coordinate systems can be thought of as a way of defining “pseudomotors” inside a PMAC controller in a manner that is analogous to the way MX defines pseudomotors. However, PMAC coordinate system axes are more powerful than MX pseudomotors, since for a coordinate system, the PMAC controller is able to ensure that all of the raw motors are able to maintain their correct relative relationship even while the motors are moving. Ordinary MX pseudomotors make sure that the real motors are at the correct positions at the beginning and end of motor moves, but they cannot do this while a move is in progress.

Warning: This driver has not yet been tested on a real beamline.

Pmac_cs_axis motor records require that some preliminary setup be done in the PMAC before they may be used. There are three primary steps in this process:

• The coordinate system that this axis is to be part of must be set up before this record may be used.
• You must write a motion program that will be run every time a move of this axis is commanded. The motion program must define the move destination, the feedrate (reciprocal of the speed), the acceleration time, and the S curve acceleration times in terms of PMAC motion variables so that the pmac_cs_axis driver can set them. I recommend that you use Q-variables so that variables used by this coordinate system will not interfer with other coordinate systems used by your PMAC.
• You must arrange for the current position of the coordinate system axis to be continuously updated to a PMAC variable that you specify. The most obvious way to do this is with a constantly running PMAC PLC program which is set up to calculate the coordinate system axis position from the real motor positions at all times. I would recommend that you use a Q-variable for this too. Of course, the kinematic calculation logic of the PLC program must match the logic of the PMAC motion program mentioned above.

An example pmac_cs_axis record looks like

det_distance motor pmac_cs_axis "" "" 0 0 200 1000 0 -1 -1 1 0 mm pmac1 0 2 Z 3 Q50 Q51 Q52 Q53 Q54

This describes a motor called det_distance which corresponds to axis Z of coordinate system 2 running in card 0 of PMAC interface pmac1. The axis performs moves using motion program 3 with position, destination, feedrate, acceleration time, and S-curve acceleration time managed by PMAC coordinate system variables Q50 through Q54.

Field Name	Field Type	Number of Dimensions	Sizes	Description
See Common motor field definitions
pmac_record	record	0	0	Name of the PMAC interface record that controls this axis.
card_number	int	0	0	Card number of the PMAC card that controls this axis. For PMACs that are not in a multi-drop configuration, the card number will normally be 0.
axis_name	char	0	0	The name of the coordinate system axis used by this motor. The possible names are X, Y, Z, ???, A, B, and C.
move_program_number	int	0	0	The number of the motion program that is used to move this axis as part of the coordinate system.
position_variable	string	1	8	Name of the PMAC variable that the MX driver uses to read the current position of the axis from.
destination_variable	string	1	8	The MX driver writes the new axis destination to this PMAC variable before starting the motion program to perform the move.
feedrate_variable	string	1	8	The MX driver sets the axis speed by writing to the specified PMAC feedrate variable.
acceleration_time_variable	string	1	8	The MX driver sets the axis acceleration time by writing to this variable.
s_curve_acceleration_time_variable	string	1	8	The MX driver sets the axis S-curve acceleration time by writing to this variable.

Note: If all you want is basic control of the individual motors belonging to a PMAC controller, then it is not necessary to create MX pmac_cs_axis motor records or coordinate systems in the PMAC. You can get basic control of the motors with just the pmac_motor records, with much less setup required. You only need pmac_cs_axis records if you want to make use of the special abilities of PMAC coordinate systems.

pmac_mce

- A pmac_mce record is used to read out the position of a motor at the end of an MX quick scan.

To be continued...

3.2.6 Disabled Motor

3.2.7 DSP E500

3.2.8 EPICS Motor

3.2.9 IMS MDrive

3.2.10 IMS Panther and 483

3.2.11 Joerger SMC24

This is an MX motor driver for the Joerger SMC24 CAMAC stepping motor controller, which is still available as of August 2003, from Joerger Enterprises, Inc.

Warning: As far as I know, this driver has not been tested in a long time. However, if broken, I expect that it would take less than a day to get the MX driver working again.

The Joerger SMC24 controller does not have an internal register to record its current position, so it needs the assistance of an external device to keep track of the motor’s absolute position. Traditionally, a Kinetic Systems 3640 CAMAC up/down counter is used as the external device, but any device capable of acting as an encoder-like device may be used as long as there is an MX encoder driver for it.

Also, traditionally the Kinetic Systems 3640 up/down counter was modified in the field to connect pairs of 16-bit up/down counters to form 32-bit up/down counters. However, if this has not been done, the driver can also emulate in software a 32-bit step counter using a 16-bit hardware encoder by setting the bit in the ”flags” variable called MXF_SMC24_USE_32BIT_SOFTWARE_COUNTER (0x1) .

3.2.12 Lakeshore 330 Temperature Controller

3.2.13 Mar Desktop Beamline

3.2.14 McLennan

3.2.15 McLennan PM-304

The MX driver for the PM304 requires that responses from the controller include an address prefix. By default, the PM304 has this feature turned off. You may turn it on by sending the string

3.2.16 National Instruments PC-STEP

3.2.17 National Instruments ValueMotion

3.2.18 Network Motor

3.2.19 Newport

Note: For the MM4000, this driver assumes that the value of the field “Terminator” under “General Setup” for the controller is set to CR/LF.

3.2.20 OMS VME58

3.2.21 OSS -GLIDE

3.2.22 Oxford Cryosystems Cryostream 600 Temperature Controller

3.2.23 Oxford Instruments ITC503 Temperature Controller

itc503_control

• A - Set auto/manual for heater and gas
• C - Set local/remote/lock status
• G - Set gas flow ( in manual only )
• O - Set heater output volts ( in manual only )

There are several other ITC503 control commands, but only the ones likely to be used in routine operation are supported.

itc503_motor

• C0 - Local and locked (default state)
• C1 - Remote and locked (front panel disabled)
• C2 - Local and unlocked
• C3 - Remote and unlocked (front panel disabled)

itc503_status

• 0 - Set temperature
• 1 - Sensor 1 temperature
• 2 - Sensor 2 temperature
• 3 - Sensor 3 temperature
• 4 - Temperature error
• 5 - Heater O/P (as
• 6 - Heater O/P (as Volts, approx.)
• 7 - Gas flow O/P (arbitrary units)
• 8 - Proportional band
• 9 - Integral action time
• 10 - Derivative action time
• 11 - Channel 1 freq/4
• 12 - Channel 2 freq/4
• 13 - Channel 3 freq/4

3.2.24 Physik Instrumente E662 Piezo Controller

3.2.25 Pontech STP100

The permitted board numbers are from 1 to 255.

The permitted values for digital I/O pins are:

Pins 5 and 6 are normally used for limit switches while either pin 3 or pin 8 is used for the home switch. This is because pins 5 and 6 already have pullup resistors.

The output of the RP command is 0 = closed and 1 = open.

3.2.26 Prairie Digital Model 40

3.2.27 Radix Databox

3.2.28 Scientific Instruments 9650 Temperature Controller

3.2.29 SCIPE Motor

3.2.30 Soft Motor

3.2.31 Velmex VP9000

3.2.32 XIA HSC-1 Huber Slit Controller

By default, the HSC-1 Huber Slit Controllers are delivered with default values that do not allow the slit blades to be moved to anywhere the blades can physically reach. The default values for parameters 1 and 2 are:

The MX drivers for the HSC-1 assume that these two parameters have been redefined to have the following values:

The reprogramming must be done using a terminal program like Kermit or Minicom. Suppose you have an HSC-1 controller with a serial number of XIAHSC-B-0001. Then the appropriate commands to send to the HSC-1 would be:
 

Then, you will be able to move the A, B, and C motors from -13000 um to +13000 um and the S motor from 0 um to 26000 um.

Please note that the HSC-1 motor positions can only be set to the value 0. A “set motor ... position” command to any other value than zero will fail. The “set motor ... position 0” command itself will cause the HSC-1 to execute an “Immediate Calibration” or “0 I” command. Also note that the slit size motor S cannot be moved to a negative value, so if S is at zero and there is a visible gap between the blades, then you will have to manually close the slit by hand.

Here is an example database for two HSC-1 controllers attached to the same serial port:

3.3 Pseudomotors

Pseudomotor support goes here.

3.3.1 ADSC Two Theta

3.3.2 A-Frame Detector Motor

This is an MX motor driver for the pseudomotors used by Gerd Rosenbaum’s A-frame CCD detector mount. The geometry of this detector mount is shown in the following figure:

The pseudomotors available are:

• detector_distance - This is the length of the line perpendicular to the plane containing the front face of the detector which passed through the center of rotation of the goniometer head.
• detector_horizontal_angle - This is the angle between the line used by the detector distance and the horizonal plane.
• detector_offset - This is the distance between the centerline of the detector and the line used to define the detector distance above.

There are three constants that describe the system:

• A - This is the perpendicular distance between the two vertical supports that hold up the detector.
• B - This is the distance along the centerline of the detector from the front face of the detector to the point where a perpendicular from the downstream detector pivot intersects this line.
• C - This is the separation between the centerline of the detector and the line defining the detector distance above.

The pseudomotors depend on the positions of three real motors. These are:

• dv_upstream - This motor controls the height of the upstream vertical detector support.
• dv_downstream - This motor controls the height of the downstream vertical detector support.
• dh - This motor controls the horizontal position of the vertical detector supports.

Confused? I am planning to write a short document that describes the definitions of these parameters in more detail and derives the formulas describing them. If you are reading this text and I have not yet written that document, then pester me until I do write it.

Warning: The detector horizonal angle is expressed internally in radians. If you want to display the angle in degrees, use the scale field of the angle pseudomotor to do the conversion.

3.3.3 APS 10-ID

3.3.4 APS 18-ID

3.3.5 Delta

3.3.6 Elapsed Time

3.3.7 Energy

3.3.8 Linear Function

3.3.9 Monochromator

The monochromator pseudomotor is implemented using a large collection of MX records. These records can be categorized into several groups:

• The monochromator record with N dependencies.
• N dependency list records.
• N dependency enable records.
• N dependency parameter records.
• N dependency record list records.
• N dependency type records.

where the value of N above is set by the value of the num_dependencies field in the monochromator record.

Monochromator Record

The MX Motor Driver Support page describes the common motor record description fields. For the monochromator driver, the following driver specific fields are present:

Example:

The monochromator record is a pseudomotor record which contains a list of the dependencies used by the pseudomotor. In general, one of the dependencies will be a primary dependency which describes the primary axis used by the monochromator pseudomotor (usually theta). The rest of the dependencies will be secondary dependencies that describe motors that are to be moved to positions that depend on the position of the primary dependency motor. There should only be one primary dependency.

In the example above, the dependencies specified are:

• theta_list - This is the primary dependency and describes the dependence of the monochromator pseudomotor on the real theta axis of the monochromator.
• momega_list - A secondary dependency that controls the angle between the first and second monochromator crystal.
• id_ev_list - A secondary dependency that controls the energy of the peak of the undulator spectrum for this beamline.
• normal_list - A secondary dependency that controls the perpendicular spacing between the first and second monochromator crystals.

This example does not include all of the available dependency types which are described in more detail below. In addition, the primary dependency does not have to be the first record listed, but it is customary to do so.

Dependency List Records

An example dependency list record looks like

• Dependency enable record - used to enable or disable the dependency. (momega_enabled in the example above.)
• Dependency type record - describes what type of dependency this is. (momega_type in the example above.)
• Dependency parameters record - describes the parameters used by this dependency. (momega_params in the example above.)
• Dependency record list - describes the records used by this dependency. (momega_records in the example above.)

The individual elements of the array are described in more detail below.

Dependency Enable Records

An example dependency enable record looks like

• 1 - The dependency is enabled and the dependent motor(s) will be moved to positions that correspond to the position of the primary dependency.
• 0 - The dependency is disabled and the dependent motor(s) will not be moved.

Dependency Parameter Records

An example dependency parameters record looks like

Dependency Record List Records

An example dependency record list looks like

Dependency Type Records

An example dependency type record looks like

At present, nine different dependency types are available. Dependency types 0 and 1 are primary dependency types, while types 2 through 8 are secondary dependency types.

Type 0 - Theta dependency

The theta dependency is used to control the position of the primary theta axis. This dependency is normally the primary dependency for the monochromator pseudomotor. If this dependency does not exist or is disabled, the real theta axis will not be moved at all.

• Record list record - This is a 1-dimensional array with only one element, specifically, the name of the real theta motor record.
• Parameters record - This record must be present, but its contents are not used by this dependency. Typically, a dummy variable will be used here as in the example below.

An example set of records for the theta dependency looks like

Normally, there is no reason for the users to disable this dependency, so it is standard to hard code it to 1 as in the example above.

Type 1 - Energy dependency

The energy dependency is a primary dependency that computes the monochromator theta angle from a monochromator energy provided by a foreign beamline control system. Use of this dependency is not recommended, unless the underlying beamline control software/hardware does not provide a direct way of querying and controlling the theta angle. Use of this dependency is incompatible with the type 0 theta dependency specified above. Do not specify both of them in the same MX database.

If you are looking for a way to control a dependent motor as a polynomial function of energy, you should be using the type 8 energy polynomial dependency described below.

• Record list record - This is a 1-dimensional array of type MXFT_RECORD containing two elements:
  • energy record - This motor record queries and controls the monochromator energy.
  • monochromator d spacing record - This is a variable record that contains the d spacing of the monochromator crystal in angstroms.
• Parameters record - This record must be present, but its contents are not used by this dependency. Typically, a dummy variable will be used here as in the example below.

An example set of records for the energy dependency looks like

The monochromator theta angle is computed using the standard Bragg equation

theta = asin( 12398.5 / ( 2.0 * d_spacing * energy ) )

Normally, there is no reason for the users to disable this dependency, so it is standard to hard code it to 1 as in the example above.

Type 2 - Polynomial dependency

This dependency type is a secondary dependency that allows a dependent motor to be moved to positions that are a polynomial function of the theta position of the monochromator. The computed position will be of the form

dependent_position = c0 + c1 * theta + c2 * (theta**2) + c3 * (theta**3) + ...

Beamline staff may configure this polynomial to have as few or as many terms in it as they want by changing the number of elements in the parameters array below. For example, a parameters array record with only two array elements will describe a dependent position that has a linear dependence on theta, while a parameters array record with four array elements describes a cubic dependence on theta. It is generally not useful to use a polynomial of higher order than cubic, although there is no limit in the record as to how high the order may be.

• Record list record - This is a 1-dimensional array with only one element, specifically, the name of the dependent motor record.
• Parameters record - This is a 1-dimensional array of type MXFT_DOUBLE which contains the coefficients of the polynomial. The coefficients are specified in order starting with the constant term and continuing up to the coefficient of the highest order term.

An example set of records for the polynomial dependency looks like

momega = 0.32 + 0.41 * theta - 0.02 * (theta**2) + 0.015 * (theta**3)

Typically, the values of these coefficients will be determined by measuring the location of the peak X-ray intensity as a function of the dependent motor position for several values of theta Then a curve will be fitted to the measurements.

Type 3 - Insertion device energy dependency

This dependency type is a secondary dependency that changes the energy of the undulator peak such that the maximum of the undulator spectrum is at the same energy as the monochromator.

• Record list record - This is a 1-dimensional array of type MXFT_RECORD containing two elements:
  • insertion device motor record - This is a motor record that controls the position of the undulator peak in units of eV.
  • monochromator d spacing record - This is a variable record that contains the d spacing of the monochromator crystal in angstroms.
• Parameters record - This is a 1-dimensional array of type MXFT_DOUBLE which contains two elements:
  • gap harmonic - This is the requested undulator harmonic number and should be a positive odd integer such as 1, 3, 5, etc. This is usually set to 1.
  • gap offset - This is an offset to be added to the computed gap energy.

For a given monochromator theta position in degrees, the undulator energy is computed as follows:

mono_energy = 12398.5 / ( 2.0 * d_spacing * sin( theta ) )

undulator_energy = ( mono_energy + gap_offset ) / gap_harmonic

Please note that if the undulator controls provided by your storage ring also have a way of setting the gap harmonic in addition to the method provided by MX, then you should only set one of them to the harmonic number and set the other to 1. For example, at the APS, if you set both EPICS’s variable for the gap harmonic to 3 and MX’s variable for the gap harmonic to 3, you would actually end up with the ninth harmonic.

An example set of records for the insertion device energy dependency looks like

Type 4 - Constant exit Bragg normal dependency

This dependency type is a secondary dependency that changes the perpendicular spacing between the first and second monochromator crystals so that the X-ray beam exiting the monochromator stays at a constant height.

• Record list record - This is a 1-dimensional array of type MXFT_RECORD containing two elements:
  • normal record - This motor record controls the perpendicular spacing between the two monochromators crystals.
  • beam offset record - This is a variable record of type MXFT_DOUBLE that contains the desired fixed offset distance of the beam expressed in the same units as the normal motor.
• Parameters record - This record must be present, but its contents are not used by this dependency. Typically, a dummy variable will be used here as in the example below.

An example set of records for the Bragg normal dependency looks like

bragg_normal = beam_offset / ( 2.0 * cos( theta ) )

If a positive move of the normal motor at theta = 0 is in the opposite direction from the desired beam offset, then the value of the beam offset must be set to a negative number. For example, this is true of the MX installations at APS sectors 10 and 17 where beam_offset = -35000 um.

Type 5 - Constant exit Bragg parallel dependency dependency

This dependency type is a secondary dependency that translates the second crystal parallel to its surface. This dependency should normally be used in combination with the Bragg normal dependency listed above. It is used to ensure that the X-ray beam does not fall off the end of the second crystal.

• Record list record - This is a 1-dimensional array of type MXFT_RECORD containing two elements:
  • parallel record - This motor record controls the translated position of the second crystal.
  • beam offset record - This is a variable record of type MXFT_DOUBLE that contains the desired fixed offset distance of the beam expressed in the same units as the normal motor.
• Parameters record - This record must be present, but its contents are not used by this dependency. Typically, a dummy variable will be used here as in the example below.

An example set of records for the Bragg parallel dependency looks like

The Bragg parallel position is computed from the beam offset and the monochromator theta angle via the equation

bragg_parallel = beam_offset / ( 2.0 * sin( theta ) )

Type 6 - Experiment table height dependency

If a given monochromator does not support fixed exit beam operation, an alternate way to ensure that the X-ray beam hits the desired target is to put the experiment on a table that can be vertically translated to track the beam.

• Record list record - This is a 1-dimensional array of type MXFT_RECORD containing three elements:
  • table height record - This motor record controls the vertical height of the experiment table.
  • table offset record - This is a variable record of type MXFT_DOUBLE that provides a way of adding a constant offset to the computed table height.
  • crystal separation record - This is a variable record of type MXFT_DOUBLE that contains the perpendicular crystal separation distance expressed in the same units as the table height motor.
• Parameters record - This record must be present, but its contents are not used by this dependency. Typically, a dummy variable will be used here as in the example below.

An example set of records for the experiment table height dependency looks like

The experiment table height position is computed via the equation

table_height = table_offset + 2.0 * crystal_separation * cos( theta )

Type 7 - Diffractometer theta dependency

The diffractometer theta dependency is used to control the Bragg angle of a diffractometer or goniostat in the experimental hutch so that it is set to the correct angle to diffract the X-ray beam coming from the monochromator. This dependency assumes that, in general, the crystal on the diffractometer will have a different d spacing than that of the monochromator crystal.

If the diffractometer angle is called htheta and the diffractometer d spacing is called hd_spacing, the diffractometer angle is computed by the equation

sin(htheta) = d_spacing * sin(theta) / hd_spacing

The raw value of htheta is adjusted using a linear equation of the form

htheta_adjusted = diffractometer_scale * htheta + diffractometer_offset

• Record list record - This is a 1-dimensional array of type MXFT_RECORD containing three elements:
  • diffractometer theta motor record - This the a motor record that controls the diffractometer theta angle.
  • monochromator d spacing record - This is a variable record that contains the d spacing of the monochromator crystal in angstroms.
  • diffractometer d spacing record - This is a variable record that contains the d spacing of the diffractometer crystal in angstroms.
• Parameters record - This is a 1-dimensional array of type MXFT_DOUBLE which contains two elements which are used to compute the adjusted diffractometer angle:
  • diffractometer scale
  • diffractometer offset

An example set of records for the diffractometer theta dependency looks like

Type 8 - Energy polynomial dependency

The energy polynomial dependency is similar to the type 2 polynomial dependency described above, except the dependent motor position is a polynomial function of the monochromator X-ray energy. Thus, the dependent position will have the form

dependent_position = c0 + c1 * energy + c2 * (energy**2) + c3 * (energy**3) + ...

This dependency assumes that the energy is expressed in eV.

• Record list record - This is a 1-dimensional array containing two elements:
  • dependent motor record - This motor record controls the dependent motor whose position is determined by the energy polynomial.
  • monochromator d spacing record - This is a variable record that contains the d spacing of the monochromator crystal in angstroms. This record is used to convert the theta angle in degrees to energy in eV.
• Parameters record - This is a 1-dimensional array of type MXFT_DOUBLE which contains the coefficients of the polynomial. The coefficients are specified in order starting with the constant term and continuing up to the coefficient of the highest order term.

An example set of records for the energy polynomial dependency looks like

Type 9 - Option selector dependency

The option selector dependency is used together with a “position_select” calculation record to switch an external value between multiple settings depending on the current value of the monochromator theta position. The “position_select” variable has an integer value from 1 to N. For example, this could be used to automatically switch between mirror stripes at certain X-ray energies.

• Record list record - This is a 1-dimensional array of type MXFT_RECORD containing two elements:
  • option selector record - This should be a calculation variable record of type “position_select” that controls the external value and contains a list of allowed values for the external value.
  • option range record - This is the name of the parameters record below.
• Parameters record - This is a 2-dimensional Nx2 array of type MXFT_DOUBLE which contains pairs of elements that describe the limits for each allowed theta range. The two values for each theta range are
  • theta range lower limit
  • theta range upper limit

  The number N is the number of theta ranges.

An example set of records for the option selector dependency looks like

The example above is for an X-ray mirror whose transverse position is determined by a motor record called stripe. There are 4 allowed positions for stripe, namely, 300, 600, 900, and 1200. The allowed theta ranges corresponding to the allowed positions are 0 to 5 degrees, 4.5 to 8.5 degrees, 8 to 11 degrees, and 10.5 to 15 degrees. The stripe position to be selected is determined by comparing the current position of theta to the parameter ranges in the variable stripe_params. According to stripe_params, the stripe motor is allowed to be at 300 if theta is between 0 and 5, or it is allowed to be at 600 if theta is between 4.5 and 8.5, and so forth. If theta moves outside the allowed range of positions for the current selection, the option selector will switch to the next selection.

Notice that the allowed ranges for theta overlap. This is to provide a deadband for switches between option selector ranges. As an example, suppose theta is currently at 7 degrees. This means that theta is within the second option selector range of 4.5 to 8.5 degrees and that the stripe motor should currently be at 600. However, if theta is moved to 9 degrees, this is outside the current option selector range, so stripe will be moved to the next allowed position of 900. However, the lower end of the new range, namely, 8 degrees, is below the upper end of the original range, namely, 8.5 degrees. This means that theta must be moved below 8 degrees before the stripe position will be moved back to the previous value of 600.

Note that if theta is below 0 degrees, the stripe motor will be sent to 300, while if theta is above 15 degrees, the stripe motor will be moved to 1200.

Bugs

Some of the dependencies are user configurable via the parameters record while others are configured via additional records added to the record list.

3.3.10 Q Motor

This is an MX pseudomotor driver for the momentum transfer parameter q, which is defined as

Warning: above must not be set to the angle of the analyzer arm. Instead, it must be set to half of that angle which is the nominal Bragg angle.

3.3.11 Segmented Move

3.3.12 Slit Motor

slit_type field - This integer field select the type of slit pseudomotor that this record represents. There are four possible values for the slit_type field, which come in two groups of two, namely, the SAME case and the OPPOSITE case. The allowed values are:

• 1 - (MXF_SLIT_CENTER_SAME)
• 2 - (MXF_SLIT_WIDTH_SAME)
• 3 - (MXF_SLIT_CENTER_OPPOSITE)
• 4 - (MXF_SLIT_WIDTH_OPPOSITE)

The SAME cases above are for slit blade pairs that move in the same physical direction when they are both commanded to perform moves of the same sign. The OPPOSITE cases are for slit blade pairs that move in the opposite direction from each other when they are both commanded to perform moves of the same sign.

As an example, for a top and bottom slit blade pair, if a positive move of each causes both blades to go up, you use the SAME case. On the other hand, if a positive move of each causes the top slit blade to go up and the bottom slit blade to go down, you use the OPPOSITE case.

3.3.13 Table Motor

3.3.14 Tangent Arm/Sine Arm

This is an MX motor driver to move a tangent arm or sine arm pseudomotor.

IMPORTANT: The moving motor position and the arm length must both be specified using the same user units, while the angle offset must be specified in radians. Thus, if the moving motor position is specified in micrometers, then the arm length must be specified in micrometers as well.

If you want to specify the angle offset in degrees rather than in radians, the simplest way is to create a ’translation_mtr’ record containing only the raw angle offset motor. Then, set a scale factor in the translation motor record that converts from radians to degrees.

A tangent arm consists of two arms that are connected at a pivot point as follows:

A linear motor is attached to the fixed arm at point A and then moves a push rod that pushes the moving arm at point B. In this geometry, the position of the moving motor, m, is related to the angle theta by the relationship

A sine arm is similar except that the linear motion is now perpendicular to the moving arm:

This changes the equation to the form

Note: The ’tangent_arm’ and ’sine_arm’ drivers share the same code and distinguished in the driver code by their different driver types, namely, MXT_MTR_TANGENT_ARM and MXT_MTR_SINE_ARM.

3.3.15 Theta-Two Theta

3.3.16 Translation

3.3.17 Wavelength

3.3.18 Wavenumber

3.3.19 XAFS Wavenumber

This MX pseudomotor driver controls another MX motor in units of XAFS electron wavenumber.

The XAFS electron wavenumber k is computed using the equation:

Chapter 4
Counter/Timers

4.1 Am9513

The following is an example database for the IIT BCPS setup for Am9513 boards:

Warning: The am9513 interface driver has only been fully implemented and tested for Am9513-based systems using 8-bit bus access.

At present, MX Am9513 timers can only use one 16-bit counter. Also note that the timer driver relies on the output for the timer’s counter being connected to its own gate input. That is, OUT(n) must be connected to GATE(n) for the timer to work. Of course, OUT(n) is also connected to the GATE inputs of the scalers that this timer is gating.

4.2 DSP QS450 or Kinetic Systems 3610

4.3 EPICS Scaler

The MX EPICS scaler support optionally can make use of globally visible dark current values. This is done by loading an additional EPICS database file in “st.cmd” that can be found in the MX base distribution in the file mx/driver_info/epics_scaler/Jscaler_dark.db. This EPICS database implements two additional records per EPICS scaler channel. For example, for scaler channel 2 the records are

• $(P)$(S)_Dark2.VAL - Dark current per second for scaler channel 2.
• $(P)$(S)_SD2.VAL - The dark current subtracted value for scaler 2.

where $(P) and $(S) are defined to have the same values as in the standard Jscaler.db database. The database is loaded into the EPICS VME crate by adding a line to the ’st.cmd’ startup script that looks like

Please note that this database contains a definition for the scaler record $(P) and $(S) itself and thus is not immediately compatible with the standard Jscaler.db database. This is due to the fact that EPICS does not supply any way for an add-on database to add forward links to existing records. If you wish to combine Jscaler.db and Jscaler_dark.db, the simplest way is to merely move the FLNK field whose value is “$(P)$(S)_cts1.PROC” in Jscaler.db to the LNK4 field of Fanout record “$(P)$(S)_fan0” defined in Jscaler_dark.db.

Hopefully, something equivalent to the dark current fields in Jscaler_dark.db will be added to some future version of Jscaler.db.

4.4 EPICS Timer

4.5 Joerger VSC8/16

4.6 MCA Timer

4.7 MCS Timer

4.8 Network Scaler

4.9 Network Timer

4.10 Ortec 974

4.11 Radix Databox Scaler/Timer

4.12 RTC-018

4.13 SCIPE Scaler

4.14 SCIPE Timer

4.15 Soft Scaler

4.16 Soft Timer

4.17 Pseudoscalers

4.17.1 Autoscale Related Pseudoscalers

4.17.2 MCA Related Pseudoscalers

4.17.3 MCS Scaler

4.17.4 Scaler Function

4.18 Pseudotimers

Timer Fanout

The MX timer fanout driver is used to control multiple MX timers in software as if they were one timer.

WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING

This driver does NOT attempt to ensure that all of the timers start at exactly the same time. This means that devices gated by different timers may not be gated on for exactly the same timer interval, although the lengths of time they are gated on for should be the same. The result is that you may get SYSTEMATIC ERRORS if you do not use this driver intelligently. It is up to you to decide whether or not this makes a difference to the experiment you are performing. The best solution is to make sure that all of your measuring devices are gated by the same hardware timer, but if that is not possible, then this driver may be useful as a stopgap.

Caveat emptor.

Chapter 5
Pulse Generator

5.1 Network Pulse Generator

5.2 Struck SIS3801

5.3 Struck SIS3807

Chapter 6
Encoder

6.1 Kinetic Systems 3640

Chapter 7
Analog I/O

7.1 APS ADCMOD2 Analog I/O

7.2 Kinetic Systems 3112 Analog Output

7.3 Kinetic Systems 3512 Analog Input

7.4 Network Analog I/O

7.5 Soft Analog I/O

7.6 Motor Controller Analog I/O

Chapter 8
Digital I/O

8.1 Bit I/O

8.2 Intel 8255

8.3 Kinetic Systems 3063

8.4 Linux Parport

8.5 Motorola MC6821

8.6 Network Digital I/O

8.7 PC Parallel Port

8.8 Port I/O Digital I/O

8.9 SCIPE Digital I/O

8.10 Soft Digital I/O

8.11 VME Digital I/O

8.12 Motor Controller Digital I/O

Chapter 9
Relays

9.1 Blind Relay

9.2 Generic Relay

9.3 Network Relay

Chapter 10
Amplifiers

10.1 APS ADCMOD2 Amplifier

10.2 Keithley 428

10.3 Network Amplifier

10.4 Oxford Danfysik IC PLUS

10.5 SCIPE Amplifier

10.6 Soft Amplifier

10.7 SRS SR-570

10.8 UDT Tramp

Chapter 11
Single Channel Analyzers

11.1 Network SCA

11.2 Oxford Danfysik Cyberstar X1000

11.3 Soft SCA

Chapter 12
Multichannel Analyzers

12.1 EPICS MCA

12.2 Network MCA

12.3 Ortec UMCBI

12.4 Soft MCA

12.5 X-Ray Instrumentation Associates

12.6 Generic Records

12.6.1 MCA Alternate Time

12.6.2 MCA Channel

12.6.3 MCA Region of Interest Integral

12.6.4 MCA Value

Chapter 13
Multichannel Encoders

13.1 MCS Elapsed Time Multichannel Encoder

13.2 MCS Multichannel Encoder

13.3 Network Multichannel Encoder

13.4 PMAC Multichannel Encoder

13.5 Radix Databox Multichannel Encoder

Chapter 14
Multichannel Scalers

14.1 EPICS MCS

The MX EPICS MCS support optionally can make use of globally visible dark current values. This is done by loading an additional EPICS analog output record per MCS channel which is used to store the dark current value. This is most easily described by giving an example.

Suppose you have a set of MCS records loaded in the EPICS “st.cmd” script that look like

Then, all that you need to add to support dark currents for these channels is to add something like the following lines to “st.cmd”.

The mcs_dark.db database file is extremely simple. The entire contents of the file is:

A copy of this file may be found in the MX base source distribution in the file mx/driver_info/epics_mcs/mcs_dark.db.

14.2 Network MCS

14.3 Radix Databox MCS

14.4 Scaler Function MCS

14.5 SIS3801

14.6 Soft MCS

Chapter 15
CCD

15.1 Network CCD

15.2 Remote MarCCD

Chapter 16
Goniostat/Diffractometer Tables

16.1 IMCA-CAT ADC Table at APS Sector 17

The ADC table is designed to support a standard crystallography goniostat. At present, it is the support for an ADSC Quantum 105 detector system. The geometry of the table is shown by the figure below:

The MX table support for ADC tables uses two different kinds of records, namely, an ADC specific table record described here and the generic table motor record described in the motor section.

16.1.1 Record Fields in the Record Description

An example database for this table type would look like:

In this example, the adsc_table record is the actual table record itself. It is configured to use soft motors x1, y1, y2, z1, z2, and z3 as the raw motors. The table parameters for the example are set to m1 = 0.4, m2 = 0.6, m3 = 0.75, rx = 0.25, ry = 0.25, and rz = 0.5.

Chapter 17
Autoscale Devices

17.1 Autoscale Amplifier

17.2 Autoscale Filter

17.3 Autoscale Filter and Amplifier

17.4 Related Devices

17.4.1 Autoscale Scaler

17.4.2 Gain Tracking Scaler

MX scaler driver to control MX gain tracking scalers. Gain tracking scalers are pseudoscalers that rescale their reported number of counts to go up and down when an associated amplifier changes its gain.

For example, suppose that the real scaler was reading 1745 counts, the amplifier was set to 10⁸ gain and the gain tracking scale factor was 10¹⁰. Then, the gain tracking scaler would report a value of 174500 counts. If the amplifier gain was changed to 10⁹ , then the gain tracking scaler would report a value of 17450 counts.

Gain tracking scalers are intended to be used in combination with autoscaling scalers, so that when the autoscaling scaler changes the gain of the amplifier, the values reported by gain tracking scalers will change to match.

Chapter 18
RS-232

18.1 EPICS RS-232

18.2 MSDOS COM

18.3 Fossil

18.4 Kinetic Systems KS3344

18.5 Network RS-232

18.6 TCP Socket

18.7 Unix TTY

18.8 Win32 COM

Chapter 19
GPIB

19.1 EPICS GPIB

19.2 Keithley 500-SERIAL RS-232 to GPIB converter

19.3 Linux Lab Project GPIB

Warning: This MX driver was originally developed for the Linux 2.0.x device driver provided by the Linux Lab Project, but that project seems to have stalled. Fortunately, the code seems to have been picked up by the Linux GPIB Package Homepage (http://linux-gpib.sourceforge.net/) which supports Linux 2.4.x. However, this MX driver has not yet been tested with the new Linux 2.4.x version of the device driver.

The Linux Lab Project GPIB driver does not provide an equivalent to the ibdev() function that finds a GPIB device by address. That makes the Linux Lab Project driver the only one that does not provide such an interface, so it is easier just to provide one for it. This is handled by adding to /etc/gpib.conf the contents of the file mx/driver_info/llp_gpib/gpib.conf_addon from the MX base source distribution, so that there is a way to find a given GPIB device by its primary address. The contents of the file gpib.conf_addon is shown in the following figure:

19.4 National Instruments GPIB

Chapter 20
CAMAC

20.1 DSP6001

20.2 Soft CAMAC

Chapter 21
VME

21.1 EPICS VME

21.2 National Instruments VXI Memacc

21.3 Struck SIS-1100 and SIS-3100

Chapter 22
Port I/O

22.1 DriverLINX Port I/O

This MX driver is an interface to the DriverLINX port I/O driver for Windows NT/98/95 written by Scientific Software Tools, Inc. The DriverLINX package may be downloaded from http://www.sstnet.com/dnload/dnload.htm. This driver is primarily intended for use under Windows NT, since the ’dos_portio’ driver already handles Windows 98/95, but it should work on all three operating systems.

Warning: These drivers have not yet been tested with Windows 2000 or Windows XP.

22.2 MSDOS Port I/O

22.3 Linux iopl() and ioperm() drivers

22.4 Linux portio driver

Chapter 23
Variables

23.1 EPICS Variables

23.2 Inline Variables

23.3 Network Variables

23.4 PMAC Variables

Chapter 24
Servers

24.1 TCP/IP Servers

Chapter 25
Scans

25.1 Linear Scans

25.1.1 Input Scans

25.1.2 Motor Scans

25.1.3 Pseudomotor Scans

25.1.4 Slit Scans

25.1.5 Theta-Two Theta Scans

25.2 List Scans

25.2.1 File List Scans

25.3 XAFS Scans

25.4 Quick Scans (also known as Fast or Slew Scans)

25.4.1 Joerger Quick Scans

25.4.2 MCS Quick Scans

Chapter 26
Interfaces to Other Control Systems

26.1 EPICS

26.2 SCIPE

Chapter 27
Incomplete or Broken Records

There are several device drivers that were never finished for some reason or other. The source code is still maintained in the MX driver library just in case the opportunity arises to finish the work.

27.1 Motors

27.1.1 Bruker GGCS

27.1.2 NSLS MMC32

27.2 Analog and Digital I/O

27.2.1 National Instruments LabPC+

27.3 Counter/Timers

27.3.1 Prairie Digital Model 45

27.4 RS-232

27.4.1 VMS Terminal