DXP - EPICS software for XIA Digital Signal Processing Systems

Contents

• Overview
• Installing EPICS for the Saturn
  • Installing the Saturn on Windows
  • Installing the Saturn on Linux
• Running the Saturn
  • Saturn startup script
  • Saturn medm screens
• Installing EPICS for the xMAP
• Running the xMAP
  • xMAP startup script
  • xMAP medm screens
• Installing the DXP2X
• Software Architecture
• Performance

Overview

The EPICS DXP module provides support for the digital signal processor based multichannel analyzers from X-ray Instrumentation Associates (XIA).

DXP currently supports the following hardware

• The xMAP, which is a 4-channel PXI card. The PXI crate is typically connected to a Windows PC with a PCI/PXI fiber-optic interface.
• The Saturn, which is a standalone desktop unit that communicates over the PC Enhanced Parallel Port (EPP) or USB port. It contains the equivalent electronics of the shaping amplifier, ADC and MCA of a conventional pulse-height analysis system. The Vortex detector from SII (formerley Radiant) is an OEM version of the Saturn, and it also works with this software.
• The DXP2X, which is a single-width CAMAC module. Each module contains 2 or 4 channels with similar pulse-processing electronics to the Saturn.

DXP currently supports this hardware under the following operating systems and interfaces:

• The xMAP with the EPICS IOC running on Windows, using the National Instruments PCI/PXI adapter. The EPICS win32-x86 (Microsoft VC++) and cygwin-x86 (gcc) architectures are supported.
• The Saturn with the EPICS IOC running on Windows, using the EPP parallel port, USB 1.0, or USB 2.0 interfaces. The EPICS win32-x86 (Microsoft VC++) and cygwin-x86 (gcc) architectures are supported.
• The Saturn with the EPICS IOC running on Linux, using the EPP parallel port, USB 1.0, or USB 2.0 interfaces.
• The DXP2X with the EPICS IOC running on vxWorks, using the Kinetic Systems 2917/3922 VME to CAMAC interface. Other CAMAC interfaces that have software support for the ESONE standard CAMAC library calls should also work, but have not been tested.

The features of the EPICS software, compared with software available from XIA are:

• Control and data acquisition are available over the network, from any application or language that supports the EPICS channel access protocol (based on TCP/IP). This means that EPICS clients written in languages like IDL, LabView, Visual Basic, etc. can control the DXP modules and read the data. These applications can be running on any computer on the Internet, they do not need to run on the computer that is attached to the XIA hardware. This client/server model is very desirable in complex data acquisition environments, such as synchrotron beamlines, because it allows the DXP control and data acquisition to be integrated with other hardware and software. For example, a control software program can move a motor, command the DXP to acquire data, and write the data to disk.
• A single software package supports the xMAP, Saturn, and the DXP2X.
• The Saturn can be run from Windows and Linux, while the XIA Saturn control programs only runs on Windows.
• The DXP2X support uses the new XIA Handel library, while the XIA MESA package uses an old LabView interface

The software consists of the following components:

• An asyn server that provides support for the EPICS MCA record via the asyn MCA device support. This permits each channel of the DXP to be connected to an MCA record identically with other supported MCA hardware, such as the Canberra AIM. The MCA record is used to control data acquisition and to acquire spectra or regions of interest.
• A EPICS DXP record that is used to set all of the many software selectable parameters for the DXP, including peaking times, pileup rejection criteria, etc. The DXP record is also used to acquire diagnostic data, such as the baseline histogram and ADC trace.
• Databases for single-element and multi-element detector systems.
• medm display screens for single-element and multi-element detector systems.
• A State Notation Language program for synchronizing acquisition and DXP parameters in multi-element detector systems.
• Example IOC boot directories for the Saturn on Windows and Linux, and for a 16 element detector with the xMAP on Windows and the DXP2X on vxWorks.

Installing EPICS for the Saturn

To install the EPICS DXP software with a Saturn on a Windows or Linux computer do the following:

• To use the parallel port (EPP) interface:
  • Configure the parallel port to be in EPP mode. This requires entering the BIOS setup screen on the computer before the operating system boots. The menus will differ from one computer to another, but it is necessary to set the parallel port to EPP mode. Other modes will not work.
• Decide whether you want to build the EPICS DXP software from source code, or install the pre-built binaries.

  Most users will just download the pre-built binaries. The Windows binaries should run on almost any version of Windows. Windows XP and Windows 2000 have been tested.

  The Linux binaries are built with Redhat Fedora kernel 2.6.27 and gcc version 4.3.0. These binaries should run on many recent versions of Linux, but this has not been extensively tested.

  Building from the source code requires downloading EPICS base and all of the required synApps components. To build from source code on Windows for the win32-x86 architecture requires Microsoft Visual Studio .NET 2003 or later, and the perl and make packages from Cygwin. To build from source code on Windows for the cygwin32-x86 architecture requires the gcc, g++, perl and make packages from Cygwin. It is beyond the scope of this document to describe how to build the source code. Consult other EPICS documentation for this.

Installing the Saturn on Windows

To use the EPICS DXP software with a Saturn on a Windows PC do the following:

• Install the Windows Port IO Driver from Scientific Software Tools. This is a software driver that lets Windows applications communicate with I/O ports, including the Enhanced Parallel Port. Although this is only needed to communicate with the EPP port, the driver must be installed even if USB only will be used, because the EPICS dxpApp application is linked with that DLL.
• To use the USB 1.0 interface:
  • Install the ProSpect or Kepler software from XIA. This will install the required Windows driver for the USB 1.0 Saturn. The driver can also be found in the Handel source code distribution which is available through the XIA software downloads Web site. The driver is found in the redist/drivers/usb1 directory.
• To use the USB 2.0 interface:
  • Install the PI-SPEC software from SII NanoTechnology USA. This software is supplied with their Vortex detectors. This will install the required Windows EZ-USB driver for the USB 2.0 Saturn. The driver can also be found in the Handel source code distribution which is available through the XIA software downloads Web site. The driver is found in the redist/drivers/usb2 directory.
