From MdsWiki

(Difference between revisions)

Revision as of 12:12, 16 June 2017

1 MDSplus EPICS interface

MDSplus EPICS interface

The MDSplus interface for EPICS is composed of three main components:

A IOC record which allow using MDSplus functionality from within EPICS Input/Output Controllers;
A Channel archiver for MDSplus, for storing data generated within EPICS IOCs (and more in gereral by any Channel Access Server (CAS) application) exported using the Channel Access protocol into MDSplus trees;
A Channel Access Server for exporting MDSplus configuration data to IOC records using the Channel Access protocol.

MDSplus Records for EPICS I/O Controllers

In EPICS control and supervision is carried out by I/O Controllers (IOCs) . Every I/O controller is an application which executes a set of interconnected components called Records. Every record carries out a specific set of actions and can propagate data to other interconnected records. The behavior of a IOC is therefore defined by the associated records, and such configuration is stored as a text file. Graphical tools exist for the proper record programming and interconnection. Every record defines a set of fields which define its behavior. Records can be executed either periodically or when the the records connected via incoming links are executed. The basic set of EPICS records has been extended to provide MDSplus functionality within IOCs, via the mdsexpr record, for evaluating MDSplus expressions. MDSplus expressions represent a very flexible way for retrieving data or executing actions, including saving data in MDSplus trees. The corresponding expression is evaluated every time that record is processed in the EPICS IOC.

mdsexpr record

When processed, record mdsexpr will provide the evaluation of the specified MDSplus expression. Since in MDSplus expressions represent a very general concept, evaluating a MDSplus expression may involve many different actions. If the expression is used in the traditional way, it will perform the computation specified by field EXPR, possibly taking up to 8 arguments, specified by fields INP1-8 (links to data arguments) and FT1-8 (types of data arguments). The result of the evaluated expression is stored in field VAL, converted to the type specified in field FTVL. Field NORD will contain the number of returned data items (>1 if an array is the result of the expression evaluation). The expression may also contain calls to routines of shareable libraries, so this record can also be used to trigger external computation, possibly taking inputs from the records connected to the mdsexpr record.

The evaluation of the expression can be carried out either locally or remotely, on any node running a mdsip server. In the latter case, the possible arguments are sent over the network and the result is sent back, using the mdsip protocol for remote data access.
The expression may also contain references to MDSplus trees: in this case fields EXP and SHOT specify the name and the shot of the tree to which data item in the expression refer to. If field EXP is empty it is assumed that the expression does not refer MDSplus pulse files (trees) and no tree is open during record initialization.
In order to specify external arguments to the expression specification, use $ arguments in the textual expression definition (field EXPR). For example, the evaluation of expression 2 * $ + $ will take the first argument specified in field INP1, multiply it for 2 and then add the second argument, specified by field INP2. Array arguments are supported since MDSplus is able to handle multidimensional elements in expression evaluation.
The specific fields of mdsexpr record are:

DTYP Device type, must be devExprSoft;
LOC Local/Remote switch. If remote, the expression is evaluated on the machine whose address is specified in DSIP;
DSIP Address of the mdsip server which will evaluate the expression;
EXPR Textual specification of the expression. Refer to MDSplus documentation for syntax description and examples;
INP1 - INP8 Input specifications, typically links to other records, they are associated with the $ argument specification in the textual expression description in EXPR;
FT1 - FT8 Type specification of the input fields;
FTVL Output type. The result of the expression is converted to the specified type;
NORD Number of returned elements, > 1 if the evaluation of the expression is an array;
NELM Maximum number of elements: used to dimension the internal buffers. Must be not less than the maximum number of samples for the inputs and the computed value;
EXP Tree name in case a tree has to be open during expression evaluation (in the case the expression contains references to data item stored in MDSplus trees). When containing an empty string no tree is open;
SHOT Shot number of the tree to be open.
ERRM Error message string. After processing it will contain the error message in case of errors.

The result of the expression is then stored in field VAL

Installation

The files required to install the records in EPICS are contained in <MDSplus root>/epics/mdsrecord.
Basic installation is performed in following steps:

Create a EPICS directory tree named mdsplusSup using the EPICS procedure MakeBaseApp starting from root <ApplicationRoot>
Copy the files in <MDSplus root>/epics/mdsrecord into the directory created: <ApplicationsRoot>/m-mdsplusSup/src/main/epics/mdsplusSupApp/src/
Build it with the EPICS mvn compile command

