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

.. $Id: configure.rst 1062 2012-08-06 21:14:17Z jemian $

=============
Configuration
=============

The steps on this page are done from within CSS-BOY.

#. Open the ``CSS_EPICS_3.1.1`` (or whatever version) directory
#. Start ``css`` by double-clicking it.
   If you use a unix or linux command line, type::
   
       ./css &

The remainder of this page assumes you are running CSS-BOY.

Workspace
======================

When CSS-BOY starts, it will prompt you to make a choice of which workspace to use.

.. note:: It is possible to suppress this prompt if you wish to always 
        use the same workspace by clicking the *Ask Again?* checkbox on the prompt screen.
        To return to this prompt screen, select the menus ``File`` and then
        ``Switch Workspace...``.

:index:`APS_sr` Project
===================================

.. warning::  This section needs to be worked out.

..
        this work has not been done yet, 
        the screens are not ready, 
        the instructions are not ready

.. TODO
        Do NOT forget to update the OPI Search Path instructions, when these screens become available

:index:`synApps` Project
===================================

Add the OPI screens from synApps as a CSS project.
   
#. Select menu ``File-->Import ...``
#. Open ``General`` category,
   select ``Existing Projects into Workspace``,
   click ``Next`` button
#. Click ``Browse ...`` button (in *Import* window)
#. navigate to ``/APSshare/epics/synApps_5_6/support/``
   (or ``/usr/local/epics/synAppsSVN/support/`` or wherever)
#. Click ``Ok`` button
#. Click ``Finish`` button (in *Import* window)

.. _synApps.project.file:

Identify synApps as a *Project*
-----------------------------------

If CSS reports that your synApps directory cannot be imported
since it is not a *project*, you can make it a project
(if you have write permission to the directory) by creating
a ``synApps/support/.project`` text XML file with this content:

.. code-block:: xml
        :linenos:
        
        <?xml version="1.0" encoding="UTF-8"?>
        <projectDescription>
                <name>synApps</name>
                <comment>EPICS synApps</comment>
                <projects/>
                <buildSpec/>
                <natures/>
        </projectDescription>

.. tip:: On line 3, the default name for the project is specified.
        This description says the default name will be *synApps*.


.. index::
        fonts.def
        color.def

synApps default fonts and colors
===========================================================

#. Select menu ``Edit-->Preferences ...``
#. Open item ``CSS Applications``
#. Open item ``Display``
#. Click on item ``BOY``
#. For Color File, replace text with ``/synApps/color.def`` or *Browse...* to it
#. For Font File, replace text with ``/synApps/font.def`` or *Browse...* to it
#. For Top OPIs, replace with OPI file of your choice

.. note:: If you get a console message that says:

      2012-04-30 15:59:12 ERROR: Failed to read font definition file.

   then you've got a typo or some other error.  Repeat these steps to fix it.
   
.. tip::  If the ``color.def`` (or ``font.def``) file are not found 
        at the root of the synApps repository, look in the synApps *xxx* module, at this path::
        
                /synApps/xxx/xxxApp/op/opi/


Setting the EPICS Address List and Repeater
===========================================================

add an IP for the gateway (192.168.0.150 is an example)::

        {Workspace}\.metadata\.plugins\org.eclipse.core.runtime\.settings\org.csstudio.platform.libs.epics.prefs
        addr_list=127.0.0.1 192.168.0.150

check the auto_addr_list::

        {Workspace}\.metadata\.plugins\org.eclipse.core.runtime\.settings\org.csstudio.platform.libs.epics.prefs
        auto_addr_list=true


Setting the :index:`OPI Search Path`
===========================================================

.. TODO
        Do NOT forget to add the APS_sr screens, when they become available

.. sidebar::  Recommendation

        For starters, define the *OPI Search Path* :ref:`through the Preferences 
        dialog <through.the.preferences.dialog>`.
        If you wish to define it in a text file, define it :ref:`in.the.workspace`.

Because the many screens from synApps come on many subdirectory paths, a
search path feature was added to CSS-BOY with version 3.1.1.  By placing each
of the subdirectory name on the search path, all the screens in that 
subdirectory may be called by name, without the full path name to the file.  
The reason for the *OPI Search Path* feature will be demonstrated in 
:ref:`calling.synapps.screens`.

OPI screens may reside on the local computer, on a file server, or be
downloaded over an internet connection.  The *OPI Search Path* is defined 
as a list of file directories, separated by vertical bars ("|"), such as::

        opi_search_path=/BOY Examples/|C:\users\5hz\Desktop\|http://ics-srv-web2.sns.ornl.gov/opi/


.. note:: As it is written in the CSS-BOY Help files:

        The path which is used to search OPI files if the given OPI path is a relative path 
        and it doesn't exist on the made up absolute path neither. 
        For example, you can put an OPI file name abc.opi or a relative path abc/def/my.opi
        for Open OPI Action, Top OPIs, Schema OPI and so on. 
        If this OPI file cannot be found as a relative path to the OPI file, it will search the 
        OPI Search Path and return the first one found on the search path. 
        It supports workspace path, local file system path and URL path. 
        The pathes are separated by the vetical bar delimiter ``|``.  For example::
        
                /synApps/areaDetector/ADApp/op/opi | /synApps/asyn/opi/boy

This might be the directory::

        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

As for how to set search path from .ini file, please refer to this tutorial: 

        http://ics-web.sns.ornl.gov/kasemir/CSS/Training/SLAC/2_4_HierarchicalPrefs.ppt

The *OPI Search Path* may be set by several ways:

* Preferences dialog
* One of several configuration file possibilities.


.. index:: OPI Search Path; Preferences Dialog
.. _through.the.preferences.dialog:

Setting ``opi_search_path`` from a Preferences Dialog
-----------------------------------------------------

