DXP - EPICS software for XIA Digital Signal Processing Systems

Contents

• Overview
• Architecture
• EPICS Records, Databases, and medm screens
  • dxpHighLevel.template
  • dxpSCA_16.template
  • dxpLowLevel.template
  • dxpSystem.template
  • dxpSaturn.template
  • microDXP.template
  • Single-element detector medm screens
  • dxpMED.template
  • Multi-element detector medm screens
  • dxpMapping.template
• Using mapping modes with the xMAP and Mercury
• Installing EPICS
  • Windows
  • Linux
• Running
  • Saturn
  • MicroDXP
  • xMAP
  • Mercury
• Performance

Overview

The EPICS DXP module provides support for the digital signal processor based multichannel analyzers from X-ray Instrumentation Associates (XIA). These devices all contain the functional equivalent of the shaping amplifier, ADC, and MCA of a conventional pulse-height analysis system. The term "DXP" in this document stands for Digital X-ray Processor, and refers to all models of the XIA hardware.

DXP 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 copper or fiber-optic bridge, but can also be controlled by a CPU processor card in the PXI crate itself.
• The Mercury (single channel) and Mercury4 (4 channel) standalone desktop units that communicate over the USB 2.0 port. They both have similar mapping features to the xMAP. Where the term Mercury is used in this document it applies to both the Mercury and Mercury4 unless otherwise stated.
• The Saturn, which is a standalone desktop unit that communicates over the PC Enhanced Parallel Port (EPP) or USB port. The Vortex detector from Hitachi (formerly SII and Radiant) is an OEM version of the Saturn, and it also works with this software.
• The MicroDXP, which is a board-level product sold to OEMs to embed in their products. It is used in some Ketek SDD detectors and in some Vortex electronics from Hitachi. It is similar to the Saturn, i.e. it is a single-element system that does not support mapping. It does not have a Gate input.

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, or with a CPU card running Windows directly in the PXI crate.
• The Mercury with the EPICS IOC running on Windows or Linux using the USB 2.0 interface.
• The Saturn with the EPICS IOC running on Windows with the USB-2.0 interface or on Linux using the EPP parallel port, USB 1.0, or USB 2.0 interfaces.
• The MicroDXP on Windows or Linux using the USB-2.0 interface.

On Windows the EPICS win32-x86 (32-bit) and windows-x64 (64-bit) architectures are supported. These architectures use the Microsoft VC++ compiler.

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 Python, 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, Mercury, Saturn, and MicroDXP.
• The Saturn, Mercury, and MicroDXP can be run from Windows and Linux, while the XIA control programs only run on Windows.

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 XIA Xerxes 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 DXP, including peaking times, pileup rejection criteria, etc. These are also used for data acquisition in the mapping modes and to acquire diagnostic data, such as the baseline histogram and ADC trace. These records use the standard asyn device support.
• A State Notation Language program (dxpMED) for synchronizing acquisition, ROIs, and DXP parameters in multi-element detector systems.
• Support for the file-saving plugins from the areaDetector package. These plugins are used to stream data to disk in the mappping modes on the xMAP and Mercury.
• Databases for single-element and multi-element detector systems.
• medm display screens for single-element and multi-element detector systems.
• Example IOC boot directories for the Saturn, Mercury, and MicroDXP on Windows and Linux, for the xMAP on Windows.

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.

EPICS Records and Databases

This document does not attempt to explain the meaning or use of all of the DXP parameters. The best documentation of the operation of the DXP modules is provided by XIA in the xMAP User's Manual, Mercury User's Manual, and the Saturn User's Manual. These manuals all provide an excellent description of the theory of digital pulse processing as implemented in the DXP models from XIA. They also describe the XIA xManager and ProSpect software, which can be useful in setting up and testing the hardware, but which do not apply when running the EPICS software. The xMAP and Mercury manuals also explain the mapping modes that these models support.

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 DXP 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 6 only to input records. If there is no auto_settings*.sav file then most of the DXP 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, for example by xManager or ProSpect.

dxpHighLevel.template

The following records are defined in the database dxpHighLevel.template. They control the high-level DXP 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_16.template and dxpSCA_32.template

