Download Serialization of EPICS Datatype Standards

National Superconducting
Cyclotron Laboratory
API MANUAL
Project Name
Project Code
Account
Department
Project Leader
Project Coordinator
Serialization of EPICS Datatype Standards
SEDS
Controls and Computing
Sheng Peng
Vasu Vuppala
Name
Prepared By
Reviewed By
Approved By
Aaron Barber
Signature
Date
7/14/14
Serialization of EPICS Datatype Standards
Revision History
Version
1.0
Date
7/14/14
[BASELINE 14-JUL -14]
Author
Aaron Barber
Description
Initial document
Page 2 of 12
Serialization of EPICS Datatype Standards
Table of Contents
1
INTRODUCTION ............................................................................................................................................. 5
1.1
1.2
1.3
1.4
1.5
PURPOSE .........................................................................................................................................................5
SCOPE.............................................................................................................................................................5
DEFINITION, ACRONYMS, AND ABBREVIATIONS .......................................................................................................5
REFERENCES .....................................................................................................................................................6
OVERVIEW .......................................................................................................................................................6
2
INSTALLATION ............................................................................................................................................... 6
3
JAVA INTERFACE ............................................................................................................................................ 7
3.1
PRODUCT FUNCTIONS ........................................................................................................................................7
3.1.1 Creating SEDS Data in Memory................................................................................................................8
3.1.2 JSON Conversion ......................................................................................................................................9
3.1.3 EPICS VType Conversion .........................................................................................................................10
3.1.4 CSV Conversion ......................................................................................................................................11
4
EXCEPTION HANDLING ................................................................................................................................ 12
5
SUPPORT ..................................................................................................................................................... 12
[BASELINE 14-JUL -14]
Page 3 of 12
Serialization of EPICS Datatype Standards
List of Figures and Tables
Table 1 Glossary ............................................................................................................................................ 5
[BASELINE 14-JUL -14]
Page 4 of 12
Serialization of EPICS Datatype Standards
1 Introduction
National Superconducting Cyclotron Laboratory (NSCL) is a world leader in rare isotope research and
nuclear science education. NSCL scientists and researchers conduct advanced research in fundamental
nuclear science, nuclear astrophysics, and accelerator physics. To facilitate the research, NSCL operates
multiple particle accelerators.
The control system at NSCL enables operators to control the various devices in the lab: ion sources,
cyclotrons, beam lines, experimental devices, and auxiliary equipment. It is based on the Experimental
Physics and Industrial Control Systems (EPICS) standard. EPICS is a distributed soft real-time control
system for large scientific experiments.
SEDS is a protocol for data processing. SEDS provides a set of software designs for high level composite
data types suitable for the application level data exchange between EPICS V4 network endpoints. SEDS
provides protocol documentation and datatype schemas. The intent is to serialize and deserialize the
datatypes as self-describing data for persistence. SEDS protocol specifies JSON as the self-describing
data language used to represent all SEDS data structures. This project will provide users the ability to
transmit standardized data between programming languages and to store standardized data in a
database.
SEDS consists of the following:


Protocol documentation
o Data structures supported by SEDS
o JSON Schemas to validate JSON data to conform to SEDS protocol
Java API
o Convert SEDS data structures between VType structures, JSON structures, and CSV data
1.1 Purpose
The objective of this document is to describe the methods of programmatically working with the SEDS
protocol through the SEDS API.
1.2 Scope
This document provides an overview of the API.
1.3 Definition, Acronyms, and Abbreviations
Table 1 Glossary
Item
SEDS
Controls
EPICS
NSCL
FRIB
CSV
[BASELINE 14-JUL -14]
Description
Serialization of EPICS Datatype Standards
FRIB’s Controls and Computing Department
Experimental Physics and Industrial Control System
National Superconducting Cyclotron Laboratory
Facility for Rare Isotope Beams
Comma Separated Values
Page 5 of 12
Serialization of EPICS Datatype Standards
JSON
PV
JavaScript Object Notation
Process Variable. Identifier for a data item in EPICS.
1.4 References
1. Open EPICS Web Site, http://openepics.sourceforge.net
1.5 Overview
The next section describes the prerequisites for using the API. The subsequent section describes the Java
interface.
2 Installation
To be able to implement a custom API, you must first install the SEDS protocol documents. If you intend
to use the Java API, you must download the corresponding libraries. The SEDS repository contains both
these modules. The documentation and the libraries are available in the SEDS repository.
The Java API depends on the schema files from the protocol documents. Ensure that the version of the
Java API and the version of the schemas match.
[BASELINE 14-JUL -14]
Page 6 of 12
Serialization of EPICS Datatype Standards
3 Java Interface
This section discusses the API summary for the Java implementation of the SEDS protocol. The Java API
defines the SEDS data structures as objects, and provides processing objects to work with them.
The Java API works with three object types: SedsType objects, VType objects, and JsonObject objects.
SedsType objects are the SEDS data structures. VType objects are the EPIC VType data structures that
are parallel to SedsType objects. JsonObject objects are the JavaEE representation of a map of namevalue pairs (representation of JSON in memory). The Java API provides a converter object that maps the
data between these three object types.
The Java API provides processing objects to import and export JsonObject objects to a source (such as a
stream, file, or string). The Java API provides processing objects to import and export the major SEDS
data structures to and from a CSV file.
The Java API provides factory objects to create SEDS data structures directly from raw data (primitive
data types in Java).
The Java API follows the builder design pattern, and the class “org.openepics.seds.core.Seds” provides
access to all processing objects. Processing objects provide conversion, serialization, deserialization, and
input/output utilities.
The protocol documentation provides extensive detail on the SEDS data structures and discusses the
process of how SEDS data is structured in JSON.
3.1 Product Functions
The following are the primary functions a user would use the SEDS Java API to accomplish.
[BASELINE 14-JUL -14]
Page 7 of 12
Serialization of EPICS Datatype Standards
3.1.1 Creating SEDS Data in Memory
The following describes several ways to create a SEDS data structure in memory and populate it with
data. The Java API uses the builder design pattern, and a factory is provided to handle constructing the
objects.
//Creating SEDS data in memory
SedsType value = Seds.newFactory().newScalar(
1234,
Seds.newFactory().newAlarm(
AlarmType.MAJOR,
"noStatus",
"simpleAlarm"
),
Seds.newFactory().newControl(
10d,
100d
),
null, //Display Data
Seds.newFactory().newTime(
Timestamp.of(1354719441, 521786982),
-1
)
);
//Creating SEDS data in memory
SedsType value = Seds.newSimpleFactory().newScalarArray(
new Double[]{1.0, 1.1, 2.0, 2.1}
);
//Creates a table
SedsTable table = Seds.newSimpleFactory().newTable(
new String[]{"time","velocity"},
new String[]{"s", "m/s"},
new Object[][]{
new Integer[]{0, 1, 2, 3, 4, 5},
new Double[]{9.0, 13.0, 16.0, 18.0, 19.0, 18.0},
}
);
[BASELINE 14-JUL -14]
Page 8 of 12
Serialization of EPICS Datatype Standards
3.1.2 JSON Conversion
The following demonstrates the process to serialize and deserialize SEDS data structures.
Serialization refers to mapping the data of a SEDS data structure to a JsonObject. Deserialization refers
to mapping the data of a JsonObject to a SEDS data structure.
A reader and a writer processing object are provided to convert the JsonObject to/from a data source
(such as a file or string).
//Serializing SEDS data in memory into a JSON file
SedsType value = ...;
Writer src = ...;
JsonObject jValue = Seds.newSerializer().serializeSEDS(value);
Seds.newWriter().write(jValue, src);
//Deserializing a JSON file into SEDS data in memory
Reader src = ...;
JsonObject jValue = Seds.newReader().read(src);
SedsType value = Seds.newDeserializer().deserializeSEDS(jValue);
[BASELINE 14-JUL -14]
Page 9 of 12
Serialization of EPICS Datatype Standards
3.1.3 EPICS VType Conversion
The following demonstrates the process to convert (or map the data from type X to type Y) between the
type systems (VType objects, SedsType objects, and JsonObject objects).
Note that the converter object provides functions to map to any of the three type systems from any of
the other type systems.
In this context, the VType system is referred to as the “client” type. Additionally, because the VType tag
interface does not overlap all types represented in SEDS (there exists a SedsAlarm which extends
SedsType, but Alarm (the VType) does not extend VType), casting must be done on the return of the
“toClientType” method call.
//Working with VTypes
SedsConverter<VTypeMapper> mapper = Seds.newVTypeConverter();
//Initial data
SedsType sedsValue = ...;
JsonObject jsonValue = ...;
VType vtypeValue = ...;
//Convert to SEDS
SedsType a = mapper.toSEDS(jsonValue);
SedsType b = mapper.toSEDS(vtypeValue);
//Convert to JSON
JsonObject c = mapper.toJSON(sedsValue);
JsonObject d = mapper.toJSON(vtypeValue);
//Convert to VTYPE
VType e = (VType) mapper.toClientType(sedsValue);
VType f = (VType) mapper.toClientType(jsonValue);
//Example
//This function takes the VType “double” value,
//converts the value to a JsonObject,
//and serializes the JsonObject as a String
public String getJSON(VDouble value) throws SedsException{
SedsConverter<VTypeMapper> mapper = Seds.newVTypeConverter();
SedsWriter writer = Seds.newWriter();
return writer.write(mapper.toJSON(value));
}
[BASELINE 14-JUL -14]
Page 10 of 12
Serialization of EPICS Datatype Standards
3.1.4 CSV Conversion
The following demonstrates the process to import/export between the SedsTable data structure and
CSV files.
//Reading a SEDS Table from CSV
BufferedReader reader = ...;
SedsTable data = Seds.newCSVConverter().importTable(reader);
//Writing a SEDS Table to CSV
BufferedWriter writer = ...;
SedsTable output = ...;
Seds.newCSVConverter().exportTable(output, writer);
//File Format
//File Extension: .csv
//File Contents: (see below)
//Row 1: list of column names
//Row 2: list of column units
//Row 3 ... N: column values
name1,name2,...,nameN
unit1,unit2,...,unitN
value11,value12,...,value1N
value21,value22,...,value2N
...
valueN1,valueN2,...,valueNN
//Example
//File Name: example.csv
//File Contents: (see below)
Distance,Shape,Time
Meters,,Seconds
10.1,flat,5
30.3,round,5
20.2,flat,10
90.9,round,10
[BASELINE 14-JUL -14]
Page 11 of 12
Serialization of EPICS Datatype Standards
4 Exception Handling
In the current version:

Java API
o Errors propagate and attach JSON data that caused the error
o SedsException errors are propagated when JSON data is not valid according to the JSON
schema from the SEDS protocol
o IllegalArgumentException errors are propagated from illegal values such as null
arguments
o Data is NOT validated when creating SEDS data structures in memory
o Data is validated when serializing and deserializing
5 Support
To report errors, corrections, and suggestions please visit the SEDS web site [1].
[BASELINE 14-JUL -14]
Page 12 of 12