You will also need to get the synApps project onto your OPI search path.  Here is how::

        Menu "CSS"
          -->   "Preferences:"
          open  "CSS Applications"
          open  "Display"
          click on  "BOY"

.. _synApps.search.path:

Change the text in for "OPI Search Path" to this really long string (all one line)::

                /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 

Keep clicking **Ok** until you dismiss all the dialogs. 
Now the paths should work.

        ..note:: Broken into several lines, this string would look like::
        
                /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          



.. index:: OPI Search Path; Configuration File

Setting ``opi_search_path`` from a Configuration File
-----------------------------------------------------

There are several configuration files that might be used 
to define the *OPI Search Path*.  The choice of which depends on the
goal of the individual.

From the ``plugin_customizations.ini`` file that comes with CSS-BOY, there are these notes:

        Fundamentally, the Eclipse preference mechanism works like this
        to allow customization at various levels:
        
        1. Each plugin might contain default settings that are hardcoded
           inside the Java sources of the plugin.
        2. In addition, each plugin might have a file preferences.ini
           in the root directory of the plugin directory or jar file.
           When present, those values override the hardcoded settings.
           Ideally, each plugin with preference settings has such a 
           preferences.ini file to define the defaults because this
           provides a convenient place to locate all the available
           settings of a plugin in one file.
        3. A plugin_customization.ini file like this one, located
           in the root of the "Product" plugin directory or jar file
           can override all of the above.
           It is ideally used to provide site-specific defaults
           (as this one does for using CSS at the SNS).
        4. When starting CSS (or any Eclipse product), a customization file
           with the same format can be provided via the -pluginCustomization
           command line option to override settings.
           NOTE: Eclipse silently ignores missing customization files.
           THERE IS NO ERROR MESSAGE when the specified file does not exist! 
        5. Finally, each end user can use the CSS/Preferences menu item to
           interactively adjust most settings. Those changes are stored in the
           workspace directory under::
           
               {Workspace}/.metadata/.plugins/org.eclipse.core.runtime/.settings

The default preferences can be set in ``plugin_customization.ini`` 
file which is located in the root of the "Product" plugin directory 
or jar file. It is ideally used to provide site-specific default
preferences. For example, you can change the default BOY preferences 
in this file with corresponding preference keys::

        org.csstudio.opibuilder/color_file=http://your_site.gov/color.def
        org.csstudio.opibuilder/font_file=http://your_site.gov/font.def
        org.csstudio.opibuilder/opi_gui_refresh_cycle=100
        org.csstudio.opibuilder/no_edit=true
        org.csstudio.opibuilder/macros="N","North"|"W","West"|"SYS","LLRF"|"SubSys","HPM"
        #popup console level, it can be NO_POP, INFO, or ALL
        org.csstudio.opibuilder/popup_console=NO_POP 

 You can also give a different customization file with the command line option -pluginCustomization when starting CSS.


.. index:: OPI Search Path; Configuration File in Workspace

.. _in.the.workspace:

in the Workspace
+++++++++++++++++++++++

One way to set the *OPI Search Path* is to set it in the Workspace, as I show here:

On my Windows 7 system, my default workspace is::

        {Workspace} = C:\Users\Pete\CSS-Workspaces\Default

and the workspace configuration file for the OPI Builder is::

        {Workspace}\.metadata\.plugins\org.eclipse.core.runtime\.settings\org.csstudio.opibuilder.prefs

Here is an example of the *org.csstudio.opibuilder.prefs* file on my Ubuntu system
(use the long, one-line :ref:`synApps search path <synApps.search.path>` given above):

.. code-block:: text
        :linenos:
        
        color_file=/iocPRJ/color.def
        eclipse.preferences.version=1
        font_file=/iocPRJ/font.def
        opi_search_path=/synApps/areaDetector/ADApp/op/opi | ... you get the idea, it's a long line
        popup_console=ALL
        top_opis=/iocPRJ/prj.opi


Creating the Beam Line Project
===========================================================

Screens for your instrument or beam line or other installation of EPICS
may already be available.  If so, you might import them by following the steps
above used to import synApps.  If you need to develop your own screens,
then follow these steps:

#. Select menu ``File-->New``
#. Open ``General`` category,
   select ``Project``,
   click ``Next`` button
#. Give it a Project name, something short such as *45ID* or *iocPRJ*
   (try to avoid using spaces, it makes things harder later on), 
#. In the ``Navigator`` view,
   open the new project by double-clicking (or any other equivalent way)
   
Create an OPI file
------------------------------------

#. Select menu ``File-->New``
#. Open ``BOY`` category,
   select ``OPI File``,
   click ``Next`` button
#. Select the folder to contain your new OPI screen,
   type the name of the new OPI file in the box,
   click ``Finish`` button

Your new screen will appear in a CSS-BOY editing window.
You might consider changing to the *OPI Editor* perspective
as this will provide much more help in editing the screen.

Once you have setup the CSS-BOY project for your EPICS installation,
you might want one particular file to be the default  *main* file
for your CSS-BOY workspace.  Edit the menu for *Top OPIs* via:
``Edit --> Preferences ... --> CSS Applications --> Display``


.. _calling.synapps.screens:

Calling synApps screens
===========================================================

Also, when calling a synApps .opi screen from the instrument or beam line, 
it is not necessary to use the full path since there is an OPI search path 
that will locate the screen.  Example, instead of::

   /synApps/motor/motorApp/op/opi/motor3x.opi

Instead, you just call::

   motor3x.opi

.. note::  If you require a specific version of synApps, for example a specific older 
                        version of areaDetector, create a separate CSS project for it in your
                        workspace.

.. TODO: could use some instructions how to create this kind of project.  An example would help.