• Chose whether to use the Cygwin or native Windows environment. The main reason to use Cygwin is to run the saveData utility, which will save EPICS scan data to disk. This utility does not currently run under the native Windows environment because it lacks the Sun RPC library.
• If using Cygwin then install the basic Cygwin package. Cygwin is a public domain package that provides Unix-like programming libraries and commands on Windows. When using the Cygwin install program use all of the default settings, which will install just the basic package into C:\Cywgin.
• If you want to run the medm display program on the Windows PC, which is recommended in most cases, you need to install Exceed. Exceed is a commercial X-Windows package from Hummingbird. After installing Exceed you need to install the EPICS Win32 Extensions, which contain medm. Note that medm may work with non-commercial versions of X windows servers for Windows, but Exceed is the only package that is guaranteed to work.
• Download the latest standalone release (e.g. dxpStandalone_XXX.tgz), of the EPICS DXP software, containing Cygwin and native Windows binaries.
• Unpack that distribution into a directory such as C:\EPICS or C:\Program Files\EPICS. The distribution file, dxpStandlone.tgz can be unpacked using WinZip, or with the gunzip and tar utilities that come with Cygwin. To use the Cygwin tools:

        $ cd /cygdrive/c/epics         # Or wherever you have chosen to put the EPICS software
        $ tar xzvf dxpStandalone_2-10.tgz    # Unpack the tar file.
        

• Make sure that the .fdd and .ini files in iocBoot/iocSaturn/ have DOS-type line terminators. This can be done by running the Cygwin bash shell and typing

        $ cd iocBoot/iocSaturn
        $ unix2dos *.fdd *ini
        

  This is necessary because these files may have Unix line terminators, depending on how they were unpacked from the distribution.
• Make sure that the .bat files in iocBoot/iocSaturn/ have execute permission. This can be done by running the Cygwin bash shell and typing

        $ cd iocBoot/iocSaturn
        $ chmod +x *.bat
        

  This is necessary because these files may not have this permission, depending on how they were unpacked from the distribution.
• Copy all of the medm .adl files into a single directory. This is simpler than defining EPICS_DISPLAY_PATH to point to all of the required directories. For example, if you decide to put the .adl files in C:\epics_adl, and if you unpacked the dxp tar file distribution into C:\epics, then type the following commands at the Cygwin bash shell prompt:

        $ mkdir /cygdrive/c/epics_adls
        $ find /cygdrive/c/epics -name '*.adl' -exec cp -f -p -v {} /cygdrive/c/epics_adls \;
        

  Define the environment variable EPICS_DISPLAY_PATH to point to C:\epics_adls. For the Windows shell use the Windows Control Panel/System/Advanced/Environment Variables. For the Cygwin shell edit your .bashrc file.
• If you look at that batch file, you will see a line that temporarily sets the environment variable PATH to C:\cygwin\bin. You may want to add this directory permanently to your Windows path for Windows shells. Again, use the Windows Control Panel/System/Advanced/Environment Variables. Modify the definition according to where you have installed Cygwin. Note that the PATH will be set to automatically include that directory when running the Cygwin bash shell.
• If you installed pre-built binaries, rather than building from source, then edit the envPaths file in iocBoot/iocSaturn. Change the paths to the locations of the directories on your system. Don't worry about the path for directories that don't exist, like SNCSEQ, EPICS_BASE, etc.

Installing the Saturn on Linux

To use the EPICS DXP software with a Saturn on a Linux computer do the following:

• To use the USB 1.0 or USB 2.0 interface:
  • Install the latest version (0.1.12 or later) of libusb from SourceForge. This software must be installed using the root account. The version of libusb that comes with most Linux systems is older, and often will not work, so install this more recent version.
• Download the latest standalone release (e.g. dxpStandalone_XXX.tgz), of the EPICS DXP software, containing Linux binaries.
• Unpack that distribution into a directory such as /usr/local/epics. The distribution file, dxpStandalone_XXX.tgz can be unpacked using the Linux tar utility, e.g.:

        tar xvzf dxpStandalone_2-10.tgz
        

• Make sure that the .fdd and .ini files in iocBoot/iocSaturn/ have Unix-type line terminators. This can be done by typing

        > cd iocBoot/iocSaturn
        > dos2unix *.fdd *.ini
        

  This is necessary because these files may have Windows line terminators, depending on how they were unpacked from the distribution.
• Copy all of the medm .adl files into a single directory. This is simpler than defining EPICS_DISPLAY_PATH to point to all of the required directories. For example, if you decide to put the .adl files in /home/epics/epics_adls, and if you unpacked the dxp tar file distribution into /home/epics/epics, then type the following commands at the shell prompt:

        $ mkdir /home/epics/epics_adls
        $ find /home/epics/epics -name '*.adl' -exec cp -f -p -v {} /home/epics/epics_adls \;
        

  Define the environment variable EPICS_DISPLAY_PATH to point to /home/epics/epics_adls. Do this by editing your .cshrc or .bashrc file.
• Access to the EPP I/O port on Linux requires root privilege. This can be done in any of following 3 ways:
  1. Prefered method. The EPICS DXP software on Linux contains a program called startWithIopl3. This program calls iopl(3) as root, and then reverts back to the non-root account to run dxpApp. NOTE: This method does not work on some versions of Linux, probably because of SELinux protections that prevent processes started with execv() from inheriting the iopl(3) permissions. To use this method the application startWithIopl3 must be installed as suid root. Do this as follows:

               > cd bin/linux-x86
               > su root
               (password)
               > chmod +s startWithIopl3
               > exit
               

     The dxpApp application can then be run without root privilege as follows:

               > cd iocBoot/iocSaturn
               > ../../bin/linux-x86/startWithIopl3 ../../bin/linux-x86/dxpApp st.cmd
               

     You can also copy startWithIopl3 to a directory like /usr/local/bin or ~/bin that is in your PATH. That way it can be run without having to specify the path.
  2. Not as good. Install the dxpApp application as suid root. Do this as follows:

               > cd bin/linux-x86
               > su root
               (password)
               > chmod +s /bin/linux-x86/dxpApp
               > exit
               

     The dxpApp application can then be run without root priviledge as follows:

               > cd iocBoot/iocSaturn
               > ../../bin/linux-x86/dxpApp st.cmd
               

  3. Least desirable method. Run dxpApp as root:

               > cd iocBoot/iocSaturn
               > su root
               (password)
               > ../../bin/linux-x86/dxpApp st.cmd
               or
               > sudo ../../bin/linux-x86/dxpApp st.cmd
               

