synApps 5.4

Introduction

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, makeBaseApp.pl, 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:

database-definition file, in calc/dbd
calcSupport.dbd
...

link library, in calc/lib/<arch>
libcalc

header files, in calc/include
transformRecord.h
...

database files, and associated autosave-request files, in calc/calcApp/Db
userTransforms10.db
userTransforms10_settings.req
...

display files, in calc/calcApp/op/adl
userTransforms10.adl
...
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.
If you haven't run into the term 'IOC' yet, two things:
  1. 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.
  2. The 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.

Contents

Here's a list of the modules and directories in synApps:

Module/directorydescription
areaDetectorSupport 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).
autosaveSupport 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.
busyThe 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.
calcRun-time expression evaluation, derived from the calcout record in EPICS base, and extended to operate on strings, arrays, and to implement coupled expressions.
camacSupport for CAMAC hardware.
ccdScientific CCD detectors, including Bruker, MAR, and Roper. (Superceded by the areaDetector module.)
configureBuild files
dac128VSupport for an IndustryPack DAC module.
delaygenSupport for delay generators, including the SRS DG645, Colby Instruments PDL100A
dxpSupport for X-Ray Instrumentation Associates's DXP digital signal processor
ebrickSupport and sample application for low-cost PC-104 and uCDIMM based IOC.
ipSupport for various serial, and other message-based, devices.
ip330Support for an IndustryPack ADC module
ipUnidigSupport for an IndustryPack digital I/O module
loveSupport for Love controllers
mcaSupport for multichannel analyzers and multichannel scalers.
modbusSupport for ModBus-protocol devices over TCP, serial RTU, and serial ASCII links
motorSupport for motors
opticsSupport for optical tables, monochromators, slits, etc.
pilatusSupport for the Dectris pixel-array detector. (Superceded by the areaDetector module.)
quadEMSupport for an APS-developed 4-channel electrometer
sscanSupport for scans (programmed control and data acquisition).
stdMiscellaneous EPICS support, including the epid (extended PID), scaler, sseq (string sequence), and timestamp records; and pvHistory support.
streamDirk Zimoch's streamDevice, in a module-flavored wrapper.
utilsMiscellaneous 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.
vacSupport for vacuum controllers
vmeSupport for VME hardware
xxxSample 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:

Moduleversiondescription
allenBradleyv2-1for communicating with Allen Bradley PLC's (ANL)
ipacv2-10required for IndustryPack support (ANL)
asynv4-10required by many modules (ANL)
seqv2-0-12for SNL programs in synApps (SLAC)
streamv2-4configurable device support for message-based devices (PSI)
vxStatsv1-7-2gvxWorks 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:

How to deploy synApps

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:

The support directory

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/

The user-directory tree

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 release, and make rebuild, in the support directory.

support/Makefile
comment out any modules you don't want to build

support/configure/RELEASE
edit the definitions of EPICS_BASE and SUPPORT with the correct paths to these directories on your system.

support/configure/CONFIG_SITE
Edit to set the following variables, which control what will be built: The supported values for these variables are YES and NO.
LINUX_USB_INSTALLED
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.
LINUX_NET_INSTALLED
This controls the build of the mca module, specifically, support for the Canberra AIM hardware.
LINUX_TIFF_INSTALLED
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.
ipac/<version>/drvIpac/drvIpac.dbd
uncomment registrar() commands for IndustryPack carriers you plan to use.

motor/<version>/motorApp/Makefile
comment or uncomment to select the motor support you want to build.

The following files must be edited before building a user directory:

ioc/<appname>/configure/RELEASE
ioc/<appname>/configure/RELEASE.win32-x86 (win32-x86 only)
edit the definition of SUPPORT with 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.

How to build synApps

  1. System configuration

    2. 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.

  2. Building and configuring the support directory

    3. If you have a built copy of EPICS base 3.14.10 or later, then building the synApps support directory should be very simple:

    1. Edit support/Makefile, support/configure/RELEASE, and support/configure/CONFIG_SITE, as noted above.
    2. Edit ipac/<version>/drvIpac/drvIpac.dbd, and motor/<version>/motorApp/Makefile, as noted above.
    3. Set the environment variable EPICS_HOST_ARCH to the architecture (and compiler, if there is a choice) on which you are building. synApps is tested with the architectures solaris-sparc, linux-x86, cygwin-x86, and win32-x86.
    4. In support, run 'make release'.
    5. In support, run '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 $(EPICS_BASE)/lib/<arch> in LD_LIBRARY_PATH.

    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*.

  3. Building and configuring a user directory

    4. 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.

How to make synApps work

  1. Setting up the IOC (vxWorks)

    2. Ensure that $(EPICS_BASE)/bin/<arch>/caRepeater gets run when your 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):

    See 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 "/APSshare/vw/T222/mv2700-asd1".

  2. Display files

    3. 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.

  3. Fitting synApps to a particular set of hardware

    4. 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:

    xxx/iocBoot/ioc*/st.cmd
    This is the ioc's startup script, and it loads the other .cmd files

    xxx/iocBoot/ioc*/*.cmd
    xxx/iocBoot/ioc*/*.substitutions
    Other command files that may or may not be invoked by st.cmd

    xxx/iocBoot/ioc*/auto_positions.req
    xxx/iocBoot/ioc*/auto_settings.req
    specifies PV's to be saved/restored automatically

    xxx/iocBoot/ioc*/saveData.req
    identifies PV's used by the saveData software, sscan records to be monitored for data, and PV's whose values are to be included in all scan-data files.

    xxx/iocBoot/ioc*/bootParms
    a copy of the boot parameters (in case the IOC processor crashes in a way that erases nonvolatile memory)

  4. Running synApps

    1. Boot parameters

      See xxx/iocBoot/ioc*/bootParms for sample boot parameters.

    2. MEDM

      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 variable 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 "164.54.53.126 164.54.53.127"

      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 environment variable 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 64008
      in 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.

    3. autosave/restore

      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 . Normally, I do this: 

      chmod a+w,g+s autosave

      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 "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.

    4. saveData

      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.

How to extend synApps

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.

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 utils directory

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
copyAdl
Look through synApps for .adl files, and copy them all to a specified directory

Example of use: 

    copyAdl $SYNAPPS/support adl_files
convertIocFiles.py
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.

mdautils-src.tar.gz
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.

mdaExplorer
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.)

mdaPythonUtils
A collection of python programs that read, write, modify, and translate MDA files.

snapDb
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.
Suggestions and Comments to:
Tim Mooney : ([email protected])
Beamline Controls & Data Acquisition Group
Advanced Photon Source, Argonne National Laboratory
Last modified: March 3, 2009