The following records are defined in the databases dxpSCA_16.template and dxpSCA_32.template. They control the 16 (Saturn and MicroDXP) or 32 (xMAP and Mercury) single-channel-analyzers (SCAs) for each channel. Each SCA is defined by a low channel and a high channel. In normal MCA Spectra mode the counts in each SCA are computed by the DXP firmware when acquisition completes. This is essentially the same information as in the MCA record ROIs. However, the SCAs are also used in the fast SCA mapping mode on the xMAP. In this mode only the total counts in each SCA are stored at each point in the map. This mode is faster than full spectrum mapping, and also uses much less disk space. The SCA definitions are also used on the Saturn (when it is equipped with the optional SCA mapping hardware and firmware) and Mercury for hardware ROI mapping. The Saturn and Mercury put 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. The Saturn has 16 such TTL output lines, the Mercury has 14 lines, and the Mercury4 has 24 lines (6 per channel). Note: in normal MCA spectra mode SCAs are permitted to overlap in channels. However in the SCA mapping mode and SCA pulse output mode, the SCA definitions must not overlap. This is because, for performance reasons, each spectrum channel must be assigned to at most one SCA.

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.

dxpLowLevel.template

The DXP firmware is actually controlled by a large number of low-level parameters. Each of these parameters is a 16-bit integer. Typically the user will only interact with the high-level parameters described above. But it can sometimes be useful to read or even modify one of these low-level parameters. The EPICS software provides a completely generic interface to these low-level parameters. When the driver initializes it queries the names of all of the low-level parameters, and makes these names available in stringin records. There is a longin record which provides the current value of each parameter, and a longout record which allows the parameter to be modified. Note that all parameters have a corresponding longout record, but some parameters are inherently read-only, so their longout records actually do nothing. The driver currently hardcodes a maximum of 300 low-level parameters, which is more than the number used by any of the existing firmware (273 is the current maximum, for the MicroDXP firmware). If a future firmware version has more parameters than this, then a single constant in the driver will need to be increased, and more records will need to be added to dxpLowLevel.template.

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.

dxpSystem.template

The following records are defined in the database dxpSystem.template. One instance of this database is loaded for each DXP system, since they control system-wide parameters. This database is loaded for both single-element (Saturn, Mercury, and MicroDXP) and multi-element (xMAP, and Mercury4) systems. All of the record names in the template file are preceeded by the macro parameter $(P), the prefix for this detector system.

dxpSaturn.template

The following records are defined in the database dxpSaturn.template. One instance of this database is loaded for a Saturn 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.

• TraceMode. The choices for the TraceMode and TraceMode_RBV records are redefined from those in dxpHighLevel.template to only include the first 2 choices, e.g. "ADC" and "Baseline history".
• PresetMode. The choices for the PresetMode and PresetMode_RBV records are defined from those in dxpHighLevel.template to only include "None", "Real time" and "Live time".
• TraceData. The NELM field is redefined from the 4096 value in dxpHighLevel.template to 4000, because that is the size of the trace array on the Saturn.
• TraceTime. The NELM field is redefined from the 4096 value in dxpHighLevel.template to 4000, because that is the size of the trace array on the Saturn.

microDXP.template

The following records are defined in the database microDXP.template. One instance of this database is loaded for a MicroDXP 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.

• Gain. The analog gain for the signal input. This is used in place of the PreampGain on the MicroDXP. Increasing this value moves the peaks to higher channel numbers. Typical values are in the range of 5-50.
• FineGain The analog fine-gain for the input signal. Increasing this value moves the peaks to higher channel numbers.

Single element detector medm screens

The following is the top-level medm screen for the DXP software. It loads the screens for each of the example IOCs.

dxpTop.adl

Top-level DXP control screen.

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

dxpSaturn.adl

Main control screen for Saturn.

dxpLowLevel.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_trace.adl

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

The following is a screen shot of the medm screen provided for the MicroDXP. Only the top-level screen is different from the Saturn, all of the other screens are the same.

microDXP.adl

Main control screen for MicroDXP.

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 multi-element (xMAP, and Mercury4) DXP 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.

Multi-element detector medm screens

The following are screen shots of the medm screens provided for multi-element detectors, e.g. xMAP and Mercury.

16element_dxp.adl

Main control screen for 16element system.

16elementFilters.adl

Screen to control DXP filter parameters.

Screen to control DXP pre-amp and MCA parameters.

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_dxp_presets.adl

