EPICS Jackie DIIRT Integration Manual

Version 2.0.0

Sebastian Marsching

aquenos GmbH

Table of Contents
I. Overview
1. Compatibility
2. Requirements
II. What’s new in EPICS Jackie DIIRT integration 2.x
III. Using the data source
1. Configuration
2. Process variable names
3. Running inside an OSGi container
List of Tables
III.1. Data-source configuration options
III.2. Mapping of Maven group and artifact IDs to bundle symbolic names

Chapter I. Overview

The DIIRT integration for EPICS Jackie provides a datasource for the DIIRT framework, so that Channel Access channels can be used in DIIRT. EPICS Jackie is a pure Java implementation of the Channel Access protocol. Please refer to the EPICS Jackie Reference Manual available from the EPICS Jackie website to learn more about EPICS Jackie.

This integration for DIIRT is particularly aimed at users that want to use Channel Access with DIIRT, but do not want to use the Channel Access support developed as part of the DIIRT framework for licensing or technical reasons. In particular, many users might find it to be an advantage that the EPICS Jackie library (and thus this DIIRT integration) is distributed under the liberal terms of the Eclipse Public License 1.0.

This document is intended as a guide on how to integrate EPICS Jackie with DIIRT. For more details on the EPICS Jackie library, please refer to the EPICS Jackie Reference Manual. This document does not intend to describe all the details of the library’s API and its implementation. For a fully detailed description of the DIIRT integration’s API, please refer to the API reference documentation. More information about the Channel Access protocol is available in the EPICS R3.16 Channel Access Reference Manual and the EPICS Channel Access Protocol Specification. Last but not least, readers should refer to the DIIRT website in order to learn more about how to use DIIRT.

1. Compatibility

The DIIRT integration for EPICS Jackie aims to be compatible with the Channel Access support that is developed within the DIIRT project. However, there are a few minor differences that one should be aware of.

In contrast to the JCA-based data source, the EPICS Jackie data source does not support the varArray configuration attribute. EPICS Jackie always supports variable-sized arrays, so they are supported even if this attribute is set to false. However, a message that the attribute has been ignored is logged in this case.

As the EPICS Jackie data source always uses the EPICS Jackie library (which is a pure Java implementation of the Channel Access protocol), it also ignores the pureJava attribute.

In addition to the configuration attributes supported by the JCA-based data source, the EPICS Jackie data source supports a few more attributes. Please refer to Section 1, “Configuration” for details about the supported configuration attributes.

EPICS Jackie and the JCA-based data source can be used in parallel. However, when using the CompositeDataSource, care must be taken to avoid conflicting provider names. The epics-jackie-datasource-jackie module contains a DataSourceProvider that uses the name jackie. This way, the JCA-based data-source provider can be on the class-path at the same time and use its name ca.

When the JCA-based data source is not on the class-path, the epics-jackie-datasource-ca module can be used. This module provides a DataSourceProvider that uses the name ca. This way, channel names that refer to the JCA-based data-source provider using the name ca will automatically and transparently use the EPICS Jackie data source without needing any further changes.

Putting both the diirt-ca and epics-jackie-diirt-datasoure-ca module on the class-path should be avoided. Such a configuration would lead to either the JCA-based or the EPICS Jackie data source being used at random because there is no priority mechanism when multiple data-source providers use the same name.

The exception is when the code is running inside an OSGi container (e.g. Eclipse Equinox as part of Control System Studio). In this case, the activator of the com.aquenos.epics.jackie.diirt.datasource.ca bundle will register its data-source provider with the PVManager's default data source, thus overriding the regular discovery mechanism. Please refer to Section 3, “Running inside an OSGi container” for details.

1.1. OSGi

The Java archives of both the EPICS Jackie library and the DIIRT integration are distributed are ready-to-use OSGi bundles, containing the required manifests. The same applies to all dependencies of EPICS Jackie, so that it can easily be deployed inside an OSGi container (for example Apache Felix or Eclipse Equinox). Even though OSGi is fully supported, EPICS Jackie and its DIIRT integration do not have any non-optional dependencies on OSGi and can thus be used outside an OSGi container without any modifications.

Please refer to Section 3, “Running inside an OSGi container” for details about using the EPICS Jackie DIIRT data-source inside an OSGi container.

1.2. Operating systems and architectures

EPICS Jackie is a pure Java-library and is designed to run on all operating systems and architectures supporting the Java Standard Edition. There are a few places where the library makes use of platform-specific features, but neither of these are critical. In these places, the code has typically been designed to support most UNIX-like operating systems (including Linux and macOS) and Microsoft Windows.

2. Requirements

While EPICS Jackie itself can be run on Java 6 and newer the DIIRT integration needs Java 8 or newer. EPICS Jackie’s only dependency is Apache Commons Lang 3.4 (or a newer version from the 3.x branch). Apart from this, there are no dependencies (not even a logging framework), making EPICS Jackie very light-weight.

