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

Last change on this file since 1046 was 1046, checked in by jemian, 10 years ago

refs #12, provides the publishing tool and changed the URL to point to the new location

  • Property svn:eol-style set to native
  • Property svn:executable set to *
File size: 12.1 KB
Line 
1.. $Id: installation.rst 616 2011-08-16 22:46:39Z jemian $
2
3Installation Instructions for Pilatus Detectors
4-------------------------------------------------------------------------------------------------
5
6There are several steps to the installation process.  This page was written during the
7installation of this code at 15ID-D on the USAXS/SAXS Pilatus 100k detector.  You might
8need to change some values to fit your situation.
9
10#. Install the EPICS database into an existing IOC.
11#. Install GUI support screens for MEDM or CSS-BOY
12#. Install Enthought Python Distribution with PyEPICS on Pilatus host computer.
13#. Install (and test and configure) ``epicsdf.py`` on Pilatus host computer.
14#. Start ``cron`` task to keep epicsdf.py running on Pilatus host computer.
15
16
17Install EPICS database in existing IOC
18^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
19
20These instructions assume the support database will run in an existing
21EPICS IOC.  In this example, ``<TOP>``
22is the absolute directory path to the IOC's top-level directory.
23In that directory, there will be some directory *someApp* where the source
24code for the IOC resides.
25
261. Check out support from subversion::
27
28     cd /tmp
29     svn co https://subversion.xray.aps.anl.gov/bcdaext/epicsdf epicsdf
30     cd epicsdf
31
322. Copy support database to ``<TOP>/someApp/Db`` directory::
33
34     cd /net/s15dserv/xorApps/epics/synApps_5_4/ioc/15iddLAX/15iddLAXApp/Db
35     cp /tmp/epicsdf/epics/epicsdf.db ./
36     svn add epicsdf.db
37     svn propset svn:eol-style native epicsdf.db
38     svn propset svn:keywords "Author Date Id Revision Url" epicsdf.db
39
403. Copy autosave request file to <TOP>/iocBoot/iocNAME directory::
41
42     cd /net/s15dserv/xorApps/epics/synApps_5_4/ioc/15iddLAX/iocBoot/ioc15iddLAX
43     cp /tmp/epicsdf/epics/epicsdf.req ./
44     svn add epicsdf.req
45     svn propset svn:eol-style native epicsdf.req
46     svn propset svn:keywords "Author Date Id Revision Url" epicsdf.req
47
484. Call support database from ``st.cmd`` file (edit that file and add like this *before* ``iocInit``)::
49
50     # 2011-08-01,PRJ
51     # database support for "df" command on Pilatus detector computer
52     # https://subversion.xray.aps.anl.gov/bcdaext/epicsdf/doc/build/html/index.html
53     dbLoadRecords("$(TOP)/15iddLAXApp/Db/epicsdf.db", "P=15iddLAX:,D=p100k:")
54
555. Register autosave request from ``auto_settings.req`` file (edit that file and add anywhere, usually at the end)::
56
57     # 2011-08-01,PRJ
58     # database support for "df" command on Pilatus detector computer
59     # https://subversion.xray.aps.anl.gov/bcdaext/epicsdf/doc/build/html/index.html
60     file epicsdf.req P=$(P),D=p100k:
61
62Keep the directory ``/tmp/epicsdf`` for use in the next step, to install the GUI support.
63
64
65Install GUI support
66^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
67
68There are support screens for MEDM and CSS-BOY in the ``epics/``
69subdirectory.
70
71* ``epics/epicsdf.adl`` : MEDM screen, needs macros ``P`` and ``D`` defined
72* ``epics/epicsdf.opi`` : CSS-BOY screen, needs macros ``P`` and ``D`` defined
73* ``epics/starter.opi`` : CSS-BOY screen, defines ``P`` and ``D`` and calls ``epicsdf.opi``
74
75Copy these screens to the appropriate directory for the tool you use::
76
77     cd /net/s15dserv/xorApps/epics/synApps_5_4/ioc/15iddLAX/15iddLAXApp/op/adl
78     cp /tmp/epicsdf/epics/epicsdf.adl ./
79     svn add epicsdf.adl
80
81The MEDM screen can be called from the command line with a command such as::
82
83   medm -x -macro P=15iddLAX:,D=p100k: epicsdf.adl &
84
85The directory ``/tmp/epicsdf`` can be discarded now.
86
87
88
89Install Enthought Python Distribution
90^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
91
92:warning: Procedure to install PyEPICS is flawed.
93  On Linux, fails to find libCom.so.3.14...
94  Works when matching libCom.so.(ver.sion) is copied to same place.
95
96These instructions describe installation of 32-bit support on the Pilatus host computer (usually SUSE Linux).
97
981. Copy deployment software to Pilatus host computer::
99
100     cd /tmp
101     svn co https://subversion.xray.aps.anl.gov/bcdaext/epd_deployment epd_deployment
102     cd epd_deployment
103 
1042. Copy Enthought installer to Pilatus host computer::
105
106    cp /APSshare/epd/downloads/epd-7.1-2-rh5-x86_64.sh ./images
107    chmod +x ./images/epd-7.1-2-rh5-x86_64.sh
108 
1093. Check the installation script for valid paths against what is available on the Pilatus host computer.
110    There are several scripts.  Here, just edit the macros in the 64-bit script
111   
112    * ``install-rhel5-64.sh``: installer shell script for 64-bit support
113
114    =============  ======================================================
115    macro          meaning
116    =============  ======================================================
117    ``SRC``        relative path to the Enthought installer script
118    ``LIBCA``      absolute path to EPICS ``libCa.so`` built for this OS
119    ``EPD_ROOT``   absolute path under which this EPD will be installed
120    =============  ======================================================
121   
122    :note:
123                Consider adding the path defined by ``${EPD_ROOT}/bin``
124                to the shell ``PATH`` variable.
125   
126        :note:
127                Suggest ``EPD_ROOT=/home/det/epd`` for Pilatus detectors.  This makes
128                the Python executable available at
129                ``/home/det/epd/rh5-x86_64/bin/python``
130               
131    These parameters seem to work well:
132
133                 SRC=/tmp/epd_deployment/images/epd-7.1-2-rh5-x86_64.sh
134                 LIBCA=/home/det/epics/base-3.14.9/lib/linux-x86_64/libca.so.3.14
135                 EPD_ROOT=/home/det/epd
136
1374. Run installation script::
138
139    /bin/sh ./install-rhel5-64.sh
140
141The directory ``/tmp/epd_deployment`` can be discarded now.
142
1435. Consider defining this environment variable::
144
145    EPD=/home/det/epd/rh5-x86_64
146
147Test PyEPICS
148~~~~~~~~~~~~
149
150Test the Python EPICS support (`PyEPICS <http://cars9.uchicago.edu/software/python/pyepics3/>`_)
151by printing the APS storage ring current.
152
153::
154
155   command_line> ${EPD}/bin/python
156   import epics
157   print epics.caget('S:SRcurrentAI')
158   
159
160This can be run as::
161
162    ${EPD_ROOT}/bin/python test_pyepics.py
163
164If this fails on the ``import epics`` statement, then the ``libCa.so`` module
165is probably not found.
166
167
168Install ``epicsdf`` Python client code
169^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
170
1711. Check out support from subversion::
172
173    cd ~
174    svn co https://subversion.xray.aps.anl.gov/bcdaext/epicsdf epicsdf
175    cd epicsdf
176
1772. Revise ``self.sender`` in :file:`src/epicsdf.py`.
178   Specify the name of a valid APS email address as the sender.
179   The :meth:`epicsdf.sendmail()`
180   sends mail using the ``mail`` program on the host operating system.  By default, the
181   Pilatus detectors are in the ``dectris.localdomain`` which is not allowed to send
182   mail within the APS.
183
184Test epicsdf
185~~~~~~~~~~~~
186
187Try running the program directly.  Note the program accepts a single PV prefix
188   as its argument (including the ``df:``)::
189
190    /home/det/epd/rh5-x86_64/bin/python src/epicsdf.py 15iddLAX:p100:df:
191
192Configure ``epicsdf`` 
193~~~~~~~~~~~~~~~~~~~~~~~~
194
195Verify that the starter shell script ``shell/epicsdf.sh`` works properly.
196   Move to the ``shell`` directory and edit both files.  Adjust these items:
197   
198   ===================  =========================================================
199   macro                example value
200   ===================  =========================================================
201   DATABASE_PREFIX      15iddLAX:p100:df:
202   APP_BASE_DIR         /home/det/epicsdf
203   PYTHON               /home/det/epd/rh5-x86_64/bin/python
204   ===================  =========================================================
205               
206These parameters seem to work well (replace ``yyyyyyy:zzzzzz`` with correct PV parts):
207
208                 DATABASE_PREFIX=yyyyyyy:zzzzzz:df:
209                 APP_BASE_DIR=/home/det/epicsdf
210                 PYTHON=/home/det/epd/rh5-x86_64/bin/python
211
212Test this by running each of these commands individually and looking at the output
213in the ``shell/epicsdf.log`` log file::
214
215   shell/epicsdf.sh start           # should start the program
216   shell/epicsdf.sh status          # should say program is running
217   shell/epicsdf.sh stop            # should stop program
218   shell/epicsdf.sh restart         # should start program
219   shell/epicsdf.sh restart         # should stop and then start program
220   shell/epicsdf.sh checkup         # does nothing this time
221   shell/epicsdf.sh stop            # should stop program
222   shell/epicsdf.sh checkup         # should start program
223   shell/epicsdf.sh checkup         # does nothing this time
224
225For convenience, you could also (enter the ``shell`` directory and)
226type ``make start``, ``make stop``, ...
227
228Note:
229The first time ``shell/epicsdf.sh`` is run, the log file will contain some
230error information since the PID file has not yet been created.  No problem
231for the first time.  Maybe some additional code will be added to work around this.
232**Ignore this error if it occurs the first time.**  You could even scrape it out
233of the log file.
234
235::
236
237     # ===== shell/epicsdf.sh start =====  Tue Aug  2 15:01:29 CDT 2011  ==================================
238     /bin/cat: /home/det/epicsdf/shell/epicsdf.pid: No such file or directory
239     ERROR: List of process IDs must follow -p.
240     ********* simple selection *********  ********* selection by list *********
241     -A all processes                      -C by command name
242     -N negate selection                   -G by real group ID (supports names)
243     -a all w/ tty except session leaders  -U by real user ID (supports names)
244     -d all except session leaders         -g by session OR by effective group name
245     -e all processes                      -p by process ID
246     T  all processes on this terminal     -s processes in the sessions given
247     a  all w/ tty, including other users  -t by tty
248     g  OBSOLETE -- DO NOT USE             -u by effective user ID (supports names)
249     r  only running processes             U  processes for specified users
250     x  processes w/o controlling ttys     t  by tty
251     *********** output format **********  *********** long options ***********
252     -o,o user-defined  -f full            --Group --User --pid --cols --ppid
253     -j,j job control   s  signal          --group --user --sid --rows --info
254     -O,O preloaded -o  v  virtual memory  --cumulative --format --deselect
255     -l,l long          u  user-oriented   --sort --tty --forest --version
256     -F   extra full    X  registers       --heading --no-heading --context
257                         ********* misc options *********
258     -V,V  show version      L  list format codes  f  ASCII art forest
259     -m,m,-L,-T,H  threads   S  children in sum    -y change -l format
260     -M,Z  security data     c  true command name  -c scheduling class
261     -w,w  wide output       n  numeric WCHAN,UID  -H process hierarchy
262     # started 9233: /home/det/epd/rh5-x86_64/bin/python /home/det/epicsdf/src/epicsdf.py 15iddLAX:p100:df:
263
264
265Start periodic ``cron`` task 
266~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
267   
268To ensure that the Python client program is restarted wfter a host reboot
269(or some other reason it has stopped), a periodic cron task checks that
270there is a PID running on the system and that PID is our python job.  This
271is done by periodically calling::
272
273    epics/epicsdf.sh checkup
274
275which will start a new client program if it is not running.
276The ``cron`` task is started by::
277
278    crontab -e
279
280:note: You will probably need to know how to use the ``vi`` editor.  Good luck!
281
282Add these contents to the end of the list, save, and then quit the editor.
283(Runs a *checkup* every 5 minutes.)::
284
285    # cron task
286    #  epicsdf-
287    #     watch some local disk partition and report it to EPICS,
288    #     send emails if space runs low
289    */5 * * * * /home/det/epicsdf/shell/epicsdf.sh checkup
290
291
292a few VI editor commands
293~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
294
295These are the few VI editor commands to help you edit the ``cron`` task.
296The notation ``[esc]`` means to press the *escape* key.  If you need more
297help, you need the manual.
298
299============== ============================================
300command        meaning
301============== ============================================
302i              start *insert* mode (so you can enter text)
303[esc]          leave insert mode
304:w!            save: write the contents back to the file
305               but do not quit ``vi`` yet.
306:q!            quit: Leave the program.  If you have not
307               saved first with ``:w!``, your changes
308               will be lost -- forever.
309               This is how you do a *cancel - no save*.
310ZZ             save and quit
311============== ============================================
312
Note: See TracBrowser for help on using the repository browser.