In order to use mdsexpr record in a EPICS IOC (named <AppName>), the following actions are requied in the IOC specific EPICS directory tree:

Copy all the dbd files from <MDSplus root>/epics/mdsrecord into <AppName>/src/main/epics/<AppName>App/src/
Modify Makefile in that directory to include the following lines:

#===========================
# MDSplus record support

<AppName>_DBD += mdsexprRecord.dbd
<AppName>_DBD += devMeSoft.dbd
<AppName>_DBD += devExprSoft.dbd

<AppName>_LIBS += mdsplusSup
mdsplusSup_DIR += <ApplicationsRoot>/m-mdsplusSup/target/main/epics/lib/linux-x86_64 
mdsplusSup_LIBS += MdsObjectsCppShr
mdsplusSup_LIBS += MdsIpShr
MdsObjectsCppShr_DIR += /usr/local/mdsplus/lib/
MdsIpShr_DIR += /usr/local/mdsplus/lib/

Build the application with the EPICS command mvn compile

MDSplus Channel Archiver for EPICS

The MDSplus channel archiver allows to connect to a set Process Variables (PVs) that are exported via Channel Access, and to store their values in a MDSplus tree. Every channel can be acquired in either of the following modes:

Scan mode The channel is read periodically, at a programmable read rate;
Monitor mode The channel is acquired only when its actual value changes and is therefore exported via the monitor functionality of Channel Access. This is the default and suggested mode of operation;
Scan/Monitor mode The channel is actually recorded using the monitor mechanism (i.e. a network transaction occurs only when its value changes), but it is saved in the pulse file at the specified scan rate. This feature is useful to avoid useless remote data accesses in the case the data items does not change frequently.

Data items are stored in the corresponding nodes in the MDSplus tree using segmented data items. Received data is buffered in memory until a preset number of samples (defined by the parameter BUF_SIZE) has been received. The number of samples to be stored in memory before being written in the pulse file depends on the rate at which PV values are updated. For PV changing at a low rate it is preferred to store every sample in the pulse file as soon as it is received, that is, defineBUF_SIZE equals to 1. For PVs changing at higher rate, using a buffer size greater than 1 improves overall performance since it avoids writing samples individually in the pulse file. The buffer size can be set at any level by defining a node named BUF_SIZE. BUF_SIZE definition is valid for every PV defined in the same tree level and corresponding subtrees, unless overridden by another BUF_SIZE node below. The default value of buffer size is 300 samples.

The command syntax for ChannelArchiver is:

java ChannelArchiver <MDSplus tree> <shot> [segment_size]

The command requires the specification of a tree from which the program will retrieve all the required information on the groups and the channels to be acquired. It is necessary to include <MDSplus root>/java/classes/mdsobjects.jar in env variable CLASSPATH.

The definition of the PVs to be monitored is implicitly defined in the target MDSplus tree. ChannelArchiver expects a given structure (subtree) containing a set of items (some mandatory, some optional). The subtree defining a given PV can be anywhere in the pulse file. When launched, ChannelArchiver scans the whole tree in order to recognize subtrees defining PVs to be monitored.

An example of tree struture defining a PV is shown below

and retrieves information on the names of the Channels to be periodically read or monitored by traversing the tree. Following is an example of tree structure for a configuration defining a group named GROUP1 and two data items: DATA1 and DATA2.

In this figure the subtree with root CNFZ specifies a PV. The specification is provided by the following nodes:

REC_NAME the Name of the PV (Mandatory);
SCAN_MODE Can be either "SCAN" for cyclic readout or "MONITOR" for monitored data collection(Mandatory) .
VAL The acquired values of the data item. (Mandatory);
ALARM Alarm severity for the data item. Severity values are stored only when changed (Mandatory).
EGU Engineering units for that data item (typically the value of an IOC record)(Optional);
HOPR High operating range for the data item(Optional);
LOPR Low operating range for the data item(Optional);
PERIOD Acquisition period (meaningful only if mode is SCAN);

At the top level some optional parameters are defined:

FILE_SIZE it represents the largest dimension in MBytes of the tree. Further data is stored in a tree with a subsequent shot number. The default value is 1GByte;
GET_TRESH it represents the period (in seconds) under which a SCAN definition for channels is changed into SCAN/MONITOR. The default value is 1 seconds;
IGN_FUTURE it represents the maximum time in advance (in hours) in respect of the time of the last sample above which the received data item is discarded. The default is 6 hours;

