"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