For obvious reasons, the DIIRT integration also depends on the DIIRT framework. It has been written for DIIRT 3.1.7, but is probably going to work with all versions from the 3.1.x branch. It is not going to work with version 3.0.x because version 3.1.0 introduced changes in the API that break compatibility with older versions.

Chapter II. What’s new in EPICS Jackie DIIRT integration 2.x

There are a few changes in the EPICS Jackie DIIRT integration 2.0 that change behavior compared to older versions.

New putCallback behavior

The behavior regarding the putCallback option (see Section 2, “Process variable names”) has changed. In earlier versions, setting this option to true only had the effect that the write operation returned immediately, but a completion notification would still be requested from the server.

This behavior has proven problematic because under certain circumstances, servers may behave differently depending on whether the put request is with or without a callback. In particular, there is an issue in EPICS Base (up to and including version 7.0.2) that causes problems when doing a second put with a callback for the same process variable before the first put operation has completed. If these two put operations happen over the same connection, the connection stalls for a significant amount of time.

Version 2.0 of the DIIRT integration uses a new API introduced in version 3.0 of EPICS Jackie to use the “no callback” variant of the put operation unless a callback has been requested. In addition to that, the putCallback option is now set to false by default.

Due to the need for the new API, version 2.0 of the DIIRT integration needs at least version 3.0 of the EPICS Jackie library.

Applications that need the old behavior (put with callback) for a channel, should explicitly set putCallback to true for that channel.

Chapter III. Using the data source

In order to use the EPICS Jackie DIIRT data-source, the epics-jackie-diirt-datasource module and its dependencies have to be on the class-path. When using Maven (or a compatible) build tool, the EPICS Jackie DIIRT modules as well as the EPICS Jackie modules can automatically be retrieved by defining a dependency to com.aquenos.epics.jackie.diirt:epics-jackie-diirt-datasource:2.0.0. Unfortunately, recent versions of the DIIRT libraries themselves are not available in The Central Repository at the time of writing. These libraries can either be built from source or they can be retrieved from Control System Studio’s P2 repository.

A data-source instance using the default configuration can be created with the following code:

JackieDataSourceConfiguration configuration =
        new JackieDataSourceConfiguration();
JackieDataSource dataSource = new JackieDataSource(configuration);

This dataSource can then be used like any other DIIRT data source. The configuration created with the default constructor uses environment variables for most configuration options. Please refer to Section 1, “Configuration” for details on how to manipulate the configuration.

Usually, one does not want to manually create a separate data source instance for each supported data source. Instead, one can rather us a CompositeDataSource. The easiest way of retrieving such a data source is using the PVManager’s getDefaultDataSource() method. In order to automatically register an EPICS Jackie data source with that CompositeDataSource one can put either the epics-jackie-diirt-datasource-ca or the epics-jackie-diirt-datasource-jackie module on the class-path.

The epics-jackie-diirt-datasource-ca module registers a data-source provider with the name ca, while the epics-jackie-diirt-datasource-jackie module registers a data-source provider with the name jackie. The name ca is also used by the JCA-based data-source provider in the org.diirt.support:diirt-ca module. Therefore, the epics-jackie-diirt-datasource-ca module should only put on the class-path when the org.diirt.support:diirt-ca module is not present. The epics-jackie-diirt-datasource-jackie module deliberately uses a different name, so that it can be used in parallel to the JCA-based module.

When wanting to replace the org.diirt.support:diirt-ca module, the epics-jackie-diirt-datasource-ca is the perfect choice because all channel names using the ca prefix are still going to be recognized, but EPICS Jackie is going to be used instead of JCA.

The epics-jackie-diirt-datasource-ca module may be installed in addition to the org.diirt.support:diirt-ca module when running inside an OSGi container, but even then it is not recommended. Please refer to Section 3, “Running inside an OSGi container” for details.

1. Configuration

There are different options for configuring the EPICS Jackie data source. Most configuration options can be set through environment variables and in fact this is the preferred way. When this is not desirable, one can choose between using an XML-based configuration file or configuring the data-source programmatically. The latter option is only available when creating the data source explicitly instead of using one of the data-source providers in combination with the CompositeDataSource.

The JackieDataSourceConfiguration class acts as a builder for itself, meaning that each of the methods manipulating the configuration actually returns a new instance with the respective part of the configuration being modified. The original configuration instance is never modified. One can use the configuration’s read method to create a configuration that is the result of the original configuration being updated with the configuration options loaded from the specified XML file. In fact, this is how the data sources created by either of the data source providers is configured. In that case, the XML file is loaded from its default location (DIIRT_HOME/datasource/ca/ca.xml or DIIRT_HOME/datasource/jackie/jackie.xml, depending on which provider is used). When the configuration file does not exist yet, a file containing some examples is automatically created.

