MX: A Portable Data Acquisition and Control Toolkit

1
MX A Portable Data Acquisitionand Control
Toolkit
William M. Lavender Biological, Chemical, and
Physical Sciences Department Illinois Institute
of Technology Chicago, Illinois
60616 http//www.imca.aps.anl.gov/mx/ lavender_at_ic
arus.csrri.iit.edu
2
What is MX?

• MX is a portable beamline control system.
• It includes a pair of servers, mxserver and
  mxupdate, to manage the hardware.
• Both Tcl/Tk GUI applications and command line
  based applications are currently supported.
• Device drivers and core functionality are
  encapsulated in the libMx library.
• LibMx is written in ANSI C to maximize its
  ability to be used from other languages and
  applications.

3
What is MX? (cont.)

• Both servers and clients use the same libMx
  library and can use the same device drivers.
• Client-server operation is not required. This
  simplifies the debugging of device drivers.
• MX has its own TCP/IP protocol, but most of MX is
  independent of the protocol used.
• Clients can use foreign protocols exclusively, or
  a mix of MX and foreign protocols.

4
Current Users of MX
MRCAT, APS Sector 10-ID materials science
IMCA-CAT, APS Sector 17-ID and 17-BM macromolecu
lar crystallography BioCAT, APS Sector
18-ID biophysical science SER-CAT, APS Sector
22-ID and 22-BM macromolecular
crystallography GCPCC Beamline,
CAMD macromolecular crystallography
5
Why I Wrote MX

• Beamline control software packages have tended to
  be environment specific and non-portable.
• Many are centered around a particular interface
  method, e.g. CAMAC or VME.
• EPICS seemed to be a less than ideal choice,
  since it requires a rather high level of
  expertise to setup, maintain, and develop for.
• Users sometimes bring in their own equipment that
  they want to interface to the beamline.

6
MX Control System Goals

• Encapsulate the core functionality in libraries
  like libMx.
• Make client-server functionality available.
• Require that libMx know very little about the
  application programs invoking it.
• Localize the knowledge libMx has of device
  hardware to driver functions with well defined
  interfaces.
• Minimize the effort required to implement new
  device drivers by putting as much functionality
  as is possible into generic code.

7
MX Control System Goals (cont.)

• Emphasize operating system independence.
• Require only ANSI C and BSD sockets or Winsock.
• Be able to interoperate with pre-existing
  beamline control systems.
• Try to minimize built-in assumptions about the
  structure of future data acquisition APIs.
• Do not depend on the presence of software that
  may not be freely distributed.
• Make the source code freely available.

8
MX Platforms

• Linux 2.0 and 2.2 - GCC
• SGI Irix 6.3 and 6.5 - SGI C compiler
• Solaris 2.5 and 2.6 - SPARCompiler C or GCC
• HP/UX 10.20 - HP/UX C compiler
• SunOS 4.1.4 - SPARCompiler C
• MacOS X - GCC
• Windows 95, 98, NT 4 - Visual C 4, 5, or 6
• MSDOS 6.2 - DJGPP 2.0.2 and Watt32

9
MX Internal Architecture

• The fundamental object is the MX record.
• Application programs maintain their set of MX
  records in a doubly linked list called the MX
  database.
• Each motor, scaler, serial port, or other device
  on a beamline is represented as an individual MX
  record.
• MX records are also used to store variables,
  server connections, and even scan parameters.
• Application programs control the beamline by
  invoking the defined functions or methods for
  each device type.

10
MX Records

• MX records are defined by the typedef MX_RECORD
  in the header file libMx/mx_rec.h.
• MX is not fully object oriented since it only has
  a fairly restricted form of inheritance.
• MX record types are organized in a fixed
  hierarchy of superclasses, classes, and types.
• Each MX record type has an associated MX driver
  which implements the methods of this record type.
• Methods are implemented via function tables
  defined in the MX_DRIVER structure.

