dxpSITORO - EPICS software for XIA FalconX Digital Signal Processing Systems

Contents

• Overview
• Architecture
• EPICS Records, Databases, and medm screens
  • dxpHighLevel.template
  • dxpSCA.template
  • dxpSystem.template
  • dxpMED.template
  • dxpMapping.template
• medm screens
• Installing dxpSITORO

Overview

The EPICS dxpSITORO module provides support for the SITORO based digital signal processor based multichannel analyzers from X-ray Instrumentation Associates (XIA). These devices include the FalconXN models, and all contain the functional equivalent of the shaping amplifier, ADC, and MCA of a conventional pulse-height analysis system. The FalconX is based on the SITORO technology from Southern Innovation

dxpSITORO supports the 1, 4, and 8 channel versions of the FalconX.

dxpSITORO currently supports this hardware under the following operating systems and compilers:

• Linux with gcc.
• Windows with Visual Studio 2015 or later.

The features of the EPICS software, compared with the ProSpect 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 Python, IDL, LabView, etc. can control the FalconX 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 controlling to the XIA hardware. This client/server model is very desirable in complex data acquisition environments, such as synchrotron beamlines, because it allows the FalconX control and data acquisition to be integrated with other hardware and software. For example, a control software program can move a motor, command the FalconX to acquire data, and write the data to disk.

Architecture

The software consists of the following components:

• An asyn port driver. This driver is implements a class called NDDxp, which is derived from the asynNDArrayDriver and asynPortDriver base C++ classes. The driver communicates with the hardware using the XIA Handel library, which in turn communicates with the Southern Innovation SINC library.
• An EPICS MCA record for each detector. This communicates with the driver via the asyn MCA device support. This support allows each detector to be treated identically with other supported MCA hardware, such as the Canberra AIM. The MCA record is used for data acquisition in the non-mapping modes, and to define regions of interest.
• A set of standard EPICS records (ai, ao, bi, bo, waveform, etc.) that are used to set all of the many software selectable parameters for the FalconX, including pulse separation, detection threshold, etc. These are also used for data acquisition in the mapping modes and to acquire diagnostic data, such as the ADC trace. These records use the standard asyn device support.
• A State Notation Language program (dxpMED) for synchronizing acquisition, ROIs, and FalconX parameters in multi-element detector systems.
• Support for the plugins from the areaDetector package. These plugins are used to stream data to disk in the mappping modes, to define ROIs, compute statistics, etc.
• Databases for single-element and multi-element detector systems.
• medm display screens.
• Example IOC boot directories for the FalconX.

The overall architecture of the EPICS dxpSITORO 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 Python Multi-Element Detector control programs, medm, spec, and others.

EPICS Records and Databases

This document does not attempt to explain the meaning or use of all of the FalconX parameters. The best documentation of the operation of the FalconX modules is provided by XIA in the FalconX Quick Start Guide. This also describes the ProSpect software, which is useful to set up and test the hardware.

For many parameters in the following databases there is both an EPICS output record (ao, bo, mbbo, etc.) and a corresponding EPICS input record (ai, bi, mbbi, etc.). The output record is used to set a new value in the hardware. The input record has an _RBV suffix, which stands for Read Back Value. It is used to read back the actual value from the hardware, which may be different from the requested value because of limitations of the hardware, errors, etc.

When the EPICS IOC starts the initial values of the records are set in the following order:

1. The default value in the record definition, typically 0.
2. The value specified in the database file (.template or .substitutions file)
3. The value read back from the hardware or Handel library. This will be the Handel default value, or the value from the .ini file if it is defined there.
4. The value from save/restore.
5. The value from a "dbpf" in the startup script.
6. The value set from the SNL program on startup.

Steps 1-3 apply to both output records and to input records. Steps 4 and 5 typically only apply to output records, and step 7 only to input records. If there is no auto_settings*.sav file then most of the parameter records will obtain their initial values from the .ini file. Thus, by deleting the auto_settings*.sav file one can force EPICS to use the same parameters that have been saved into an .ini file by ProSpect.

dxpHighLevel.template

The following records are defined in the database dxpHighLevel.template. They control the high-level parameters such as peaking time, etc. One instance of this database is loaded for each detector channel in the system. All of the record names in the template file are preceeded by the macro parameters $(P)$(R), where $(P) is the prefix for this detector system, and $(R) is the name of this specific channel. $(P) should be unique for all EPICS IOCs on the subnet, and $(R) is typically dxp1:, dxp2:, etc.