• USB devices on Linux are automatically created with read-only permission for non-root users by default. In order to run the dxpApp application without root privilege it is necessary to change the device permissions. Because these devices are created dynamically when the Saturn is connected, this cannot just be done once statically. Rather it requires using the "hotplug" or "udev" facilities on Linux to have the device permissions set correctly each time the Saturn connects. More recent Linux kernels use the "udev" facility, older kernels use the "hotplug" facility. I do not know exactly which kernel version the switch to udev was done, but I do know from my systems that 2.6.9 uses hotplug while 2.6.22 uses udev. If the directory /etc/hotplug exists then the system is presumably using hotplug. In that case the directory /dev/bus/usb will probably not exist, only /proc/bus/usb will exist.
  Here is a recipe for older systems using hotplug.
  1. Add the following 3 lines to the file /etc/hotplug/usb.usermap

               # XIA Saturn
               usbsaturn            0x0003      0x10e9   0x0700    0x0000       0x0000      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
               usbsaturn            0x0003      0x10e9   0x0701    0x0000       0x0000      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
             

     These lines instruct the hotplug facility to run the script /etc/hotplug/usb/usbsaturn whenever the Saturn is added to the system. 10e9 is the vendor ID for the Saturn, and 0700 and 0701 are the product IDs for the USB 1.1 and USB 2.0 versions of the Saturn.
  2. Create the file /etc/hotplug/usb/usbsaturn containing the following lines:

               #!/bin/bash
     
               if [ "${ACTION}" = "add" ] && [ -f "${DEVICE}" ]
               then
                       chmod 666 "${DEVICE}"
               fi
            

• This script tells hotplug to set the permissions on the Saturn USB device to 666 (owner, group, and world read/write):

           [root@vincent usb]# ls -lt /proc/bus/usb/001/021
           -rw-rw-rw-  1 root root 134 Jan  8 12:20 /proc/bus/usb/001/021
         

  
  Here is a recipe for newer systems using udev.
  1. Create a file in /etc/udev/rules.d called, for example, "80-saturn.rules". Put the following 2 lines in this file.

                SUBSYSTEM=="usb_device",ACTION=="add",SYSFS{idVendor}=="10e9",SYSFS{idProduct}=="0700",MODE="0666"
                SUBSYSTEM=="usb_device",ACTION=="add",SYSFS{idVendor}=="10e9",SYSFS{idProduct}=="0701",MODE="0666"
              

     These rules instruct the udev facility to set the permissions on the USB device to 666 (owner, group and world read/write) for the Saturn whenever it is added to the system. 10e9 is the vendor ID for the Saturn, and 0700 and 0701 are the product IDs for the USB 1.1 and USB 2.0 versions of the Saturn. Note that the 10e9 ID is case sensitive!
  2. Force the udevd daemon to reload its rules:

                $ /sbin/udevcontrol reload_rules
              

• These changes for udev should cause the Saturn USB device to have the correct permissions:

           baja:/etc/udev/rules.d>ls -lt /dev/bus/usb/005/021
           crw-rw-rw- 1 root root 189, 532 2008-01-07 16:08 /dev/bus/usb/005/021
         

  However, on some Linux versions libusb uses /proc/bus/usb by default, rather than /dev/bus/usb, so the permissions set by udev will not have the desired affect. This can be fixed by defining the environment variable USB_DEVFS_PATH to be /dev/bus/usb. In fact I now add the following command to the EPICS IOC startup script (st.cmd) on Linux when using USB, just before the xiaInit command:

          # On Linux execute the following command so that libusb uses /dev/bus/usb
          # as the file system for the USB device.  
          # On some Linux systems it uses /proc/bus/usb instead, but udev
          # sets the permissions on /dev, not /proc.
          epicsEnvSet USB_DEVFS_PATH /dev/bus/usb
        

  This could obviously be done in the shell startup script instead if desired.
• Make sure that the script files in iocBoot/iocSaturn/ have execute permission. This can be done by running the Cygwin bash shell and typing

        $ cd iocBoot/iocSaturn
        $ chmod +x START_IOC*
        

  This is necessary because these files may not have this permission, depending on how they were unpacked from the distribution.
• If you installed pre-built binaries, rather than building from source, then edit the envPaths file in iocBoot/iocSaturn. Change the paths to the locations of the directories on your system. Don't worry about the path for directories that don't exist, like SNCSEQ, EPICS_BASE, etc.

Running the Saturn

There are several things that should be done to run Saturn system under the EPICS software.

• Edit iocBoot/iocSaturn/saturn.ini. Uncomment to appropriate lines to select correct the firmware for the Saturn speed (20MHz or 40MHz) and pre-amp type (reset or RC). Uncomment the correct lines for the interface you are using (EPP, USB 1.0 or USB 2.0).
• Edit iocBoot/iocSaturn/st.cmd to uncomment the correct dbLoadRecords command for your pre-amp type (reset or RC).
• Make sure that the switch inside the Saturn is set for the correct pre-amp type. The switch is labeled "RAMP" for reset pre-amps and "OFFSET" for RC pre-amps.
• Connect the parallel port or USB cable from the Saturn to the PC, and turn on the Saturn.
• Under Windows, start the EPICS IOC and medm by running the batch file iocBoot/iocSaturn/START_IOC.bat. This can be done by double clicking on the icon for this file. You should see the EPICS IOC commands in a Windows command shell, and you should hear clicking sounds from the Saturn. If everything works correctly, you can then begin to collect and display spectra.
• Under Linux start the EPICS IOC and medm by running the script iocBoot/iocSaturn/START_IOC. This can be done by typing:

        > cd iocBoot/iocSaturn
        > ./START_IOC
        

  You may need to edit the START_IOC script depending on how you chose to solve the root priviledge problem, and whether startWithIopl3 is in your path. You should see the EPICS IOC commands, and you should hear clicking sounds from the Saturn. If everything works correctly, you can then begin to collect and display spectra.

After verifying that you can control the Saturn from medm there are some things you should do to customize your installation. First, you should edit saturn.ini to set the polarity, the pre-amp gain, and the time after reset (for reset pre-amps) or the RC time constant (for RC pre-amps). Consult the Saturn User's Manual for information on how to determine and set these parameters.

The saturn.ini file will contain lines like the following:

  type_value = 10.
  channel0_gain = 1.7
  channel0_polarity = +
  