11
The MX_RECORD Structure
typedef struct mx_record_type long
mx_superclass / MXR_LIST_HEAD, MXR_INTERFACE,
etc. / long mx_class / MXI_CAMAC, MXC_MOTOR,
etc. / long mx_type / MXT_MTR_E500,
MXT_MTR_PANTHER, etc. / char nameMXU_RECORD_NAM
E_LENGTH1 char labelMXU_LABEL_LENGTH1 voi
d acl char acl_descriptionMXU_ACL_DESCRIPTION_
LENGTH1 signed long handle int
precision int resynchronize long
flags struct mx_record_type
list_head struct mx_record_type
previous_record struct mx_record_type
next_record void record_superclass_struct /
Ptr to MX_SCAN, MX_VARIABLE, etc. / void
record_class_struct / Ptr to MX_CAMAC,
MX_MOTOR, etc. / void record_type_struct /
Ptr to MX_DSP6001, MX_E500, etc. / void
record_function_list / Ptr to
MX_RECORD_FUNCTION_LIST / void
superclass_specific_function_list void
class_specific_function_list long
num_record_fields MX_RECORD_FIELD
record_field_array struct mx_record_type
allocated_by long
num_groups struct mx_record_type
group_array long
num_parent_records struct mx_record_type
parent_record_array long
num_child_records struct mx_record_type
child_record_array MX_CLOCK_TICK
event_interval MX_CLOCK_TICK next_event_time v
oid event_queue / Ptr to MXSRV_QUEUED_EVENT
/ void application_ptr MX_RECORD
12
An MX record list
13
MX Device Types
MX Interface Types
Amplifier Analog Input Analog Output Digital
Input Digital Output Encoder Motor Multichannel
Analyzer Multichannel Encoder Multichannel
Scaler Relay Scaler Table Timer
CAMAC Generic GPIB Port I/O RS-232
MX Server Types
TCP/IP
MX Variable Types
Calc EPICS Inline MX
14
MX Scan Types
MX has a selection of scan types optimized for
different kinds of experiments.

• Linear Scan
• Input Scan
• Motor Scan
• Slit Scan
• q-2q Scan

• Quick Scan
• Joerger Quick Scan
• MCS Quick Scan

• XAFS Scan

(multiple energy and k regions)

• List Scan

15
MX Motor Drivers
Am9513-based controller APS undulator
(EPICS) Bruker D8 (prerelease) Compumotor
6000/6K DAC motor Delta Tau PMAC Delta Tau PMAC
(EPICS) DSP E500 EPICS motor record IMS Panther
HI/HE Joerger SMC-24 LakeShore 330 temp.
ctrl. McLennan PM-304
MX network motor National Inst.
ValueMotion Newport MM-3000 Newport
MM-4000/4005 OMS VME-58 (Linux) PI E-662 piezo
controller Pontech STP-100 Radix Databox
motor SCIPE network motor Soft motor Velmex
VP9000 XIA HSC-1 slit controller
16
MX Pseudomotor Drivers
Delta (position difference) Elapsed time Linear
function Monochromator Q 4p sinq/l Sector 18-ID
mono Slit center or width Table pseudomotor -
(x, y, z, roll, pitch, yaw)
q-2q pseudomotor Translation pseudomotor X-ray
energy X-ray wavelength X-ray wavenumber XAFS
wavenumber (k)
17
MX Monochromator Pseudomotor
The MX monochromator pseudomotor couples the
motion of several groups of dependent motors and
devices such that they track changes in the
monochromator angle, q.
Supported dependency types
Monochromator q (of course)
Polynomial function of monochromator q
Polynomial function of monochromator energy
APS undulator energy Fixed exit crystal
separation Fixed exit crystal translation
Diffractometer table height
Diffractometer q
18
ADC Table Pseudomotor
Supports linear x, y, and z translation of the
rotation center.
Supports pure roll, pitch, and yaw motions
about the rotation center.
Uses a small angle approximation for rotations.
19
MX Application Programs
MX currently supports writing application
programs in C and Tcl/Tk. Support is planned
for Python, C, and Labview.
Command line programs
motor - a general data acquisition and
control program for MX. mxget mxput - shell
commands for talking to an MX server.
goniostat - used by MarCCD to control the X-ray
energy.
Tcl/Tk GUI programs
imcagui - a protein crystallography GUI
capable of setting up and
performing MAD experiments. optimize - an
end-user GUI for performing simple optimizations
of the X-ray intensity.
mxgui - a general data acquisition and control
GUI intended for beamline
staff users. mxcontrol - an MX server control
and log display GUI.
20
(No Transcript)
21
Selecting an Absorption Edge
22
(No Transcript)
23
(No Transcript)
24
MXGUI - A Beamline Staff GUI
25
MXGUI - Setting up a motor scan
26
MXGUI - Setting up an XAFS scan
27
MX Network Protocol