Screen to display presets for each detector.

mercuryOutputs.adl

Screen to control the Mercury trigger and livetime auxiliary outputs.

16element_dxp_statistics.adl

Screen to display the elapsed statistics 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_trace.adl

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

dxpMapping.template

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

This document does not attempt to explain the mapping mode features of the xMAP or Mercury that these records control. The user should read the chapter on Mapping Mode in the xMAP User's Manual or Mercury User's Manual to understand the mapping features of these models. The short document on using the Handel library for mapping mode on the xMAP Handel Quick Start Manual for the xMAP can also be useful. Though the material discussed there was mostly useful for writing the EPICS driver, it can also help to understand how the system works.

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

Using mapping modes with the xMAP and Mercury

In the mapping modes on the xMAP and Mercury 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 into an NDArray object. It 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.

The data in each NDArray object is a 16-bit unsigned integer array with dimensions [BufferSize, ModulesPerSystem]. 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 2^20 (1048576) but can be smaller than this. ModulesPerSystem is the total number of xMAP modules in the system, and is always 1 for the Mercury. In MCA mapping and SCA mapping modes 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 or SCA data. In List mapping mode the buffer contains 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 section entitled "Mapping Mode Data" in the xMAP User's Manual and Mercury User's Manual.

The EPICS software does not provide records to configure the Gate, Sync, or LBUS masters in the system. This is because there can be a variable number of these depending on how many PCI bus segments the xMAPs use. The Gate, Sync, and LBUS masters should be configured with the xManager configuration wizard, or by directly editing the .ini file. The values for the masters in the .ini file will be used, EPICS does not modify them.

The following medm screen is used to configure the mapping modes on the xMAP and the Mercury.

mappingControl.adl

The following medm screen is used to configure the netCDF file plugin to save mapping mode data on the xMAP and the Mercury.

NDFileNetCDF.adl

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

1. Select the mapping mode (CollectMode record)
2. In MCA mapping and SCA mapping modes:
   • Select the pixel advance mode (PixelAdvanceMode record)
   • Select the number of pixels per run (PixelsPerRun record)
3. In List Mapping mode:
   • Select the list mode variant (ListMode record)
4. In the netCDF 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 or Capture 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. In MCA mapping or SCA mapping modes 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. In List mapping modes the buffer fills up with event data even if the Sync or Gate pixel clock is not advancing.
7. Each time a buffer fills up the netCDF plugin will be called, writing data to disk.
8. In MCA mapping mode 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. In MCA and SCA mapping modes once the requested number of pixels per run has occured acquisition will automatically stop. In List mapping mode acquisition must be manually stopped with the StopAll record.
10. If the netCDF plugin is in stream or capture 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 also be saved into NeXus or TIFF files, rather than netCDF files.

Which mapping mode to use depends on the needs of the experiment. If only the counts in ROIs are needed then it is most efficient to collect data in SCA mapping mode. The counts in the SCAs are the total counts, with no background subtraction. However, it is possible to define additional SCAs in regions of no peaks, and correct for background during post-processing by using these "background" SCAs to estimate the background counts per channel. List mapping mode can be used to collect data with very high time resolution (20 ns). It is also often more faster and more efficient in disk space than MCA mapping mode, with essentially the same information. The speed and file size in List mapping mode depends of course on the number of x-rays per second. Each x-ray event requires 6 bytes (2 for the x-ray energy, and 4 for the clock time or pixel number). Consider a 4-detector xMAP system with a count rate of 100,000 cps per detector. The total data rate in List mapping mode will be 4 detectors * 100,000 events/s * 6 bytes/event = 2.4 MB/sec. That can be compared to running the same system in MCA mapping mode with 2048 channel spectra at the fastest possible pixel rate, 1000 pixels/s. In that case the data rate is 4 detectors * 2048 channels * 2 bytes/channel * 1000 pixels/s = 16MB/s. In this case List mapping results in almost 7 times less data than MCA mapping, because most of the spectral channels are 0 in MCA spectra mode. The only significant difference is that in list mode there is no measure of live time at each "pixel", and it will require more post-processing to arrange the data into spectra, if that is what is desired.

This is a Python program called fast_mapping.py that implements such a 2-D scan. This is a simple program that was written by Yan Fen and me at the SSRF (Shanghai Synchrotron). It works as follows:

• The system contains an SIS3820 multi-channel scaler. This has its external channel advance connected to the stepper motor pulses driving the X sample stage. The External Prescale is set to divide these pulses by the number of motor pulses per pixel. Each time the X stage motor moves by this amount the SIS3820 collects the data from the ion chamber (I0) and other counter inputs into its MCA records. It also outputs a trigger pulse on its CIP output, which is input into the xMAP Sync input to do a pixel advance on the xMAP.
• There are 2 EPICS sscan records.
  • X15U1:test:scan1 is the fast inner scan. It drives the X stage motor. It is configured to collect 1-D arrays, which are the SIS3820 MCA records. These are saved into MDA files by the saveData utility in EPICS. It has detector triggers for the SIS3820 EraseStart PV. However, this is just to forces the sscan record wait until the SIS3820 is done at the end of the row. It is actually necessary to start the SIS3820 and xMAPs before the scan starts. This is because the sscan record begins moving the motor before it fires its detector triggers, and that will not work here, they need to start counting before the motor starts moving. When each row is collected this scan is started by the Python script. It will save the SIS3820 counters into a separate MDA file for each row, because it does not think a 2-D EPICS scan is in progress.
  • X15U1:test:scan2 is the slow outer scan. Its positioner is the Z stage motor. However, we are only using this scan as a convenient place for the user to enter the start, end, step size and number of points of the Z scan. This scan record is not actually executed. Rather the Python program reads the PVs for this scan and moves the motor itself. The reason for this is that there are things that need to be done at the start of each row that are much more easily done in the Python program than in the sscan record. This includes setting up the netCDF file plugin, starting the SIS3820 and xMAP, etc.
• At the very beginning of the 2-D scan the Python code does the following:
  • Reads the size of the scan in the X and Z directions (nFast, nSlow) from the sscan records.
  • Writes nFast into the NuseAll PV of the SIS3820 so that it stops after this many channel advances. It also writes nFast into the xMAP PixelsPerRun PV to set the number of pixels per run.
  • Computes the number of xMAP buffers that each scan row will require. This is ((nFast+1)/124 + 1), because each buffer can hold 124 pixels when collecting 2048 channel spectra. (To be more general it should read the value of PixelsPerBuffer from the xMAP rather than hardcoding 124). Writes this value into the NumCapture PV of the netCDF plugin.
  • Writes the desired base file name into the FileName PV of the netCDF plugin.
  • Writes 1 into the FileNumber PV of the netCDF plugin. The netCDF file plugin was also previously configured to have a valid FilePath, AutoIncrement=Yes, and FileTemplate="%s%s_%d.nc". It was thus saving files with names like MyScan_1.nc, MyScan_2.nc, ... for rows 1, 2, ... of the scan.
  • Sets the netCDF file plugin FileWriteMode PV to Stream (choice 2). This means that all of the pixels for one scan row will be streamed into a single netCDF file.
• The Python program then executes a 1-D loop over the number of rows (Z stage pixels) in the scan. For each row of the scan it does the following:
  • Starts the netCDF plugin streaming by writing 1 to the Capture PV.
  • Sets the speed of the X stage motor to its fast flyback speed.
  • Starts the X stage moving to the start position.
  • Starts the Z stage moving to the position for this row.
  • Waits for the X and Z stages to arrive at their target positions.
  • Sets the speed of the X stage motor to the desired scan speed (i.e. pixel size / time per pixel).
  • Erases and starts the SIS3820.
  • Erases and starts the xMAP. Waits 0.5 seconds after this to allow the xMAP to be ready.
  • Starts the fast scan (scan 1). That will start the X stage moving, and will wait for the SIS3820 to complete. saveData will write the SIS3820 MCA data to the MDA file at the end of the scan row.
  • Waits for the xMAP to be done.

There are IDL functions available in the CARS IDL detector package to conveniently extract the MCA, SCA, or List mode data from netCDF files produced with the netCDF plugin. read_xmap_netcdf.pro reads mapping data from a single netCDF file. It calls read_nd_netcdf.pro and decode_xmap_buffers.pro. read_xmap_2d.pro is an IDL procedure that calls read_xmap_netcdf.pro to read all of the netCDF files for an entire 2-D scan collected by programs such as the Python program described above.

