source: cssboy_deployment/docs/source/configure.rst @ 1123

Last change on this file since 1123 was 1123, checked in by ehanson, 10 years ago

Updated documentation with opisys info

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL
File size: 14.3 KB
Line 
1.. $Id: configure.rst 1123 2012-10-01 15:34:46Z ehanson $
2
3=============
4Configuration
5=============
6
7The steps on this page are done from within CSS-BOY.
8
9#. Open the ``CSS_EPICS_3.1.1`` (or whatever version) directory
10#. Start ``css`` by double-clicking it.
11   If you use a unix or linux command line, type::
12   
13       ./css &
14
15The remainder of this page assumes you are running CSS-BOY.
16
17Workspace
18======================
19
20When CSS-BOY starts, it will prompt you to make a choice of which workspace to use.
21
22.. note:: It is possible to suppress this prompt if you wish to always
23        use the same workspace by clicking the *Ask Again?* checkbox on the prompt screen.
24        To return to this prompt screen, select the menus ``File`` and then
25        ``Switch Workspace...``.
26
27:index:`APS System` Project (opisys)
28====================================
29
30Add OPI screens from the APS System as a project.
31
32#. Select menu ``File-->Import ...``
33#. Open ``General`` category,
34   select ``Existing Projects into Workspace``,
35   click ``Next`` button
36#. Click ``Browse ...`` button (in *Import* window)
37#. Navigate to wherever you checked out the ``opisys/`` folder
38#. Click ``Ok`` button
39#. Click ``Finish`` button (in *Import* window)
40
41:index:`synApps` Project
42===================================
43
44Add the OPI screens from synApps as a CSS project.
45   
46#. Select menu ``File-->Import ...``
47#. Open ``General`` category,
48   select ``Existing Projects into Workspace``,
49   click ``Next`` button
50#. Click ``Browse ...`` button (in *Import* window)
51#. Navigate to ``/APSshare/epics/synApps_5_6/support/``
52   (or ``/usr/local/epics/synAppsSVN/support/`` or wherever)
53#. Click ``Ok`` button
54#. Click ``Finish`` button (in *Import* window)
55
56.. _synApps.project.file:
57
58Identify synApps as a *Project*
59-----------------------------------
60
61If CSS reports that your synApps directory cannot be imported
62since it is not a *project*, you can make it a project
63(if you have write permission to the directory) by creating
64a ``synApps/support/.project`` text XML file with this content:
65
66.. code-block:: xml
67        :linenos:
68       
69        <?xml version="1.0" encoding="UTF-8"?>
70        <projectDescription>
71                <name>synApps</name>
72                <comment>EPICS synApps</comment>
73                <projects/>
74                <buildSpec/>
75                <natures/>
76        </projectDescription>
77
78.. tip:: On line 3, the default name for the project is specified.
79        This description says the default name will be *synApps*.
80
81
82.. index::
83        fonts.def
84        color.def
85
86synApps default fonts and colors
87===========================================================
88
89#. Select menu ``Edit-->Preferences ...``
90#. Open item ``CSS Applications``
91#. Open item ``Display``
92#. Click on item ``BOY``
93#. For Color File, replace text with ``/synApps/color.def`` or *Browse...* to it
94#. For Font File, replace text with ``/synApps/font.def`` or *Browse...* to it
95#. For Top OPIs, replace with OPI file of your choice
96
97.. note:: If you get a console message that says:
98
99      2012-04-30 15:59:12 ERROR: Failed to read font definition file.
100
101   then you've got a typo or some other error.  Repeat these steps to fix it.
102   
103.. tip::  If the ``color.def`` (or ``font.def``) file are not found
104        at the root of the synApps repository, look in the synApps *xxx* module, at this path::
105       
106                /synApps/xxx/xxxApp/op/opi/
107
108
109Setting the EPICS Address List and Repeater
110===========================================================
111
112add an IP for the gateway (192.168.0.150 is an example)::
113
114        {Workspace}\.metadata\.plugins\org.eclipse.core.runtime\.settings\org.csstudio.platform.libs.epics.prefs
115        addr_list=127.0.0.1 192.168.0.150
116
117check the auto_addr_list::
118
119        {Workspace}\.metadata\.plugins\org.eclipse.core.runtime\.settings\org.csstudio.platform.libs.epics.prefs
120        auto_addr_list=true
121
122
123Setting the :index:`OPI Search Path`
124===========================================================
125
126.. TODO
127        Do NOT forget to add the APS_sr screens, when they become available
128
129.. sidebar::  Recommendation
130
131        For starters, define the *OPI Search Path* :ref:`through the Preferences
132        dialog <through.the.preferences.dialog>`.
133        If you wish to define it in a text file, define it :ref:`in.the.workspace`.
134
135Because the many screens from synApps come on many subdirectory paths, a
136search path feature was added to CSS-BOY with version 3.1.1.  By placing each
137of the subdirectory name on the search path, all the screens in that
138subdirectory may be called by name, without the full path name to the file. 
139The reason for the *OPI Search Path* feature will be demonstrated in
140:ref:`calling.synapps.screens`.
141
142OPI screens may reside on the local computer, on a file server, or be
143downloaded over an internet connection.  The *OPI Search Path* is defined
144as a list of file directories, separated by vertical bars ("|"), such as::
145
146        opi_search_path=/BOY Examples/|C:\users\5hz\Desktop\|http://ics-srv-web2.sns.ornl.gov/opi/
147
148
149.. note:: As it is written in the CSS-BOY Help files:
150
151        The path which is used to search OPI files if the given OPI path is a relative path
152        and it doesn't exist on the made up absolute path neither.
153        For example, you can put an OPI file name abc.opi or a relative path abc/def/my.opi
154        for Open OPI Action, Top OPIs, Schema OPI and so on.
155        If this OPI file cannot be found as a relative path to the OPI file, it will search the
156        OPI Search Path and return the first one found on the search path.
157        It supports workspace path, local file system path and URL path.
158        The pathes are separated by the vetical bar delimiter ``|``.  For example::
159       
160                /synApps/areaDetector/ADApp/op/opi | /synApps/asyn/opi/boy
161
162This might be the directory::
163
164        C:\Users\Pete\Downloads\sns_css_3.1.1-win32.win32.x86_64\CSS_3.1.1\plugins\org.csstudio.sns.product_3.1.1.20120718
165
166As for how to set search path from .ini file, please refer to this tutorial:
167
168        http://ics-web.sns.ornl.gov/kasemir/CSS/Training/SLAC/2_4_HierarchicalPrefs.ppt
169
170The *OPI Search Path* may be set by several ways:
171
172* Preferences dialog
173* One of several configuration file possibilities.
174
175
176.. index:: OPI Search Path; Preferences Dialog
177.. _through.the.preferences.dialog:
178
179Setting ``opi_search_path`` from a Preferences Dialog
180-----------------------------------------------------
181
182You will also need to get the synApps project onto your OPI search path.  Here is how::
183
184        Menu "CSS"
185          -->   "Preferences:"
186          open  "CSS Applications"
187          open  "Display"
188          click on  "BOY"
189
190.. _synApps.search.path:
191
192Change the text in for "OPI Search Path" to this really long string (all one line)::
193
194                /synApps/areaDetector/ADApp/op/opi | /synApps/asyn/opi/boy | /synApps/autosave/asApp/op/opi | /synApps/busy/busyApp/op/opi | /synApps/calc/calcApp/op/opi | /synApps/camac/camacApp/op/opi | /synApps/dac128V/dac128VApp/op/opi | /synApps/delaygen/delaygenApp/op/opi | /synApps/dxp/dxpApp/op/opi | /synApps/iocStats/op/opi | /synApps/ip/ipApp/op/opi | /synApps/ip330/ip330App/op/opi | /synApps/ipUnidig/ipUnidigApp/op/opi | /synApps/love/loveApp/op/opi | /synApps/mca/mcaApp/op/opi | /synApps/modbus/modbusApp/op/opi | /synApps/motor/motorApp/op/opi | /synApps/optics/opticsApp/op/opi | /synApps/quadEM/quadEMApp/op/opi | /synApps/softGlue/softGlueApp/op/opi | /synApps/sscan/sscanApp/op/opi | /synApps/std/stdApp/op/opi | /synApps/vac/vacApp/op/opi | /synApps/vme/vmeApp/op/opi | /synApps/xxx/xxxApp/op/opi | opisys/sr | opisys/sr/Gate_Pictures | opisys/sr/absApp | opisys/sr/blmApp | opisys/sr/bmbpm | opisys/sr/bunchIApp | opisys/sr/bunchPurity | opisys/sr/facilitiesApp | opisys/sr/fe | opisys/sr/flagApp | opisys/sr/id | opisys/sr/idbpm | opisys/sr/imagingApp | opisys/sr/iocinfoApp | opisys/sr/mpsApp | opisys/sr/mpsApp/uniq_gen | opisys/sr/operationsApp | opisys/sr/operationsApp/save | opisys/sr/p0fbApp | opisys/sr/psApp | opisys/sr/psApp/noiseMonitoring | opisys/sr/pss | opisys/sr/pss/adl | opisys/sr/scraperApp | opisys/sr/srTuneApp | opisys/sr/tuneApp | opisys/sr/vacApp | opisys/time/injtimeApp | opisys/time/mtimeApp
195
196
197Keep clicking **Ok** until you dismiss all the dialogs.
198Now the paths should work.
199
200        ..note:: Broken into several lines, this string would look like::
201       
202                /synApps/areaDetector/ADApp/op/opi
203                | /synApps/asyn/opi/boy
204                | /synApps/autosave/asApp/op/opi
205                | /synApps/busy/busyApp/op/opi
206                | /synApps/calc/calcApp/op/opi
207                | /synApps/camac/camacApp/op/opi
208                | /synApps/dac128V/dac128VApp/op/opi
209                | /synApps/delaygen/delaygenApp/op/opi
210                | /synApps/dxp/dxpApp/op/opi
211                | /synApps/iocStats/op/opi
212                | /synApps/ip/ipApp/op/opi
213                | /synApps/ip330/ip330App/op/opi
214                | /synApps/ipUnidig/ipUnidigApp/op/opi
215                | /synApps/love/loveApp/op/opi
216                | /synApps/mca/mcaApp/op/opi
217                | /synApps/modbus/modbusApp/op/opi
218                | /synApps/motor/motorApp/op/opi
219                | /synApps/optics/opticsApp/op/opi
220                | /synApps/quadEM/quadEMApp/op/opi
221                | /synApps/softGlue/softGlueApp/op/opi
222                | /synApps/sscan/sscanApp/op/opi
223                | /synApps/std/stdApp/op/opi
224                | /synApps/vac/vacApp/op/opi
225                | /synApps/vme/vmeApp/op/opi/synApps/xxx/xxxApp/op/opi         
226
227
228
229.. index:: OPI Search Path; Configuration File
230
231Setting ``opi_search_path`` from a Configuration File
232-----------------------------------------------------
233
234There are several configuration files that might be used
235to define the *OPI Search Path*.  The choice of which depends on the
236goal of the individual.
237
238From the ``plugin_customizations.ini`` file that comes with CSS-BOY, there are these notes:
239
240        Fundamentally, the Eclipse preference mechanism works like this
241        to allow customization at various levels:
242       
243        1. Each plugin might contain default settings that are hardcoded
244           inside the Java sources of the plugin.
245        2. In addition, each plugin might have a file preferences.ini
246           in the root directory of the plugin directory or jar file.
247           When present, those values override the hardcoded settings.
248           Ideally, each plugin with preference settings has such a
249           preferences.ini file to define the defaults because this
250           provides a convenient place to locate all the available
251           settings of a plugin in one file.
252        3. A plugin_customization.ini file like this one, located
253           in the root of the "Product" plugin directory or jar file
254           can override all of the above.
255           It is ideally used to provide site-specific defaults
256           (as this one does for using CSS at the SNS).
257        4. When starting CSS (or any Eclipse product), a customization file
258           with the same format can be provided via the -pluginCustomization
259           command line option to override settings.
260           NOTE: Eclipse silently ignores missing customization files.
261           THERE IS NO ERROR MESSAGE when the specified file does not exist!
262        5. Finally, each end user can use the CSS/Preferences menu item to
263           interactively adjust most settings. Those changes are stored in the
264           workspace directory under::
265           
266               {Workspace}/.metadata/.plugins/org.eclipse.core.runtime/.settings
267
268The default preferences can be set in ``plugin_customization.ini`` 
269file which is located in the root of the "Product" plugin directory
270or jar file. It is ideally used to provide site-specific default
271preferences. For example, you can change the default BOY preferences
272in this file with corresponding preference keys::
273
274        org.csstudio.opibuilder/color_file=http://your_site.gov/color.def
275        org.csstudio.opibuilder/font_file=http://your_site.gov/font.def
276        org.csstudio.opibuilder/opi_gui_refresh_cycle=100
277        org.csstudio.opibuilder/no_edit=true
278        org.csstudio.opibuilder/macros="N","North"|"W","West"|"SYS","LLRF"|"SubSys","HPM"
279        #popup console level, it can be NO_POP, INFO, or ALL
280        org.csstudio.opibuilder/popup_console=NO_POP
281
282 You can also give a different customization file with the command line option -pluginCustomization when starting CSS.
283
284
285.. index:: OPI Search Path; Configuration File in Workspace
286
287.. _in.the.workspace:
288
289in the Workspace
290+++++++++++++++++++++++
291
292One way to set the *OPI Search Path* is to set it in the Workspace, as I show here:
293
294On my Windows 7 system, my default workspace is::
295
296        {Workspace} = C:\Users\Pete\CSS-Workspaces\Default
297
298and the workspace configuration file for the OPI Builder is::
299
300        {Workspace}\.metadata\.plugins\org.eclipse.core.runtime\.settings\org.csstudio.opibuilder.prefs
301
302Here is an example of the *org.csstudio.opibuilder.prefs* file on my Ubuntu system
303(use the long, one-line :ref:`synApps search path <synApps.search.path>` given above):
304
305.. code-block:: text
306        :linenos:
307       
308        color_file=/iocPRJ/color.def
309        eclipse.preferences.version=1
310        font_file=/iocPRJ/font.def
311        opi_search_path=/synApps/areaDetector/ADApp/op/opi | ... you get the idea, it's a long line
312        popup_console=ALL
313        top_opis=/iocPRJ/prj.opi
314
315
316Creating the Beam Line Project
317===========================================================
318
319Screens for your instrument or beam line or other installation of EPICS
320may already be available.  If so, you might import them by following the steps
321above used to import synApps.  If you need to develop your own screens,
322then follow these steps:
323
324#. Select menu ``File-->New``
325#. Open ``General`` category,
326   select ``Project``,
327   click ``Next`` button
328#. Give it a Project name, something short such as *45ID* or *iocPRJ*
329   (try to avoid using spaces, it makes things harder later on),
330#. In the ``Navigator`` view,
331   open the new project by double-clicking (or any other equivalent way)
332   
333Create an OPI file
334------------------------------------
335
336#. Select menu ``File-->New``
337#. Open ``BOY`` category,
338   select ``OPI File``,
339   click ``Next`` button
340#. Select the folder to contain your new OPI screen,
341   type the name of the new OPI file in the box,
342   click ``Finish`` button
343
344Your new screen will appear in a CSS-BOY editing window.
345You might consider changing to the *OPI Editor* perspective
346as this will provide much more help in editing the screen.
347
348Once you have setup the CSS-BOY project for your EPICS installation,
349you might want one particular file to be the default  *main* file
350for your CSS-BOY workspace.  Edit the menu for *Top OPIs* via:
351``Edit --> Preferences ... --> CSS Applications --> Display``
352
353
354.. _calling.synapps.screens:
355
356Calling synApps or System screens
357===========================================================
358
359Also, when calling a synApps or system .opi screen from the instrument or beam line,
360it is not necessary to use the full path since there is an OPI search path
361that will locate the screen.  Example, instead of::
362
363   /synApps/motor/motorApp/op/opi/motor3x.opi
364
365Instead, you just call::
366
367   motor3x.opi
368
369.. note::  If you require a specific version of synApps, for example a specific older
370                        version of areaDetector, create a separate CSS project for it in your
371                        workspace.
372
373.. TODO: could use some instructions how to create this kind of project.  An example would help.
374
375
Note: See TracBrowser for help on using the repository browser.