• MX is bundled with a network protocol and a pair
  of servers that implement it.
• mxserver - manages hardware and handles
  communication with clients.
• mxupdate - handles automatic save and restore of
  database parameters.
• The protocol is designed to be simple to
  implement and easy to extend.
• Most of MX does not depend on this protocol and
  clients are not required to use it.
• This protocol is included so that MX can be a
  standalone system.

28
MX Network Protocol (cont.)

• MX protocol is an RPC style protocol.
• Asynchronous callback support is planned but is
  not fully implemented yet.
• MX protocol messages have a binary header with an
  ASCII body.
• Uses record field names to identify the object of
  the message. For example, theta.position''.
• Currently 3 types of messages are implemented
  get_array_ascii, put_array_ascii, get_field_type.
  Other types are planned.
• The protocol is intended to have a simple core,
  but be extensible by negotiation at runtime.

29
Future Plans for MX Protocol

• Use numeric handles rather that passing record
  field names.
• Finish implementation of asynchronous callbacks.
• Explore passing data using binary XDR format.
• Add support for automatic resource discovery and
  browsing of servers.
• Improve support for security and add ACLs.

30
MX is Transport Independent

• The driver API does not distinguish between
  remotely and locally controlled devices.
• Applications can switch between drivers and
  protocols just by changing a config file.
• Servers can be clients and clients can be
  servers.
• Clients can simultaneously use several different
  network protocols.

31
APS Sector 17-ID Control System
32
MX Simulated Devices

• The driver API does not distinguish between real
  devices and simulated devices.
• Almost every MX driver type has a simulated
  driver available.
• Very useful for offline development and testing
  of new software.
• Potentially useful for user training.
• Can use simulated devices alongside real devices.