• The type_value is the transient settling time after a reset in microseconds for reset pre-amps. It is the RC time constant in microseconds for RC pre-amps. 10 microseconds is a reasonable value for both of these to start with.
• The gain is specified in mV/keV, and is used so that the energy units in the DXP software are correct. Most pre-amps are in the 1-4 mV/keV range. The best way to set this value is to set the EMAX parameter (energy of last channel) in EPICS, and see how well it agrees with reality when you calibrate the spectrum with a known source. Then iteratively edit the saturn.ini file and restart EPICS until the actual EMAX matches the requested one. Getting it to within a few percent is fine, since you will do accurate calibration of the EPICS MCA spectra when you collect data.
• The polarity can be "+" or "-". A positive polarity means that an x-ray pulse produces a voltage step with a rising edge.

The example IOC directory, iocSaturn, creates EPICS process variables with names like dxpSaturn:dxp1.PKTIM, where dxpSaturn is the "prefix" for the process variable names, dxp1 is the DXP record name, and PKTIM is the field name. This is fine for installations where there will be at most one Saturn on the subnet. However, in many cases there will be the possibility of more than one Saturn running EPICS on the same subnet. If this is the case then it is essential that each one use a different prefix, because EPICS process variable names must be unique on a subnet. Here is how to give your Saturn a unique name, and still be able to upgrade the EPICS software easily. It is recommended that you follow these instructions even if you don't have name conflicts on your IOC, so that files you edit are in a directory that will not be overwritten when you upgrade the EPICS software.

• Make a copy of the iocSaturn directory. Let's assume you will make your prefix be mySaturn:, so a good name for the directory would be iocmySaturn/.
• Edit all files in that directory (including st.cmd, auto_settings.req, and START_IOC*), changing all occurances of dxpSaturn: to mySaturn:.
• If you have created any higher-level medm screens that load the medm screens in this package, you will need to edit them to pass the new prefix, mySaturn:
• The next time you unpack a new version of the EPICS DXP software it will overwrite the iocSaturn directory. However, if you have made your own new directory, mySaturn/, that will not be modified.

The EPICS DXP application uses the EPICS save/restore facility. This means that all of the important parameters that you might change when running the Saturn are saved in files in the subdirectory called autosave/ under your IOC directory. These parameters include the peaking time, the update rates for displays and nearly 200 other parameters. The next time you start EPICS it will restore these values automatically from the file called autosave/auto_settings.sav. It is a good idea to make copies of this file from time to time so that you can get back to old settings if the file is lost or corrupted.

Saturn startup script

The following is a typical startup script for the Saturn.

#########################################
< envPaths

# Tell EPICS all about the record types, device-support modules, drivers,
# etc. in this build from dxpApp
dbLoadDatabase("../../dbd/dxp.dbd")
dxp_registerRecordDeviceDriver(pdbbase)

# On Linux execute the following command so that libusb uses /dev/bus/usb
# as the file system for the USB device.  
# On some Linux systems it uses /proc/bus/usb instead, but udev
# sets the permissions on /dev, not /proc.
epicsEnvSet USB_DEVFS_PATH /dev/bus/usb

# Initialize the XIA software
# Set logging level (1=ERROR, 2=WARNING, 3=XXX, 4=DEBUG)
xiaSetLogLevel(2)
# Edit saturn.ini to match your Saturn speed (20 or 40 MHz), 
# pre-amp type (reset or RC), and interface type (EPP, USB 1.0, USB 2.0)
xiaInit("saturn.ini")
xiaStartSystem

# DXPConfig(serverName, ndetectors, ngroups, pollFrequency)
DXPConfig("DXP1",  1, 1, 100)


# DXP record
# Execute the following line if you have a Vortex detector or 
# another detector with a reset pre-amplifier
dbLoadRecords("../../dxpApp/Db/dxp2x_reset.db","P=dxpSaturn:, R=dxp1, INP=@asyn(DXP1 0)")
# Execute the following line if you have a Ketek detector or 
# another detector with an RC pre-amplifier
#dbLoadRecords("../../dxpApp/Db/dxp2x_rc.db","P=dxpSaturn:, R=dxp1, INP=@asyn(DXP1 0)")

# MCA record
dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=dxpSaturn:, M=mca1, DTYP=asynMCA,INP=@asyn(DXP1 0),NCHAN=2048")
dbLoadRecords("../../dxpApp/Db/mcaCallback.db", "P=dxpSaturn:, M=mca1,INP=@asyn(DXP1 0)")

# Template to copy MCA ROIs to DXP SCAs
dbLoadTemplate("roi_to_sca.substitutions")

# Setup for save_restore
< ../save_restore.cmd
save_restoreSet_status_prefix("dxpSaturn:")
dbLoadRecords("$(AUTOSAVE)/asApp/Db/save_restoreStatus.db", "P=dxpSaturn:")
set_pass0_restoreFile("auto_settings.sav")
set_pass1_restoreFile("auto_settings.sav")

### Scan-support software
# crate-resident scan.  This executes 1D, 2D, 3D, and 4D scans, and caches
# 1D data, but it doesn't store anything to disk.  (See 'saveData' below for that.)
dbLoadRecords("$(SSCAN)/sscanApp/Db/scan.db","P=dxpSaturn:,MAXPTS1=2000,MAXPTS2=1000,MAXPTS3=10,MAXPTS4=10,MAXPTSH=2048")

# Debugging flags
#xiaSetLogLevel(4)
#asynSetTraceMask DXP1 0 255
#var mcaRecordDebug 10
#var dxpRecordDebug 10

iocInit

### Start up the autosave task and tell it what to do.

# Save settings every thirty seconds
create_monitor_set("auto_settings.req", 30, P=dxpSaturn:)

### Start the saveData task.
saveData_Init("saveData.req", "P=dxpSaturn:")
#########################################

Here are some comments on the commands in this file.

#########################################
< envPaths
#########################################

This command loads the envPaths file that defines the paths to other EPICS modules. You will need to edit this file if you installed the pre-built binaries rather than building from source code.

#########################################
dbLoadDatabase("../../dbd/dxp.dbd")
dxp_registerRecordDeviceDriver(pdbbase)
#########################################

These commands load the EPICS database definition files.

# On Linux execute the following command so that libusb uses /dev/bus/usb
# as the file system for the USB device.  
# On some Linux systems it uses /proc/bus/usb instead, but udev
# sets the permissions on /dev, not /proc.
epicsEnvSet USB_DEVFS_PATH /dev/bus/usb

