The ChimeraTK-ControlSystemAdapter-TangoAdapter implements the ChimeraTK Control System Adapter for Tango

Integrating your control system application into Tango

Prerequisites:

The application has been written with the ChimeraTK-ApplicationCore library
The application MUST have a ChimeraTK::ApplicationFactory instead of a plain static application instance

To integrate the application into Tango, it has to be linked against the ChimeraTK-ControlSystemAdapter-TangoAdapter library. Simply use the find_package() Feature from CMake. The package provides imported targets, so all you have to do is to use target_link_library(${PROJECT_NAME} PRIVATE ChimeraTK::ChimeraTK-ControlSystemAdapter-TangoAdapter).

Tango Device Server configuration

As is common with Tango device servers, it is possible to configure certain aspects of the server through properties

Tango Device Server working folder

To run the the same device server executable with different configurations, use the WorkingFolder property. It should contain a path either relative to the location of the executable or a fully qualified path on the filesystem.

If no property is provided, the working folder will be the folder that contains the device server executable.

ApplicationCore to Tango attribute mapping

By default, the Tango adapter will export all available variables in the variable household of the application to Tango as attributes. ApplicationCore's hierarchical names are translated as follows:

The top level Application module is separated from the rest of the hierarchy with an underscore. The rest of the hierarchy is appended translating "/" to ".". For example, /ControlUnit/AverageCurrent/heatingCurrentAveraged becomes ControlUnit_AverageCurrent.heatingCurrentAveraged.

Complex mapping of attributes through configuration

More complex mapping and filtering of process variables is supported as well through a configuration file.

The configuration file for the extended attribute mapping configuration is called applicationName-AttributeMapper.xml. applicationName must be replaced with the name of your application.

<?xml version="1.0" encoding="UTF-8"?>
<deviceServer>
    <deviceClass name="MD22">
        <description>DFMC-MD22 stepper motor</description>
        <deviceInstance name="test/md22/0">
            <import>/Motor1</import>
        </deviceInstance>
        <deviceInstance name="test/md22/1">
            <import>/Motor2</import>
        </deviceInstance>
    </deviceClass>
    <deviceClass name="MD22Controller">
        <title>MD22 Controller</title>
        <description>DFMC-MD22 stepper controller</description>
        <deviceInstance name="test/md22/controller" stateSource="/Motors/state" statusSource="/Motors/status">
            <attribute name="numberOfMotors" source="/Motors/nMotors">
                <description>The number of motors in this device server</description>
                <egu>n/a</egu>
                <eventing>off</eventing>
            </attribute>
            <attribute name="position" source="/Motors/position">
                <description>The current position of the motor</description>
                <egu>mm</egu>
                <eventing>change</eventing>
            </attribute>
            <attribute name="statusWord" source="/Motors/statusWord">
                <description>The status word of the controller</description>
                <egu>n/a</egu>
                <eventing>dataReady</eventing>
            </attribute>
            <attribute name="newDataTrigger" source="/Motors/newDataTrigger">
                <description>A Void register announcing that new data is available</description>
                <egu>n/a</egu>
                <eventing>change</eventing>
            </attribute>
        </deviceInstance>
    </deviceClass>
</deviceServer>

In the example above we declare a deviceServer with two deviceClasses and three deviceInstances.

There can only be one deviceServer per configuration. The number of device classes and device instances, however, is not limited.

The deviceClass has a mandatory name attribute and contains any number of deviceInstances. Variables inside the device instance can either be mass-imported by using the import tag, where the naming translation as described above is applied.

A device class can have an optional title and description. Those override the device properties usually provided by the C++ code. If not given, title defaults to the class name and description to "ChimeraTK-based DeviceServer".

It is also possible to map individual variables to attributes using the <attribute> tag. The <attribute> tag has a mandatory source attribute describing the path to the process variable. Using the optional name attribute, the attribute name can be specified.

One can also override the description and egu of the process variable using the <description> and <egu> child tags of <attribute>.

The optional <eventing> child tag enables Tango event generation for the attribute. Its content is one of off (the default), dataReady or change. dataReady emits a DATA_READY event and change a CHANGE event, both on every update of the attribute's process variable. The two kinds differ in their payload, not in when they fire: a CHANGE event carries the value and its quality, a DATA_READY event only the event counter. Eventing is only allowed for readable scalar and spectrum attributes. An unknown value and a write-only attribute are rejected when the mapper file is read. Image attributes are not implemented.

Setting the Tango device state and status

By default a device starts up in state ON and with the status "Application is running.". An application can take control of both by naming a readable process variable in the optional stateSource and statusSource attributes of the deviceInstance tag.

stateSource has to be an integral process variable, typically a ChimeraTK::StatusAccessor. Its value is mapped to the Tango device state: 0 becomes ON, 1 becomes FAULT, 2 becomes OFF and 3 becomes ALARM. Any other value results in state UNKNOWN and a warning is logged.

statusSource has to be a string process variable. Its value is used as the status of the device.

State and status are updated whenever the application publishes a new value. This includes the value which is already available when the device is created, so a device starts up in the state and with the status published by the application instead of the defaults above. A source which is not in the variable household of the application, or which is not readable, makes the start-up fail.