33
MX Programming API
MX has an extensive API. All of it cannot be
shown here, so we show only motor related
functions.
mx_motor_get_position() mx_motor_is_busy() mx_moto
r_positive_limit_hit() mx_motor_negative_limit_hit
() mx_motor_move_absolute() mx_motor_array_move_a
bsolute() mx_wait_for_motor_stop() mx_wait_for_mot
or_array_stop() mx_motor_soft_abort() mx_motor_im
mediate_abort() mx_motor_set_position() mx_motor
_find_home_position() mx_motor_is_at_home_switch()
mx_motor_constant_velocity_move()
mx_motor_get_speed() mx_motor_set_speed() mx_motor
_save_speed() mx_motor_restore_speed() mx_motor_se
t_speed_between_positions() mx_motor_get_accelera
tion_type() mx_motor_get_acceleration_parameters()
mx_motor_set_acceleration_parameters() mx_motor_g
et_acceleration_time() mx_motor_get_acceleration_d
istance() mx_motor_compute_pseudomotor_position_
from_real_position() mx_motor_compute_real_posit
ion_from_ pseudomotor_position() mx_motor_compu
te_extended_scan_range() mx_motor_get_parameter()
mx_motor_set_parameter()
34
Cu K-edge scan in C using MX
include ltstdio.hgt include "mx_rec.h" include
"mx_motor.h" include "mx_scalr.h" include
"mx_timer.h" define DATABASE_FILENAME "example.da
t" int main() MX_RECORD record_list,
energy_motor_record MX_RECORD i_zero_record,
i_trans_record, timer_record double start,
step_size, measurement_time, energy int i,
num_steps, busy long i_zero_value,
i_trans_value mx_setup_database( record_list,
DATABASE_FILENAME ) energy_motor_record
mx_get_record( record_list, "energy"
) i_zero_record mx_get_record(
record_list, "Io" ) i_trans_record
mx_get_record( record_list, "It" ) timer_record
mx_get_record( record_list, "timer1"
) start 8950 step_size 1.0 num_steps
101 measurement_time 1.0 for ( i 0 i lt
num_steps i ) mx_scaler_clear(
i_zero_record ) mx_scaler_clear(
i_trans_record ) energy start step_size
(double) i mx_motor_move_absolute(
energy_motor_record, energy, 0 ) mx_timer_start
( timer_record, measurement_time ) busy
TRUE while ( busy ) mx_msleep(10)
/ Wait for 10 milliseconds / mx_timer_is_busy
( timer_record, busy ) mx_scaler_read(
i_zero_record, i_zero_value ) mx_scaler_read(
i_trans_record, i_trans_value ) printf(
"10.3f 10lu 10lu\n", energy,
i_zero_value, i_trans_value ) exit(0)
35
Cu K-edge scan in Tcl using MX
! /opt/mx/bin/mxtclsh set mxdir "/opt/mx" set
database_filename "example.dat" source file
join mxdir "lib" "mx.tcl" package require
Mx Mxinit set record_list
Mxsetup_database database_filename set
energy_motor_record record_list get_record
"energy" set i_zero_record record_list
get_record "Io" set i_trans_record
record_list get_record "It" set timer_record
record_list get_record "timer1" set
start 8950 set step_size 1.0 set num_steps
101 set measurement_time 1.0 for set i 0 i
lt num_steps incr i i_zero_record
clear i_trans_record clear set energy expr (
start step_size i ) energy_motor_record
move_absolute energy set busy 1 while busy
after 10 set busy energy_motor_record
is_busy timer_record start
measurement_time set busy 1 while busy
after 10 set busy timer_record is_busy
set i_zero_value i_zero_record read
set i_trans_value i_trans_record read
puts format "10.3f 10lu 10lu"
\ energy i_zero_value i_trans_value
36
MX Driver Header File
/ McLennan PM304 motor data structures
/typedef struct MX_RECORD
rs232_record int axis_number int
axis_encoder_number MX_PM304MX_API
mx_status_type mxd_pm304_initialize_type( long
type )MX_API mx_status_type mxd_pm304_create_rec
ord_structures( MX_RECORD record )MX_API
mx_status_type mxd_pm304_finish_record_initializat
ion(MX_RECORD record )MX_API mx_status_type
mxd_pm304_delete_record( MX_RECORD record
)MX_API mx_status_type mxd_pm304_print_motor_str
ucture( FILE file, MX_RECORD record )MX_API
mx_status_type mxd_pm304_read_parms_from_hardware(
MX_RECORD record)MX_API mx_status_type
mxd_pm304_write_parms_to_hardware( MX_RECORD
record )MX_API mx_status_type mxd_pm304_open(
MX_RECORD record )MX_API mx_status_type
mxd_pm304_close( MX_RECORD record )MX_API
mx_status_type mxd_pm304_resynchronize( MX_RECORD
record )MX_API mx_status_type
mxd_pm304_motor_is_busy( MX_MOTOR motor
)MX_API mx_status_type mxd_pm304_move_absolute(
MX_MOTOR motor )MX_API mx_status_type
mxd_pm304_get_position( MX_MOTOR motor )MX_API
mx_status_type mxd_pm304_set_position( MX_MOTOR
motor )MX_API mx_status_type
mxd_pm304_soft_abort( MX_MOTOR motor )MX_API
mx_status_type mxd_pm304_immediate_abort(
MX_MOTOR motor )MX_API mx_status_type
mxd_pm304_positive_limit_hit( MX_MOTOR motor
)MX_API mx_status_type mxd_pm304_negative_limit_
hit( MX_MOTOR motor )MX_API mx_status_type
mxd_pm304_find_home_position( MX_MOTOR motor
)MX_API mx_status_type mxd_pm304_constant_veloci
ty_move( MX_MOTOR motor )MX_API mx_status_type
mxd_pm304_get_parameter( MX_MOTOR motor
)MX_API mx_status_type mxd_pm304_set_parameter(
MX_MOTOR motor )extern MX_RECORD_FUNCTION_LIST
mxd_pm304_record_function_listextern
MX_MOTOR_FUNCTION_LIST mxd_pm304_motor_function_li
st
37
MX Driver Header File (cont.)
/ Define some extra functions for the use of
this driver. /MX_API mx_status_type
mxd_pm304_command( MX_PM304 pm304, char
command, char response, int
response_buffer_length, int debug_flag
)MX_API mx_status_type mxd_pm304_getline(
MX_PM304 pm304, char buffer, int
buffer_length, int debug_flag )MX_API
mx_status_type mxd_pm304_putline( MX_PM304
pm304, char buffer, int debug_flag )MX_API
mx_status_type mxd_pm304_getc( MX_PM304
pm304, char c, int debug_flag )MX_API
mx_status_type mxd_pm304_getc_nowait( MX_PM304
pm304, char c, int debug_flag )MX_API
mx_status_type mxd_pm304_putc( MX_PM304
pm304, char c, int debug_flag )extern long
mxd_pm304_num_record_fieldsextern
MX_RECORD_FIELD_DEFAULTS mxd_pm304_rfield_def_ptr
define MXD_PM304_STANDARD_FIELDS \ -1, -1,
"rs232_record", MXFT_RECORD, NULL, 0, 0,
\ MXF_REC_TYPE_STRUCT, offsetof(MX_PM304,
rs232_record), \ 0, NULL, (MXFF_IN_DESCRIPTION
MXFF_IN_SUMMARY), \ \ -1, -1,
"axis_number", MXFT_INT, NULL, 0, 0,
\ MXF_REC_TYPE_STRUCT, offsetof(MX_PM304,
axis_number), \ 0, NULL, (MXFF_IN_DESCRIPTION
MXFF_IN_SUMMARY), \ \ -1, -1,
"axis_encoder_number", MXFT_INT, NULL, 0, 0,
\ MXF_REC_TYPE_STRUCT, offsetof(MX_PM304,
axis_encoder_number), \ 0, NULL,
(MXFF_IN_DESCRIPTION MXFF_IN_SUMMARY)
38
An Example MX Driver Function
MX_EXPORT mx_status_type mxd_pm304_move_absolute(
MX_MOTOR motor ) const char fname
"mxd_pm304_move_absolute()" MX_PM304
pm304 char command20 char
response20 long motor_steps mx_status_type
status status mxd_pm304_get_pointers( motor,
pm304, fname ) if ( status.code !
MXE_SUCCESS ) return status motor_steps
motor-gtraw_destination.stepper / Format the
move command and send it. / sprintf( command,
"mald", motor_steps ) status
mxd_pm304_command( pm304, command, response,
sizeof response, PM304_DEBUG ) if (
status.code ! MXE_SUCCESS ) return
status / Did we get an "OK" response? / if
( strcmp( response, "OK" ) ! 0 ) return
mx_error( MXE_DEVICE_IO_ERROR, fname, "Did not
get 'OK' response from controller. Instead got
's'", response ) return MX_SUCCESSFUL_RESUL
T
39
Future Plans

• Server-side improvements
• Improve mxserver's ability to cope with broken or
  missing hardware.
• Add callback support to mxserver.
• Performance and concurrency improvements.
• Create servers to export MX services to other
  control systems (EPICS, CORBA, etc.)
• GUI database configuration tool.
• GUI server control tool.

40
Future Plans (cont.)

• Client-side improvements
• Development of more application specific GUIs.
• Export MX APIs to more languages (Python, C,
  Labview, etc.)
• Add client-side part of callback support.
• General improvements
• Port MX to new platforms (QNX, VMS, etc. )
• Collaborate with SER-CAT to develop MX systems
  based on Delta Tau PMAC controllers.
• Add new data file formats such as HDF/NeXus.
• Addition of new drivers.

41
Summary

• MX is now in use at 6 APS beamlines, 1 CAMD
  beamline, and in X-ray labs at IIT.
• Several beamlines at APS, ALS, NSLS, and CLS have
  expressed interest.
• Runs on a variety of hardware platforms.
• Designed to interoperate with other control
  systems and user interfaces.
• We are interested in collaborating with other
  groups on the further development and application
  of MX.

42
Acknowledgements
A. Howard IMCA-CAT, IIT J. Chrzas IMCA-CAT,
IIT L. Keefe IMCA-CAT, IIT C. Segre MRCAT,
IIT B. Bunker MRCAT, Notre Dame N. Leyarovska
MRCAT, IIT H. Tostmann MRCAT, Univ. of
Florida J. Terry MRCAT, IIT J. Kropf MRCAT,
Argonne Natl. Lab. G. Bunker BioCAT, IIT R.
Fischetti BioCAT, IIT J. Fait SER-CAT,
Univ. of Georgia G. Rosenbaum SER-CAT, Univ. of
Georgia J. Quintana DND-CAT, Northwestern E.
Westbrook ALS Beamline 4.2.2, MBC M. White
GCPCC beamline at CAMD, Univ. of Texas
Medical Branch