EPICS easyPVA

EPICS V4 Working Group, Working Draft, 19-Feb-2015

This version:
easyPVA.html
Latest version:
easyPVA_20150219.html
Previous version:
easyPVA_20141110.html
Editors:
Marty Kraimer, BNL
Matej Sekoranja, Cosylab
Greg White, SLAC/PSI

Abstract

EasyPVA (Easy PVAccess) is a software library that provides to an EPICS client programmer, a friendly client side programming interface to the data of an EPICS based control system. It is intended for such uses as rapid development of ad hoc programs by controls engineers, or to provide scientists a way to directly develop analytical applications.

Specifically, easyPVA provides an easy interface for pvAccess, which is the software support for high speed controls network communications used in EPICS version 4. PvAccess provides a callback based interface, which can be hard to use. EasyPVA provides an interface that does not require callbacks even for monitors.

EasyChannel provides many "convenience" methods to directly get and put scalar and scalarArray data types. Additional methods provide access to the full features of pvAccess.

EasyMultiChannel provides access to data from multiple channels as long as each channel has a top level field named value. EasyMultiChannel provides two ways to access data from multiple channels: The first is as an NTMultiChannel. The second is as a double array. The double array can be used if the value field of every channel is a numeric scalar. There is code for NTMultiChannel that helps with access to more complicated data types.

EasyPVA will become part of pvAccess when it is ready.

For more information about EPICS generally, please refer to the home page of the Experimental Physics and Industrial Control System.

Status of this Document and of the EasyPVA Software

This is the 19-Feb-2015 revision of the EPICS EasyPVA document.

The immediate outstanding issues are:

multiChannel - support unconnected channels
Currently both get and monitor require that all channels are connected.
muitiChannel monitor eventCalllback
Not sure this is handled correctly
multiChannel deltaTime
Not sure this has a good algorithm

This document acts as both a specification document and as a user guide. As of this revision, the software is NOT specification complete. Therefore, readers should be aware that the present implementation may not include all of the facilities described here. In addition the API is not final and may change.

As of this revision, at draft Java interfaces have been described here for most of the intended EasyPVA facilities. However, EasyPVA, EasyChannel, EasyGet, EasyPut, EasyMonitor, EasyMultiChannel, EasyMultiGet, EasyMultiPut, EasyMultiMonitor,and EasyRPC are the only interfaces currently implemented, and they have only been implemented in Java. In addition EasyMultiGet and and EasyMultiPut have methods that mention NTMultiChannel. They provide a top level pvStructure that has the format of an NTMultiChannel. Until normativeTypesJava is implemented no helper facility is available for using the data.

There is example source code that exercises the Java implementation of EasyGet, EasyPut, EasyMultiGet, EasyMultiPut, and EasyRPC. AllTests runs all the Example tests. There is also a test suite for EasyGet. However, it is not complete and much more testing should be done.

Table of Contents


Introduction

EasyPVA is a synchronous API for accessing PVData via PVAccess. It provides an interface to many of the features provided by pvData and pvAccess.

The EasyPVA API has the following features:

  1. Makes common requests easy to program
  2. Provides full access to the pvAccess API for more demanding applications
  3. Allows efficient client side programs.

The following describes the Java version of EasyPVA. Since newer versions of Matlab support direct calls to Java, EasyPVA is ideally suitable for accessing EPICS data from Matlab. There will also be C++ version.

This is the overview for EasyPVAJava. JavaDoc documentation is available at doxygenDoc

Initialization

A client obtains the interface to EasyPVA via the call:

EasyPVA easy = EasyPVAFactory.get();

The client can make this call many times, but an instance of the EastPVA interface object is only created in the first call. This first call also starts the PVAccess client factory.

EasyPVA Overview

EasyPVA creates interfaces to one of the following:

EasyChannel
This creates an interface for accessing a single channel.
There are two methods for creating an EasyChannel, with the difference being that the second specifiers the name of the provider. The other assumes that the provider is "pva" (pvAccess).
EasyMultiChannel
This creates an interface for accessing a set of channels.
There are multiple methods for creating an EasyMultiChannel. The provider can be supplied or use a default of "pva". A union for the UnionArray for accessing the value fields of each channel can be provided or a default of variant union will be used.

There are additional methods that allows the client to:

  1. Control how error messages are handled.
  2. Control when get/put commands are sent the channel or channels.

EasyChannel Overview

This interface creates Easy support for each PVAccess::Channel create method:

EasyField
This gets the introspection interface from a channel. The implementation provides full access to the features of Channel::getField.
EasyProcess
This is used to process a channel. The implementation provides full access to the features of ChannelProcess.
EasyGet
This is used to get values from a channel. The implementation allows full access to all the features of ChannelGet. By default it asks for the fields value, alarm, and timeStamp. If the channel has a value field then EasyGet provides convenience methods for a scalar value and for an array value.
EasyPut
This is used to get the current value of a channel and to put values to a channel. The implementation allows full access to all the features of ChannelPut. By default it asks for the field value, alarm, and timeStamp. If the channel has a value field then EasyPut provides convenience methods for a scalar value and for an array value.
EasyRPC
This is an interface to ChannelRPC. The implementation allows full access to all the features of ChannelRPC.
EasyPutGet
This is an interface to ChannelPutGet. Details TBD.
EasyMonitor
This is an interface to Monitor. The implementation allows full access to all the features of pvAccess Monitor.
EasyArray
This is an interface to ChannelArray. Details TBD.
EasyProcess
This is an interface to ChannelProcess. Details TBD.

EasyMultiChannel Overview

This interface creates Easy support for accessing a set of channels. The only requirement of the channels is that each must have a top level field named value.

EasyMultiGet
This is used to get values from a a set of channels. The result can either be an NTMultiChannel structure or a double[] array. The createGet method determines the result type.
EasyMultiPut
This is used to get and put values from/to a set of channels. The data supplied can either be an NTMultiChannel structure or a double[] array. The createPut method determines the type.
EasyMonitor
This is used to monitor values from a set of channels. Each event can either be an NTMultiChannel structure or a double[] array. The createMonitor method determines the data type.

shell

Directory shell has the following files:

exampleDatabaseEasyPVA.zip
When unzipped this is used to create an example IOC database. The database has the record used by the examples are tests that come with easyPVAJava. It uses pvDatabaseCPP to build the database. After unzipping the file:
cd configure
cp ExampleRELEASE.local RELEASE.local
edit RELEASE.local
cd ..
make
cd iocBoot/exampleDatabase
../../bin/<arch:>/exampleDatabase st.cmd
You now have a running database.
source
This file creates the CLASSPATH required to run the examples and tests. You have to edit it for your environment.
rpcServiceExample
This starts the RPCServiceExample. This is required by ExampleEasyRPC.
exampleGet
This runs ExampleGet.
exampleGetDouble
This runs ExampleGetDouble
doublePut
This runs DoublePut.
doubleArrayPut
This runs DoubleArrayPut
exampleMonitor
This runs ExampleMonitor
exampleMonitorCallback
This runs ExampleMonitorCallback
exampleMultiMonitor
This runs ExampleMultiMonitor. It and polls every few seconds for monitor events. It gets data as NTMultiChannel.
exampleMultiMonitorDouble
This runs ExampleMultiMonitorDouble. It has an event listener for new events. It gets data as an array of doubles.

Examples

These are examples in package org.epics.pvaccess.easyPVA.example See the source code for each example. In order to run the examples exampleDatabaseEasyPVA must be running.

There is a shell command to run each example,

Tests

A test directory has a number of tests for easyPVAJava. In order to run the tests both exampleDatabaseEasyPVA and rpcServiceExample must be running. For now these tests are being run as eclipse unit tests. The tests also provide examples of using EasyPVA.