It is possible to convert the XML definition of the original EPICS channel archiver tool into the XML specification of the reference tree for the MDSplus ChannelArchiver. Following is the xml definition of the original archiver tool, corresponding to the tree shown above:

The following command translates the original channel archiver configurationinto the tree specification in xml of the for the MDSplus CannelArchiver.

xsltproc epics2mdsplus.xsl <original xml description>.xml > <TreeName>.xml

epics2mdsplus is a XSL translation file available in <MDSplusRoot>/epics/archiver. The second argument is the file name of the original EPICS channel archiver configuration and the output is redirected to a xml file containing the MDSplus xml definition for a tree. Such description is converted into a MDSplus tree with the following command:

java CompileTree <TreeName>.xml <TreeName>

after making sure that <MDSplusRoot>/java/classes/jTraverser.jar is included in CLASSPATH.

Currently, the MDSplus ChannelArchiver does not support http-based introspection for getting information from a running ChannelArchiver program. It is planned that these feature will be added in the next months.

Directory <MDSplusRoot>/epics/archiver contains also two jar files implementing the EPICS Channel Access protocol. In order to compile ChannelArchiver.java you need to include these two jar files in CLASSPATH together with the jar file <MDSplusRoot>/java/classes/mdsobjects.jar

MDSplus Channel Access server for EPICS

The MDSplus Channel Access Server exports data contained in pulse files over Channel Access. It is intended to ease the usage of MDSplus for storing configuration data and to let such data be natively available in IOCs. It is also possible to use any EPICS tool (e.g. from CSS) for the graphical configuration set-up, using a MDSplus pulse file as data repository. In this case the presence of the pulse file becomes transparent (both the interface and the IOC records access data over Channel Access), but allows for a unique repository of configuration data, following the data centric philosophy of MDSplus.
The MDSplus Channel Access server can operate in two modes: append and non append. In non append mode data written through Channel Access overwrites previous data for that Process Variable in the pulse file. In append mode, previous data is not deleted, so that the history of that Process Variable is maintained in the pulse file. In the latter case MDSplus segments are used, and the old values together with their associated times (i.e. the EPICS time at which they have been set) are available in the pulse files.

The command line syntax of the MDSplus ChannelAccess server is:

casmds <experiment_name> <shot> [append]

When started, the server scans the pulse file in order to find the defined tag names. It is expected that data associated with a single process variable will be contained in a subtree. The only mandatory data item for this subtree are PV_NAME containing the name of the Process Variable and VAL, containing the actual value of the corresponding PV. If the usage of node VAL is TEXT, the PV will be exported as a text PV, otherwise it is exported as a numeric PV. The other (optional) nodes of the subtree associated with a given Process Variable are:

DIMS: specifies whether the numeric PV is a scalar or a (multidimensional) array. It is an integer array: if empty or missing, the PV is assumed to be scalar, otherwise it contains for each dimension the corresponding number of elements
LOPR
HOPR: operating range definition
HIGH_ALARM
LOW_ALARM: alarm threshold definition
HIGH_WARN
LOW_WARN: warning threshold definition
HIGH_CTRL
LOW_CTRL: control threshold definition
HIGH_GRAPH
LOW_GRAPH: graphical display limits
UNITS: the units for the PV
ENUMS : enumerated state strings

Except for VAL, the other PV data items are optional and are read at startup. They are used to provide additional information in the Channel Access protocol as well as for setting the appropriate Alarm and severity definition when PVs are monitored.

Installation

The MDSplus Channel Access server is implemented as a set of C++ classes which inherit from the EPICS Channel Access Portable Server. The source files are in <mdsplus_distr_root>/epics/cas. In order to build the MDSplus Channel Access Server the following steps are required:
- Using the EPICS MakeBaseApp perl script build the directory tree and the associated configuration file. Call the application casmds. The command is:

<epics root>/epics/base/bin/<arch>/makeBaseApp.pl -b $EPICS_BASE -t caServer casmds

where <epics root> and <arch> refer to the root directory of EPICS distribution and the used architecture, respectively.
- Copy the source files in <mdsplus_distr_root>/epics/cas to <appRoot>/casmdsApp
- Add the following lines to the Makefile defined in <appRoot>/casmdsApp (where it is assumed that the MDSplus shared libraries are in /usr/local/mdsplus/lib64), replacing the lines starting with casexampleSRCS +=:

SRCS += main.cc
SRCS += mdsServer.cc
SRCS += mdsPV.cc
SRCS += mdsChannel.cc
SRCS += pvEntry.cc
PROD_LIBS += MdsObjectsCppShr
PROD_LIBS += MdsIpShr
MdsObjectsCppShr_DIR += /usr/local/mdsplus/lib
MdsIpShr_DIR += /usr/local/mdsplus/lib
USR_INCLUDES += -I/usr/local/mdsplus/include

- Replace in the Makefile line

PROD_HOST = casexample

with

PROD_HOST = casmds

within <appRoot>/casmdsApp call make

Retrieved from "https://www.mdsplus.org/index.php/Documentation:Users:EPICS"

 ==MDSplus Channel Archiver for EPICS==
-The MDSplus channel archiver allows to connect to a set of IOC data items which are exported via Channel Access, and to store their values in a MDSplus tree. Every channel can be acquired in either of the following modes:
+The MDSplus channel archiver allows to connect to a set Process Variables (PVs) that are exported via Channel Access, and to store their values in a MDSplus tree. Every channel can be acquired in either of the following modes:
 * '''Scan mode''' The channel is read periodically, at a programmable read rate;
-* '''Monitor mode''' The channel is acquired only when its actual value changes and is therefore exported via the monitor functionality of Channel Access. This is the suggested mode of operation;
+* '''Monitor mode''' The channel is acquired only when its actual value changes and is therefore exported via the monitor functionality of Channel Access. This is the default and suggested mode of operation;
-* '''Scan/Monitor mode''' The channel is actually recorded using the monitor mechanism (i.e. a network transaction occurs only when its value changes), but it is saved in the pulse file at the specified scan rate. This feature is useful to avoid useless remote data accesses in the case the data items does not change frequently.<br />
+* '''Scan/Monitor mode''' The channel is actually recorded using the monitor mechanism (i.e. a network transaction occurs only when its value changes), but it is saved in the pulse file at the specified scan rate. This feature is useful to avoid useless remote data accesses in the case the data items does not change frequently.<br /><br />
-Data items are stored in the corresponding nodes in the MDSplus tree using segmented data items. Received data is buffered in memory until a preset number of samples has been received. The number of samples to be stored in memory before being written in the pulse file depends on the rate at which PV values are updated. For PV changing at a low rate it is preferred to store every sample in the pulse file as soon as it is received, that is, define the buffer size equals to 1. For PVs changing at higher rate, using a buffer size greater than 1 improves overall performance sinc it avoids writing samples individually in the pulse file. The dimension of the memory buffer can be set at any level by defining a node named '''BUF_SIZE'''.   '''BUF_SIZE''' definition is valid for every PV defined in the same subtree, unless overridden  by another '''BUF_SIZE''' node in some subtree.  The default value of buffer size is 300 samples.
+Data items are stored in the corresponding nodes in the MDSplus tree using segmented data items. Received data is buffered in memory until a preset number of samples (defined by the parameter BUF_SIZE) has been received. The number of samples to be stored in memory before being written in the pulse file depends on the rate at which PV values are updated. For PV changing at a low rate it is preferred to store every sample in the pulse file as soon as it is received, that is, defineBUF_SIZE equals to 1. For PVs changing at higher rate, using a buffer size greater than 1 improves overall performance since it avoids writing samples individually in the pulse file. The buffer size can be set at any level by defining a node named '''BUF_SIZE'''.   '''BUF_SIZE''' definition is valid for every PV defined in the same tree level and corresponding subtrees, unless overridden  by another '''BUF_SIZE''' node below.  The default value of buffer size is 300 samples.
 <br />
-Channels can be grouped into groups, and it is possible to define group-level data acquisition policies. A disabling  expression can in fact be specified at the group level, possibly referring to the values of other data items. Whenever a new data item is available, the disable expression, if any, for its group is evaluated, and the data actually saved on the tree only if the result of the evaluation is 0. In this way it is possible to define data acquisition policies avoiding, for example, acquiring groups of data items in the case the corresponding plant is switched off. A flag will be associated with every data item specifying if it concurs to the evaluation of a disable expression, and in this case the data item is stored all the same in the tree.
 <br />
 The command syntax for ChannelArchiver is:<br />
  java ChannelArchiver <MDSplus tree> <shot> [segment_size]