The following is an IDL program that calls read_xmap_2d for a 501x500 scan of a Ni mesh. It extracts the Ni Ka peak (channels 716 to 776) from the data. It sums over all the channels in this region, normalizes by live time, sums over all 7 detectors, and finally displays the image with the IDL iTools iimage procedure.

    ; Read data, only channels 716 to 776
    d = read_xmap_2d('Scan4_', 501, live_time=live_time, real_time=real_time, $
                     events=events, triggers=triggers, channel=[716,776])
    ; Sum over channels 716 to 776 (first dimension)
    tot = total(d, 1)
    ; Divide by live time for each detector for each pixel, but live=0 increase to .001
    tot1 = tot/(live_time>.001)
    ; Sum over the detectors
    tot2 = total(tot1, 1)
    ; Display
    iimage, tot2
end

This scan was done at SSRF with the following parameters:

• 1x1 micron pixels.
• 500x501 pixel scan.
• 2.5 ms per pixel
• 7-element Si(Li) detector with 2 xMAP modules.
• Total scan time was 38 minutes

This is the image produced from the "iimage" command in the above program after interactively adding some annotation.

This is another example of a scan done at SSRF of a mouse spleen with the following parameters:

• 3x3 micron pixels.
• 530x647 pixel scan.
• 20 ms per pixel
• 7-element Si(Li) detector with 2 xMAP modules.
• Total scan time was 178 minutes

This is the image produced by summing over the counts in the channel regsions for K, Fe, and Zn. The image in the lower right is a visible light image from the sample microscope.

This spectrum of a 10x10 pixel region high in Zn in the above image. It was produced by reading the entire spectrum for 10x10 pixel region and then summing over all 100 pixels, and then summing over all 7 detectors.

This is an example of decoding the buffers in IDL for List Sync mode data. It computes and plots the histogram (spectrum) of all of the events.

IDL> buff = read_nd_netcdf('list_mapping_sync_001.nc')
IDL> help, buff                                       
BUFF            INT       = Array[1048576, 4]
IDL> d = decode_xmap_buffers(buff)                    
IDL> help, /structure, d                              
** Structure XMAPLISTDATA, 8 tags, length=32, data length=32:
   LISTMODE        LONG                 1
   PDATA           POINTER   <ptrheapvar17>
   PPIXELCLOCK     POINTER   <PtrHeapVar18>
   PNUMEVENTS      POINTER   <PtrHeapVar19>
   PREALTIME       POINTER   <PtrHeapVar20>
   PLIVETIME       POINTER   <PtrHeapVar21>
   PINPUTCOUNTS    POINTER   <PtrHeapVar22>
   POUTPUTCOUNTS   POINTER   <PtrHeapVar23>
IDL> help, *d.pData                                   
<PtrHeapVar17>  INT       = Array[349525, 4]
IDL> help, *d.pPixelClock
<PtrHeapVar18>  LONG      = Array[349525, 4]
IDL> help, *d.pRealTime
<PtrHeapVar20>  FLOAT     = Array[16]
IDL> h = histogram((*d.pData) and 8191)
IDL> iplot, h, yrange=[1,1e3], /ylog

This is the histogram (spectrum) of all of the events for all detectors. Note that bits 13 and 14 (detector channel number 0-3) for each event are masked off.

Installing the EPICS DXP software

To install the EPICS DXP software first decide whether you want to build the EPICS DXP software from source code, or install the pre-built binaries (Windows only).

Building from the source code requires downloading EPICS base and all of the required synApps components. It is beyond the scope of this document to describe how to build the source code. Consult other EPICS documentation for this.

The DXP software provides example IOC directories, iocBoot/iocSaturn, iocBoot/iocMicroDXP, iocBoot/iocXMAP, iocBoot/iocMercury. These create 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. The default prefixes are dxpSaturn:, microDXP:. dxpXMAP:, and dxpMercury. These prefixes would be OK for installations where there will be at most one IOC of a given type on the subnet. However, in many cases there will be the possibility of more than one DXP 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 EPICS DXP application uses the EPICS save/restore facility. This means that all of the important parameters that you might change when running the DXP 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_settings.sav. On multi-element systems the files are called auto_settings4.sav, or auto_settings16.sav, etc. 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.