This command forces libusb to use the /dev/bus/usb filesystem, rather than /proc/bus/usb, which some kernels use by default. This is needed because udev sets permissions on /dev/bus/usb, not /proc/bus/usb.

#########################################
# Initialize the XIA software
# Set logging level (1=ERROR, 2=WARNING, 3=XXX, 4=DEBUG)
xiaSetLogLevel(2)
# Edit saturn.ini to match your Saturn speed (20 or 40 MHz), 
# pre-amp type (reset or RC), and interface type (EPP, USB 1.0, USB 2.0)
xiaInit("saturn.ini")
xiaStartSystem
#########################################

These commands set the logging (debugging) level for the XIA Handel software. It initializes the XIA software with the appropriate .ini file, and then starts the XIA software. You will hear clicking in the Saturn box when the xiaStartSystem command is executing.

#########################################
# DXPConfig(serverName, ndetectors, ngroups, pollFrequency)
DXPConfig("DXP1",  1, 1, 100)
#########################################

This command starts the EPICS "asyn" server called DXP1. It defines the number of detectors in the system, and the number of detector groups. We use 1 detector group (containing all of the detectors) to efficiently do operations that should be done on all detectors simultaneously. The pollFrequency determines the rate at which the poller thread will check for acquisition complete. 100 Hz is typical, it does not put a significant load on the system, but reduces the average latency in determining when the run is complete to 5ms.

#########################################
# DXP record
# Execute the following line if you have a Vortex detector or
# another detector with a reset pre-amplifier
dbLoadRecords("../../dxpApp/Db/dxp2x_reset.db","P=dxpSaturn:, R=dxp1, INP=@asyn(DXP1 0)")
# Execute the following line if you have a Ketek detector or
# another detector with an RC pre-amplifier
#dbLoadRecords("../../dxpApp/Db/dxp2x_rc.db","P=dxpSaturn:, R=dxp1, INP=@asyn(DXP1 0)")

# MCA record
dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=dxpSaturn:, M=mca1, DTYP=asynMCA,INP=@asyn(DXP1 0),NCHAN=2048")
dbLoadRecords("../../dxpApp/Db/mcaCallback.db", "P=dxpSaturn:, M=mca1,INP=@asyn(DXP1 0)")

# Template to copy MCA ROIs to DXP SCAs
dbLoadTemplate("roi_to_sca.substitutions")
#########################################

These commands load the EPICS databases for the MCA and DXP records. The names of the PV, the number of MCA channels, and the type of detector pre-amp are all chosen in these commands. The mcaCallback.db file is used with the poller to cause the MCA records to read data when acquisition completes.

#########################################
# Setup for save_restore
< ../save_restore.cmd
save_restoreSet_status_prefix("dxpSaturn:")
dbLoadRecords("$(AUTOSAVE)/asApp/Db/save_restoreStatus.db", "P=dxpSaturn:")
set_pass0_restoreFile("auto_settings.sav")
set_pass1_restoreFile("auto_settings.sav")

### Scan-support software
# crate-resident scan.  This executes 1D, 2D, 3D, and 4D scans, and caches
# 1D data, but it doesn't store anything to disk.  (See 'saveData' below for that.)
dbLoadRecords("$(SSCAN)/sscanApp/Db/scan.db","P=dxpSaturn:,MAXPTS1=2000,MAXPTS2=1000,MAXPTS3=10,MAXPTS4=10,MAXPTSH=2048")
#########################################

These commands initialize the save/restore system that remembers changes in parameter settings when the IOC is rebooted. They load the databases for general purpose scanning to be done in the IOC. The maximum number of points in each nested scan is defined here, as is the maximum number of channels of MCA data that can be stored in the scanH record.

#########################################
# Debugging flags
#xiaSetLogLevel(4)
#asynSetTraceMask DXP1 0 255
#var mcaRecordDebug 10
#var dxpRecordDebug 10
#########################################

These commands set the debugging level of the EPICS software. asynSetTraceMask controls the debugging in drvDXP and devDXP. This uses the asynTrace facility, with different bits turning on different types of output. 1 turns on only error reporting, 255 turns on all messages. mcaRecordDebug and dxpRecordDebug turn on messages from the mcaRecord and dxpRecord respectively. 0 turns off messages, 10 turns on all messages.

#########################################
iocInit

### Start up the autosave task and tell it what to do.

# Save settings every thirty seconds
create_monitor_set("auto_settings.req", 30, P=dxpSaturn:)

### Start the saveData task.
saveData_Init("saveData.req", "P=dxpSaturn:")
#########################################

These commands start the EPICS software (iocInit), and start the save/restore software saving parameters every 30 seconds, and start the task that saves data from the scan records. Edit the file saveData.req to change what additional EPICS PVs are saved with every scan. You might want to include the MCA record energy calibration fields, etc.

Note that there is a different startup scripts, st_med.st, and a corresonding .adl file, 1element_dxp.adl. This startup script and medm display is almost identical to the st.cmd and single_element_dxp.adl medm display. The difference is that it uses PVs to control acquisition that are compatible with the multi-element databases used by the DXP2X and xMAP. Client software that is configured to work with the multi-element detectors will work with the Saturn if this startup script is used.

Saturn medm screens

The following are screen shots of the medm screens provided for the Saturn.

single_dxp_top.adl

Main control screen for Saturn.

dxp.adl

Complete screen for low-level DXP parameters and control.

dxp_sca.adl

Screen for SCA display and control.

mca.adl

Screen to display the spectral data and control acquisition.

dxp_baseline.adl

Screen to display the baseline histogram and control its update rate.

dxp_baseline_history.adl

Screen to display the baseline history and control its update rate.

dxp_trace.adl

Screen to display the ADC trace, and control the time per point and update rate.

Installing EPICS for the xMAP

To install the EPICS DXP software with an xMAP system on a Windows computer do the following:

• Follow the instructions for installing the Saturn on Windows. The Windows Port I/O driver needs to be installed, even though the xMAP does not use the EPP port, because the dxpApp application is linked with that DLL. Also, where the directions say iocBoot/iocSaturn use iocBoot/iocXMAP instead.
• Install the PCI/PXI converter from National Instruments.
• Install the National Instruments driver software.
• Install the latest version of the xManager software from XIA. The EPICS software distribution includes the xManager DLLs that are required for the EPICS software. However, xManager installs a Windows driver that is not included with the EPICS software. It can also be useful to have xManager available on the computer to compare with the EPICS software.
• In configuring xManager you will have created a .ini file describing the PCI slots for each xMAP, etc. You can copy that file to the iocXMAP directory or edit one of the .ini files there that most closely matches your system configuration (xmap4.ini, xmap8.ini, etc.).

