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

.. $Id: instructions.rst 1051 2012-07-18 15:01:17Z jemian $

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

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
#. Unzip the contents someplace.  Typical for me is:
   ``~/Apps/CSS_EPICS_3.1.0``


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

#. Open the ``CSS_EPICS_3.1.0`` (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 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``


Notes
------------

.. note:: This could be set in in a ``.ini`` file.  Needs some research...

::

  Edit (Menu)
    Preferences
      CSS Applications
            Display
              BOY
                    OPI Search Path

  /synApps/areaDetector | /synApps/asyn | /synApps/autosave | /synApps/busy | /synApps/calc | /synApps/camac | /synApps/dac128V | /synApps/delaygen | /synApps/dxp | /synApps/iocStats | /synApps/ip | /synApps/ip330 | /synApps/ipUnidig | /synApps/love | /synApps/mca | /synApps/modbus | /synApps/motor | /synApps/optics | /synApps/quadEM | /synApps/softGlue | /synApps/sscan | /synApps/std | /synApps/vac | /synApps/vme | /synApps/xxx

**PRJ:** Here are these instructions as I sent them in an email on 2012-06-10::

        To get the synApps OPI screens, you need to do one of the following (subject to change as we improve this process over the next months as all these options are development status):

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


        checkout from SVN, then import project
                svn co https://subversion.xor.aps.anl.gov/bcdaext/cssboy_deployment/all_opi/ /path/to/a/new/synApps_all_opi


        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 text in entry box for "OPI Search Path" to this really long string (all one line)

          /synApps/areaDetector | /synApps/asyn | /synApps/autosave | /synApps/busy | /synApps/calc | /synApps/camac | /synApps/dac128V | /synApps/delaygen | /synApps/dxp | /synApps/iocStats | /synApps/ip | /synApps/ip330 | /synApps/ipUnidig | /synApps/love | /synApps/mca | /synApps/modbus | /synApps/motor | /synApps/optics | /synApps/quadEM | /synApps/softGlue | /synApps/sscan | /synApps/std | /synApps/vac | /synApps/vme | /synApps/xxx

        click "Ok" until you out of the dialogs.  Now the paths should work.


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

you would just call::

   motor3x.opi


Definitions
-----------

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

============  ==================================================================
term
============  ==================================================================
Workspace     file system directory containing directories 
              and files used by a single CSS-BOY user
Project       subdirectory within a ``workspace`` containing
              related files and subdirectories
``.js``       javascript file
``.opi``      display screen file used by CSS-BOY
Perspective   Defined arrangement of Views and Editors in eclipse.
              A Perspective can be customized and saved within
              the Workspace for later recall.
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? ???
Editor        One type of display in eclipse.
Navigator     Used to browse the Workspace for files and subdirectories.
eclipse       Java-based software providing a configurable interactive 
              development environment (IDE).  Eclipse can be highly
              customized to deliver a specific application,
              such as CSS or CSS-BOY.
CSS           Control System Studio from DESY, based on eclipse
CSS-BOY       CSS Best Opi Yet EPICS Display software (replacement for medm)
============  ==================================================================


.. rubric:: The Glossary

.. glossary::

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

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

``.js``
        javascript file

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

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

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? ???

Editor
        One type of display in eclipse.

Navigator
        Used to browse the Workspace for files and subdirectories.

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

CSS
        Control System Studio from DESY, based on eclipse

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


--------------------

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