The DXP IOC application and EPICS clients both need to be able to start the EPICS caRepeater application. This application is built as part of EPICS base. If you are installing the Windows prebuilt versions of the DXP software you can obtain caRepeater as part of the EPICS Windows Tools package, which includes medm. Put the installation directory into your PATH environment variable. That way EPICS will be able to find caRepeater. It will also provide many useful EPICS shell utilities, such as caput, caget, camonitor, etc.

Installing the DXP software on Windows

To install the EPICS DXP software with a Saturn, MicroDXP, Mercury, or xMAP on a Windows PC do the following:

• To use the USB 2.0 interface with the Saturn, MicroDXP or Mercury:
  • Install the latest version of Prospect for the appropriate model from XIA. This will install the required Windows drivers for the USB 2.0 interface.
• For an xMAP system do the following:
  • Install the PCI/PXI converter from National Instruments.
  • Install the National Instruments driver software.
  • Install the latest version of the xManager software from XIA. This will install the Plx driver that is used to communicate with the xMAP modules. It will also run a Configuration Wizard that will create an initial .ini file with the correct PCI bus and slot addresses for your system. 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.). It is useful to have xManager available on the computer to compare with the EPICS software.
• If you want to run the medm display program on the Windows PC, which is recommended in most cases, you need to install an X11 server. MobaXterm provides a free version which works well, and OpenText Exceed is a commercial package that also works well. After installing Exceed you need to install the EPICS Windows Tools, which contain medm.
• Download source code from Github or the latest standalone release of the EPICS DXP software, containing pre-built Windows binaries.
• If using the pre-built version unpack that distribution into a directory such as C:\EPICS or C:\Program Files\EPICS.
• Copy all of the medm .adl files into a single directory, for example C:\EPICS\adls. This is simpler than defining EPICS_DISPLAY_PATH to point to all of the required directories. Define the environment variable EPICS_DISPLAY_PATH to point to C:\EPICS\adls. 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/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.

The XIA software is very slow when downloading the firmware files (.fdd files) to the hardware when the files reside on a remote file system. It is best to put the FDD files on a local file system, particularly when using an xMAP system with multiple xMAP modules.

Installing the DXP software on Linux

To use the EPICS DXP software with a Saturn, MicroDXP, or Mercury on a Linux computer do the following:

• To use the USB 1.0 or USB 2.0 interface:
  • Install the libusb-devel package using your system's package manager.
• To use the EPP interface the machine must have a parallel port that is capable of operating in EPP mode.
  • Reboot the machine and enter the BIOS configuration screen. Configure the parallel port to operate in EPP mode.
• Download the latest source code release, of the DXP software. You will need to build that with EPICS base and other synApps modules, including areaDetector/ADSupport and ADCore. The procedure for building from source is beyond the scope of this document.
• 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 your synApps distribution including dxp is in /home/epics/epics/synApps/support, then type the following commands at the shell prompt:

        $ mkdir /home/epics/epics_adls
        $ find /home/epics/synApps/support -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 2 ways:
  1. Better method. Install the dxpApp application as suid root. Do this as follows:

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

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

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

  2. Less desirable method. Run dxpApp as root:

               > cd iocBoot/iocSaturn
               > su root
               (password)
               > ../../bin/linux-x86_64/dxpApp st.cmd
               or
               > sudo ../../bin/linux-x86_64/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, MicroDXP, or Mercury is connected, this cannot just be done once statically. Rather it requires using the "udev" facility on Linux to have the device permissions set correctly each time the device connects. To use udev to allow non-root access to the devices do the following:
  1. Create a file in /etc/udev/rules.d called, for example, "80-xia.rules". Put the following lines in this file.

                
     SUBSYSTEM=="usb",ACTION=="add",ATTRS{idVendor}=="10e9",ATTRS{idProduct}=="0700",MODE="0666"
     SUBSYSTEM=="usb",ACTION=="add",ATTRS{idVendor}=="10e9",ATTRS{idProduct}=="0701",MODE="0666"
     SUBSYSTEM=="usb",ACTION=="add",ATTRS{idVendor}=="10e9",ATTRS{idProduct}=="0702",MODE="0666"
     SUBSYSTEM=="usb",ACTION=="add",ATTRS{idVendor}=="10e9",ATTRS{idProduct}=="0703",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 or Mercury whenever it is added to the system. 10e9 is the vendor ID for XIA. 0700 and 0701 are the product IDs for the USB 1.1 and USB 2.0 versions of the Saturn. 0702 and 0703 are the product IDs for the Mercury and Mercury4. Note that the 10e9 ID is case sensitive! For other models (MicroDXP from Hitachi or Ketek for example) use the lsusb command to see what the vendor ID and product ID is for the device when it is plugged into the system. Create a new line in the 80-xia.rules containing those values.
     Note that the Linux "udev" facility has been evolving quite rapidly. The above lines work on a relatively recent Linux kernel (2.6.27). On older kernels the following syntax was required:

     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"
     SUBSYSTEM=="usb_device",ACTION=="add",SYSFS{idVendor}=="10e9",SYSFS{idProduct}=="0702",MODE="0666"
     SUBSYSTEM=="usb_device",ACTION=="add",SYSFS{idVendor}=="10e9",SYSFS{idProduct}=="0703",MODE="0666"
              

     In the older version the SUBSYSTEM is "usb_device" rather than "usb", and the SYSFS keyword rather than ATTRS is used.
  2. Force the udevd daemon to reload its rules:

                $ /sbin/udevcontrol reload_rules
              

  These changes for udev should cause the Saturn or Mercury 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. One can 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/ and iocBoot/iocMercury have execute permission. This can be done by 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.