The format of the configuration file has been chosen so that it is compatible with the one used by the JCA-based data-source. This means that when an existing ca.xml is found, it can be used without modifications. However, there are a few minor differences in how the EPICS Jackie data source interprets the configuration file.

The EPICS Jackie data source does not support the varArray attribute on the dataSourceOptions element. It can be specified, but it will be ignored and a different value than true will result in a message being logged. EPICS Jackie always supports variable-sized arrays, which is why specifying this configuration option does not make any sense when using EPICS Jackie.

The same applies to the pureJava attribute on the jcaContext. EPICS Jackie only has a pure Java implementation, so a different value than true does not make sense.

The EPICS Jackie data-source supports a number of additional configuration options that are not available for the JCA-based data source. For a few of the configuration options, it uses different default values than the JCA-based data source. Please refer to Table III.1, “Data-source configuration options” for a full list of configuration options supported by the EPICS Jackie data source. If a configuration option can be specified both by setting an environment variable or by specifying it in the XML file, the XML file takes precedence. This means that the environment variable is only used if the setting is not specified in the XML file. The default value specified in the table is only used when the configuration option is not specified in the XML file and the environment variable is not set either.

Table III.1. Data-source configuration options
XML pathEnvironment variableDefault valueDescription
/ca/dataSourceOptions/@dbePropertySupportednot availabletrue If true, a second monitor monitoring the PV’s meta-data is registered for each PV. This monitor uses the DBE_PROPERTY event mask. If false, the PV’s meta-data is only read once when the connection with the server is established.
/ca/dataSourceOptions/@honorZeroPrecisionnot availabletrue If true, the precision specified by a PV is honored, even if it is zero. This means that for a PV with a precision of zero, no fractional digits are printed when formatting its numeric value. If false, a precision of zero is ignored and the numeric value is formatted using a default number of fractional digits.
/ca/dataSourceOptions/@monitorMasknot availableVALUE If VALUE, the monitor mask is set to DBE_VALUE | DBE_ALARM. If ALARM, the monitor mask is set to DBE_ALARM. If ARCHIVE, the monitor mask is set to DBE_ARCHIVE. An integer number is interpreted as monitor mask where the respective bits are set.
/ca/dataSourceOptions/@rtypValueOnlynot availablefalse If true and a PV’s name ends with .RTYP, the monitor that is added for this PV uses the DBR_STRING type instead of DBR_TIME_STRING. This option exists to work around a bug in some EPICS versions where requesting the DBR_TIME_STRING type for the RTYP field would result in problems. If false, the DBR_TIME_STRING type is always requested for a PV that reports a native type of DBR_STRING, even if this PV’s name ends with .RTYP.
/ca/jcaContext/@addr_listEPICS_CA_ADDR_LIST  Same meaning and format as specified by the Channel Access Reference Manual.
/ca/jcaContext/@auto_addr_listEPICS_CA_AUTO_ADDR_LISTtrue Same meaning as specified by the Channel Access Reference Manual, but unlike the environment variable, the XML attribute uses the values true and false instead of YES and NO.
/ca/jcaContext/@auto_array_bytesEPICS_CA_AUTO_ARRAY_BYTEStrue Same meaning as specified by the Channel Access Reference Manual, but unlike the environment variable, the XML attribute uses the values true and false instead of YES and NO. Please note that specifying this option has no effect when the max_array_bytes attribute is specified in the configuration file because that attribute is going to take precedence.
/ca/jcaContext/@connection_timeoutEPICS_CA_CONN_TMO30.0 Same meaning and format as specified by the Channel Access Reference Manual.
/ca/jcaContext/@cid_block_reuse_timenot available900000 Number of milliseconds before a client-side channel ID may be reused.
/ca/jcaContext/@hostnamenot availablesystem’s hostname Hostname sent to a Channel Access server at the start of a new connection.
/ca/jcaContext/@max_array_bytesEPICS_CA_MAX_ARRAY_BYTES  Same meaning and format as specified by the Channel Access Reference Manual. The value of this attribute takes precedence over the auto_array_bytes attribute, so if both are specified, the auto_array_bytes attribute has no effect. However, this does not apply to the EPICS_CA_MAX_ARRAY_BYTES environment variable: The value of this variable is overridden if auto_array_bytes is set to true.
/ca/jcaContext/@max_search_periodEPICS_MAX_SEARCH_PERIOD300.0 Same meaning and format as specified by the Channel Access Reference Manual.
/ca/jcaContext/@mcast_ttlEPICS_CA_MCAST_TTL1 Same meaning and format as specified by the Channel Access Reference Manual.
/ca/jcaContext/@name_serversEPICS_CA_NAME_SERVERS  Same meaning and format as specified by the Channel Access Reference Manual.
/ca/jcaContext/@repeater_portEPICS_CA_REPEATER_PORT5065 Same meaning and format as specified by the Channel Access Reference Manual.
/ca/jcaContext/@server_portEPICS_CA_SERVER_PORT5064 Same meaning and format as specified by the Channel Access Reference Manual.
/ca/jcaContext/@usernamenot availablesystem’s username Username sent to a Channel Access server at the start of a new connection.

