"EPICS For Dummies"
Andrew Hoover and Stephen Pate
NMSU
ahoover@nmsnpb.nmsu.edu pate@nmsu.edu
**********************************************************************
HOW TO CREATE AND ACCESS A "calc" DATABASE IN AN IOC USING EPICS
**********************************************************************
0. Introduction
WHAT IS GOING ON HERE? That is what I am always asking myself while I
am learning EPICS. This tutorial is intended to help you through one
EPICS exercise. We are going to make a very simple calculator (I mean
SIMPLE). In the end you will have a graphical user interface in which
you can type an equation involving the variables A and B in one window
(e.g., "A+B"), then you will be able to enter the values of A and B in
two other windows (e.g. "5" and "3") and the answer will be displayed
in a fourth window (e.g. "8"). In order to do this, we will have to
bring up the EPICS and VxWorks software systems and learn about
EPICS databases. But at the end we will have touched on a large
number of aspects of the EPICS system, aspects which will be needed in
any real application.
Outline: (1) Hardware and Software that you need
(2) Environment variables, paths, directories and all that stuff
(3) The actual calculator database -- how to make it and load it
(4) The graphical user interface
============================================================================
1. Hardware and Software that you need
Software:
EPICS software package (we use R3.12 here)
tcsh 6.06 (tcsh seems to be the best login shell for EPICS)
Gnu-make 3.75
native c compiler (cc on most machines)
perl 5.0
CVS 1.9 (PHENIX standard system for maintaining software, not
really needed for this exercise)
Hardware:
VME crate
IOC -- MVME 162 or MVME 167
vxWorks Boot Proms in your IOC
host (Solaris, HP, whatever you have)
host and IOC connected to your local ethernet
============================================================================
2. Environment variables, paths, directories and all that stuff
ENVIRONMENT VARIABLES: (we list here the values we use, your own
installation will no doubt vary)
setenv VX_HOST_TYPE solaris needed by make files
setenv VX_HSP_BASE /vxw/5.2 these three all point
setenv VX_BSP_BASE /vxw/5.2 to the operating system
setenv VX_VW_BASE /vxw/5.2 stuff loaded to the IOC
setenv EPICS_ROOT ~phoncs/epics root of all epics stuff
setenv EPICS $EPICS_ROOT needed by scripts and makefiles
setenv HOST_ARCH `$EPICS_ROOT/startup/HostArch` runs script which determines
the host architecture
setenv EPICS_EXTENSIONS $EPICS_ROOT/extensions where the extensions are
PATH: There are many modifications to this item. You need a path to
the vxWorks toolkit: /usr/local/gnu/solaris.68k/bin
You need paths to the epics executables:
$EPICS_ROOT/base/bin/$HOST_ARCH
./appSR/tools
./appSR/bin/$HOST_ARCH
./base/tools
./base/bin/$HOST_ARCH
$EPICS_EXTENSIONS/bin/$HOST_ARCH
ALL of these things are handled in the ~/.cshrc and various scripts that
it calls -- you may have to modify these scripts for your location.
WHERE THINGS ARE: (again, this is a description of our system, yours may
vary according to your tastes)
/vxw/5.2/ location of vxWorks operating system
/phenix/computing/online/epics/v3.12/ location of epics core software
Then the $EPICS_ROOT/ directory has these directories in it
apple -> /phenix/computing/online/epics/v3.12/apple
base -> /phenix/computing/online/epics/v3.12/base
config -> /phenix/computing/online/epics/v3.12/config
extensions
local_files
prod
setup_epics
setup_epics~
startup -> /phenix/computing/online/epics/v3.12/startup
app/ looks like this:
drwxr-xr-x 2 phoncs staff 512 Aug 23 05:13 adl_gen
drwxr-xr-x 6 phoncs staff 512 Aug 24 04:49 hvca
adl_gen/ contains a package of medm software written at JLab to
facilitate the production of medm gui's.
HARDWARE CONFIGURATION:
IOC -- Factory switch settings are fine -- be sure J2 is closed, as this makes
the IOC the system controller. The IOC must be installed in the
leftmost slot of the VME crate. Be careful in removing the
Motorola boot proms and replacing them with the vxWorks ones.
IOC BOOT LINE: -- READ THE MANUAL! If you have the IOC in the "[VxWorks]"
prompt, then you can print out the boot line using the "p"
command. Here is a typical output of the "p" command:
[VxWorks Boot]: p
boot device : ei
processor number : 0
host name : muon
file name : /vxw/5.2/config/mv167/vxWorks
inet on ethernet (e) : 128.123.29.114:ffff0000
host inet (h) : 128.123.29.7
user (u) : vxw
flags (f) : 0x0
target name (tn) : muonioc1
startup script (s) : /usr/users/phoncs/epics/prod/ioc/muonioc1/startup
What will happen at boot time: This IOC will call itself "muonioc1" on
the local subnet and use the IP address 128.123.29.144 (subnet mask
ffff0000). It will use the ethernet interface through its transition
module (ei) as a boot device. It will use an "rsh" command through
the account "vxw" on the host "muon" to get the vxWorks kernel and
then run the startup script also found on "muon". The IP address of muon
is 128.123.29.7.
You can change the boot line parameters using the "c" command -- you
will be prompted one at a time for each of the above items. Don't be
surprised if the delete key doesn't work properly, you may have to
start over the "c" command if you make a mistake. Be sure and check
what you did with the "p" command.
STARTUP SCRIPT: Here is a simple one:
# IOC: muonioc1
# Location: test lab in Gardiner Hall
shellPromptSet("muonioc1> ");
# network stuff
hostAdd "muon","128.123.29.7"
hostAdd "nmsnpb","128.123.29.93"
# Define HOME to operational area
HOME="/usr/users/phoncs/epics/prod/ioc/muonioc1"
cd HOME
#< loadtrial
cd "/usr/users/phoncs/epics/base/bin/mv167"
ld < iocCore
ld < drvSup
ld < recSup
ld < devSup
ld < seq
cd "/usr/users/phoncs/testepics"
dbLoad "trial.database"
iocLogDisable=1
cd HOME
memShow
iocInit "sample.def"
coreRelease()
This script just sets the prompt to reflect the ethernet name of the
processor, then adds a couple of hosts so that users can login from
them. It then sets the working directory to the location given. Then
the EPICS support software is loaded (drvSup, recSup, etc...).
Finally, "trial.database" is retrieved from the ../testepics directory
and loaded into the IOC. The only file which we will discuss now is
the "trial.database" file since it contains the description of the
database in our exercise. All the other stuff in the startup script
are support files that you would need to have loaded in any
application. (The exact directory paths used above will vary with
each installation.)
==========================================================================
3. The actual calculator database -- how to make it and load it
EPICS is about databases. The function of the database in EPICS,
typically, is to control and/or monitor remote hardware. Each
entry in the database is typically either an input to or output from a
hardware device interface, or is a computed number based on such
values. Limits can be set on the allowed ranges of these entries, and
alarms sounded in case those limits are exceeded. The entries in the
database can be backed up or restored, in part or in full, at any
time.
Our exercise will not deal with external hardware at all. We will
simply setup a "calc" database and use it as a calculator. The "calc"
database type is used for doing complex calculations from the database
entries.
At this point you need to have a copy of the EPICS IOC Record Reference
Manual, which you can find at
www.aps.anl.gov/asd/controls/epics/EpicsDocumentation/WWWPages/EpicsDoc.html
I'm using the Release 3.12 manual. In the Chapter about the Calc type
database record (in my copy this is chapter 8), you will see all the
various fields that can be in this kind of record. We will "take the
defaults" on most of this stuff. Here is brief rundown on what
happens in a calc record: There is a field, VAL, which contains the
value of the completed calculation. The calculation equation is
contained as a string in the field CALC. This equation can contain
inputs called A, B, C, D, .... K, L. You can use as many of these as
you like. For example, the CALC field may be just "A+B" which would
calculate the sum of A and B. The actual values of the inputs A and B
are themselves fields which could (for example) be related to values
coming in from hardware somewhere. We will enter the values of
the inputs from a graphical interface.
First you must create a trial.db file. Inside of this file is
where you define the EPICS supported records you wish to use. A simple
trial.db file would be:
database(trial){
record(calc,"mycalc"){
field(PREC,"2")
}
}
Note how the syntax is similar to the definition of a data structure in C.
Here I have defined a record of type "calc". I have called the
name of this record "mycalc". There are a number of predefined fields
which are then created containing default values (the VAL and CALC
fields and the input fields, for example). The only field I have
declared here is "PREC". The PREC field determines the precision to
which the value of the record will be reported (e.g. PREC = 2 means
that the the value of the record "mycalc" will be reported with 2
decimal places accuracy). Each record has an associated value,
carried by the VAL field. Calling the name of the record will give
the current value of the VAL field. The calc record supports a number
of mathematical operations and input variables. For more information
on this, consult the EPICS IOC Record Reference Manual.
To turn the trial.db file into a binary trial.database file which
is loaded into the IOC, you must use the EPICS program db2database. Simply
type "db2database trial.db", and let the program do all the work. When
db2database runs, it will look for the files "default.dctsdr" and
"default.sdrSum". You should copy these files to your working directory.
You can consult the man pages for more information on using the db2database
command (simply type "db2database").
After db2database runs, the file trial.database will appear in
your directory -- this is a binary file. This is the file which the
IOC startup script looks for when it boots (see above). After you
create trial.database, make sure it is in the directory where the IOC
will look for it and then boot the IOC from scratch and you will have
a database called "trial.database" in your IOC consisting of a calc
record called "mycalc".
=============================================================================
4. How to access and update your database -- the gui
In this exercise we are going to go ahead and introduce you to
a very nice graphical user interface (gui) system. The basic
component of the system is the Motif Editor and Display Manager (MEDM)
which provides access to the database via a gui. Normally, you could
just use MEDM and create the gui by hand. We are going to go to a
higher level of programming and use a set of tools developed at
Jefferson Lab for use with MEDM. This set of tools is called adl_gen
and you can get the software and documentation at
http://nuclear.physics.nmsu.edu/spate/phenix/epics/adl_generate.tar.gz
This contains the files:
adl-help.ps these are two ps files
adl-tech.ps which describe the software -- read them!
adl_def.h include file needed to build programs (obsolete?)
adl_gen.c c source code
adl_gen.h include files needed to build programs (we use this one)
adl_gen.o object library, you will probably need to rebuild this
for your machine
In our exersice, this set of tools is used by a C program called trialgui.c
to build a motif gui. This program "includes" the file "adl_gen.h" which
defines the adl_gen tools. You also have to link it with the "adl_gen.o"
object file. You can get the source code at
http://nuclear.physics.nmsu.edu/spate/phenix/epics/trialgui.c
After reading the adl_gen documentation, then review this source code.
Within this program, the gui is created out of a set
of "adl_object"s. You can learn more about MEDM objects at
http://www.aps.anl.gov/asd/controls/epics/EpicsDocumentation/ExtensionsManuals
/MEDM/MEDM.html (or MEDM.ps)
If you simply want to display the current value of the field, you
would use the adl_object "TEXT_UPDATE". This will create a box on the
gui screen which displays the value of the field "A" in the record
"mycalc". If you want to be able to change the actual value of "A" in
the database, you would use the adl_object "TEXT_ENTRY". This will
create a box on the gui screen that will enable you to manually type
in the value you want the field "A" to be.
If you want to access a different field, you must reset the
channel variable and create another "TEXT_ENTRY" object connected to that
channel.
Useful tip: If you want to use decimal numbers, you should set
the MEDM variable "format" to "decimal".
After compiling and linking trailgui, execute it and you will
get a file called "trialgui.adl" -- this is an ascii file which
describes the gui in a way that MEDM understands. You can start the
gui like so:
"medm -x trialgui.adl &"
and this will bring up the display.
You now have a means by which to access and update the calc
record in the IOC. You will be able to enter a formula involving the
variables A and B, enter values for A and B, and see the result calculated.
Your EPICS calculator is now complete.
=============================================================================
5. Review
1 - obtain proper hardware and software
2 - decide what you want to do
3 - read epics manuals
4 - design what you want to do around epics [editorial]
5 - create a database description (.db file)
6 - convert it to a binary database (.database file)
7 - load the database into the IOC at boot time
8 - create and start up gui
9 - you have access to your database