DABC extension to the EPICS DIM interface

Introduction

Based upon the existing EPICS DIM interface several data structures provided by DABC (Data Acquisition Backbone Core) transporting values together with additional attributes, similar to EPICS records, via the transport mechanisms of DIM should be able to be accessed from EPICS via an extension to the above mentioned original interface.

Motivation, Timescale, and Objectives

The upcoming CBM test beamtime sets the time scale for this project
connecting EPICS and DABC via DIM made visible via the CSS framework (EPICS → EPICS extensions → Control System Studio).

Objectives

Objectives of this project are:

• make existing EPICS DIM interface available
• update/extend or check this device support module to be able to access those elementary data types provided via a DIM service(/command) service

  	type	EPICS record supported and mapped to
  services
  	floating point (double)	ai/ao
  	string	stringin/stringout
  	integer	longin/longout mbbi(Direct)/mbbo(Direct)
  commands
  	no parameter, action	ao, bo, longout, stringout
  	string	stringout

• map DABC records value together with some of their attributes, defined in dabc/records.h (@JAM: could you upload/attach the records.h to EPICS records maybe by setting an additional option in the OUT/INP signaling DABC-mode :

  	type	EPICS record supported and mapped to	comments
  services
  	rate meter (double)	ai, ao
  	state	stringin/stringout	any conversion of string based information should be done in db, or some kind of enum should be provided (iterator index?) for mbbi(Direct)/mbbo(Direct), longin, longout
  	info	stringin/stringout	dito.
  	hist	hist record ???	have to check whether hist can be supported
  commands (?)
  	no parameter, action	ao/ai, bo/bi, longout/longin, stringout/stringin

• ...

---

People & Tasks

People

• Adamczweski-Musch, Jörn (JAM), EE, GSI
• Kolb, Burkhard (BK), HADES/CBM, GSI
• Zumbruch, Peter (PZ), EE/KS, GSI

---

Tasks

• Code development and extension of device support: PZ
• DABC and DIM expertise: JAM
  • Providing information about data structures
  • Providing test system
• EPICS expertise: BK, PZ
  • code checks
• EPICS runtime database building, preparations and templates: BK
• CSS based GUI building: JAM, BK
• ...

---

Details

DABC structures a.k.a. "records"

Please describe here the task of those structures, and the mapping of their values (types) and attributes to the EPICS records

rate meter

Here is definition of structure for ratemeter (from $DABCSYS/base/dabc/records.h);

typedef struct{
      float value; 
      int displaymode; // one of the DISPLAY_x
      float lower; // limit. If limits are equal, use autoscale
      float upper; // limit
      float alarmlower; // alarm
      float alarmupper; // alarm
      char color[16]; // (color name: Red, Green, Blue, Cyan, Yellow, Magenta)
      char alarmcolor[16]; // (color name: Red, Green, Blue, Cyan, Yellow, Magenta)
      char units[16];
   } RateRec;

   enum RateDisplayMode { 
        DISPLAY_ARC = 0,
        DISPLAY_BAR = 1,
        DISPLAY_TREND = 2,
        DISPLAY_STAT = 3 };
        
   extern const char* RateRecDesc;

with the RateRecDesc defining the DIM structure like this:

const char* dabc::RateRecDesc = "F:1;L:1;F:1;F:1;F:1;F:1;C:16;C:16;C:16";

The RateDisplayMode is a hint how the ratemter should be displayed on GUI (tachometer, bar, trending or statistic histogram). Can be neglected though.
Suggestion for mapping the structure elements to attributes of EPICS ai:

structure.element	EPICS - Attribute
RateRec.value	VAL
RateRec.lower	LOPR
RateRec.upper	HOPR
RateRec.alarmlower	LOW
RateRec.alarmupper	HIGH
RateRec.units	EGU
"DIMinfo name"	NAME	name is the record name to be defined in the database

-- JoernAdamczewski - 05 May 2010

state

Here is definition of structure for state (from $DABCSYS/base/dabc/records.h);

 typedef struct{
      int severity; // (0=success, 1=warning, 2=error, 3=fatal)
      char color[16]; // (color name: Red, Green, Blue, Cyan, Yellow, Magenta)
      char status[16]; // status name
   } StatusRec;
   
   extern const char* StatusRecDesc;

with the StatusRecDesc defining the DIM structure like this:

const char* dabc::StatusRecDesc = "L:1;C:16;C:16";

The color names are currently defined by

const char* dabc::col_Red = "Red";
const char* dabc::col_Green = "Green";
const char* dabc::col_Blue = "Blue";
const char* dabc::col_Cyan = "Cyan"; 
const char* dabc::col_Yellow = "Yellow"; 
const char* dabc::col_Magenta = "Magenta"; 

The possible state names appear in field status[]
and are declared as string constants in dabc/Manager.h and have currently following values:

const char* dabc::Manager::stNull = "Null";
const char* dabc::Manager::stHalted = "Halted";
const char* dabc::Manager::stConfigured = "Configured";
const char* dabc::Manager::stReady = "Ready";
const char* dabc::Manager::stRunning = "Running";
const char* dabc::Manager::stFailure = "Failure";
const char* dabc::Manager::stError = "Error";

Mapping to a EPICS mbbi could be achieved by assigning these state names to fields ZRST-FFST which should map input string from StatusRec.status to one of 16 possible states? The EPICS VAL field would then take a corresponding enumeration value. Fields severity and color could be neglected at first.

structure.element	EPICS - Attribute
StatusRec.status	see suggestion above
"DIMinfo name"	NAME	name is the record name to be defined in the database

Note that for each DABC node, the name of the DIM service indicating the FSM state is defined by string "RunState" (with the node name prefix in front).
-- JoernAdamczewski - 05 May 2010

info message

This can be used to display for each node the last current status, or to write the infos into a log file or text list field.
Here is definition of structure for info message (from $DABCSYS/base/dabc/records.h);

   typedef struct{
    int verbose; //(0=Plain text, 1=Node:text)
    char color[16]; //(Red, Green, Blue, Cyan, Magenta, Yellow)
    char info[128]; // info message
   } InfoRec;
   
   extern const char* InfoRecDesc;

with DIM structure descriptor

const char* dabc::InfoRecDesc = "L:1;C:16;C:128";;

Could be probably mapped to a EPICS stringin like this:

structure.element	EPICS - Attribute
InfoRec.info	VAL
InfoRec.color	"Green"=info, "Yellow"=warning, "Red"=error
InfoRec.verbose	neglectable
"DIMinfo name"	NAME	name is the record name to be defined in the database

additional service information

Apart from the DABC structure fields, the DIM "quality" word is used in DABC for additional information. The bytes of this word have following meanings: mode-visibility-type-status (from msb to lsb). Functions for evaluating these properties can be found in $DABCSYS/controls/dimcontrol/src/nameParser.cxx.
Especially the type field can be used to identify record (apart from the DIM service structure string); following DABC types exist (from nameParser.h):

    enum recordtype {
     ATOMIC      = 0,
     GENERIC     = 1,
     STATUS      = 2,
     RATE        = 3,
     HISTOGRAM   = 4,
     MODULE      = 5,
     PORT        = 6,
     DEVICE      = 7,
     QUEUE       = 8,
     COMMANDDESC = 9,
     INFO        = 10
    };

For EPICS use case, the types ATOMIC (simple string, integer, double); RATE (rate meter); STATUS (FSM state); and INFO (string message for logfile) are interesting.
The visibility byte uses bit flags to indicate certain GUI operation modes:

#define DABC_VIS_VISIBLE     (1<<0) //VISIBLE
#define DABC_VIS_MONITOR     (1<<1) //MONITOR
#define DABC_VIS_CHANGABLE  (1<<2)//CHANGEABLE
#define DABC_VIS_IMPORTANT  (1<<3) //IMPORTANT
#define DABC_VIS_LOGGABLE  (1<<4) //write to log window

Currently used are DABC_VIS_LOGGABLE (write info record string to a logfile, or not) and DABC_VIS_CHANGABLE (indicate that this atomic parameter may be changed by command).
The status byte may contain information for log messages like:

 enum recordstat{
     NOTSPEC    = 0,
     SUCCESS    = 1,
     MESSAGE    = 2,
     WARNING    = 3,
     ERR        = 4,
     FATAL      = 5
    };

Value message, warning, error could be expressed as alarm colors? This is additional possibility for InfoRec apart from mapping the color names.
-- JoernAdamczewski - 05 May 2010
-- PeterZumbruch - 27 May 2010

State switching commands

Declared as string constants in dabc/Manager.h with following values:

const char* dabc::Manager::stcmdDoConfigure = "DoConfigure";
const char* dabc::Manager::stcmdDoEnable = "DoEnable";
const char* dabc::Manager::stcmdDoStart = "DoStart";
const char* dabc::Manager::stcmdDoStop = "DoStop";
const char* dabc::Manager::stcmdDoError = "DoError";
const char* dabc::Manager::stcmdDoHalt = "DoHalt";

DABC uses separate DIM commands without parameters for this which are identified by these Names (note that each DIM command has name prefix which identifies the target node for command!) Exact list of example services/commands to be delivered soon.

-- JoernAdamczewski - 05 May 2010

---

Software

Development EPICS

• GSI EPICS installation: EPICS base 3.14.10 maybe 3.14.11 later

---

code repository:

starting point: EPICS DIM Interface as is

• CVS:
  • :ext:lxi001.gsi.de:/u/epics/cvs/repos/projects/projects/EPICS-DIM-interface/dev/caDIMInterface
• Tarball:
  • EPICS-DIM-Interface.tar.bz2: Tarball of the current CVS content, 18.05.2010
-- PeterZumbruch - 18 May 2010

---

DABC extension

• CVS:
  • the same as the original one, the DABC extension is a preprocessor switch checking the existence of the environment variable DABCSYS, which should have been set by a previous dabclogin.
-- PeterZumbruch - 25 Jan 2011

---

---

Test system(s)

EPICS IOC

• lxlenny32 * based on the CVS an IOC test system is started (anywhere) from where the server can be seen
• lxg1436 (CBM, BK): user: cbmdcs and cbmoper
  • started a record database in /u/cbmdcs/apps/streamTest/exampleApp/Db
  • see dabc... template and substitutions files
  • a dummy IOC with these dummy variables for testing the GUI could be started by going to ../../iocBoot/iocstream and then typing "../../bin/linux-x86/example st.cmd" on any etch linux (except lxg1436, where a sever is already running)

---

DABC/DIM server

• (JAM)
  • JAM provides a standby and on-call running DABC dummy DAC system on lxg0532
    • current configuration:
      • Controller and DIM_DNS_NODE: lxg0532
      • Combiner: lxi036, lxi048
      • Builder: lxi034

pure DIM server, serving artificial DABC structures

H.Essel provides this basic ansatz for testing:
• either use the existing goofy version :
  • # set <Testserver Directory>  TEST_BASE
export TEST_BASE=~goofy/dim/testserver
• or use the tarball:
  • testserver.tar.bz2: DIM testserver tarball
    • unpack it to <Testserver Directory>
  • # set <Testserver Directory> TEST_BASE
export TEST_BASE=<Testserver Directory>
To start follow this script:
# change to directory
cd $TEST_BASE

# init dabc settings
. dabclogin
# init dim dns settings

export DIM_DNS_NODE=$(hostname)
# start dim dns server

dimDns &
# start testserver

linux/tEPICSserver abc abc &

# start dabc monitor to check activity
moni &

-- PeterZumbruch - 19 May 2010

---

Implementation of the extensions

The DABC extension will be activated by:

• a compiler switch DABC_SUPPORT
• another keyword for the INP/OUT in the database configuration
  • Xe: complex structure extensions

    Xe=DABC:Status	state record
    Xe=DABC:Rate	rate record
    Xe=DABC:Info	info record

• examples (from templates)
  • INP/OUT: @ @T=C @S=DABC/$(node):$(nodeIndex)/$(action)$(actionNodeIndex)/DataRate.Receiver @Xe=DABC:Rate
  • all:

                   
            record(ai, "$(prefix)$(node):DataRate_Receiver") {
              field(DESC, "$(node) DataRate.Receiver")
              field(DTYP, "caDIMInterface")
              field(INP, "@ @T=C @S=DABC/$(node):$(nodeIndex)/$(action)$(actionNodeIndex)/DataRate.Receiver @Xe=DABC:Rate")
            } 

---

Status

Project Start

• Initiated Project (BK, JAM, PZ) - 05 May 2010
• Created documentation project page (PZ) - 05 May 2010

Code: (PZ)

• • 
    

    basic code ( Xe=DABC:Xyz, DABC_SUPPORT )	implemented
    state record	stringin/out implemented
    	TODO: mbbi/mbbo
    rate record	ai/ao implemented
    info record	stringin/out implemented
    Commands	TODO

  • in addition
    • general stringin/out support (data format C[:N] )
    • undefined length support (data format just Y )
    • in preparation: support for selection on structures and arrays ( e.g. "L:1;D:5;C:1;X:4" )

Debugging and Tests:

Test Systems

pure DIM server, serving artificial DABC structures

• • simple database templates for state, rate, and info
  • database built from templates (stringin and ai)
  • running IOC
  • connecting EPICS IOC
  • caget / (caput, not allowed) / camonitor
  • BOY GUI (CSS SNS): (also part of CVS)
    

DABC Test System

• • complex database templates for builder, controller, combiner, done
  • database built from templates (stringin and ai), done
  • running IOC
  • connecting EPICS IOC
  • caget /( caput, not allowed )/ camonitor
  • BOY GUI: also part of CVS
    • gui:
      
    • numbers:
      
    • rate:
      
    • status and info:
      
    • strings:
      

General

• TODO: Test by the users (BK, JAM)
• TODO: Performance Tests
• TODO: Valgrind / e-fence ...
• TODO: assert problem at IOC startup, to be investigated

---

Outlook

• let also EPICS provide/serve data in form of DABC structures

---

-- PeterZumbruch - 11 Mar 2011