2. Process variable names

Usually, the process variable (PV) names are simply interpreted as Channel Access channel names and passed on to the Channel Access client. However, there is a way of specifying additional per-PV configuration options as part of the PV name.

Such a configuration string has the form of an object in JSON syntax and is separated from the channel name by a space. For example, if the channel name is “myChannel” the complete PV name including a configuration string might be “myChannel {"longString":true}”.

At the moment, the EPICS Jackie data source supports two configuration options. The longString option specifies whether a channel having a native data-type of DBR_CHAR should be treated as a string (true) or as an array of numeric values (false). By default, this option is false, except for channel names matching a specific pattern (see below).

The putCallback option specifies whether, when writing a value, the data source should wait for an acknowledgement from the server (true) or should report success as soon as the request is sent (false). By default, this option is false.

The EPICS Jackie data source uses an actual JSON parser when processing the configuration string, so any valid JSON representation of these configuration options is accepted. The JCA-based data source, however, is more picky and only accepts the four fixed strings {"longString":true}, {"longString":false}, {"putCallback":true}, and {"putCallback":false}. So if one wants the PV names to stay compatible with the JCA-based data source, one has to restrict oneself to these four variants and cannot specify more than one configuration option at the same time.

The EPICS Jackie data source treats channel names in a special way when they have the form “myName.FIELD$”, where “myName” is any string and “FIELD” is any string starting with an upper-case letter and only containing digits and upper-case letters. For such PVs, the longString option is set to true by default, but it can be overridden by explicitly setting it as part of the JSON string mentioned earlier.

3. Running inside an OSGi container

The EPICS Jackie DIIRT integration modules and there dependencies are distributed as OSGi bundles, so they can easily be used inside an OSGi container. Please refer to Table III.2, “Mapping of Maven group and artifact IDs to bundle symbolic names” for a list of the modules and their respective bundle symbolic names.

Table III.2. Mapping of Maven group and artifact IDs to bundle symbolic names
Group IDArtifact IDBundle symbolic name
com.aquenos.epics.jackieepics-jackie-clientcom.aquenos.epics.jackie.client
com.aquenos.epics.jackieepics-jackie-commoncom.aquenos.epics.jackie.common
com.aquenos.epics.jackie.diirtepics-jackie-diirt-datasourcecom.aquenos.epics.jackie.diirt.datasource
com.aquenos.epics.jackie.diirtepics-jackie-diirt-datasource-cacom.aquenos.epics.jackie.diirt.datasource.ca
com.aquenos.epics.jackie.diirtepics-jackie-diirt-datasource-jackiecom.aquenos.epics.jackie.diirt.datasource.jackie
com.aquenos.epics.jackie.diirtepics-jackie-diirt-vtypecom.aquenos.epics.jackie.diirt.vtype

Usually, only one of the com.aquenos.epics.jackie.diirt.datasource.ca and com.aquenos.epics.jackie.diirt.datasource.jackie bundles is installed. The com.aquenos.epics.jackie.diirt.datasource.ca bundle is intended to replace the org.diirt.support.ca bundle, while the com.aquenos.epics.jackie.diirt.datasource.jackie bundle is intended to be used side-by-side with it.

When running inside an OSGi container, the activator of the com.aquenos.epics.jackie.diirt.datasource.ca bundle registers its data-source provider with the PVManager's default data source, thus overriding the regular discovery mechanism. This means that if both the com.aquenos.epics.jackie.diirt.datasource.ca and the org.diirt.support.ca bundle are present, the provider from EPICS Jackie will take precedence when using the PVManager’s default data source. However, this does not apply when creating a CompositeDataSource directly (using its constructor or the DataSourceProvider’s createDataSource method). In this case, the ambiguity of which data-source provider is going to be used for the ca name remains. For this reason, it is best to avoid installing both the com.aquenos.epics.jackie.diirt.datasource.ca and the org.diirt.support.ca bundle inside the same OSGi container.

The easiest way of installing the EPICS Jackie data source in Control System Studio (or any other Eclipse-based product) is using the P2 repository at http://oss.aquenos.com/epics/jackie/diirt/download/update-site/2.0.0/. This repository contains the bundles for the EPICS Jackie DIIRT integration, the EPICS Jackie Channel Access client, and the Apache Commons Lang 3 library. However, it does not contain the DIIRT framework bundles as these bundles are already a part of the Control System Studio repository.