dxpSCA.template

The following records are defined in the databases dxpSCA.template. They control the 16 (FalconX1), 4 (FalconX4) or 2 (FalconX8) single-channel-analyzers (SCAs) for each channel. Each SCA is defined by a low channel and a high channel. The SCA definitions are for hardware ROI mapping. The FalconX puts out a pulse on a TTL output line when an x-ray falls within the channel range of that SCA. This allows very fast mapping, since there is no need to read the spectrum at each point in the scan.

One instance of this database is loaded for each SCA and each detector channel in the system. All of the record names in the template file are preceeded by the macro parameters $(P)$(R), where $(P) is the prefix for this detector system, and $(R) is the name of this specific channel. The macro $(N) is used to define the SCA number.

dxpSystem.template

The following records are defined in the database dxpSystem.template. One instance of this database is loaded for each FalconX system, since they control system-wide parameters. All of the record names in the template file are preceeded by the macro parameter $(P), the prefix for this detector system.

dxpMED.template

The following records are defined in the database dxpMED.template (MED stands for Multi-Element Detector). One instance of this database is loaded for each system, since they control system-wide parameters. Only the records in this database that are intended for use by EPICS clients are documented here. Records that are not intended to be accessed from clients are not documented, since they may be changed in the future. Records in this database are implemented in several ways. Some are connected to an MCA record that is configured with a special address that signifies that it controls all detector channels. That record communicates directly with the driver. Other records are implemented in a State Notation Language program which monitors the system-wide records like PresetMode, and copies them to the individual detector records.

All of the record names in the template file are preceeded by the macro parameter $(P), the prefix for this detector system.

dxpMapping.template

The following records are defined in the database dxpMapping.template. One instance of this database is loaded for a FalconX system, since they control system-wide mapping parameters.

This document does not attempt to explain the mapping mode features of the FalconX that these records control. The user should read the FalconX mapping document to understand the mapping features. Note that the document says that list mode mapping is supported, but this is not yet the case, currently only MCA mapping is supported by the XIA Handel library.

All of the record names in the template file are preceeded by the macro parameter $(P), the prefix for this detector system.

Using mapping mode

In the mapping mode data are collected into a double-buffered memory on the module. When one half of the buffer memory is full the EPICS driver reads the data from that buffer and converts it into an NDArray object. If NDArrayMode=Raw buffers then there is no conversion of the buffer when it is copied to the NDArray. If NDArrayMode=MCA spectra then the buffer is unpacked into an NDArray of dimensions [numMCAChannels, numDetectors]. The driver then calls any registered plugins with that NDArray. The plugins will typically be one of the NDPluginFile plugins which will write the data to disk. The useful file plugins can write the data in netCDF, NeXus/HDF5, and TIFF formats. The JPEG plugin will not be useful, because the data are not images. The data can also be passed to the NDPluginStdArrays plugin which can make the data available to EPICS channel access clients as waveform records.

When NDArrayMode=Raw buffers the data in each NDArray object is a 32-bit unsigned integer array with dimensions [BufferSize, NumDetectors]. BufferSize is the size of the double-buffered memory in use, which is controlled by the AutoPixelsPerBuffer and PixelsPerBuffer records. It has a maximum value of 4456704 but can be smaller than this. In MCA mapping mode the buffer for each module in this array contains the data for each pixel, including the elapsed live and real time, triggers and events, and the MCA data. In List mapping mode the buffer will contain the event data for each x-ray event. The details of the buffer structure are beyond the scope of this document, but the buffer structure is thoroughly described in the FalconX mapping document.

To collect mapping mode data one would typically execute the following steps:

1. Select the MCA mapping mode (CollectMode record)
2. Select the pixel advance mode (PixelAdvanceMode record)
3. Select the number of pixels per run (PixelsPerRun record)
4. In the netCDF or HDF5 plugin
   • Set the Enable record to Enable.
   • Set the FilePath, FileName, FileNumber, FileTemplate, AutoIncrement, FileWriteMode, NumCapture, and Autosave records to the desired values. Typically AutoIncrement=Yes, FileWriteMode=Stream, NumCapture= number of buffers to be captured = PixelsPerRun/PixelsPerBuffer.
   • If FileWriteMode is Stream then start capture/streaming with the Capture record. NOTE: Before stream or capture can be started there must have been at least 1 callback to the plugin in the current mapping mode with the same CollectMode and PixelsPerBuffer currently in use. This is because stream and capture modes need to know the buffer size that will be received at the time that capture/streaming is started. This can be done by simply enabling the file plugin and doing a quick run. Just start a run, advance a few pixels with the NextPixel record, and stop the run. Even though only a few pixels have been collected the entire buffer is read out, so the size is correct.
