.. $Id: installation.rst 1046 2012-07-17 21:09:27Z jemian $ Installation Instructions for Pilatus Detectors ------------------------------------------------------------------------------------------------- There are several steps to the installation process. This page was written during the installation of this code at 15ID-D on the USAXS/SAXS Pilatus 100k detector. You might need to change some values to fit your situation. #. Install the EPICS database into an existing IOC. #. Install GUI support screens for MEDM or CSS-BOY #. Install Enthought Python Distribution with PyEPICS on Pilatus host computer. #. Install (and test and configure) ``epicsdf.py`` on Pilatus host computer. #. Start ``cron`` task to keep epicsdf.py running on Pilatus host computer. Install EPICS database in existing IOC ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ These instructions assume the support database will run in an existing EPICS IOC. In this example, ```` is the absolute directory path to the IOC's top-level directory. In that directory, there will be some directory *someApp* where the source code for the IOC resides. 1. Check out support from subversion:: cd /tmp svn co https://subversion.xray.aps.anl.gov/bcdaext/epicsdf epicsdf cd epicsdf 2. Copy support database to ``/someApp/Db`` directory:: cd /net/s15dserv/xorApps/epics/synApps_5_4/ioc/15iddLAX/15iddLAXApp/Db cp /tmp/epicsdf/epics/epicsdf.db ./ svn add epicsdf.db svn propset svn:eol-style native epicsdf.db svn propset svn:keywords "Author Date Id Revision Url" epicsdf.db 3. Copy autosave request file to /iocBoot/iocNAME directory:: cd /net/s15dserv/xorApps/epics/synApps_5_4/ioc/15iddLAX/iocBoot/ioc15iddLAX cp /tmp/epicsdf/epics/epicsdf.req ./ svn add epicsdf.req svn propset svn:eol-style native epicsdf.req svn propset svn:keywords "Author Date Id Revision Url" epicsdf.req 4. Call support database from ``st.cmd`` file (edit that file and add like this *before* ``iocInit``):: # 2011-08-01,PRJ # database support for "df" command on Pilatus detector computer # https://subversion.xray.aps.anl.gov/bcdaext/epicsdf/doc/build/html/index.html dbLoadRecords("$(TOP)/15iddLAXApp/Db/epicsdf.db", "P=15iddLAX:,D=p100k:") 5. Register autosave request from ``auto_settings.req`` file (edit that file and add anywhere, usually at the end):: # 2011-08-01,PRJ # database support for "df" command on Pilatus detector computer # https://subversion.xray.aps.anl.gov/bcdaext/epicsdf/doc/build/html/index.html file epicsdf.req P=$(P),D=p100k: Keep the directory ``/tmp/epicsdf`` for use in the next step, to install the GUI support. Install GUI support ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There are support screens for MEDM and CSS-BOY in the ``epics/`` subdirectory. * ``epics/epicsdf.adl`` : MEDM screen, needs macros ``P`` and ``D`` defined * ``epics/epicsdf.opi`` : CSS-BOY screen, needs macros ``P`` and ``D`` defined * ``epics/starter.opi`` : CSS-BOY screen, defines ``P`` and ``D`` and calls ``epicsdf.opi`` Copy these screens to the appropriate directory for the tool you use:: cd /net/s15dserv/xorApps/epics/synApps_5_4/ioc/15iddLAX/15iddLAXApp/op/adl cp /tmp/epicsdf/epics/epicsdf.adl ./ svn add epicsdf.adl The MEDM screen can be called from the command line with a command such as:: medm -x -macro P=15iddLAX:,D=p100k: epicsdf.adl & The directory ``/tmp/epicsdf`` can be discarded now. Install Enthought Python Distribution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :warning: Procedure to install PyEPICS is flawed. On Linux, fails to find libCom.so.3.14... Works when matching libCom.so.(ver.sion) is copied to same place. These instructions describe installation of 32-bit support on the Pilatus host computer (usually SUSE Linux). 1. Copy deployment software to Pilatus host computer:: cd /tmp svn co https://subversion.xray.aps.anl.gov/bcdaext/epd_deployment epd_deployment cd epd_deployment 2. Copy Enthought installer to Pilatus host computer:: cp /APSshare/epd/downloads/epd-7.1-2-rh5-x86_64.sh ./images chmod +x ./images/epd-7.1-2-rh5-x86_64.sh 3. Check the installation script for valid paths against what is available on the Pilatus host computer. There are several scripts. Here, just edit the macros in the 64-bit script * ``install-rhel5-64.sh``: installer shell script for 64-bit support ============= ====================================================== macro meaning ============= ====================================================== ``SRC`` relative path to the Enthought installer script ``LIBCA`` absolute path to EPICS ``libCa.so`` built for this OS ``EPD_ROOT`` absolute path under which this EPD will be installed ============= ====================================================== :note: Consider adding the path defined by ``${EPD_ROOT}/bin`` to the shell ``PATH`` variable. :note: Suggest ``EPD_ROOT=/home/det/epd`` for Pilatus detectors. This makes the Python executable available at ``/home/det/epd/rh5-x86_64/bin/python`` These parameters seem to work well: SRC=/tmp/epd_deployment/images/epd-7.1-2-rh5-x86_64.sh LIBCA=/home/det/epics/base-3.14.9/lib/linux-x86_64/libca.so.3.14 EPD_ROOT=/home/det/epd 4. Run installation script:: /bin/sh ./install-rhel5-64.sh The directory ``/tmp/epd_deployment`` can be discarded now. 5. Consider defining this environment variable:: EPD=/home/det/epd/rh5-x86_64 Test PyEPICS ~~~~~~~~~~~~ Test the Python EPICS support (`PyEPICS `_) by printing the APS storage ring current. :: command_line> ${EPD}/bin/python import epics print epics.caget('S:SRcurrentAI') This can be run as:: ${EPD_ROOT}/bin/python test_pyepics.py If this fails on the ``import epics`` statement, then the ``libCa.so`` module is probably not found. Install ``epicsdf`` Python client code ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Check out support from subversion:: cd ~ svn co https://subversion.xray.aps.anl.gov/bcdaext/epicsdf epicsdf cd epicsdf 2. Revise ``self.sender`` in :file:`src/epicsdf.py`. Specify the name of a valid APS email address as the sender. The :meth:`epicsdf.sendmail()` sends mail using the ``mail`` program on the host operating system. By default, the Pilatus detectors are in the ``dectris.localdomain`` which is not allowed to send mail within the APS. Test epicsdf ~~~~~~~~~~~~ Try running the program directly. Note the program accepts a single PV prefix as its argument (including the ``df:``):: /home/det/epd/rh5-x86_64/bin/python src/epicsdf.py 15iddLAX:p100:df: Configure ``epicsdf`` ~~~~~~~~~~~~~~~~~~~~~~~~ Verify that the starter shell script ``shell/epicsdf.sh`` works properly. Move to the ``shell`` directory and edit both files. Adjust these items: =================== ========================================================= macro example value =================== ========================================================= DATABASE_PREFIX 15iddLAX:p100:df: APP_BASE_DIR /home/det/epicsdf PYTHON /home/det/epd/rh5-x86_64/bin/python =================== ========================================================= These parameters seem to work well (replace ``yyyyyyy:zzzzzz`` with correct PV parts): DATABASE_PREFIX=yyyyyyy:zzzzzz:df: APP_BASE_DIR=/home/det/epicsdf PYTHON=/home/det/epd/rh5-x86_64/bin/python Test this by running each of these commands individually and looking at the output in the ``shell/epicsdf.log`` log file:: shell/epicsdf.sh start # should start the program shell/epicsdf.sh status # should say program is running shell/epicsdf.sh stop # should stop program shell/epicsdf.sh restart # should start program shell/epicsdf.sh restart # should stop and then start program shell/epicsdf.sh checkup # does nothing this time shell/epicsdf.sh stop # should stop program shell/epicsdf.sh checkup # should start program shell/epicsdf.sh checkup # does nothing this time For convenience, you could also (enter the ``shell`` directory and) type ``make start``, ``make stop``, ... Note: The first time ``shell/epicsdf.sh`` is run, the log file will contain some error information since the PID file has not yet been created. No problem for the first time. Maybe some additional code will be added to work around this. **Ignore this error if it occurs the first time.** You could even scrape it out of the log file. :: # ===== shell/epicsdf.sh start ===== Tue Aug 2 15:01:29 CDT 2011 ================================== /bin/cat: /home/det/epicsdf/shell/epicsdf.pid: No such file or directory ERROR: List of process IDs must follow -p. ********* simple selection ********* ********* selection by list ********* -A all processes -C by command name -N negate selection -G by real group ID (supports names) -a all w/ tty except session leaders -U by real user ID (supports names) -d all except session leaders -g by session OR by effective group name -e all processes -p by process ID T all processes on this terminal -s processes in the sessions given a all w/ tty, including other users -t by tty g OBSOLETE -- DO NOT USE -u by effective user ID (supports names) r only running processes U processes for specified users x processes w/o controlling ttys t by tty *********** output format ********** *********** long options *********** -o,o user-defined -f full --Group --User --pid --cols --ppid -j,j job control s signal --group --user --sid --rows --info -O,O preloaded -o v virtual memory --cumulative --format --deselect -l,l long u user-oriented --sort --tty --forest --version -F extra full X registers --heading --no-heading --context ********* misc options ********* -V,V show version L list format codes f ASCII art forest -m,m,-L,-T,H threads S children in sum -y change -l format -M,Z security data c true command name -c scheduling class -w,w wide output n numeric WCHAN,UID -H process hierarchy # started 9233: /home/det/epd/rh5-x86_64/bin/python /home/det/epicsdf/src/epicsdf.py 15iddLAX:p100:df: Start periodic ``cron`` task ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To ensure that the Python client program is restarted wfter a host reboot (or some other reason it has stopped), a periodic cron task checks that there is a PID running on the system and that PID is our python job. This is done by periodically calling:: epics/epicsdf.sh checkup which will start a new client program if it is not running. The ``cron`` task is started by:: crontab -e :note: You will probably need to know how to use the ``vi`` editor. Good luck! Add these contents to the end of the list, save, and then quit the editor. (Runs a *checkup* every 5 minutes.):: # cron task # epicsdf- # watch some local disk partition and report it to EPICS, # send emails if space runs low */5 * * * * /home/det/epicsdf/shell/epicsdf.sh checkup a few VI editor commands ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These are the few VI editor commands to help you edit the ``cron`` task. The notation ``[esc]`` means to press the *escape* key. If you need more help, you need the manual. ============== ============================================ command meaning ============== ============================================ i start *insert* mode (so you can enter text) [esc] leave insert mode :w! save: write the contents back to the file but do not quit ``vi`` yet. :q! quit: Leave the program. If you have not saved first with ``:w!``, your changes will be lost -- forever. This is how you do a *cancel - no save*. ZZ save and quit ============== ============================================