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

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

ready

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