5. Start acquisition with the EraseStart record.
6. Do something that causes the pixels to advance. This could be using the NextPixel record, or an external advance source such as a pulse generator, motor pulse train, etc.
7. Each time a buffer fills up the file plugin will be called, writing data to disk.
8. Each time the buffer fills up the MCA spectra for the first pixel in that buffer will be sent to the MCA records, so they can be displayed. This provides a periodic visual feedback on the MCA data.
9. Once the requested number of pixels per run has occured acquisition will automatically stop.
10. If the file plugin is in stream mode and NumCapture was specified correctly, then it will also automatically stop capturing when the last buffer is received. If NumCapture was 0 or was too large, then stream/capture should be manually stopped by writing 0 to the Capture record.

Data acquisition in mapping mode is very flexible. When doing a 2-D map, for example, one could stream the data for the entire map into a single large netCDF file. Alternatively, one could save just a single scan row into each file, and restart the file plugin for each row, using a new file name, or auto-increment on the file number. Data can be saved into HDF5, NeXus, netCDF or TIFF files.

There are IDL functions available in the CARS IDL detector package to conveniently extract the mapping mode data from netCDF files produced with the netCDF plugin. read_nd_netcdf.pro reads the data from a netCDF file written by the areaDetector NDFileNetCDF plugin. If raw buffers were written to the file then decode_falcon_buffers.pro can be used to decode the data.

medm screens

The following are screen shots of the medm screens for the FalconX.

Installing the EPICS dxpSITORO software

To install the dxpSITORO software first decide whether you want to build the software from source code, or install the pre-built binaries. The Windows binaries should run on almost any version of Windows. The Linux binaries are normally built with Redhat RHEL7, but builds for other Linux versions can be provides on request.

Building from the source code requires downloading EPICS base and all of the required synApps components, including areaDetector/ADCore and ADSupport. To build from source code on Windows requires Microsoft Visual Studio 2015 or later, plus perl and GNU make. It is beyond the scope of this document to describe how to build the source code. Consult other EPICS documentation for this.

The dxpSITORO software provides example IOC directory, iocBoot/FalconX. This create EPICS process variables with names like dxpSITORO:dxp1:DetectorPolarity, where dxpSITORO is the "prefix" for the process variable names, dxp1 is for the first detector channel, and DetectorPolarity is the parameter being controller. This prefix would be OK for installations where there will be at most one FalconX on the subnet. However, in many cases there will be the possibility of more than one FalconX module 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. The following is how to give your IOC a unique prefix, 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 subnet, 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 iocFalconX directory, for example to ioc13IDD_FalconX.
• Edit all files in that directory (including 4element.cmd, 4element.substitutions, and START_IOC*), changing all occurances of the prefix dxpSITORO: to another prefix, for example to the prefix 13IDD_SITORO:.
• 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.
• The next time you unpack a new version of the EPICS dxpSITORO software it will overwrite the iocFalconX directory. However, if you have made your own new directory that will not be modified.

The dxpSITORO application uses the EPICS save/restore facility. This means that all of the important parameters that you might change when running the software 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 many other parameters. The next time EPICS is started it will restore these values automatically from the file called autosave/auto_settings4.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.

Even if the EPICS IOC will be run on Linux it is advisable to install have a Windows PC on which you should install the latest version of the Prospect software from XIA. ProSpect is needed to "characterize" the detector, which measures the pulse shape from each detector element and derives a model to fit the shape. ProSpect can also run a Configuration Wizard that will create an initial .ini file with the correct settings for your system. You can copy that file to the iocFalconX directory or edit the falconxn4.ini file there. It is useful to have ProSpect available on the computer to compare with the EPICS software.

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 ./epics_adls, and if you unpacked the synApps modules include areaDetector into ./epics/support and unpacked the dxpSITORO distribution into ./epics/support/dxpSITORO then type the following commands at the Linux or Cygwin bash shell prompt:

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

Define the environment variable EPICS_DISPLAY_PATH to point to this epics_adls directory. For the Windows shell use the Windows Control Panel/System/Advanced/Environment Variables.

If you installed pre-built binaries, rather than building from source, then edit the envPaths file in iocBoot/iocFalconX. 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.