DOOCS server for DUMMIES by Olaf Hensler, Gerhard Grygiel -MCS-. Date: 9.
Feb. 2010. This document describes how to come to a first DOOCS server and ...
DOOCS server for DUMMIES by Olaf Hensler, Gerhard Grygiel -MCSDate: 9. Feb. 2010 This document describes how to come to a first DOOCS server and explain all the relevant steps. This description will show how to write a DOOCS server for a hardware called “mybox”. Design Idea The main design idea of DOOCS is to model a certain piece of hardware into a software class. That means, one models an ion-pump, a magnet or one BPM. Several objects of this class are created during start-up of this server by adding them to the servers configuration file.
Preparation ●
login to a FLASH Unix server ssh ttfuser2 for SunOS-sparc ( VME front-end ), ssh flashuser for SunOS-sparcv9 ( middle-layer server ) or ssh linux4 for Linux development
●
create a doocs directory in your home directory mkdir doocs cd doocs
●
one may check the DOOCSARCH environment variable with : echo $DOOCSARCH It should be : ○
DOOCSARCH == SunOS-sparc for unoptimized server
○
DOOCSARCH == SunOS-sparcv8 for optimized VME front-end server
○
DOOCSARCH == SunOS-sparcv9 for optimized middle-layer server
○
DOOCSARCH == SunOS-i386 for Solaris Intel platfrom
○
DOOCSARCH == Linux for Debian/Linux
○
DOOCSARCH == Darwin-i386 for Apple OS
●
Checkout the configuration for Solaris or Linux cvs -d /doocs/doocssvr1/cvsroot checkout SunOS-sparc/CONFIG cvs -d /doocs/doocssvr1/cvsroot checkout SunOS-sparc/DEFINEDOOCSROOT or cvs -d /doocs/doocssvr1/cvsroot checkout Linux/CONFIG cvs -d /doocs/doocssvr1/cvsroot checkout Linux/DEFINEDOOCSROOT
●
The following script will checkout the example DOOCS server and immediately rename it to “mybox” Just run the DUMMYserver script to do the job DUMMYserver mybox In most of the cases one will write the server inside ~/doocs/source/server/ttf. The convention is, that the directory and the files are named similar to the hardware. E.g. the
directory name is “mybox”. So the directory will be ~/doocs/source/server/ttf/mybox. The header file will be eq_mybox .h and the source file will be mybox_rpc_server.cc. The server binary will be called mybox_server, the corresponding configuration has to be mybox_server.conf.
Class design Having the preparation finished, this source code can be adapted to the given hardware. The dominating design idea of a DOOCS server is, that this EqFct class should reflect the properties of the hardware. The EqFct class defines a location and gives it already about 10 standard properties. The programmer has to decide, which properties are needed in addition. These properties are picked together from a long list of data functions, called D_fct. Do I need a floating point reading (D_float) of a pressure, do I want to archive this value use D_floathist, do I have a bit register use D_status. Properly I need to switch something on or off, so D_bit is needed and has to be overloaded. Usually the hardware determines the communication to use. DOOCS offers SEDAC (D_sedac), ProfiBus (D_profi), CANbus (D_can), Ethernet (D_DOOCSenet) or VME access. There are many more, for a complete list please check the DOOCS home page. The programmer has to declare these D_fct classes in the eq_mybox .h file and give it the DOOCS network name in the mybox_rpc_server.cc file.
Most important methods ●
the constructor Inside the constructor all the DOOCS properties with its network names are defined. At start-up of the DOOCS server here are all the D_fct objects are created and initialized with the values from mybox_server.conf file.
●
the init method The init method is called at start up time for every location. It can be used to initialize the hardware during start-up of the server. All the settings from the mybox_server.conf file are already known here.
●
the update method Usually DOOCS server are using the timer of the operating system to do frequent readout of the hardware. When this timer event occurs, a function is called and loops over all locations. So all the work for one location is done inside update.
●
the online method The online method is called, when sending a “1” (type bool) to the property SET.ONLINE. The idea of this method is to find out by a hardware call, e.g. SEDAC, if a certain device is available.
●
the interrupt_usr1 method This method is call by an external signal, e.g. from the timing system, to be in synch with some hardware. Like the update method, interrupt_usr1 is called once per location.
Other methods Most of these methods are usually empty, but have to be part of the DOOCS server, cause they are declared inside the DOOCS server library. ●
eq_init_prolog ()
Called once before the init loop. May be used for global initialization, which are common to all devices e.g. open a communication. ●
eq_init_epilog () Called once after the init loop.
●
post_init_prolog () Called once before the post_init loop.
●
post_init_epilog () Called once after the post_init loop.
●
refresh_prolog () Called once before the update loop.
●
refresh_epilog () Called once after the update loop.
●
interrupt_usr1_prolog(int) interrupt_usr1_epilog(int) Called,when SIGUSR1 interrupt is used
●
interrupt_usr2_prolog(void) interrupt_usr2_epilog(void) Called,when SIGUSR2 interrupt is used
●
post_init_prolog(void)
●
post_init_epilog(void)
●
cancel(void) Called for every location, when the DOOCS server exits
●
eq_cancel(void) Called, when the DOOCS server exits
Sending commands Usually one needs to send something to the hardware to set a register or to switch a device on/off. To do it from the network one needs to overload one of the d_fct. For instance, if one wants to send a float value to the hardware, the D_float class will be overloaded. The method to overload is the D_float::set_value() method. Its sets the internal float value and one has to add software to set the hardware. // Declaration of the class class D_myfloat : public D_float { public: D_myfloat ( char* pn, EqFct* efp ) : D_float( pn, (EqFct*)efp ), eq_fct_(efp) };
void
set_value ( float f );
// Overloaded method void {
D_myfloat::set_value ( float f ) D_float::set_value ( f ); // set the local value // // Do your hardware access here
{}
}
For a more advanced example of a D_bit overloading, check the attached source code.
Compile and run In order to compile your DOOCS server, please define your environment variable DOOCSARCH and then just type make inside the source directory. On Solaris define DOOCSARCH to SunOS-sparc On Linux define DOOCSADRH to Linux $ cd ~/doocs/source/server/test/mybox $ make This make run will create an object directory called : ~/doocs/SunOS-sparc/server/test/mybox for Solaris and ~/doocs/Linux/server/test/mybox for Linux After a successful compiler run all the .o files and the actual DOOCS server binary are now inside this directory. To run the server do the following steps: cd ~/doocs/SunOS-sparc/server/test/mybox cp ~/doocs/source/server/test/mybox/mybox_server.conf . For a first local test, add/change the following line somewhere behind SVR.NAME: into the mybox_server.conf to. SVR.RPC_NUMBER:
610498009
This allows you to run the DOOCS server without a name service (ENS) entry. ./mybox_server &
starts the DOOCS server
To see it from the first client application, start our “rpc_test” program. rpc_test & Now scroll down to TEST.DOOCS, click on it and again on LOCALHOST_8888. Now you should see the location list from your mybox_server.conf file.
Install on a front-end On Solaris Under Solaris we use the standard OS package system. The server programmer has to provide a file called “pkginfo”. Edit this pkginfo file to your needs: the convention for the package name is to start the name with DOOCS and then some abbreviation of your server, e.g. DOOCSmybox. Another important entry is the RPC_LIBNO. This number is used for the name service ENS and to configure the watchdog_server on the front-ends automatically. Contact O.Hensler or G.Grygiel for this number and an entry into the nameservice ENS. To create a package just run cd ~/doocs/source/server/test/mybox make package To install this package on your front-end computer, login as doocsadm and do the following steps :
ssh myboxcomputer -l doocsadm cd /doocs/doocssvr1/SunOS-sparc/packages/obj sudo pkgadd -d . DOOCSmybox This last command installs your server and all necessary libraries on the front-end disk. The DOOCS server is now installed in /export/doocs/server/mybox_server. Just go there to edit the mybox_server.conf file, e.g. change the server location name and add your additional locations. cd /export/doocs/server/mybox_server nedit mybox_server.conf & To start the server use the “doocs” script and type : cd /export/doocs/server ./doocs mybox_server On Linux
CVS checkin In order to get our DOOCS server into the Concurrent Versioning System CVS do the following steps: cd ~/doocs/source/server/test/ cvs add mybox cd mybox cvs add eq_mybox.h mybox_rpc_server.cc mybox_server.conf pkginfo Makefile
Appendix Example header file: // file eq_example.h // // Test Eq functions class // // This is a general test server. The server get the name of the // test file and for the history file at compile-time as define parameter // inside the makefile // // // Olaf Hensler, - MCS4 // // last update: // 07. Feb. 2010 // #ifndef eq_example_h #define eq_example_h #include "eq_fct.h" #define CodeExample 10 // eq_fct_type number for the .conf file class D_mybit : public D_bit { EqFctExample* public:
eq_fct_;
// pointer to the location
D_mybit ( char* pn, u_char b, u_short* sp, EqFctExample* efp ) : D_bit( pn, b ,sp, (EqFct*)efp ), eq_fct_(efp) {} void void
set_value ( int ); read() {}
// does NOT read from .conf file at start up
}; class EqFctExample : public EqFct { private: D_floathist D_int D_status D_mybit D_bit public:
};
value_; int_value_; status_; bit0_; bit1_;
// overloaded bit
EqFctExample ( ); void void
update (); init (); // started after creation of all Eq's
int
fct_code()
{ return CodeExample; };
static int conf_done;
#endif
Example source file: // file eq_example.cc // // Example Eq function class // // This is a general example server used for the documentation // "DOOCSserver for Dummies" // // Olaf Hensler, - MCS4 // // last update: // 07. Feb. 2010 // // #include "eq_example.h" #include "eq_sts_codes.h" #include "eq_fct_errors.h" EqFct*
example_fct;
char*
object_name = "ExampleServer";
int
EqFctExample::conf_done = 0;
EqFctExample::EqFctExample ( ) : EqFct ("NAME = location" ), value_ ("FLOATDATA test value with history", this, "TEST" ), int_value_ ("INTDATA integer test value", this ), status_ ("REGISTER a hardware refister 16bits", this ), bit0_ ("BIT0 first bit of REGISTER", 0, &status_.stat_, this), bit1_ ("BIT1 second bit of REGISTER", 1, &status_.stat_, this) { if (!conf_done) { list_append(); conf_done = 1; } } void
eq_init_prolog () {}
// called once before init of all EqFct's
// // The init() method is call for every location during startup of the server // Initialization of the hardware may be done here // void EqFctExample::init ( ) { std::cout