The example IOC directory, iocXMAP, creates EPICS process variables with names like dxpXMAP:dxp1.PKTIM, where dxpXMAP: is the "prefix" for the process variable names, dxp1 is the DXP record name, and PKTIM is the field name. This is OK for installations where there will be at most one xMAP system on the subnet. However, in many cases there will be the possibility of more than one xMAP running EPICS on the same subnet. If this is the case then it is essential that each one use a different prefix, because EPICS process variable names must be unique on a subnet. Here is how to give your xMAP system a unique name, and still be able to upgrade the EPICS software easily. It is recommended that you follow these instructions even if you don't have name conflicts on your IOC, so that files you edit are in a directory that will not be overwritten when you upgrade the EPICS software.

• Make a copy of the iocXMAP directory. Let's assume you will make your prefix be myXMAP:, so a good name for the directory would be iocmyXMAP/.
• Edit all files in that directory (including *.cmd, auto_settings*.req, *.template, and START_IOC*), changing all occurances of dxpXMAP: to myXMAP:.
• If you have created any higher-level medm screens that load the medm screens in this package, you will need to edit them to pass the new prefix, myXMAP:
• The next time you unpack a new version of the EPICS DXP software it will overwrite the iocXMAP directory. However, if you have made your own new directory, myXMAP/, that will not be modified.

Running the xMAP

There are several things that should be done to run xMAP system under the EPICS software.

• There are startup scripts and template files for systems with 4, 8, 12, or 16 channels (1, 2, 3, or 4 xMAP modules). If you have a different number of channels you will need to create new files.
• You can manually start the software by doing the following in the Cygwin bash shell:

          cd iocBoot/iocXMAP  # Or the new directory you created
          ../../bin/cygin-x86/dxpApp.exe 16element.cmd  # Or 4element.cmd, etc.
       

• You can also start the EPICS IOC and medm by running the batch file iocBoot/iocXMAP/START_IOC.bat. This can be done by double clicking on the icon for this file. You should see the EPICS IOC commands in a Windows command shell, and you should hear clicking sounds from the xMAPS. If everything works correctly, you can then begin to collect and display spectra.
• You can do scans and save complete spectra with the EPICS sscan and saveData facilities.

xMAP startup script

The following is a typical startup script for the xMAP.

#########################################
< envPaths

# Tell EPICS all about the record types, device-support modules, drivers,
# etc. in this build from dxpApp
dbLoadDatabase("$(DXP)/dbd/dxp.dbd")
dxp_registerRecordDeviceDriver(pdbbase)

# Setup for save_restore
< ../save_restore.cmd
save_restoreSet_status_prefix("dxpXMAP:")
dbLoadRecords("$(AUTOSAVE)/asApp/Db/save_restoreStatus.db", "P=dxpXMAP:")
set_pass0_restoreFile("auto_settings16.sav")
set_pass1_restoreFile("auto_settings16.sav")

# Set logging level (1=ERROR, 2=WARNING, 3=INFO, 4=DEBUG)
xiaSetLogLevel(2)
xiaInit("xmap16.ini")
xiaStartSystem

# DXPConfig(serverName, ndetectors, ngroups, pollFrequency)
DXPConfig("DXP1",  16, 1, 100)

dbLoadTemplate("16element.template")

#xiaSetLogLevel(4)
#asynSetTraceMask DXP1 0 255
#asynSetTraceIOMask DXP1 0 2
#var dxpRecordDebug 10

### Scan-support software
# crate-resident scan.  This executes 1D, 2D, 3D, and 4D scans, and caches
# 1D data, but it doesn't store anything to disk.  (See 'saveData' below for that.)
dbLoadRecords("$(SSCAN)/sscanApp/Db/scan.db","P=dxpXMAP:,MAXPTS1=2000,MAXPTS2=1000,MAXPTS3=10,MAXPTS4=10,MAXPTSH=2048")

iocInit

seq dxpMED, "P=dxpXMAP:, DXP=dxp, MCA=mca, N_DETECTORS=16"

### Start up the autosave task and tell it what to do.
# Save settings every thirty seconds
create_monitor_set("auto_settings16.req", 30, "P=dxpXMAP:")

### Start the saveData task.
saveData_Init("saveData.req", "P=dxpXMAP:")

Here are some comments on the commands in this file.

< envPaths
#########################################

This command loads the envPaths file that defines the paths to other EPICS modules. You will need to edit this file if you installed the pre-built binaries rather than building from source code.

#########################################
# Tell EPICS all about the record types, device-support modules, drivers,
# etc. in this build from dxpApp
dbLoadDatabase("$(DXP)/dbd/dxp.dbd")
dxp_registerRecordDeviceDriver(pdbbase)
#########################################

These commands load the EPICS database definition files.

#########################################
# Setup for save_restore
< ../save_restore.cmd
save_restoreSet_status_prefix("dxpXMAP:")
dbLoadRecords("$(AUTOSAVE)/asApp/Db/save_restoreStatus.db", "P=dxpXMAP:")
set_pass0_restoreFile("auto_settings16.sav")
set_pass1_restoreFile("auto_settings16.sav")
#########################################

These commands initialize the save/restore system that remembers changes in parameter settings when the IOC is rebooted.

#########################################
# Set logging level (1=ERROR, 2=WARNING, 3=INFO, 4=DEBUG)
xiaSetLogLevel(2)
xiaInit("xmap16.ini")
xiaStartSystem
#########################################

These commands set the logging (debugging) level for the XIA Handel software. It initializes the XIA software with the appropriate .ini file, and then starts the XIA software. You will hear clicking in the xMAP modules when the xiaStartSystem command is executing. The xamp16.ini file is the same type of file that xManager requires. If you have xManager running on your system you can just copy that .ini file to your IOC directory for EPICS. This file must be edited from the one that is distributed with the EPICS software to define the PCI bus slots in your PXI crate.

#########################################
# DXPConfig(serverName, ndetectors, ngroups, pollFrequency)
DXPConfig("DXP1",  16, 1, 100)
#########################################

