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.
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.
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.
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.
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.
There are a few changes in the EPICS Jackie DIIRT integration 2.0 that change behavior compared to older versions.
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.
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.
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.
| XML path | Environment variable | Default value | Description |
|---|---|---|---|
| /ca/dataSourceOptions/@dbePropertySupported | not available | true |
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/@honorZeroPrecision | not available | true |
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/@monitorMask | not available | VALUE |
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/@rtypValueOnly | not available | false |
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_list | EPICS_CA_ADDR_LIST | Same meaning and format as specified by the Channel Access Reference Manual. | |
| /ca/jcaContext/@auto_addr_list | EPICS_CA_AUTO_ADDR_LIST | true |
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_bytes | EPICS_CA_AUTO_ARRAY_BYTES | true |
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_timeout | EPICS_CA_CONN_TMO | 30.0 | Same meaning and format as specified by the Channel Access Reference Manual. |
| /ca/jcaContext/@cid_block_reuse_time | not available | 900000 | Number of milliseconds before a client-side channel ID may be reused. |
| /ca/jcaContext/@hostname | not available | system’s hostname | Hostname sent to a Channel Access server at the start of a new connection. |
| /ca/jcaContext/@max_array_bytes | EPICS_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_period | EPICS_MAX_SEARCH_PERIOD | 300.0 | Same meaning and format as specified by the Channel Access Reference Manual. |
| /ca/jcaContext/@mcast_ttl | EPICS_CA_MCAST_TTL | 1 | Same meaning and format as specified by the Channel Access Reference Manual. |
| /ca/jcaContext/@name_servers | EPICS_CA_NAME_SERVERS | Same meaning and format as specified by the Channel Access Reference Manual. | |
| /ca/jcaContext/@repeater_port | EPICS_CA_REPEATER_PORT | 5065 | Same meaning and format as specified by the Channel Access Reference Manual. |
| /ca/jcaContext/@server_port | EPICS_CA_SERVER_PORT | 5064 | Same meaning and format as specified by the Channel Access Reference Manual. |
| /ca/jcaContext/@username | not available | system’s username | Username sent to a Channel Access server at the start of a new connection. |
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.
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.
| Group ID | Artifact ID | Bundle symbolic name |
|---|---|---|
| com.aquenos.epics.jackie | epics-jackie-client | com.aquenos.epics.jackie.client |
| com.aquenos.epics.jackie | epics-jackie-common | com.aquenos.epics.jackie.common |
| com.aquenos.epics.jackie.diirt | epics-jackie-diirt-datasource | com.aquenos.epics.jackie.diirt.datasource |
| com.aquenos.epics.jackie.diirt | epics-jackie-diirt-datasource-ca | com.aquenos.epics.jackie.diirt.datasource.ca |
| com.aquenos.epics.jackie.diirt | epics-jackie-diirt-datasource-jackie | com.aquenos.epics.jackie.diirt.datasource.jackie |
| com.aquenos.epics.jackie.diirt | epics-jackie-diirt-vtype | com.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.