areaDetector: Installation Guide ================================= Marty Kraimer, Brookhaven National Laboratory --------------------------------------------- Mark Rivers, University of Chicago ----------------------------------- This product is made available subject to acceptance of the [EPICS open source license](http://epics-pvdata.sourceforge.net/LICENSE.html) Introduction ------------ This is a guide for installing and building R2-0 and later of the EPICS areaDetector module. This guide is intended for both areaDetector users and developers. areaDetector can be obtained as a release or by cloning from the github repository. This guide provides instructions for: * Installing, building, and running from source code. These instructions should work on any supported EPICS host architecture, e.g. Linux, Windows, Mac OSX. This document assumes that the reader has already installed an EPICS development environment, and has built [EPICS base](http://www.aps.anl.gov/epics/base/R3-14), the [EPICS asyn module](http://www.aps.anl.gov/epics/module/soft/asyn), and the required [EPICS synApps modules](http://www.aps.anl.gov/bcda/synApps). * Installing and running a pre-built binary distribution. Installing and Building from Source Code ======================================== The build process attempts to make the build process easy for typical cases but allow site specific overrides. areaDetector uses many other products. EPICS Products Required for Building areaDetector ------------------------------------------------- areaDetector requires [EPICS base](http://www.aps.anl.gov/epics/base/index.php). Any relatively recent R3.14 release should work. areaDetector also requires [asyn](http://www.aps.anl.gov/epics/modules/soft/asyn/). The most recent release of asyn is recommended. Each areaDetector detector module builds both a library and an EPICS IOC application. To build the library only EPICS base and asynDriver are required. To build the IOC application the [synApps](http://www.aps.anl.gov/bcda/synApps) modules AUTOSAVE, BUSY, CALC, and SSCAN are required. The most recent release of the synApps modules is recommended. EPICS base, asyn and the synApps modules must be built before building areaDetector. External Products Required for Building areaDetector ---------------------------------------------------- areaDetector always uses the TIFF, ZLIB, JPEG, SZIP, and HDF5 libraries, (except on vxWorks where none of these are available). GRAPHICSMAGIC is optional. For Windows areaDetector includes pre-built libraries for these packages and nothing additional needs to be installed. Windows users can skip the rest of this section. In areaDetector releases prior to R2-0 prebuilt versions of these libraries were also included for Linux and Darwin. This became too hard to maintain because of compiler version dependencies, so they are no longer provided. On Linux and Darwin the TIFF, JPEG and ZLIB libraries always need to be installed, whether building from source code or using the pre-built binaries. The HDF5 and SZIP packages need to be installed when building from source code. HDF5 and SZIP do not need to be installed on machines that will only run the pre-built binaries on Linux or Darwin, because the binaries are statically linked and include these libraries in the executable. ### TIFF, JPEG, and Z On Linux and Darwin the libtiff, libjpeg, and libz libraries often come already installed. If they are not already installed then they are normally available for installation via the standard package installation tools, e.g. "yum install" on Redhat systems, "apt get" for Debian systems, etc. If for some reason you cannot install these libraries using the standard package installation tools, they can be installed from source code distributions as follows. For each product download the source code from a product download site and then build. Each site provides some combination of .zip, .tar, .tar.gz, etc. If the file is a zip file then just execute: unzip file.zip If the file is any flavor of tar just execute: tar xf file All of the following products put the result of unzip or tar into a sub-directory. cd to that directory and follow the instructions for the appropriate sub-section. #### TIFF This can be downloaded from [libTIFF](http://www.remotesensing.org/libtiff). Then click on the Master Download Site and download the latest stable release. After the latest release is unziped cd to the release and execute the commands: ./configure make sudo make install The include and library files are installed by default into **/usr/local** ####ZLIB This can be downloaded from [zlib](http://www.zlib.net). Then look for latest release download. After untaring the release ./configure make sudo make install The include and library files are installed by default into **/usr/local** ####JPEG This can be downloaded from [libjpeg](http://www.linuxfromscratch.org/blfs/view/svn/general/libjpeg.html). Read the instructions from the web site about installing. I suggest that it be installed into **/usr/local** instead of **/usr**. Thus to install: ./configure --prefix=/usr/local \ --mandir=/usr/share/man \ --with-jpeg8 \ --disable-static \ &&; \ sed -i -e '/^docdir/ s/$/\/libjpeg-turbo-1.3.0/' \ -e '/^exampledir/ s/$/\/libjpeg-turbo-1.3.0/' Makefile && make make test sudo make install ### HDF5, SZIP, and GRAPHICS_MAGICK On Linux and Darwin these libraries may not be installed, and may not be available via the standard package installation tools. Follow these steps to install them from source. #### SZIP This can be downloaded from [SZIP](http://www.hdfgroup.org/doc_resource/SZIP). Click on **SZIP Source** and download the release that appears. After the latest release is untared, cd to the release and execute the commands: ./configure --prefix=/usr/local make make check sudo make install #### HDF5 This can be downloaded from [HDF Group](http://www.hdfgroup.org/HDF5/). Click on Downloads, then Current Release, then HDF5 Software, then Source Code, then latest release. After the latest release is untared, cd to the release and execute the commands: ./configure --prefix=/usr/local/hdf5 make make check sudo make install make check-install #### GRAPHICSMAGICK This can be downloaded from the mercurial repository with these commands: hg clone http://hg.code.sf.net/p/graphicsmagick/code graphicsmagick-code cd graphicsmagick-code/ ./configure make sudo make install However recent attempts to build or link with GraphicsMagick have led to a variety of errors. Thus, the NDFileGraphicsMagick plugin and ADURL driver have been disabled in areaDetector R2-0 by setting USE_GRAPHICS_MAGICK=NO in areaDetector/configure/CONFIG_SITE.local until these problems are fixed. Downloading and Installing areaDetector Source Code --------------------------------------------------- The areaDetector source code is kept on [gitub.com/areaDetector](https://github.com/areaDetector). It can be downloaded 2 ways: 1. Via the "git clone" command: git clone --recursive https://github.com:areaDetector/areaDetector.git 2. By downloading tar.gz or zip files for a specific release of each module through a Web browser or by the wget command: wget https://github.com/areaDetector/areaDetector/archive/R2-0.tar.gz If downloading tar files then each repository must be downloaded separately. To build the "core" of areaDetector the following repositories must be downloaded: * areaDetector/areaDetector * areaDetector/ADBinaries * areaDetector/ADCore To also build a specific detector, for example the ADProsilica, also download * areaDetector/ADProsilica All of the submodules (i.e. ADBinaries, ADCore, ADProsilica, etc.) should be placed under the top-level areaDetector directory. After all the required products have been installed and a release of areaDetector has been downloaded then do the following in the areaDetector/configure directory: cp EXAMPLE_RELEASE_PATHS.local RELEASE_PATHS.local cp EXAMPLE_RELEASE_LIBS.local RELEASE_LIBS.local cp EXAMPLE_RELEASE_PRODS.local RELEASE_PRODS.local cp EXAMPLE_CONFIG_SITE.local CONFIG_SITE.local ### Edit RELEASE_PATHS.local The definitions for SUPPORT, AREA_DETECTOR, and EPICS_BASE must all be changed. All definitions must include the full path name. The normal way of installing the EPICS components is to install and build ASYN and all synApp components under a single directory located by SUPPORT in this file. ### Optionally create RELEASE_PATHS.local.$(EPICS_HOST_ARCH) Some installations chose to build for multiple target architectures using different development machines in the same directory tree on a file server. In this case the path to SUPPORT, AREA_DETECTOR and BASE may be different for each architecture. For example BASE on Linux might be /usr/local/epics/base-3.14.12.4, while on a Windows machine using the same copy of BASE the path might be H:/epics/base-3.14.12.4. In this case RELEASE_PATHS.local could specify the path for Linux while RELEASE_PATHS.win32-x86 could specify the path for the win32-x86 build host. RELEASE_PATHS.local is read first, and then any definitions there will be replaced by RELEASE_PATHS.EPICS_Target_ARCH if it exists. ### Edit RELEASE_LIBS.local The location of ASYN must be specified. It is normally placed in the SUPPORT directory defined in RELEASE_PATHS.local. If your version has the same path as the one that appears then no changes are necessary. As described above RELEASE_LIBS.local.$(EPICS_HOST_ARCH) can be used if the ASYN version or path is different for a specific target architecture. This is usually not necessary even for building Linux and Windows in the same tree, because only the definition of SUPPORT in RELEASE_PATHS.local.$(EPICS_HOST_ARCH) needs to be changed. ### Edit RELEASE_PRODS.local The definitions for CALC, BUSY, SSCAN, and AUTOSAVE must be specified. If your versions have the same paths that appear no changes are necessary. As described above RELEASE_LIBS.local.$(EPICS_HOST_ARCH) can be used if the ASYN version or path is different for a specific target architecture. This is usually not necessary even for building Linux and Windows in the same tree, because only the definition of SUPPORT in RELEASE_PATHS.local.$(EPICS_HOST_ARCH) needs to be changed. ### Edit CONFIG_SITE.local The definitions for HDF5, SZIP, and GRAPHICS_MAGICK may need to be changed. If the instructions in the preceeding sections are used then CONFIG_SITE.local should be: # Define the location of HDF5 HDF5 = /usr/local/hdf5 HDF5_LIB = $(HDF5)/lib HDF5_INCLUDE = -I$(HDF5)/include # Define the location of SZLIB SZIP = /usr/local SZIP_LIB = $(SZIP)/lib SZIP_INCLUDE = -I$(SZIP)/include # Define the location of Graphics Magic GRAPHICS_MAGICK = /usr/local GRAPHICS_MAGICK_LIB = $(GRAPHICS_MAGICK)/lib GRAPHICS_MAGICK_INCLUDE = -I$(GRAPHICS_MAGICK)/include/GraphicsMagick ### Optionally edit areaDetector/Makefile You can edit this file to change which detectors will be built. Some detectors are commented out in the distribution because they cannot be built on all systems. For example the Roper driver can only be built on Windows systems with the Princeton Instruments WinView or WinSpec programs installed, and the Point Grey driver can currently only be built on Linux systems if the version of libc.so is 2.14 or greater. You may also want to comment out detectors that you don't need. ### make Just type: make If this fails then some required products have probably not been installed. ### Run SimDetector cd ADCore/iocs/simDetectorIOC/iocBoot/iocSimDetector ### Edit Makefile to set ARCH to your $(EPICS_HOST_ARCH) architecture make cp envPaths envPaths.linux ../../bin/linux-x86_64/simDetectorApp st.cmd.linux Installing Pre-Built Binary Versions of areaDetector ==================================================== Pre-built binary versions of areaDetector are provided for ADCore and for each detector. This is provided as a convenience so that it is not necessary to set up a build system to run areaDetector on a specific detector. The instructions here use the Pilatus (ADPilatus) module as an example. Substitute Pilatus with the name of the detector you are working with. The pre-built binaries can be found on the [CARS Web site](http://cars.uchicago.edu/software/pub/). There is a subdirectory there for each detector (e.g. ADPilatus) that contains all of the releases for that detector. The pre-built binaries contain executables for one or more of the following architectures: - linux-x86 (32-bit Linux built on Fedora Core 15, gcc 4.6.3, libc 2.14.1) - linux-x86_64 (64-bit Linux built on Fedora Core 15, gcc 4.6.3, libc 2.14.1) - linux-x86_gcc43 (32-bit Linux build on Fedora Core 9, gcc 4.3.0, libc 2.8) - linux-x86_64-gcc42 (64-bit Linux built on SUSE, gcc 4.2.1, libc 2.6.1) - darwin-x86 (64-bit Mac OSX built on Darwin 11.4.2, ??, clang 4.2) - win32-x86 (32-bit Windows, VS2010 compiler, statically linked) - win32-x86-dynamic (32-bit Windows, VX2010 compiler, dyanamically linked) - windows-x64 (64-bit Windows, VS2010 compiler, statically linked) - windows-x64-dynamic (64-bit Windows, VX2010 compiler, dyanamically linked) Note that the linux-x86 and linux-x86_64 builds are done a relatively new Linux system and will not run on RHEL 6, for example. The linux-x86-gcc43 and linux-x86_64-gcc42 architectures are built on much older versions of Linux, and should run on most Linux systems. Follow these steps to use the prebuilt version. * Create an installation directory for the module. On Windows I typically use C:\EPICS\support. On Linux I typically use /home/ACCOUNT/epics/support, where ACCOUNT is the name of the account that is normally used to run the detector software, e.g. marccd on a marCCD detector, mar345 on a mar345 detector, det on a Pilatus detector, etc. * Place the distribution file in this directory. Then issue the commands (Unix style) tar xvzf ADPilatus_RX-Y.tgz On Windows it is more convenient to download the zip file and extract it using Windows Explorer. * In the ADPilatus/iocs/pilatusIOC/iocBoot/ directory make a *copy* of the example iocPilatus directory and give it a new local name, e.g. ioc13Pilatus1. By doing this you will be able to update to later versions of areaDetector without overwriting modifications you make in the ioc13Pilatus1 directory. * In the new io13Pilatus1 directory you just created edit st.cmd to change the PV prefix $(PREFIX) to one that is unique to your site. PV prefixes must be unique on the subnet, and if you use the default prefix there could be a conflict with other detectors of the same type. * In the same ioc13Pilatus1 directory edit the file envPaths to point to the locations of all of the support modules on your system. Normally this is handled by the EPICS build system, but when using the prebuilt version this must be manually edited. Do not worry about the path to EPICS_BASE, it is not required. Display Managers ================ A display manager is needed to view the areaDetector control screens. Control screens are provided for the following display managers: MEDM, EDM, CSS, and caQtDM. The native screens are created manually using MEDM. The EDM, CSS and caQtDM screens are converted from the MEDM screens using conversion utilities. These are discussed in a later section. In order to control the detectors and the plugins you should install one or more of MEDM, EDM, CSS, caQtDM. ### MEDM The source code for medm can be downloaded from: [medm](http://www.aps.anl.gov/epics/extensions/medm/index.php) This requires openMotif. medm can be built from source on Linux if the openMotif library is available (which it is not for some new releases, such as Fedora 20). It is available for Windows as via an [EPICS Windows Tools MSI installer package](http://www.aps.anl.gov/epics/distributions/win32/index.php). ### EDM This can be downloaded through links on the [EDM home page](http://ics-web.sns.ornl.gov/edm). ### CSS This can be downloaded through links on the [CSS home page](http://controlsystemstudio.org). ### caQtDM This can be downloaded through links on the [caQtDM home page](http://epics.web.psi.ch/software/caqtdm). Configuration ============= Before running an areaDetector application it is usually necessary to configure a number of items. * EPICS environment variables. There are several environment variables that EPICS uses. I suggest setting these in the .cshrc (or .bashrc) file for the account that will be used to run the detector. - EPICS_CA_AUTO_ADDR_LIST and EPICS_CA_ADDR_LIST. These variables control the IP addresses that EPICS clients use when searching for EPICS PVs. The default is EPICS_CA_AUTO_ADDR_LIST=YES and EPICS_CA_ADDR_LIST to be the broadcast address of all networks connected to the host. Some detectors, for example the marCCD and mar345, come with 2 network cards, which are on 2 different subnets, typically a private one connected to the detector and a public one connected to the local LAN. If the default value of these variables is used then EPICS clients (e.g. medm) running on the detector host computer will generate many errors because each EPICS PV will appear to be coming from both networks. The solution is to set these variables as follows: setenv EPICS_CA_AUTO_ADDR_LIST NO setenv EPICS_CA_ADDR_LIST localhost:XX.YY.ZZ.255 where XX.YY.ZZ.255 should be replaced with the broadcast address for the public network on this computer. - EPICS_CA_MAX_ARRAY_BYTES. This variable controls the maximum array size that EPICS can transmit with Channel Access. The default is only 16kB, which is much too small for most detector data. This value must be set to a large enough value on both the EPICS server computer (e.g. the one running the areaDetector IOC) and client computer (e.g. the one running medm, ImageJ, IDL, etc.). This should be set to a value that is larger than the largest waveform record that will be used for the detector. For example if using a detector with 1024x1024 pixels and 4-bytes per pixel (waveform record FTVL=LONG) then EPICS_CA_MAX_ARRAY_BYTES would need to be at least 1024 * 1024 * 4 = 4153344. In practice it should be set at least 100 bytes larger than this because there is some overhead. For example: setenv EPICS_CA_MAX_ARRAY_BYTES 4154000 Do not simply set EPICS_CA_MAX_ARRAY_BYTES to a very large number like 100MB or 1GB. EPICS Channel Access allocates buffers of exactly EPICS_CA_MAX_ARRAY bytes whenever the required buffer size exceeds 16 kB, and one does not want unnecessarily large buffers to be allocated. - EPICS_DISPLAY_PATH. This variable controls where medm looks for .adl display files. If the recommendation below is followed to copy all adl files to a single directory, then this environment variable should be defined to point to that directory. For example: setenv EPICS_DISPLAY_PATH /home/det/epics/adls * medm display files. It is convenient to copy all medm .adl files to a single directory and then point the environment variable EPICS_DISPLAY_PATH to this directory. The alternative is to point EPICS_DISPLAY_PATH to a long list of directories where the adl files are located in the distributions, which is harder to maintain. On the Pilatus, for example, create a directory called /home/det/epics/adls, and put all of the adl files there. To simplify copying the adl files to that location use the following one-line script, which can placed in /home/det/bin/sync_adls. find /home/det/epics/support -name '*.adl' -exec cp -fv {} /home/det/epics/adls \; This script finds all adl files in the epics/support tree and copies them to /home/det/epics/adls. That directory must be created before running this script. Similar scripts can be used for other Linux detectors (marCCD, mar345, etc.) and can be used on Windows as well if Cygwin is installed. Each time a new release of areaDetector is installed remove the old versions of each support module (areaDetector, asyn, autosave, etc.) and then run this script to install the latest medm files. Running the IOC Application =========================== Each example IOC directory comes with a Linux script (start_epics) or a Windows batch file (start_epics.bat) or both depending on the architectures that the detector runs on. These scripts provide simple examples of how to start medm and the EPICS IOC. For example, for the mar345 iocBoot/iocMAR345/start_epics contains the following: medm -x -macro "P=13MAR345_1:, R=cam1:" mar345.adl & ../../bin/linux-x86/mar345App st.cmd This script starts medm in execute mode with the appropriate medm display file and macro parameters, running it in the background. It then runs the IOC application. This script assumes that iocBoot/iocMAR345 is the default directory when it is run, which could be added to the command or set in the configuration if this script is set as the target of a desktop shortcut, etc. The script assumes that EPICS_DISPLAY_PATH has been defined to be a location where the mar345.adl and related displays that it loads can be found. You will need to edit the script in your copy of the iocXXX directory to change the prefix (P) from 13MAR345_1: to whatever prefix you chose for your IOC. The start_epics script could also be copied to a location in your PATH (e.g. /home/mar345/bin/start_epics). Add a command like cd /home/mar345/epics/support/areaDetector-2-0/ADmar345/iocs/mar345IOC/iocBoot/iocMAR345 at the beginning of the script and then type start_epics from any directory to start the EPICS IOC. Image Viewers ============= areaDetector comes with tools to display images over EPICS Channel Access using ImageJ and IDL. These viewers are described in [areaDetectorViewers.html](http://cars.uchicago.edu/software/epics/areaDetectorViewers.html). HDFView can be used to view files saved with the HDF5 file writing plugins. ImageJ can also be used to view files saved with the TIFF, JPEG, and netCDF plugins.