source: epicsdf/doc/build/html/_sources/installation.txt @ 616

.. $Id: installation.rst 607 2011-08-05 20:38:58Z 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, ``<TOP>``
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.xor.aps.anl.gov/bcdaext/epicsdf epicsdf
     cd epicsdf

2. Copy support database to ``<TOP>/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 <TOP>/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.xor.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.xor.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.xor.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 <http://cars9.uchicago.edu/software/python/pyepics3/>`_) 
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.xor.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
============== ============================================