source: cssboy_deployment/docs/source/instructions.rst @ 1056

.. $Id: instructions.rst 1056 2012-07-18 20:27:16Z jemian $

==========================
Instructions
==========================

.. caution:: At this time, this documentation is a collection of notes
        related to installation or configuration of CSS-BOY.  It needs to be 
        set into some sort of order.

Install OPI screens (and other resources such as image files, javascript,
or definition files) into projects within your workspace.  The OPI screens 
from *synApps* [#synApps]_ will go into their own project within your 
workspace.  The screens from the APS accelerator will go into another
project.  Your instrument and beam line screens will typically go into
a single project but it is possible that you might have separate projects
for upstream optics, beam line staff, and users.

  Each *project* within CSS may come from a separate location:
  
  * local directory within your account and CSS workspace
  * file server accessible from your directory space
  * NFS or SMB (Samba) file server
  * Version Control working directory
  
  You can't share the CSS Workspace with another user, 
  even if that other user is logged in with the same name.
  This will likely cause abnormal behavior for CSS.
  **But**, you can import a common or shared directory into your CSS
  workspace.

Leave the *CSS* project for use as a sandbox (special area for files
which you are testing or using for a short time and do not wish to treat
as part of everyone's workspace).


Install CSS-BOY on your computer
++++++++++++++++++++++++++++++++

CSS [#CSS]_ (Control System Studio) was designed at DESY, Hamburg, Germany.  
CSS is software that provides a rich
environment for EPICS controls.

The SNS at ORNL added the BOY (Best Opi Yet -- 
where OPI is an EPICS term Operator Programmer Interface) 
component which is an EPICS display tool.

        .. tip:: Use the SNS release
                
                For some time, APS developed a custom CSS product [#aps_css]_ to provide
                features and customizations that were not part of the SNS build.
                
                It is recommended now to use the CSS-BOY as built by the team at
                SNS [#css_boy_downloads]_.
        
        .. note:: 
           You need a Java Runtime Environment (at least) to run CSS.
           Also, you will need one or more EPICS IOCs to serve PVs
           or all you can do is use the simulator inside CSS.

#. Visit this URL and download the most-recent version of 
   **Basic EPICS** for your OS:
   http://ics-web.sns.ornl.gov/css/products.html
   
   (Alternative URL: https://ics-web.sns.ornl.gov/css/updates/apps/ )
#. Unzip the contents someplace.  Typical for me is:
   ``~/Apps/CSS_EPICS_3.1.1``


add OPI screens from synApps as a CSS project
+++++++++++++++++++++++++++++++++++++++++++++

#. 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 &
   
#. 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)

.. note::  If CSS reports that your synApps directory cannot be imported
        since it is not a *project*, you can make it a project by creating
        a ``synApps/support/.project`` text XML file with this content::

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


define 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.


Define a project for your EPICS installation
+++++++++++++++++++++++++++++++++++++++++++++

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 *44ID* 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``


Setting the OPI Search Path
------------------------------------

.. note:: This could be set in a ``.ini`` file.  Needs some research...
        Check the help for "Setting Preferences"
        
        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.


Getting the synApps OPI screens
-------------------------------------

To get the synApps OPI screens, you need to do one of the following 
(subject to revision):

#. import synApps project from /APSshare
        path:   /APSshare/epics/synApps_5_6/support/all_opi


#. checkout synApps development trunk from SVN, then import as project
        There is a script to do the checkout::

                https://subversion.xor.aps.anl.gov/synApps/support/trunk/checkout.csh 
        
        One way is to place this file in */usr/local/epics* and then run it.
        It will create a directory called *synAppsSVN/support* that contains
        the development trunk.


Importing the synApps OPI screens
-------------------------------------

To import synApps OPI screens as a project in CSS-BOY::

        Menu "File"
          -->  "Import ..."
          open  "General"
          select "Existing projects into workspace"
        button [Next]
        under "Select root directory:", browse to or enter path on file system
        make sure checkbox is marked for "synApps"
        button [Finish]


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"

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:: From 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


Calling the synApps OPI 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.


Setting the OPI Search Path
------------------------------

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

::
                             {Workspace}\.metadata\.plugins\org.eclipse.core.runtime\.settings\org.csstudio.opibuilder.prefs
        C:\Users\Pete\CSS-Workspaces\Default\.metadata\.plugins\org.eclipse.core.runtime\.settings\org.csstudio.opibuilder.prefs

Set OPI Search Path from .ini file
--------------------------------------------

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

For example::

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



Glossary of Terms
++++++++++++++++++++++++++++++++

Some of the terms used by eclipse and CSS and CSS-BOY may be unfamiliar.

.. glossary::

``.js``
        javascript file

``.opi``
        display screen file used by CSS-BOY

CSS
        Control System Studio [#css]_ from DESY, based on eclipse

CSS-BOY
        CSS Best Opi Yet EPICS Display software (replacement for medm)

eclipse
        Java-based software providing a configurable interactive 
        development environment (IDE).  Eclipse [#eclipse]_ can be highly
        customized to deliver a specific application,
        such as CSS or CSS-BOY.

Editor
        One type of display in eclipse.

Navigator
        Used to browse the Workspace for files and subdirectories.

Perspective   
        Defined arrangement of Views and Editors in eclipse.
        A Perspective can be customized and saved within
        the Workspace for later recall.

Project
        subdirectory within a *workspace* containing
        related files and subdirectories

View
        One type of display in eclipse, some can be undocked
        (or torn-off) so they can be a spearate window.
        
        ??? Are undocked Views saved as part of the Perspective? ???

Workspace
        file system directory containing directories 
        and files used by a single CSS-BOY user



Footnotes
++++++++++++++++++++++++++++++++

.. [#eclipse]                   http://eclipse.org
.. [#css_boy_downloads] http://ics-web.sns.ornl.gov/css/products.html
.. [#css]                               http://css.desy.de
.. [#aps_css]                   http://css.aps.anl.gov
.. [#synApps]                   http://www.aps.anl.gov/bcda/synApps