This command starts the EPICS "asyn" server called DXP1. It defines the number of detectors in the system, and the number of detector groups. We use 1 detector group (containing all of the detectors) to efficiently do operations that should be done on all detectors simultaneously. The pollFrequency determines the rate at which the poller thread will check for acquisition complete. 100 Hz is typical, it does not put a significant load on the system, but reduces the average latency in determining when the run is complete to 5ms.

#########################################
dbLoadTemplate("16element.template")
#########################################

This command loads the template file that in turns loads the databases for the MCA and DXP records. The content of the template file is discussed below.

#########################################
# Debugging flags
#xiaSetLogLevel(4)
#asynSetTraceMask DXP1 0 255
#asynSetTraceIOMask DXP1 0 2
#var dxpRecordDebug 10
#########################################

These commands set the debugging level of the EPICS software. asynSetTraceMask controls the debugging in drvDXP and devDXP. This uses the asynTrace facility, with different bits turning on different types of output. 1 turns on only error reporting, 255 turns on all messages. mcaRecordDebug and dxpRecordDebug turn on messages from the mcaRecord and dxpRecord respectively. 0 turns off messages, 10 turns on all messages.

#########################################
### Scan-support software
# crate-resident scan.  This executes 1D, 2D, 3D, and 4D scans, and caches
# 1D data, but it doesn't store anything to disk.  (See 'saveData' below for that.)
dbLoadRecords("$(SSCAN)/sscanApp/Db/scan.db","P=dxpXMAP:,MAXPTS1=2000,MAXPTS2=1000,MAXPTS3=10,MAXPTS4=10,MAXPTSH=2048")
#########################################

These commands load the databases for general purpose scanning to be done in the IOC. The maximum number of points in each nested scan is defined here, as is the maximum number of channels of MCA data that can be stored in the scanH record.

#########################################
iocInit

seq dxpMED, "P=dxpXMAP:, DXP=dxp, MCA=mca, N_DETECTORS=16"

### Start up the autosave task and tell it what to do.
# Save settings every thirty seconds
create_monitor_set("auto_settings16.req", 30, "P=dxpXMAP:")

### Start the saveData task.
saveData_Init("saveData.req", "P=dxpXMAP:")
#########################################

The iocInit starts the EPICS software. The seq command starts the dxpMED State-Notation-Language program that implements the "Copy 1 To All" feature for the DXP records. It also copies MCA ROIs to DXP SCAs, and computes combined elapsed and live times, etc. The last two commands start the save/restore task and start the task that saves data from the scan records. Edit the file saveData.req to change what additional EPICS PVs are saved with every scan. You might want to include the MCA record energy calibration fields, etc.

The 16element.template file looks like this:

#########################################
file "$(DXP)/dxpApp/Db/dxpMED.db"
{
pattern
{P,           MCAALL,    INP          } 
{dxpXMAP: mcaAll, "@asyn(DXP1,-1)"}
}

file "$(MCA)/mcaApp/Db/simple_mca.db"
{
pattern
{P,           M,       DTYP,         INP           PREC,  CHANS}
{dxpXMAP:   mca1  "asynMCA",   "@asyn(DXP1,0)",   2,     2048}
{dxpXMAP:   mca2  "asynMCA",   "@asyn(DXP1,1)",   2,     2048}
{dxpXMAP:   mca3  "asynMCA",   "@asyn(DXP1,2)",   2,     2048}
{dxpXMAP:   mca4  "asynMCA",   "@asyn(DXP1,3)",   2,     2048}
{dxpXMAP:   mca5  "asynMCA",   "@asyn(DXP1,4)",   2,     2048}
{dxpXMAP:   mca6  "asynMCA",   "@asyn(DXP1,5)",   2,     2048}
{dxpXMAP:   mca7  "asynMCA",   "@asyn(DXP1,6)",   2,     2048}
{dxpXMAP:   mca8  "asynMCA",   "@asyn(DXP1,7)",   2,     2048}
{dxpXMAP:   mca9  "asynMCA",   "@asyn(DXP1,8)",   2,     2048}
{dxpXMAP:   mca10 "asynMCA",   "@asyn(DXP1,9)",   2,     2048}
{dxpXMAP:   mca11 "asynMCA",   "@asyn(DXP1,10)",  2,     2048}
{dxpXMAP:   mca12 "asynMCA",   "@asyn(DXP1,11)",  2,     2048}
{dxpXMAP:   mca13 "asynMCA",   "@asyn(DXP1,12)",  2,     2048}
{dxpXMAP:   mca14 "asynMCA",   "@asyn(DXP1,13)",  2,     2048}
{dxpXMAP:   mca15 "asynMCA",   "@asyn(DXP1,14)",  2,     2048}
{dxpXMAP:   mca16 "asynMCA",   "@asyn(DXP1,15)",  2,     2048}
{dxpXMAP:  mcaAll "asynMCA",   "@asyn(DXP1,-1)",  2,     2048}
}

# DXP records
file "$(DXP)/dxpApp/Db/xmap_reset.db"
{
pattern
{P,           R,        INP       }
{dxpXMAP:   dxp1   "@asyn(DXP1,0)"}
{dxpXMAP:   dxp2   "@asyn(DXP1,1)"}
{dxpXMAP:   dxp3   "@asyn(DXP1,2)"}
{dxpXMAP:   dxp4   "@asyn(DXP1,3)"}
{dxpXMAP:   dxp5   "@asyn(DXP1,4)"}
{dxpXMAP:   dxp6   "@asyn(DXP1,5)"}
{dxpXMAP:   dxp7   "@asyn(DXP1,6)"}
{dxpXMAP:   dxp8   "@asyn(DXP1,7)"}
{dxpXMAP:   dxp9   "@asyn(DXP1,8)"}
{dxpXMAP:   dxp10  "@asyn(DXP1,9)"}
{dxpXMAP:   dxp11  "@asyn(DXP1,10)"}
{dxpXMAP:   dxp12  "@asyn(DXP1,11)"}
{dxpXMAP:   dxp13  "@asyn(DXP1,12)"}
{dxpXMAP:   dxp14  "@asyn(DXP1,13)"}
{dxpXMAP:   dxp15  "@asyn(DXP1,14)"}
{dxpXMAP:   dxp16  "@asyn(DXP1,15)"}
#{dxpXMAP:  dxpAll  "@asyn(DXP1,-1)"}
}
#########################################

