synApps is a collection of EPICS software intended to support most of the common requirements of an x-ray laboratory or synchrotron-radiation beamline. Because it is EPICS software, synApps is extensible by developers and end users, to support new devices and experimental techniques. This extensibility frees synApps to focus mostly on general-purpose capabilities and infrastructure, from which application-specific software can be built or assembled.
Thus, for example, synApps provides support for motors, scalers, and scans, but it does not tie those items together into an immediately executable scan (of specific motors, to acquire specific scaler channels, for a specific dwell time, etc.). The user does this at run time (or a knowledgeable user can provide a fully specified scan, and give the novice user a button to start it).
Similarly, synApps provides support for ADC's and PID loops, but somebody has to tell the PID software what feedback value to read, what conditioning function to run it through, what PID parameters to use, and what actuator to drive. By default, all of these choices can be made at top level, by the end user. Or, a knowledgeable user can provide a fully specified PID loop, and make it available to a novice user through a simplified or otherwise customized interface. The techniques and tools used to accomplish this are essentially the same as those a user would have applied at run time, so the packaged solution can be prototyped and tested at run time.
synApps is organized into modules, whose structure is based on the example
directory tree produced by the EPICS application,
typically with two additional directories: a documentation directory, and a
display-file directory. synApps modules typically contain source code, EPICS
databases and database-definition files, autosave-request files, client scripts,
display files, libraries and executables, and documentation.
Most synApps modules are intended primarily to export support to other modules. Some synApps modules produce bootable software, in addition to support software, but in most cases, this bootable software is primarily for testing, and for demonstrating how the support software can be used. The support exported by a module is of the following types, with example names and locations from the calc module:
One synApps module, the xxx module, is different: it doesn't export anything. It imports support from other modules, and produces bootable software to support an EPICS IOC. The xxx module is documentation in runnable form, and also a template from which a synApps application can be constructed. xxx is not comprehensive: it doesn't apply all of synApps. It's usually a little behind the rest of synApps, it focusses more on VME crates than on other kinds of IOCs, and it's a compromise between what is most widely used and what is most likely to build and run out of the box.
- database-definition file, in calc/dbd
- link library, in calc/lib/<arch>
- header files, in calc/include
- database files, and associated autosave-request files, in calc/calcApp/Db
- display files, in calc/calcApp/op/adl
If you haven't run into the term 'IOC' yet, two things:
EPICS Application Developer's Guide is an essential reference for anyone planning to develop or deploy EPICS software. While you won't need to read the guide to build or run synApps, you will need it to understand what you've done, to diagnose problems, and to extend synApps in any significant way.
- IOC stands for Input/Output Controller. Initially, this was a VME crate with a processor running EPICS under the VxWorks operating system, but beginning with EPICS 3.14, an EPICS IOC can also be a set of tasks on a workstation running Linux, Windows, Cygwin, Solaris, RTEMS, Mac OS, and, no doubt, other operating systems.
Here's a list of the modules and directories in synApps:
|areaDetector||Support for area (i.e., 2-D, or image) detectors, including CCDs, pixel array detectors, and online imaging plates. This module replaces the ccd and pilatus modules (which are nevertheless included in this version of synApps, though they will no longer be supported).|
|autosave||Support for saving software parameters at run time, and restoring them during the next reboot. Autosave is also a way to initialize array PV's at boot time.|
|busy||The busy record, which allows developers more ways to indicate when an operation is complete. Previously, this record was provided by the sscan module, because the sscan record is one of its beneficiaries.|
|calc||Run-time expression evaluation, derived from the calcout record in EPICS base, and extended to operate on strings, arrays, and to implement coupled expressions.|
|camac||Support for CAMAC hardware.|
|ccd||Scientific CCD detectors, including Bruker, MAR, and Roper. (Superceded by the areaDetector module.)|
|dac128V||Support for an IndustryPack DAC module.|
|delaygen||Support for delay generators, including the SRS DG645, Colby Instruments PDL100A|
|dxp||Support for X-Ray Instrumentation Associates's DXP digital signal processor|
|ebrick||Support and sample application for low-cost PC-104 and uCDIMM based IOC.|
|ip||Support for various serial, and other message-based, devices.|
|ip330||Support for an IndustryPack ADC module|
|ipUnidig||Support for an IndustryPack digital I/O module|
|love||Support for Love controllers|
|mca||Support for multichannel analyzers and multichannel scalers.|
|modbus||Support for ModBus-protocol devices over TCP, serial RTU, and serial ASCII links|
|motor||Support for motors|
|optics||Support for optical tables, monochromators, slits, etc.|
|pilatus||Support for the Dectris pixel-array detector. (Superceded by the areaDetector module.)|
|quadEM||Support for an APS-developed 4-channel electrometer|
|sscan||Support for scans (programmed control and data acquisition).|
|std||Miscellaneous EPICS support, including the epid (extended PID), scaler, sseq (string sequence), and timestamp records; and pvHistory support.|
|stream||Dirk Zimoch's streamDevice, in a module-flavored wrapper.|
|utils||Miscellaneous tools, including support for converting an application from one version of synApps to another; support for the MDA file format, written by the sscan module; and support for EPICS-application prototyping.|
|vac||Support for vacuum controllers|
|vme||Support for VME hardware|
|xxx||Sample user-application directory|
See support/configure/RELEASE for a complete set of compatible module versions. This release of synApps is compatible with EPICS release 3.14.10, Tornado 2.2, and the following EPICS modules/versions, which are produced and maintained by other members of the EPICS collaboration. These modules are not part of synApps, but their maintainers have permitted us to distribute copies along with synApps:
|allenBradley||v2-1||for communicating with Allen Bradley PLC's (ANL)|
|ipac||v2-10||required for IndustryPack support (ANL)|
|asyn||v4-10||required by many modules (ANL)|
|seq||v2-0-12||for SNL programs in synApps (SLAC)|
|stream||v2-4||configurable device support for message-based devices (PSI)|
|vxStats||v1-7-2g||vxWorks statistics, modified by us (SNS)|
Previous versions of synApps included and relied on the genSub module. In EPICS 3.14.10, a replacement for the genSub record, called the asub record, is included in base, and synApps has been modified to use it instead of the genSub record.
For convenience, this distribution includes the module versions listed above, in place and ready to build, with minor modifications to build files. A few of the modules have suffered more substantial modifications to fix problems, add display files, etc.
synApps includes software developed by the Beamline Controls & Data Acquisition and the Accelerator Controls groups of the Advanced Photon Source (APS); by developers in APS Collaborative Access Teams – notably, Mark Rivers (CARS-CAT); and by developers in the EPICS collaboration outside of the APS – notably, those at the Stanford Linear Accelerator Center, the Swiss Light Source/Paul Scherrer Institut, the Diamond Light Source, the National Synchrotron Light Source, the Australian Light Source, and the Canadian Light Source.
Aside from EPICS databases, SNL (State Notation Language) programs, and the like, synApps contains the following code:
|aCalcout||calcout record extended to handle array expressions|
|busy||utility record: calls recGblFwdLink only when its VAL field is zero, allowing CA clients, and asyn drivers to participate in EPICS putNotify (ca_put_callback()) operations.|
|dxp||XIA's DXP digital signal processor Set/read signal-processor parameters|
|epid||Extended version of the PID record, previously in EPICS base. Intended for implementing feedback loops|
|mca||support for multichannel analyzers, and some other array-valued detectors|
|motor||stepper and servo motors, "soft" motor|
|sCalcout||calcout record extended to handle string expressions, links, and values.|
|sscan||Replaces the scan record (Ned Arnold/APS) previously in EPICS base. This version uses a modified version of recDynLlib that supports dbNotify command completion. It uses ca_put_callback to do puts, instead of ca_put.|
|scanparm||scan parameters for use with the scan record|
|sseq||string-sequence record. This is a modified version of the seq record in base. This version can link to/from either string or numeric PVs, and it can use dbCaPutLinkCallback to wait for completion of the execution started by one link before going on to the next.|
|swait||replaces the wait record previously in EPICS base. This version uses a modified version of recDynLlib that supports dbNotify command completion. It uses ca_put_callback to do puts, instead of ca_put.|
|table||6-degree-of-freedom optical table|
|transform||like an array of calc records, with output links|
|vme||generic vme record (Mark Rivers/APS/CARS-CAT)|
|timestamp||(written by Stephanie Allison/SLAC) Needed by the vxStats module, but apparently not available in a published module.|
|ai||CONSTANT||devAiTodSeconds||Sec Past Epoch|
|ai||GPIB_IO||devAiGP307Gpib||Vg307 GPIB Instrument|
|ai||INST_IO||devAiAb1791||Allen Bradley 1791|
|ai||INST_IO||devAiClusts||VX stats clusts|
|ai||INST_IO||devAiHeidND261||asyn ai HeidND261|
|ai||INST_IO||devAiMKS||HPS SensaVac 937|
|ai||INST_IO||devAiStrParm||asyn ai stringParm|
|ai||VME_IO||devAiA32Vme||Generic A32 VME|
|ai||VME_IO||devAiBunchClkGen||APS Bunch Clock|
|ai||VME_IO||devAiVaroc||ESRF Varoc SSI Encoder Iface|
|ai||VME_IO||devIK320GroupAi||Heidenhain IK320 Group|
|ao||INST_IO||devAoAb1791||Allen Bradley 1791|
|ao||INST_IO||devAoEurotherm||asyn ao Eurotherm|
|ao||INST_IO||devAoStrParm||asyn ao stringParm|
|ao||VME_IO||devAoA32Vme||Generic A32 VME|
|ao||VME_IO||devAoBunchClkGen||APS Bunch Clock|
|bi||AB_IO||devBiAb16||AB-16 bit BI|
|bi||AB_IO||devBiAb32||AB-32 bit BI|
|bi||GPIB_IO||devBiGP307Gpib||Vg307 GPIB Instrument|
|bi||INST_IO||devBiStrParm||asyn bi stringParm|
|bi||VME_IO||devBiA32Vme||Generic A32 VME|
|bi||VME_IO||devBiBunchClkGen||APS Bunch Clock|
|bo||AB_IO||devBoAb16||AB-16 bit BO|
|bo||AB_IO||devBoAb32||AB-32 bit BO|
|bo||GPIB_IO||devBoGP307Gpib||Vg307 GPIB Instrument|
|bo||INST_IO||devBoStrParm||asyn bo stringParm|
|bo||VME_IO||devBoA32Vme||Generic A32 VME|
|bo||VME_IO||devBoBunchClkGen||APS Bunch Clock|
|longin||INST_IO||devLiStrParm||asyn li stringParm|
|longin||VME_IO||devLiA32Vme||Generic A32 VME|
|longout||INST_IO||devLoStrParm||asyn lo stringParm|
|longout||VME_IO||devLoA32Vme||Generic A32 VME|
|mbbi||AB_IO||devMbbiAb16||AB-16 bit BI|
|mbbi||AB_IO||devMbbiAb32||AB-32 bit BI|
|mbbi||VME_IO||devMbbiA32Vme||Generic A32 VME|
|mbbiDirect||AB_IO||devMbbiDirectAb16||AB-16 bit BI|
|mbbiDirect||AB_IO||devMbbiDirectAb32||AB-32 bit BI|
|mbbo||AB_IO||devMbboAb16||AB-16 bit BO|
|mbbo||AB_IO||devMbboAb32||AB-32 bit BO|
|mbbo||VME_IO||devIK320Dir||Heidenhain IK320 Sign|
|mbbo||VME_IO||devIK320Funct||Heidenhain IK320 Command|
|mbbo||VME_IO||devIK320ModeX3||Heidenhain IK320 X3 Mode|
|mbbo||VME_IO||devMbboA32Vme||Generic A32 VME|
|mbboDirect||AB_IO||devMbboDirectAb16||AB-16 bit BO|
|mbboDirect||AB_IO||devMbboDirectAb32||AB-32 bit BO|
|mca||VME_IO||devSTR7201||Struck STR7201 MCS|
|scaler||VME_IO||devScalerSTR7201||Struck STR7201 Scaler|
|stringin||CONSTANT||devSiTodString||Time of Day|
|stringin||GPIB_IO||devSiGP307Gpib||Vg307 GPIB Instrument|
|stringin||INST_IO||devSiStrParm||asyn si stringParm|
|stringout||INST_IO||devSoEurotherm||asyn so Eurotherm|
|stringout||INST_IO||devSoStrParm||asyn so stringParm|
|stringout||VME_IO||devIK320Parm||Heidenhain IK320 Parameter|
|waveform||VME_IO||devWfBunchClkGen||APS Bunch Clock|
In addition to this top-level documentation, synApps modules have their own documentation directories, and the xxx module contains examples of how much of the software is imported, loaded, and run. Some modules have their own example iocBoot directories.
The synApps support/utils directory contains a variety of scripts, programs, etc., that some have found useful.
Although synApps is distributed as a single 'support' directory, it's normally deployed as a two-part system: a 'support' directory, and one or more 'user' directories. The support directory can be installed on a read-only file system, along with EPICS base and other modules, and used from there by user directories, each of which typically begins as a copy (or a collection of copies) of the xxx module, and is customized/extended to suit a particular application and set of hardware.
I'm not being very precise about what is meant by a user directory, because there are a number of reasonable variations. At the simplest, a single copy of the xxx module, which supports a single IOC, is a user directory. If several IOC's cooperate to serve a single application (such as a synchrotron beamline), one might make several independent copies of xxx, or one might extend a single xxx copy to contain multiple xxxApp directories, and multiple iocBoot/iocxxx directories. At APS, we have several top-level user directories, each of which contains a number of copies of xxx, most of which, in turn, contain multiple xxxApp and iocBoot/iocxxx directories.
Here's what a complete installation might look like (much detail omitted) with all the files you will have to edit before you can build or boot an IOC:
synApps_5_4/support/ Makefile <— EDIT to build Makefile.win32-x86 <— EDIT to build for win32-x86 all_adl/ allenBradley/ areaDetector/ asyn/ busy/ calc/ camac/ ccd/ configure/ CONFIG_SITE <— EDIT to build RELEASE <— EDIT to build RELEASE.win32-x86 <— EDIT to build for win32-x86 ... dac128V/ delaygen/ documentation/ dxp/ ebrick/ ip/ ip330/ ipUnidig/ ipac/ drvIpac/drvIpac.dbd <— EDIT to build love/ mca/ modbus/ motor/ motorApp/ Makefile <— EDIT to build optics/ pilatus/ quadEM/ seq/ sscan/ std/ stream/ utils/ vac/ vme/ vxStats/ xxx/
synApps_5_4/ioc/ 1bm/ Makefile bin/ configure/ RELEASE <— EDIT to build RELEASE.win32-x86 <— EDIT to build for win32-x86 dbd/ iocBoot/ Makefile nfsCommands ioc1bma/ Makefile camac.cmd canberra_1.cmd canberra_13.cmd canberra_3.cmd dac128V.cmd dxp_16.cmd industryPack.cmd ip330.cmd ipUnidig.cmd quadEM.cmd save_restore.cmd serial.cmd vme.cmd st.cmd basic_motor.substitutions canberra_13.substitutions canberra_3.substitutions dac128V.substitutions dxp_16.substitutions ip330Scan.substitutions ipUnidig.substitutions motor.substitutions picMot.substitutions pid_fast.substitutions pid_slow.substitutions quadEM_pid.substitutions scanParms.substitutions vxStats.substitutions auto_positions.req auto_settings.req autosave/ cdCommands or envPaths saveData.req ioc1bmb/ ioc1bmc/ ioc1bmd/ <much like ioc1bma> release.pl setup_epics_common start_epics_1bma start_epics_1bmb start_epics_1bmc start_epics_1bmd 1bmaApp/ 1bmbApp/ 1bmcApp/ 1bmdApp/ 1id/ 2bm/ 2id/ ... <much like 1bm>
As shown above, the following files can or must be edited to modify the way
the synApps support directory is built. After modifying files in the support,
or support/configure directories, you should run
make rebuild, in the support directory.
- comment out any modules you don't want to build
- edit the definitions of
SUPPORTwith the correct paths to these directories on your system.
- Edit to set the following variables, which control what will be built: The supported values for these variables are
- This controls the build of the dxp module. If usb is not installed for developers, then parts of dxp/dxpApp/handelSrc will not be built, and the example application executable, dxpApp, will not be built, so dxp/iocBoot cannot be used.
- This controls the build of the mca module, specifically, support for the Canberra AIM hardware.
- This controls the build of the areaDetector module, and is understood to indicate whether libtiff.a, libjpeg.a, and libz.a are all installed. If they are not installed, areaDetector will not build, and xxx will not try to use areaDetector.
registrar()commands for IndustryPack carriers you plan to use.
- comment or uncomment to select the motor support you want to build.
The following files must be edited before building a user directory:
- edit the definition of
SUPPORTwith the correct path to the support directory
The association between a user directory, and the support directory on which it depends, is made entirely by the file, configure/RELEASE, in the user directory. Typically, this file simply includes the configure/RELEASE file from the support directory, but it may differ: it may specify EPICS modules not included in synApps, for example. Or, if the support directory contains more than one built version of a module (the original and a bug fix, for example) the user directory can choose which version it will use.
Note, however, that the modules in synApps are interdependent. Many of the modules depend on the asyn module, for example, and there are many other dependencies, both direct and implied. (If module a depends on module b, and module b depends on module c, then a also depends on c, and it must specify the same version of c that b specifies.) The complete set of modules selected by a user directory must be self consistent, and the EPICS build will ensure this, unless you tell it not to.
Before building synApps, you should ensure that your system has the libraries, header files, etc. required to build the modules you want to build. Here's a list of the operating-system dependencies we've documented so far.
Please help: new users are particularly well placed to help us complete this list. Long-time developers typically have lots of things correctly configured that they don't even remember configuring.
Cygwin is configured from a menu of choices organized by function. You will need the following components from the following menu headings:
If you have a built copy of EPICS base 3.14.10 or later, then building the synApps support directory should be very simple:
EPICS_HOST_ARCHto the architecture (and compiler, if there is a choice) on which you are building. synApps is tested with the architectures
make'. (You should be able to use '
make -j' to build synApps much more quickly than it has previously built.)
You should use the same GNU Make executable that was used to build EPICS
base. You may need
$(EPICS_BASE)/bin/<arch> in your path,
and you may need
When executed in the support directory, '
make release' will go to
all of the modules support/Makefile knows about and edit the configure/RELEASE
files in those modules so that they all build from the same versions of EPICS
base and other known modules.
Typically, the build will not succeed the first time, because you will not have all of the required system support. If you find that you cannot build some synApps module, you should comment it out of both support/Makefile, and support/configure/RELEASE*.
Once synApps' support directory has built without errors, the xxx module will have been configured (xxx/configure/RELEASE will have correct, absolute paths to base and support) and built, so you can use it as an example – or, better, a template – for constructing user directories to support your IOCs. To make a template of xxx, clean and uninstall it, and tar a copy of the directory. To use the template, untar it, cd to its top-level directory and run utils/changePrefix to change the PV-name prefix from xxx to whatever you want. (Note you must have support/utils in your command path, or you could copy utils/changePrefix and utils/doSed to a directory that is in your command path. Note that changePrefix is synApps-version specific.)
Here's what I do:
# Do once when synApps is built: cd $(SYNAPPS)/support/xxx setenv EPICS_HOST_ARCH <host architecture> gnumake clean uninstall (repeat as needed for any other architectures) tar cvf ../xxx.tar * # Do whenever a new user directory ('1bm', in this example) is needed: cd $(SYNAPPS)/ioc mkdir 1bm cd 1bm tar xf $(SYNAPPS)/support/xxx.tar changePrefix xxx 1bma mv iocBoot/iocvxWorks iocBoot/ioc1bma edit iocBoot/ioc1bma/Makefile to specify the IOC processor type gnumake
To put a second application, 1bmb, into 1bm, I run the following commands:
cd $(SYNAPPS)/ioc mkdir temp cd temp tar xf $(SYNAPPS)/support/xxx.tar changePrefix xxx 1bmb mv iocBoot/iocvxWorks iocBoot/ioc1bmb edit iocBoot/ioc1bmb/Makefile to specify the ioc processor type cd $(SYNAPPS)/ioc mv temp/1bmbApp/start_epics_1bmb 1bm mv temp/1bmbApp 1bm mv temp/iocBoot/ioc1bmb 1bm/iocBoot rm -rf temp cd 1bm gnumake
Edit the files above to agree with your hardware, to load the databases you want, etc., set up the IOC processor's parameters to load from the software just configured, and boot the crate. If you don't know how to do this, read on.
$(EPICS_BASE)/bin/<arch>/caRepeater gets run
workstation boots. If you have no way of doing this, you can run it manually
or put the command in your .login file.
Setup your host system to work with the EPICS processor. See the VxWorks Programmer's Guide if you have a copy. Here's what we do (on a Sun workstation):
(On some workstations we must type "
This gets the xterm communicating with the crate processor.
boot device : dc processor number : 0 host name : <server> file name : /usr/local/vxWorks/T222/mv2700-asd1 inet on ethernet (e) : xxx.xxx.xxx.xxx:fffffe00 inet on backplane (b): host inet (h) : xxx.xxx.xxx.xxx gateway inet (g) : user (u) : <vx_username> ftp password (pw) (blank = use rsh): <vx_password> flags (f) : 0x0 target name (tn) : iocxxx startup script (s) : /home/server/USER/epics/xxx/iocBoot/iocxxx/st.cmd other (o) :
support/xxx/iocBoot/ioc*/bootParms for other processor
types. If your VME processor has mount access to an 'APSshare' NFS file
server, you can specify the 'file name', above, as
synApps includes hundreds of display files intended for use with the EPICS display manager, MEDM. Other EPICS display managers exist, and I once did a mass automated translation of MEDM display files to the EDL display manager's file format, using software developed by others. This translation was only partially satisfactory, but we don't have the resources to do the job better or more generically. In this documentation, I'll limit attention to MEDM display files.
This happens in the user directory. Generally, you must tell "EPICS" what hardware is in your crate, and what addresses, interrupt vectors, etc. you have set your hardware to use. (See support/xxx/documentation/vme_address.html for a list of suggested values.) You also must specify which motors any slit, table, monochromator, etc., control software is to use. If you use serial or GPIB, you must match port names to hardware devices, set serial-port parameters, and specify GPIB addresses. For any IndustryPack modules, you must specify the IP carrier and slot into which you've loaded those modules.
In a complete job of fitting synApps to an IOC's hardware, all of the following files will be touched:
This is the file run by the IOC at boot time. It loads an executable built in
the IOC directory (e.g.,
xxx.munch), sets parameters to configure that
software, makes calls to that software to configure it for a particular set of
hardware, and loads databases from synApps modules. Mostly, it sources other
.cmd files that do these same things.
This file, and the files it sources, are probably worth studying. They are
reasonably well commented, and contain
dbLoadRecords() commands for most of
the EPICS databases in synApps.
To load more motors, add lines to the file
xxx/iocBoot/ioc*/motor.substitutions. For motors controlled by a
VME board, edit
vme.cmd to specify the hardware address, etc. For
motors controlled through a serial connection, edit
If you want the new motors to work with the 'AllStop' button
– see the top-level MEDM display
xxx.adl), load the database
$(MOTOR)/db/motorUtil.db, and run the command
If you want the IOC automatically to save positions and settings of the new
motors, and restore them when the crate reboots, add lines to the files
To use a pair of motors to control a slit, search for
xxx/iocBoot/ioc*/st.cmd, and edit the
dbLoadRecords() command you'll find there. The example in
st.cmd loads two copies of
2slit.db intended for use
as the horizontal and vertical members of a four-jaw slit. The MEDM displays
4slit*.adl are involved in these
The slit database makes the following assumptions about the two motors attached to the individual slit leaves:
2slit.db database allows users to move either the slit
virtual motors or the actual motors, and it keeps all the readback values
current regardless of how the actual motors got moved or recalibrated. But it
does not automatically reset the slit *drive* values when the actual motors are
used. This must be done manually, using the "SYNC" button on the
2slit.adl display. Pressing this button causes the database to
read the actual motor drive values and set the slit-drive values accordingly.
To recalibrate slit positions, press the "Set" button, type in the current slit position as you want it to be called, and press the "Use" button. This procedure uses the "Set" buttons of both motors the slit software talks to, and the user/dial offsets of those motors actually implement the recalibration.
There is a new, experimental slit database in synApps which uses soft motor records as the user/client interface. This allows clients that know how to control a motor also to control a slit, with some limitations. We hope to use soft motor records in front of other positioners (e.g. monochromators, optical tables, insertion devices, and DAC channels) in the future.
Optical tables are controlled by a custom EPICS record (the "table" record),
used in the database
table.db and controlled via MEDM displays
Table virtual motors behave in much the same way as do slit virtual motors. However, the table software does not use user/dial offsets in the underlying motor to implement recalibration (it can't, since it works through a nonlinear transform). Instead, the table maintains its own offsets for all of the six coordinated motions it implements. Pressing the "Set" button causes new table positions to modify the offsets instead of moving the table (which is exactly the way motor and slit calibration works). In addition to a "Sync" button, which reads motor positions and calculates the table positions from them, the table display has an "Init" button, which zeros all offsets before doing a "sync" operation. It also has a "Zero" button, which manipulates all the table offsets to make the current table positions zero without moving or recalibrating any motors.
Several varieties of crystal monochromators are supported in synApps: two
constant-offset "channel-cut" monochromators, a high-resolution double-crystal
monochromator, and a spherical-grating monochromator. Most are supported by
databases paired with State Notation Language (SNL) programs, and several MEDM
displays. The EPICS databases
kohzuSeq.db, SNL program
kohzuCtl.st, and MEDM displays
kohzu*.gif) are involved in control of two varieties of
high-heat-load monochromators. The EPICS database
hrCtl.st, and MEDM displays
involved in control of the high-resolution double-crystal monochromator. The
spherical grating monochromator is supported by the database
and the displays
The APS standard user filters combine several motors and solenoids to control
the placement of filter material in the beam path. The databases
filterLock.db, and the MEDM displays
involved in this application.
Impromptu coordinated motions and other bits of run-time programming are handled by what we call a "userCalc" (actually just a swait record with a nice MEDM interface) or a "userTransform" (actually just a transform record with a nice MEDM interface). We normally load sets of these and other records into each EPICS processor, specifically for end-user programming. Users type in expressions to be evaluated, and link inputs and outputs, as needed, to glue existing objects together to do what they want done at the moment. Here are some examples of the tasks that have been accomplished with userCalcs and userTransforms:
Run-time programming involving strings and/or numbers can be done with userStringCalcs, which resemble userCalcs closely, but differ in significant details. A package containing two stringCalcs and an 'asyn' record (called a "deviceCmdReply") is also available for run-time programming of simple support for serial and other message-based devices.
Run-time programming involving arrays and/or numbers can be done with userArrayCalcs, which resemble userCalcs closely, but differ in significant details.
Scans of up to five dimensions are supported by the
standardScans.db database. Scan data is written to disk by the
saveData program, whose user interface is contained in
saveData.db. The number of data points per scan dimension is
standardScans.db is loaded, and is limited to 2000,
unless the environment variable
Note that loading
saveData.db does not automatically cause scan data to be
written to disk. You must also call the function
saveData_Init(), specifying a
scan-configuration file (
saveData.req) which tells saveData which sscan records
Also note that initializing saveData is an all-or-nothing choice. If you
initialize saveData, then all scans performed by sscan records named in
the configuration file will be written to disk. If saveData cannot write a
file, it will prevent the next scan from completing. (Scans performed by sscan
records that are not named in
saveData.req are completely outside of this
restriction. The data they accumulate is not written to disk by saveData, so
saveData is not involved in their operation.)
Run-time programming of sequences is possible using the sseq record and related
Up to four measurement steps involving positioners, detectors, and end
calculations (e.g., to support dichroism experiments) can be done with the
4step.db database and the related MEDM display,
4step.adl. The entire
measurement sequence can be involved in a scan by treating the 4step database
as you would treat the scaler or mca software.
xxx/iocBoot/ioc*/bootParms for sample boot parameters.
See the MEDM Operator's Manual for detailed information on the special needs of this X11/Motif program. I'll assume those needs have been met.
Edit the file
xxx/start_epics_xxx to so it sets the environment
EPICS_APP to the directory that contains
xxxApp. If you plan to run MEDM on a
workstation that isn't on the same subnet as the IOC's, you'll need to
uncomment and edit the definition of the environment variable
EPICS_CA_ADDR_LIST. In principle, you should be able to name only the
broadcast address for the subnet that contains the IOC's, but if this doesn't
work, you can put in the IP addresses of all the IOC's you want to connect
with, separated by spaces, as follows:
setenv EPICS_CA_ADDR_LIST "188.8.131.52 184.108.40.206"
If you want to use arrays larger than 16000 bytes (e.g., MCA spectra of more
than 4000 channels, or scans of more than 2000 data points), you must set the
EPICS_CA_MAX_ARRAY_BYTES, in *both* the IOC and
workstation, to the size of the largest array you plan to send over the
network, plus the size of the extra data channel access might be asked to
include with the array. On a Unix system, for example, you might say
setenv EPICS_CA_MAX_ARRAY_BYTES 64008in the IOC's st.cmd file, you'd say
putenv "EPICS_CA_MAX_ARRAY_BYTES=64008"This will permit scans of up to 8000 points (8000 doubles * 8 bytes per double + 8 bytes for channel-access overhead), and mca spectra of up to 16000 channels.
To bring up the top-level MEDM display for synApps software, cd to xxx and type "start_epics_xxx" (e.g., start_epics_1bma). This script locates the directories that might have MEDM-display files and includes them in the environment variable EPICS_DISPLAY_PATH, cd's to xxxApp/op/adl, and runs MEDM with the default top-level display file.
You must give the crate write permission to xxx/iocBoot/ioc*/autosave so it can
write the files auto_positions.sav and auto_settings.sav there. It's also
helpful to set the autosave directory's 'group' bit so that files the crate
writes will be owned by the owner of the directory instead of by
To modify the list of PV's that are saved and restored, edit the files
The autosave software is started by the lines
" saveData is a CA client that monitors sscan records and saves scan data to
disk. On vxWorks, this is an NFS-mounted disk; on other operating systems, it's
whatever file system the system provides for the standard C library. The
saveData software is configured with the file xxx/iocBoot/ioc*/saveData.req,
which needs no special attention unless you want to modify the list of EPICS
PV's whose values are to be saved with every data file. To do this, look for
the string "[extraPV]" in the file, and edit the list of PV's immediately
following that string. If an entry in this list contains only the PV name,
saveData will describe the PV, in the data file, using the .DESC field of the
record that contains that PV. If a string follows the PV name, saveData will
use the string instead.
chmod a+w,g+s autosave
create_monitor_set(..." in xxx/iocBoot/ioc*/st.cmd. The restore
happens during iocInit as a result of function calls inserted into initHooks.o,
which is included in the library provided by the autosave module, and
linked into the executable loaded by xxx/iocBoot/ioc*/st.cmd.
To modify the list of PV's that are saved and restored, edit the files xxx/iocBoot/ioc*/auto_settings.req and xxx/iocBoot/ioc*/auto_positions.req
The autosave software is started by the lines
saveData is a CA client that monitors sscan records and saves scan data to disk. On vxWorks, this is an NFS-mounted disk; on other operating systems, it's whatever file system the system provides for the standard C library. The saveData software is configured with the file xxx/iocBoot/ioc*/saveData.req, which needs no special attention unless you want to modify the list of EPICS PV's whose values are to be saved with every data file. To do this, look for the string "[extraPV]" in the file, and edit the list of PV's immediately following that string. If an entry in this list contains only the PV name, saveData will describe the PV, in the data file, using the .DESC field of the record that contains that PV. If a string follows the PV name, saveData will use the string instead.
Like all EPICS software, synApps can be extended in many ways, and at many levels, by EPICS developers and users. (That's how the package came to exist in the first place. It started as a single App directory, and folks just added stuff.) But synApps pushes the idea a little bit further toward end users who are not developers. One of the driving notions behind the development of synApps was to put as much of EPICS' flexibility and power as seems both wise and practical, into the hands of end users – typically, scientists running experiments – whose backgrounds in software development and implementation vary over a wide range.
Here is a list of techniques by which synApps has already been extended by users and developers, arranged very roughly according to the amounts of effort, skill, and EPICS knowledge required.
This is certainly too simple to be considered an extension – all you do
is type something like "
(A-B)/I" – but it's still pretty
useful, and it demonstrates a technique that will be used for much more
The first extension that many users attempt is the programming of a scan. This might also seem more like mere use than extension, but it can become a very highly evolved skill, and it is software development in a reasonably literal sense. If you buy into the notion that an EPICS database is essentially a program (in a very high-level programming language), then scan configuration can be viewed as the simpler end of a continuum.
synApps encourages run-time programming of a number of EPICS record types, by providing the following kinds of support:
The word "userCalc" has become generic for the records and database fragments with which run-time programming is done, and most of the records so used are, in fact, calculation records whose expressions can be modified by users. But synApps also contains records and databases intended for run-time programming of other kinds:
userStringSeqs10.db, userStringSeqs10_settings.req, userStringSeq*.adl
*pid_control.db, *pid_control_settings.req, pid*.adl
ramp_tweak.db, ramp_tweak_settings.req, ramp_tweak*.adl
deviceCmdReply.db, deviceCmdReply_settings.req, deviceCmdReply*.adl
4step.db, auto_4step_settings.req, 4step.adl
In addition to "userCalcs", many synApps records and databases contain sections intended primarily for run-time programming by end users. Examples include end-of-acquisition calculations for scalers and digital multimeters; region-of-interest summing, and background-subtraction for mca records.
End users know better than anybody what they want in a graphical user interface. One thing they've demonstrated that they want, is the ability to have some control over the user interface without having to specify every little detail to a programmer. MEDM provides end users with the ability easily to create custom displays, and synApps provides over 600 stock user-interface fragments that can be called up from, or included as part of, a user crafted display.
An EPICS IOC is populated and configured by ASCII command files, which knowledgeable end users can edit to add motors, change default baud rates, load additional copies of databases, etc.
Many synApps end users have written scripts, in languages such as the unix shell, Python, SPEC macro, IDL, tcl, perl, and Labview, to simplify and/or standardize beamline operations. Any language can be used for this purpose, if it can be fitted with a Channel-Access interface.
One very easy step from run-time programming to EPICS-database development can be taken by using the wxPython program, snapDb.py, (in the utils directory) to "freeze" a collection of programmed userCalcs into an independently loadable database. snapDb can also generate a first cut at a user interface for the database.
But most EPICS database development is done with a database-configuration tool, such as VDCT, or a text editor. In any case, EPICS-database development typically involves the selection of device support, the specification of links and link attributes, and the setting of parameters. More sophisticated development also involves the programming of an initialization strategy into the database, and maybe the writing of an autosave-request file, for it.
This is probably the simplest way to add custom C code to an EPICS application. SynApps contains several examples of this type of code, among them are arrayTest.c, interp.c, and subAve.c, all in the directory support/calc/calcApp/src.
This is probably the next easiest, and next most capable, way of adding compiled code to an application. SNL also introduces (to this list) the notion of client-side program development, for an SNL program is a Channel Access client, even though it runs on an IOC. Again, synApps has a bunch of examples, which you can find by searching for ".st" files.
Documentation for SNL can be found in the seq module, a copy of which is bundled with synApps (though seq is not part of synApps).
If synApps doesn't contain device support for the device you want to use, you can probably find (in synApps or elsewhere) a device-support example that has, at least, the structure of the sort of support you will need.
Nobody writes device support from scratch; it's just not an effective way to develop. Everybody tries to find the closest approximation to what they need, and modifies it until it serves their purpose. One important use of the EPICS tech-talk email list is to gather suggestions, from folks further up the learning curve, on what might be a good piece of code to modify for a particular purpose.
This requires a lot of skill, effort, and information. Developers at this level need the EPICS Application Developer's Guide, the Channel Access Reference Manual, and very capable cross-platform GUI infrastructure.
This also requires a lot of skill, effort, and information. Developers at this level need the EPICS Application Developer's Guide, and the EPICS Record Reference Manual. One of the very best features of EPICS is the fact that experts in module development can collaborate with experts in client-side development, even if the developers are unaware of each other.
All of the extension strategies described above produce (or, at least can produce) results which are fully integrated into the control system. This means that they can be used in further extensions by the same techniques. Thus, motors ganged together by a transform record can be scanned, driven by a PID loop, or controlled by another userCalc.
The synApps support/utils directory contains a variety of executables that may be useful in administering and/or using synApps. Some of these tools are probably peculiar to the way synApps is used at APS.
- changePrefix, doSed
- These are for the application developer's convenience in changing EPICS prefixes in a user directory. You must be in the top level of the user directory to run changePrefix, and you should do a "gnumake clean uninstall" before running it.
Example of use:cd $(SYNAPPS)/ioc/1bm changePrefix xxx 1bma
- Look through synApps for .adl files, and copy them all to a specified directory
Example of use:copyAdl $SYNAPPS/support adl_files
- This file, and its associates, are intended to help convert an IOC directory from one version of EPICS to another, by collecting data from an existing IOC directory, and attempting to correctly edit files in a new IOC directory. See support/utils/HowToUse_convertIocFiles.txt for more information on this program.
- This tar file contains utility programs for using data files written by the sscan module's "saveData" program. These programs were written by Dohn Arms, and contributed to synApps.
- This wxPython program displays the content of MDA files, and directories of MDA files. (An MDA file is the scan-data file produced by the synApps sscan module's saveData software during a scan.)
- A collection of python programs that read, write, modify, and translate MDA files.
- A wxPython rapid development tool for EPICS databases and MEDM display files. This program supports the use of EPICS' run-time programmability to prototype EPICS databases, using records loaded into an IOC. It's particularly useful with synApps "userCalcs", a collection of various record types intended for end users to program at run time.