+ <br />
-The command requires the specification of a tree from which the program will retrieve all the required information on the groups and the channels to be acquired. It is necessary to include <MDSplus root>/java/classes/mdsobjects.jar in env variable CLASSPATH.<br /><br />ChannelArchiver expects a given structure in the passed tree, and retrieves information on the names of the Channels to be periodically read or monitored by traversing the tree. Following is an example of tree structure  for a configuration defining a group named GROUP1 and two data items: DATA1 and DATA2.
+The command requires the specification of a tree from which the program will retrieve all the required information on the groups and the channels to be acquired. It is necessary to include <MDSplus root>/java/classes/mdsobjects.jar in env variable CLASSPATH.<br /><br />
+The definition of the PVs to be monitored is implicitly defined in the target MDSplus tree.  ChannelArchiver expects a given structure (subtree) containing a set of items (some mandatory, some optional). The subtree defining a given PV can be anywhere in the pulse file. When launched, ChannelArchiver scans the whole tree in order to recognize subtrees defining PVs to be monitored.
+<br /><br />
+An example of tree struture defining a PV is shown below
+and retrieves information on the names of the Channels to be periodically read or monitored by traversing the tree. Following is an example of tree structure  for a configuration defining a group named GROUP1 and two data items: DATA1 and DATA2.
 <br />
 [[Image:ChannelArchiver.jpg]]
 <br />
-At the top level some parameters are defined. Some of them have been defined for compatibility with the original EPICS channel archiver and are meaningless here. The meaningful global parameters are:
+In this figure the subtree with root '''CNFZ''' specifies a PV. The specification is provided by the following nodes:
+* '''REC_NAME''' the Name of the PV  (Mandatory);
+* '''SCAN_MODE''' Can be either "SCAN" for cyclic readout or "MONITOR" for monitored data collection(Mandatory) .
+* '''VAL''' The acquired values of the data item. (Mandatory);
+* '''ALARM''' Alarm severity for the data item. Severity values are stored only when changed (Mandatory).
+* '''EGU''' Engineering units for that data item (typically the value of an IOC record)(Optional);
+* '''HOPR''' High operating range for the data item(Optional);
+* '''LOPR''' Low operating range for the data item(Optional);
+* '''PERIOD''' Acquisition period (meaningful only if mode is SCAN);
+<br /><br />
+At the top level some optional parameters are defined:
 * '''FILE_SIZE''' it represents the largest dimension in MBytes of the tree. Further data is stored in a tree with a subsequent shot number. The default value is 1GByte;
 * '''GET_TRESH''' it represents the period (in seconds) under which a SCAN definition for channels is changed into SCAN/MONITOR. The default value is 1 seconds;
 * '''IGN_FUTURE''' it represents the maximum time in advance (in hours)  in respect of the time of the last sample above which the received data item is discarded. The default is 6 hours;
-At the group level item '''DISABLE''' is defined, containing the definition of the disable expression for that group. The group subtree contains as many subtrees as the number of defined channels for that group. Every channel subtree defines the following configuration items:
-* '''REC_NAME''' the Name of the Channel for the Channel Access protocol;
-* '''EGU''' Engineering units for that data item (typically the value of an IOC record);
-* '''HOPR''' High operating range for the data item;
-* '''LOPR''' Low operating range for the data item;
-* '''PERIOD''' Acquisition period (meaningful only if mode is SCAN);
-* '''IS_DISABLE''' Indicates whether that data item contributes to the disable expression (and is therefore always stored);
-* '''SCAN_MODE''' Can be either "SCAN" for cyclic readout or "MONITOR" for monitored data collection. If mode is "SCAN" and PERIOD less than GET_TRESH, a Channel Access monitor is internally used;
-* '''VAL''' The actual values of the data item;
-* '''ALARM''' Alarm severity for the data item. Severity values are stored only when changed.
 It is possible to convert the XML definition of the original EPICS channel archiver tool into the XML specification of the reference tree for the MDSplus ChannelArchiver. Following is the xml definition of the original archiver tool, corresponding to the tree shown above:<br /><br />

Navigation

Search

Personal tools

From MdsWiki

Revision as of 12:12, 16 June 2017

Contents

MDSplus EPICS interface

MDSplus Records for EPICS I/O Controllers

mdsexpr record

Installation

MDSplus Channel Archiver for EPICS

MDSplus Channel Access server for EPICS

Installation