Running the EPICS DXP software

Running the Saturn

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

• Edit saturn.ini in the IOC directory. 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).
• 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 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.

Running the MicroDXP

The iocBoot/iocMicroDXP contains a file called KETEK_DPP2_usb2.ini. You may need to edit this file, although I have used it unchanged for both a Ketek and Hitachi Vortex MicroDXP. The IOC is started the same way as for the Saturn above.

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 or 16 channels (1 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 Windows cmd shell:

          cd iocBoot\iocXMAP  # Or the new directory you created
          ..\..\bin\windows-x64\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_WIN32.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 may need to edit these batch files to set the prefix for your IOC, the location of your medm adl files, etc.
• You can do scans and save complete spectra with the EPICS sscan and saveData facilities.

Running the Mercury

The Mercury can be run under Linux or Windows. As with the Saturn and xMAP described above there is an example mercury4.ini, and there are example startup scripts (START_IOC for Linux, and START_IOC_WIN32 for Windows).

Performance

Normal MCA Spectra Mapping Mode

The following measurements were done in normal MCA Spectra mode with R3-0 of the dxp module to determine the performance of the DXP software in rapidly collecting complete spectra in a scan. The tests were done with the following conditions:

• Both cygwin-x86 and win32-x86 architectures on Windows. However, spectra were only saved to disk when testing with the cygwin-x86 architecture, because win32-x86 did not support the saveData software at the time of these tests. saveData is now supported on both win32-x86 and windows-x64.
• 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 the EraseStart record. Its detectors were configured to collect spectra from the MCA records. The Saturn collected 1 MCA spectrum at each scan point, the xMAP, Mercury, and DXP2X collected 4 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 positioner readback was "time", which is how the time to execute the scan was measured.
• The scan fields of the MCA status, MCA read, and DXP read records were Passive to minimize overhead. The poller thread time was .01 seconds on the Saturn and DXP2X, .005 seconds on the Mercury, and .001 seconds on the xMAP. Callbacks 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 for the xMAP is shown in this screen shot.

Mapping Mode

The following measurements were done in using the MCA Mapping and MCA Mapping modes with R3-0 of the dxp module to determine the performance of the DXP software in rapidly collecting data in a scan. The tests were done with the following conditions:

• Both cygwin-x86 and win32-x86 architectures on Windows.
• 2048 channel spectra in MCA Mapping mode
• 32 SCAs (ROIs) in SCA Mapping mode
• External Sync pixel advance mode
• The external sync signal was generated with an SIS3801 multichannel scaler. The SIS3801 was operated in internal channel advance mode. The dwell time was set to be the fastest that would work before errors began, with 100 microsecond resolution, e.g. 3.6 ms per pixel worked and 3.5 ms per point failed.
• netCDF file saving plugin used to stream the data to a local disk.
• 2000 points were collected.
• The system configuration for the Mercury test is shown in this screen shot.