This file defines the mca and DXP records that get loaded. It defines the maximum number of channels in the MCA records. It also loads the multi-element DXP database (dxpMED.db). This database is used with the dxpMED.st SNL program to do collective actions on multiple DXP or MCA records.

Note that there are supplied startup scripts, template files and auto_settings.req files for 4, 8, 12, and 16 channel xMAP systems. If you have a different number of channels you need to create your own files using these as examples. There are currently only medm screens for a 16-element detector system. You will need to copy and edit these for different numbers of detectors. For fewer detectors than 16 you can simply use the 16element files temporarily and ignore the ugly white fields for non-existant records!

xMAP medm screens

The following are screen shots of the medm screens provided for the xMAP.

16element_dxp.adl

Main control screen for 16element xMAP system.

16element_dxp_a;;.adl

Complete screen for low-level DXP parameters and control.

16element_dxp_statistics.adl

Screen to display trigger counts and events in run, plus ICR and OCR.

16element_ROI_SCA.adl

Screen to display ROI and SCA counts for a single ROI/SCA on each detector.

16element_cal.adl

Screen to display energy calibration parameters for each detector.

16element_time.adl

Screen to display preset and elapsed times for each detector.

16element_plots.adl

Screen to display the spectral data for each detector.

16element_baseline.adl

Screen to display the baseline histograms and control the update rate.

16element_history.adl

Screen to display the baseline histories and control the update rate.

16element_trace.adl

Screen to display the ADC traces, and control the time per point and update rate.

Installing the DXP2X

The DXP4C2X CAMAC module is supported under vxWorks. It works with the Kinetic Systems 3922/2922 VME to CAMAC adapter.

The example IOC directory, iocDXP2X, creates EPICS process variables with names like dxp2X:dxp1.PKTIM, where dxp2X: is the "prefix" for the process variable names, dxp1 is the DXP record name, and PKTIM is the field name. This is OK for installations where there will be at most one DXP2X system on the subnet. However, in many cases there will be the possibility of more than one DXP2X running EPICS on the same subnet. If this is the case then it is essential that each one use a different prefix, because EPICS process variable names must be unique on a subnet. Here is how to give your DXP2X system a unique name, and still be able to upgrade the EPICS software easily. It is recommended that you follow these instructions even if you don't have name conflicts on your IOC, so that files you edit are in a directory that will not be overwritten when you upgrade the EPICS software.

• Make a copy of the iocDXP2X directory. Let's assume you will make your prefix be myDXP2X:, so a good name for the directory would be iocmyDXP2X/.
• Edit all files in that directory (including *.cmd, auto_settings*.req, *.template, and START_IOC*), changing all occurances of dxp2X: to myDXP2X:.
• If you have created any higher-level medm screens that load the medm screens in this package, you will need to edit them to pass the new prefix, myDXP2X:
• The next time you unpack a new version of the EPICS DXP software it will overwrite the iocDXP2X directory. However, if you have made your own new directory, myDXP2X/, that will not be modified.
• There are example startup scripts (e.g. 4element.cmd), Handel initialization files (e.g. 4element_reset.ini), database templates (e.g. 4element.template), and autosave request files (e.g. auto_settings4.req) for 4, 8, 12 and 16 element systems. The .ini file will almost certainly need to be edited to match your detector and CAMAC configuration.

Software Architecture

The overall architecture of the EPICS DXP software is shown in the diagram below. At the top level are EPICS Channel Access client applications, such as the IDL MCA Display program, the IDL Multi-Element Detector (MED) Display program, medm, spec, and others.

At the next level is the dxpMED State Notation Language program, which is used to synchronize acquisition and settings for multi-element detectors. This program also uses EPICS Channel Access, but it typically runs in the same EPICS IOC that is controlling the XIA hardware.

Next are the DXP and MCA records, which communicate with device support. In the case of the MCA record, this device support is devMcaAsyn, which is itself device-independent, and talks to drvDxp. The device support for the dxpRecord is specific to the XIA hardware. drvDxp and devDxp both communicate with the XIA Handel library, which calls the XIA Xerxes library. Xerxes calls the machine dependent libraries, md_epics and md_win95, which call the operating system specific hardware libraries to perform the actual low-level I/O.

The poller thread rapidly polls the acquisition status (acquiring or done) while acquisition is in progress. This thread issues callbacks when acquisition is complete to records that have registered with it. It is used to minimize latencies, so that the MCA records will be processed when acquisition completes without the MCA records themselves having to process rapidly. The poll rate is set in the DXPConfig() command in the startup script. It is typically set to 100Hz, which does not significantly load the system, but provides a 5msec average latency in determining when acquisition is complete.

Performance

Tests were done with R2-7 of the dxp module to measure the performance of the Saturn and xMAP systems in rapidly collecting complete spectra in a scan. The tests were done with the following conditions:

• Cygwin architecture on Windows. This is currently required for the saveData software.
• 2048 channel spectra
• 0.01 second acquisition time, in order to attain real data but with minimal overhead.
• EPICS scan records.
  • The inner scan was the scanH record, which had its detector trigger configured to .mca.ERST (Saturn) or EraseStart (xMAP) in the mca/dxp database. Its detectors were configured to collect spectra from the MCA records. The Saturn collected 1 MCA spectrum at each scan point, the xMAP collected 4, 8, 12 or 16 spectra at each scan point.
  • The outer scan was the scan1 record. It had no positioner drive PV to minimize overhead. The detector trigger was scanH.EXSC. Its detectors were ElapsedReal, ElapsedLive, and the first ROI, mca1.R0.
• The scan fields of the MCA status, MCA read, and DXP read records were Passive to minimize overhead. The poller thread was running at 100 Hz, and caused the MCA records to be processed when acquisition was complete.
• saveData was used to save the scan data to a local hard disk, not across the network.
• 1000 scan points were collected. There were no positioner or detector delays in the scan records.
• The scan records were running on the same IOC as the DXP software.
• The system configuration is shown in the screen shot below.

Note that these measurements were made using the simple unbuffered mode on the xMAP. The xMAP has 4MB of onboard memory per channel, and the release 0.9.1 firmware allows one to use this memory to buffer many spectra, in response to a software or hardware trigger signal. This can be used to rapidly acquire many spectra, and then read them out quickly at the end. The EPICS software does not yet support this feature, but will in a future release.