FESA Design Documentation
Fesa version 3 User doc.
FESA Team
Copyright CERN&GSI 2014. All rights reserved.

1. Introduction

The first step to develop equipment software with FESA is, to define what the equipment software has to do and what it's structure will be. An equipment specialist designs this equipment-software using the FESA’s design tool. By doing-so he describes the equipment, based on a XML-design-document. This document is validated against a FESA XML-schema, which enforces all FESA-design-constraints. After the XML-class design is finished, FESA automatically can generate C++ source-code out of this design-document. The developer only need's to implement some well defined methods(E.g. the communication to the hardware). In these C++ methods the developer can easily use all provided FESA-services.

Designing any equipment software with FESA starts answering the following questions:

2. Equipment-Model

The metamodel is subdivided into several complementary areas, for which the equipment specialist has to make design choices:

3. Include

This element is optional and is not meant to be touched (added/removed) by the class-developer because it's automatically managed by the FESA plug-in. It is automatically inserted in the design-document as soon as the FESA-class defines an inheritance relationship.

It is used to receive the definition of the base-class when a FESA-class defines an "inheritance" relationship with another class. The definition of the base class is not duplicated in the XML design document but included using the "XInclude" concept provided by XML.

The included document contains only the useful information, required to make the inheritance of the direct base classes working. The base-class itself can include the information of upper classes in case where the inheritance depth is more than 2.

4. Information

All basic informational attributes of a FESA class are defined here:

5. Ownership

Here a class ownership is defined in terms of responsible, creator and optionally a list of editors having some specific rights.

5.1. Responsible

Describes a long term responsibility, less ephemeral than a creator or an editor (departure, moving,..).

5.2. Creator

Defines the class design creator in terms of user's login.

5.3. Editor

Allows to manage user privileges for different editors of the class.

6. Relationship

FESA defines three types of relationship between FESA classes.

6.1. Association

Light coupling between FESA classes. Only the public interface (properties) of the related class can be accessed. The related class is identified by the couple class-name/version. A class can define 0..n association relationships. A typical example where the association is useful is when a system is modeled using the delegation model.

Let’s imagine a class, named “Signal-class”, which needs to control a timing-hardware. But this timing-hardware is as well shared by other systems. So instead of embedding all the knowledge to control the timing-hardware in the“Signal-class”, the idea behind the association is, to delegate the control of the timing-hardware to a generic “Timing-class”. Therefore the “Signal-class” provides a property to control the timing-hardware, but internally calls the appropriate "Timing-class" property to do the job by using a device instance of the "Timing-class".

The class, which should be associated does not even need to run on the same front-end, since the connection to it's properties is done via the middleware. As well check the on-subscription-event-source for more information.

6.2. Composition

This type of relationship allows to combine simple FESA classes to model a complex system and therefore allows FESA class code reuse. Breaking a complex system into sub-systems, comes down to say this complex system is “composed of” many FESA classes. Composition is a stronger form of aggregation where the whole composition and the parts have the same lifetime. The figure below shows such a system using the composition relationship. All classes of the composition need to be gathered by using one deployment-unit. The deployment-unit will create a binary which consists of all classes and represents the whole composition.

TT and PT FESA classes have no dependencies with other FESA classes and could be, if it makes sense, either deployed as stand-alone class or re-used by another system.

6.3. Inheritance

Important Note: Inheritance is not fully integrated yet in FESA. The following features cannot be guaranteed!

This type of relationship should be used to model variants of a similar device-type, or when it makes sense to define a common abstract FESA class to enforce a common interface or behavior to derived classes. Inheritance between FESA classes should be applied as soon as the “Is a” and “Is like” relationship is true. A FESA class may extend only one direct base class. To inherit from more than one class is not foreseen in FESA.

The following picture shows a possible inheritance-scenario:

Inheritance in FESA, allows the re-usage of existing design-data and code, provided by the base-class (or it's parent-classes). This list gives a short overview what inheritance means for the different sections within FESA:

7. Interface

In this section the set of services published to the outside (clients from the control-room or middle-tier software layer) is defined. Designing an equipment’s interface involves listing so-called properties that can be remotely accessed through the controls-middleware.

7.1. Device-interface

The device-interface groups all the properties which are device-specific. They can be thought as non-static methods in an object-oriented languages. Therefore accessing a device-interface property will require a device-instance.

7.1.1. Setting

This element is meant to group all the setting properties defined by a FESA class which can be used by clients to control the equipment, using the controls middleware.

General information about setting properies can be found here.

7.1.2. Acquisition

This element is meant to group all the acquisition properties defined by a FESA class which can be used by clients to acquire equipment's data, using the controls middleware.

General information about acquisition properies can be found here.

7.2. Global-interface

The Global-interface groups all the global device properties which can be thought of as static methods in an object-oriented languages. Therefore accessing a global-interface property will require to use the global-instance.

7.2.1. Setting

This element is meant to group all the setting properties defined by a FESA class which can be used by clients to control the equipment, using the controls middleware.

General information about setting properies can be found here.

7.2.2. Acquisition

This element is meant to group all the acquisition properties defined by a FESA class which can be used by clients to acquire equipment's data, using the controls middleware.

General information about acquisition properies can be found here.

7.3. Interface - shared definitions

In order to avoid duplication, the context of the chapters below is used by different other chapters.

7.3.1. Property

A FESA-property is considered as interface to the outside-world. Clients can use properties in order to obtain data from a FESA-class, or to send data to the class.

Within a property the class developer can define the data which send to(received by) the client in so called value-items.

Furthermore the class developer has to define server-actions for the property. A get- or set-call, triggered by any client, causes the property to execute a server-action which handles the client request.

Properties are roughly structured into tree types:

  • acquisition-property
  • setting-propertys
  • command-propertys
  • All tree types are available as global-, and as device-properties. Furtermore specialized property-sub-types can be avaiable, which all base on these three types.

    7.3.2. Setting-property

    A setting-property can be accessed in write-mode(set) in order to set specific values of the class or in read(get,subscription) mode in order to obtain the current settings.

    7.3.3. Command-property

    A command property can be accessed only in write-mode(set). Most of the time such a property implements actions like "Reset" or "Calibrate" Usually the corresponding server-actions can be operated whitout any particular data sent by the client.

    7.3.4. Acquisition-property

    An acquisition-property can be accessed only in read(get,subscription) mode.

    7.3.5. GSI-Setting-Property

    This GSI-specific Setting property expands the basic FESA-Setting property.

    It is used by GSI-operations to control all parameters of the device.

    An instance of this property type should be named "Setting". In this instance all frequently used data needed for daily operations should be gathered.

    For exotic values that are not used in daily operations additional GSI-Setting-Properties should be defined.

    The two properties "Setting" and "Acquisition" are related, and it is recommended to use the same value-items in both properties where this is applicable. For instance, for a motor, both the Setting and the Acquisition property should contain a value-item “position”. The position item in Setting is used to control the position, whereas the position item in Acquisition is used to return the measured value.

    When performing conversions of values it is recommended to provide the possibility to read back the original value as well as the transformed value.

    7.3.6. GSI-Init-Property

    Control property, used to initialize the hardware-device with default values from the device instantiation file. Additionally performs a “Reset” of the device ( see property “Reset” )

    7.3.7. GSI-Power-Property

    This GSI-specific property is used to enable or disable a device or to put it in standby mode. The Power property is write-only.

    7.3.8. GSI-Reset-Property

    Control property, used to reset to a starting state. Performs a hardware-reset and acknowledges failure states of the hardware-device, if any. Resets internal states of the front-end software to starting conditions. The current setting data is kept.

    7.3.9. GSI-Acquisition-Property

    This GSI-specific Acquisition property extends the basic FESA-Acquisition property by the acquisition-context-item.

    It is used by GSI-operations to retrieve acquisition-data from the hardware. It also contains information on the circumstances under which the acquisition was made.

    An instance of this type of property should be named "Acquisition" if possible. In this instance all frequently used data needed for daily operations should be gathered.

    For exotic values that are not used in daily operations additional GSI-Acquisition-Properties should be defined.

    7.3.10. GSI-Version-Property

    This GSI-specific Acquisition property extends the basic FESA-Acquisition property by the version-item.

    The name of the GSI-Version-Property always is "Version". It can be used by clients in order retrieve the current Class-Version, the FESA release, the DeployUnit version, hardware and firmware versions as well as other version information.

    The basic version-items "class_version", "deploy_unit_release" and "fesa_release" are automatically filled by the framework.

    7.3.11. GSI-Status-Property

    This GSI-specific acquisition property extends the basic FESA-Acquisition property by GSI-specific value-items.

    The name of the GSI-Status-Property always is "Status". The property shall return an overview of the current device state. If the device does not work properly the status property gives information on the reason for this malfunction.

    Note that there is as well a a field-suffix "_status". However this suffix is not related to the GSI-status-property

    7.3.12. GSI-ModuleStatus-Property

    This GSI-specific acquisition property extends the basic FESA-Acquisition property by GSI-specific value-items.

    The name of the GSI-ModuleStatus-Property always is "ModuleStatus". It shall give detailed information on the state of 3rd party hardware and software components which are required to operate the device.

    7.3.13. GSI-DeviceDescription-Property

    This acquisition property provides general information about the binary.

    The get-action of the property is generated automatically. It is not possible to add any items in this property

    7.3.14. power-item

    The GSI-specific power-item automatically transforms the GSI-power-field in a data format which is supported by the RDA middleware.

    More information can be found in the documentation for the GSI-power-field.

    For general information about value items refer to the general value-item documentation.

    7.3.15. acquisition-context-item

    The GSI-specific acquisition-context-item automatically transforms the GSI-acquisition-context-field in a data format which is supported by the RDA middleware. This allows the usage of default server actions when referencing a acquisition-context-field.

    More information can be found in the documentation for the GSI-acquisition-context-field.

    For general information about value items refer to the general value-item documentation.

    7.3.16. version-item

    The GSI-specific value-item is used to add a version name in combination with a version string to the RDA middleware.

    For general information about value-items refer to the general value-item documentation.

    7.3.17. status-item

    This GSI-specific item is used to automatically transform the GSI-status-field in a data format which is supported by the RDA middleware.

    More information can be found in the documentation for the GSI-status-field.

    For general information about value-items refer to the general value-item documentation.

    7.3.18. detailed-status-item

    This GSI-specific value item contains a list of boolean values which give detailed information about the device-status.

    Each list-entry has a label which is provided in the detailed-status-labels-item.

    Each list-entry has a severity-level which is provided in the detailed-status-severity-item.

    More information can be found in the documentation for the GSI-detailed-status-field.

    For general information about value-items refer to the general value-item documentation.

    7.3.19. detailed-status-labels-item

    This GSI-specific value item provides labels for the different items of the GSI-detailed-status-item

    More information can be found in the documentation for the GSI-detailed-status-labels-field.

    For general information about value-items refer to the general value-item documentation.

    7.3.20. detailed-status-severity-item

    This GSI-specific value item provides severity-levels for the different items of the GSI-detailed-status-item

    More information can be found in the documentation for the GSI-detailed-status-severity-field.

    For general information about value-items refer to the general value-item documentation.

    7.3.21. powerState-item

    This GSI-specific item is used to automatically transform the GSI-powerState-field in a data format which is supported by the RDA middleware.

    More information can be found in the documentation for the GSI-powerState-field.

    For general information about value-items refer to the general value-item documentation.

    7.3.22. control-item

    This GSI-specific item is used to automatically transform the GSI-control-field in a data format which is supported by the RDA middleware.

    More information can be found in the documentation for the GSI-control-field.

    For general information about value-items refer to the general value-item documentation.

    7.3.23. interlock-item

    This GSI-specific item is used to automatically transform the GSI-interlock-field in a data format which is supported by the RDA middleware.

    More information can be found in the documentation for the GSI-interlock-field.

    For general information about value-items refer to the general value-item documentation.

    7.3.24. opReady-item

    This GSI-specific item is used to automatically transform the GSI-opReady-field in a data format which is supported by the RDA middleware.

    More information can be found in the documentation for the GSI-opReady-field.

    For general information about value-items refer to the general value-item documentation.

    7.3.25. modulesReady-item

    This GSI-specific item is used to automatically transform the GSI-modulesReady-field in a data format which is supported by the RDA middleware.

    More information can be found in the documentation for the GSI-modulesReady-field.

    For general information about value-items refer to the general value-item documentation.

    7.3.26. error_collection-item

    The GSI-specific error_collection-item automatically transforms the GSI-error_collection-field in a data format which is supported by the RDA middleware. This allows the usage of default server actions.

    More information can be found in the documentation for the GSI-error_collection-field.

    For general information about value-items refer to the general value-item documentation.

    7.3.27. timing-info-item

    This GSI-specific item contains the name of the attached WhiteRabbit timing-receiver device, if there is any.

    More information can be found in the dokumentation of the linked field.

    For general information about value-items refer to the general value-item documentation.

    7.3.28. module-status-item

    This GSI-specific value item contains a list of enum values which give information about the status of required 3rd party hardware and software modules. ( software-modules e.g are: the SAFT-daemon, an associated FESA-class, a kernel-driver )

    Each list-entry has a label which is provided in the module-status-labels-item.

    More information can be found in the documentation for the GSI-module-status-field.

    For general information about value-items refer to the general value-item documentation.

    7.3.29. module-status-labels-item

    This GSI-specific value item provides labels for the different items of the GSI-module-status-item

    More information can be found in the documentation for the GSI-module-status-labels-field.

    For general information about value-items refer to the general value-item documentation.

    7.3.30. property-info-item

    This GSI-specific item contains the names of all properties provided by this class. This information is filled by the FESA-framework.

    For general information about value-items refer to the general value-item documentation.

    7.3.31. device-info-item

    This GSI-specific item contains the names of all devices which run on the specific FESA-binary. This information is filled by the FESA-framework.

    For general information about value-items refer to the general value-item documentation.

    7.3.32. global-device-info-item

    This GSI-specific item contains the names of the global-device which runs on the specific FESA-binary. This information is filled by the FESA-framework.

    For general information about value-items refer to the general value-item documentation.

    7.3.33. host-info-item

    This GSI-specific item contains the hostname on which the FESA-binary runs. This information is filled by the FESA-framework.

    For general information about value-items refer to the general value-item documentation.

    7.3.34. Property Description

    The description provides a short explanation of what the property does.

    7.3.35. Property-name

    The name of a property is unique within a FESA class

    7.3.36. Multiplexed

    "TRUE" means that this property supports the usage of multiplexed data.

    7.3.37. Notification-order

    This optional attribute can be used to priorize the client-notification-process across all properties of this class.

    The lower the order-number, the higher the priority which will be used to notify clients. The concrete priority of each notification thread can be further optimized in the instantiation-document.

    7.3.38. Visibility

    This attribute indicates clearly the property category, allowing, for instance to make a distinction between the operational interface and the expert interface. The different options are:

    The visibility is as well used to manage the FESA class life-cycle. For instance it should not be possible to change an “operational” property as soon as a FESA class is operational.

    7.3.39. On-Change

    This attribute indicates if the property is updated periodically or only when the data changes. Being on-change or not is not incompatible with being multiplexed or not. Typically, multiplexed properties are not on-change and non-multiplexed properties are on-change. However, a multiplexed property can be on-change as well meaning that the data will be cycle dependent but won't depend on the cycle occurence, or even never change, and therefore won't be updated periodically.

    7.3.40. Subscribable

    This attribute tells if the property supports usage of subscription. For example it could make sense to forbid subscription for an expert acquisition-property, which returs a huge amount of data.

    7.3.41. Export

    List of the systems where the device property data can be exported to when notified

    7.3.42. Post-Mortem export

    Post-Mortem parameters

    7.3.43. Post-Mortem attributes

    Post-Mortem attributes have a name, a reference to a value-item, and a value. The value can itself be a reference to a value-item, or a string.

    7.3.44. Server-action-ref

    Used to refer to a server-action which will be executed when this property is triggered by a client(get/set/subscription). The server-action has to be defined previously in the "actions" element.

    7.3.45. Abstract-server-action

    An abstract-server-action can only be created in an "abstract" class and has to be implemented by each derived class. In the abstract base-class no implementation has to be provided. Refere to the chapter "inheritance" for more information.

    7.3.46. Value-item

    The data-container which is transfered when the client triggers a property via "get", "set" or subscription is a composite structure that is build of one or several so called "value-items". This concrete value item defines one value, which is passed between the client and the FESA class. The value which is passed may either be copy of a internal data-field, or any other user defined value.

    7.3.47. Min-value-item

    Meta value item giving information about the lower bound of a numeric value item inside the same property. This is used by InCA to colour the elements in the workingsets/knobs. Behaves like normal value-items

    7.3.48. Max-value-item

    Meta value item giving information about the upper bound of a numeric value item inside the same property. This is used by InCA to colour the elements in the workingsets/knobs. Behaves like normal value-items

    7.3.49. Units-value-item

    Meta value item giving information about the units of a value item inside the same property. This is used by InCA to display information the workingsets/knobs. (Different from value-item unit which is only used for documentation purpose) Behaves like normal value-items

    7.3.50. Filter-item

    Filter-items provide the option to fine-tune the execution of server-actions by passing additional data elements. The structure of a filter-item is the same as for the value-item, apart from the fact that its entries never reference existing data-field and are always defined within the filter’s naming scope.

    As an example, filters could be used for data conversion, low-pass or filtering and averaging of measurements, selection or a particular signal component or time-window, or parameters of a signal transform (e.g. radix of an FFT).

    7.3.51. Priority-offset

    Within the priority offset of a property one can adjust the priority level which will be used to execute the connected server-actions.

    7.3.52. Cycle-stamp-item

    The cycle-stamp-item describes the time when a specific cycle in which the acquisition was done, has started. It is only relevant for multiplexed properties.

    7.3.53. Cycle-name-item

    The cycle-name-item contains the name of the cycle in which the acquisition was done. It is only relevant for multiplexed properties.

    7.3.54. Update-flag-item

    This item is only relevant for subscription. It indicates the type of the client notification. (initial update, normal update, or update triggered by a foreign clinet-set)

    7.3.55. Acquisition-stamp-item

    The acquisition-stamp-item describes the concrete time when the acquisition-data was measured.

    7.3.56. Set-action

    When a client triggers a "Set" of this property using the controls middleware, a set-action will be triggered. Here you can define which set-action you would like to trigger for this property.

    7.3.57. Get-action

    When a client triggers a "get" of this property using the controls middleware, a get-action will be triggered. Here you can define which get-action you would like to trigger for this property.

    7.3.58. Item-name

    Defines the name of the property-item. This name will be the name of the data-entry in the data container of this property, which is transfered between the client and the FESA-class. The name should be unique in the scope of the property definition.

    7.3.59. Optional

    TODO: What does optional mean?

    7.3.60. Data-type

    Defines the data-type, used for this item.

    7.3.61. ID

    This attribute provides a document-wide unique identifier for the value-item. It is automatically generated on purpose, with the aim of managing the Fesa Class life cycle.

    7.3.62. Direction

    Defines the direction of the data-flow. Possible options:

    Depending of the context in which the value-item is defined, the direction can be predefined and fixed (immutable). For example value-items defined in the context of an acquisition-property have a fixed value equal to "OUT". Recommendations: for setting-property this attribute needs to be set conscientiously for each value-item, knowing that some value-items are just read-only values, meaning that they are present only when getting the property.

    8. Custom-types

    Besides the fesa-data-types, it is possible to define "custom data types" in FESA. Some of the custom-types are already predefined and used by the framework, others are class-specific.

    8.1. Constant

    This Type allows to define any type of constant.(only unsigned int constants are treat seperately for historical reasons)

    8.2. Enum

    This type allows to specify an enumeration by adding items for each possible enumerated value.

    8.3. State-enum

    This type allows to specify an device-status enumeration. A state-enum contains some predefined states which may be used by the class-developer.

    8.3.1. State

    This item allows to specifiy a state in detail.

    8.4. Bit-enum

    This custom-type allows to define bit pattern of 16 and 32 bits.

    8.5. Custom-types - shared definitions

    In order to avoid duplication, the context of the chapters below is used by different other chapters.

    8.5.1. Access

    "Access" describes the access type which can be used for an item.

    8.5.2. Name

    The name of the custom-type, constrained by the pattern: ([_A-Za-z])([_A-Za-z0-9:])*

    8.5.3. Value

    This item contains the value which is used for this constant.

    9. Data

    At the heart of any equipment-software, the device-model represents the software abstraction of an underlying device. This is a data-holder of which the attributes are continuously transferred to and from the hardware in order to ensure that the real device and its software are synchronized at run-time. Specifying a proper device-model is one of the most important steps of equipment-software design and it consists in defining a set of fields. Every piece of information about the underlying hardware-device is stored as field.These fields are structured into the following categories:

    9.1. Device-data

    Device-data groups all the device-fields which can be thought non-static variables in an object-oriented languages. Therefore accessing a device-data field will require a device-instance.

    9.1.1. Configuration

    Configuration-fields are only initialized once. After startup of a FESA-class they keep their value and are not changed any more. All configuration fields are read-only fields.

    9.1.1.1. HW-address

    This field is used to create a placeholder to store hardware addresses during instantiation. One of the child element has to exist and it is possible to supply both at the same time as well as several of the same type.

    9.1.1.1.1. Host

    Here you can fill in detailed information about a hardware-address.

    9.1.1.1.2. Logical-address

    Here you can specify a logical-address which may be necessary to use the defined hardware-address.

    9.1.1.2. Device-relations-field

    Used for the association-relationship. ( TODO: add useful info here )

    9.1.2. Setting

    Setting-fields are used to store values which are needed to control the hardware-equipment.

    9.1.3. Acquisition

    Acquisition-fields are used to store data, which was produced by the hardware-equipment.

    9.2. Global-data

    The global-data groups all the global fields which can be thought of as static variables in an object-oriented languages. In the code they can be accessed by using the global-instance.

    9.2.1. Configuration

    Configuration-fields are only initialized once. The values for initialization are provided by the instantiation-document

    After startup of a FESA class they keep thair value and are not changed any more. All configuration fields are read-only fields.

    9.2.2. Setting

    Setting-fields are used to store values which are needed to control the hardware-equipment.

    9.2.3. Acquisition

    Acquisition-fields are used to store data, which was produced by the hardware-equipment.

    9.3. Timing-domain-data

    Accelerator facilities are often seperated into different timing domains to seperate between the timing of different sub-accelerators which need to work together. Here fields which are timing-domain specific can be stored.

    9.3.1. Configuration

    Configuration-fields are only initialized once. The values for initialization are provided by the instantiation-document

    9.4. Data - shared definitions

    In order to avoid duplication, the context of the chapters below is used by different other chapters.

    9.4.1. Field

    A field in FESA is used to store data, which either comes from the physical-device, or from a client. There are tree main field-types, and some specialized types, which can be used. The main types are:

    9.4.2. Configuration field

    Configuration-fields are only initialized once. The values for initialization are provided by the instantiation-document

    9.4.3. Setting field

    Setting-fields are used to store values which are needed to control the hardware-equipment.

    9.4.4. Acquisition field

    Acquisition-fields are used to store data, which was produced by the hardware-equipment.

    9.4.5. Fault-field

    A fault-field is used to indicate a internal status. (Similar to the alarm-field, but only for internal usage)

    9.4.6. Acquisition state-field

    An acquisition-state-field indicates the current state of e.g. the hardware-equipment or some measurement values. An acquisition state-field and can be used to inform clients about state-changes.

    9.4.7. Setting state-field

    Different from the acquisition-state-field, a setting-state-field is used to request for new states. E.g. a client may send a state, which should be gained by the hardware-device.

    9.4.8. Acquisition cycle-name-field

    A Cycle-name-field can store the name of a cycle. The cycle-name e.g. can be obtained from the multiplexing-context.

    9.4.9. Setting cycle-name-field

    A Cycle-name-field can store the name of a cycle. The cycle-name e.g. can be obtained from the multiplexing-context.

    9.4.10. Acq-stamp-field

    An acquisition-stamp-field can store the value of an acquisition-stamp. The acquisition-stamp e.g. can be obtained from the timing-event or from the hardware-device.

    9.4.11. Cycle-stamp-field

    A Cycle-stamp-field can store the value of a cycle-stamp. The cycle-stamp e.g. can be obtained from the multiplexing-context.

    9.4.12. GSI-power-field

    This GSI-specific setting field is used in order to enable the device, disable it or set it into a standby-mode(if supported).

    The enumeration "DEVICE_POWER" allows the following values:

  • 1 ON: The device will be set to a fully operational state.
  • 2 OFF: The device will be turned off.
  • 3 STANDBY: The device will be set to an optional standby-mode. Follow this link for more information.
  • 9.4.13. GSI-acquisition-context-field

    This GSI-specific acquisition field is used to store meta-information of acquisition data.

    In contrast to the default value-items acq-stamp-item, cycle-name-item and cycle-stamp-item, this value-item is not only available for client-subscriptions, but as well for client-get-actions.

    The structure data-type "GSI_ACQ_CONTEXT" consists of the following items:

  • int32_t processIndex: Index of the process which triggered the acquisition.
  • int32_t sequenceIndex: Index of the sequence which triggered the acquisition.
  • int32_t chainIndex: Index of the beam production chain which triggered the acquisition.
  • int32_t eventNumber: Number of the event which triggered the acquisition.
  • int32_t timingGroupID: ID of the timing group on which the event occurred.
  • int64_t acquisitionStamp: (UTC in nanoseconds) Time when the acquisition was done.
  • int64_t eventStamp: (UTC in nanoseconds) Time on which the WhiteRabbit timing receiver triggered the software-action.
  • int64_t processStartStamp: (UTC in nanoseconds) Time on which the dedicated process started.
  • int64_t sequenceStartStamp: (UTC in nanoseconds) Time on which the dedicated sequence started.
  • int64_t chainStartStamp: (UTC in nanoseconds) Time on which the dedicated beam production chain started.
  • More information on how to use the field in an RT-Action can be found here

    9.4.14. GSI-status-field

    This GSI specific field describes the summary of the device status.

    The enumeration "DEVICE_STATUS" allows the following mutually exclusive values:

  • 0 UNKNOWN: The device status is unknown.
  • 1 OK: The device is working fine, it can be used by clients or locally.
  • 2 WARNING: The device is not fully operational; A device in WARNING state can still be used operationally, but clients must be informed of a problem that might become worse. Details on the warning should be provided in the field detailedStatus.
  • 3 ERROR: The device is in a fault state. Details on the error should be provided in the fields detailedStatus and error_collection.
  • Please note that the status of a device can still be "OK" when control is set to "REMOTE" or powerState is different from "ON"!

    The enumeration-value should always be coherent with the active alarm-state.

    9.4.15. GSI-interlock-field

    This GSI specific field signals that the device currently receives an interlock. The flag should be hissed until the interlock is cleared.

    Depending on the severity of the interlock, the fields status, detailedStatus and opReady should be updated.

    9.4.16. GSI-opReady-field

    This GSI specific field is used to signal that the device is ready to be used operationally in the facility.

    Usually that implies that the field status signals "OK" or "WARNING", the field control signals "REMOTE" and the field modulesReady signals "true". For most devices the value of "opReady" does not change when the hardware device is turned on/off.

    If the usual logic does not apply for a specific device, exceptional logic should be described in the documentation of the related FESA class!

    9.4.17. GSI-modulesReady-field

    This GSI specific boolean field is used to signal that all required 3rd party hardware and software modules are ready to be used. ( software-modules are e.g: the SAFT-daemon, an associated FESA-class, a kernel-driver )

    If the field-value is "FALSE", the GSI-ModuleStatus-Property should give detailed information about which module is concerned.

    9.4.18. GSI-detailed-status-field

    This GSI specific field shows the current state of the device in detail (not mutually exclusive). Each bit of this boolean array can be used to model a sub state of the device.

    The field detailedStatus_labels has to be used in order to define name labels for each bit.

    The field detailedStatus_severity has to be used in order to define the severity level of each bit.

    This field is used to complement the information contained in the status field. Whenever status is different from "OK", this field should provide detailed information on the fault.

    9.4.19. GSI-powerState-field

    This GSI specific field describes the current power state of the device.

    The enumeration "DEVICE_POWER_STATE" allows the following values (mutually exclusive):

  • 0 UNKNOWN: The device's power state is unknown
  • 1 ON: The device is fully powered
  • 2 OFF: The device is turned off
  • 3 STANDBY: The device is in a standby-mode. Follow this link for more information.
  • 4 POWER_DOWN: The device is shutting down. Please note that some properties may not be accessible during this time. After shutdown the device will be in the state OFF
  • 5 POWER_UP: The device is starting up. Please note that some properties may not be accessible during this time.
  • Please note that the status of a device can still be "OK" when the powerState is different from "ON" !

    9.4.20. GSI-control-field

    This GSI specific field describes if the device is controlled remotely or local.

    The bit-enumeration "DEVICE_CONTROL" allows the following values:

  • 0 REMOTE: The device is controlled normally through the control system
  • 1 LOCAL: The device is controlled locally. It may be accessed in read-only mode via the control system
  • Please note that the status of a device can still be "OK" when controlled locally!

    9.4.21. GSI-error_collection-field

    The GSI-specific error_collection-field is designed as ringbuffer of the depth [MAX_NUMBER_OF_ERROR_MESSAGES]. It stores all active error messages, their corresponding error-codes, timestamps and cycle names.

    The field provides the method addError(...) which should be used to report errors. It automatically takes care of the ringbuffer, provides an error timestamp and saves the error as log message via the logging system.

    More information on how to use the method can be found here.

    An appropriate alarm should be raised for permanent state changes of the device as well as for errors.

    The error_collection array has the length "MAX_NUMBER_OF_ERROR_MESSAGES". Each element has the struct type "GSI_ERROR" which provides the following values:

  • error_string: The variable-length message of the error. To be filled by the class developer via AddError(...). The maximum leangth of this string is defined by the constant "MAX_ERROR_MESSAGE_LENGTH".
  • error_code: The error code is a placeholder only at the moment. Later each device will have predefined error codes.
  • error_timestamp: An error timestamp will be automatically added by using the method addError(...). The stamp has the type int64_t.
  • error_cycle_name: As well the cycle name will be automatically filled by using the method addError(...). The maximum length of this string is defined by the constant [MAX_CYCLE_NAME_LENGTH].
  • 9.4.22. GSI-module-status-field

    This GSI specific field shows the current state of all 3rd party hardware and software modules which are required to use the device. ( software-modules e.g are: the SAFT-daemon, an associated FESA-class, a kernel-driver )

    The related field moduleStatus_labels is used in order to define name labels for the different modules.

    The state of all device-specific 3rd party hardware and software modules should be listed here.

    The enumeration "MODULE_STATUS" allows the following mutually exclusive values:

  • 0 UNKNOWN: The module status is unknown.
  • 1 OK: The module is working fine..
  • 2 WARNING: The module is not fully operational; A module in WARNING state can still be used operationally, but clients must be informed of a problem that might become worse. Details on the warning should be provided in the field detailedStatus.
  • 3 ERROR: The module is in a fault state. Details on the error should be provided in the fields detailedStatus and error_collection.
  • 4 NOT_AVAILABLE: The module could not be found.
  • 9.4.23. GSI-detailed-status-labels-field

    This GSI specific field defines all the label names for the boolean array detailedStatus

    You can either directly put default values at class level, or you can do so in the instantiation document if the values need to be specific per device.

    9.4.24. GSI-module-status-labels-field

    This GSI specific field defines all the module names for the enum array moduleStatus

    You can either directly put default values at class level, or you can do so in the instantiation document if the values need to be specific per device.

    All device-specific 3rd party hardware and software modules should be listed here.

    9.4.25. telegram-group-field

    This GSI-specific field is still under construction. (Currently the same than used at CERN).

    Since this field is not tested at all, and may change in the future it is not recommended to use it.

    9.4.26. GSI-detailed-status-severity-field

    This GSI specific field defines all severity-levels for the items of the boolean-array detailedStatus

    You can either directly put default-values at class-level, or you can do so in the instantiation-document later, if the values need to be device-specific.

    The used bit-enumeration "DETAILED_STATUS_SEVERITY" allows the following values:

  • 0 INFO: This bit only has informational character
  • 1 WARNING_ON_FALSE: If this bit is false a warning is flagged
  • 2 ERROR_ON_FALSE: If this bit is false an error is flagged
  • 9.4.27. GSI-timing-receiver-name-field

    This GSI-specific field contains the name of the attached WhiteRabbit timing-receiver device, if there is any.

    The default value of the field can be filled in the instance-file.

    9.4.28. STANDBY

    The enumeration item STANDBY can be used in the GSI-powerState-field and the GSI-power-field in order to communicate the device state.

    STANDBY is an optional state and is only supported by a couple of devices. It is a sort of “parking state” in which the device can stay for hours or even days. The state is defined by the following characteristics:

    9.4.29. Default

    By adding a default-node, a predefined default value will be used to initialize this field.

    The default value needs to be provided here, but as well can be overwritten per device in the instantiation document.

    For more complex types, a bracket-notation can be used in order to describe the data.

    9.4.30. Name

    Here you can specify the name of this field.

    9.4.31. Persistent

    Boolaen value. Persistance is a service which can be used for setting-fields. If enabled, the actual value of the corresponding field is always saved in a so called "persistancy-file".

    If the FESA class is restarted, the value of this field, stored in the persistancy-file, will be used to initialize the field on the new startup.

    9.4.32. Data-consistent

    Optional attribute for fields. "true", if not defined.

    If "false" is used, the corresponding field has read/write access on the server and on the RT-side. However for this case data-consistancy cannot be ensured any more by FESA.

    9.4.33. Multiplexed

    Boolean value

    Detailed information about "multiplexing" can be found here.

    9.4.34. Shared

    Boolean value

    9.4.35. Extra-Multiplexed

    For setting-fields it is possible to add additinal multiplexing criteria which are defined in the instantiation-document. This flag indicates, that the corresponding field uses these additional criteria.

    For each extra-criteria, the existing entities of the field are doubled.

    E.g. If the field uses normal multiplexing, having 12 different cycles: 12 entities.

    If six extra-criteria are added: 12 * (6+1) = 84 entities of the field.

    The additional information to identify the right entity of the field is extracted from the payload of the Timing-System.

    9.4.36. Severity

    Enumeration, which describes the seriousness of something. Possible values:

    10. Actions

    Actions are a component of the framework, where actually something happens. There are different types of actions for different purposes. Some are automatically generated by FESA, others need to be filled by the class developer. Take a look into the different actions to see their purpose.

    10.1. Get-server-action

    A get-server-action can be triggered by "get" command of a client, or a subscription. Usually it is used to read out acquisition-fields and send the data to the client.

    Each setting-property and each acquisition-property needs to implement a get-server-action.

    10.2. Set-server-action

    A set-server-action can be triggered by a "set" command of a client. Usually it is used to write client data into setting-fields.

    Each setting-property and each acquisition-property needs to implement a get-server-action.

    10.3. RT-action

    RealTime-actions execute user-specific code. They are used to do any kind of harware interaction. RealTime actions are started with high RT-priorities, which allows them to delay e.g. server-actions and communicate with the hardware in minimum time.

    10.4. Abstract-RT-action

    An abstract RealTime-action has no implementation in the base-class. However, the child-class needs to provide an implementation for the action.

    10.5. Actions - shared definitions

    In order to avoid duplication, the context of the chapters below is used by different other chapters.

    10.5.1. Notified-property

    Whenever this action is executed, the defined properties will trigger a client-update for all clients which have a subscription to the property.

    10.5.2. Triggered-event-source

    Set-server-actions and rt-actions have the possibility to trigger the start of other rt-actions using on-demand-events. Here you can specify which on-demand-source will be triggered after execution.

    10.5.3. Disabling-alarm

    Within this item you can force a server-action to automatically lower the alarm state of an alarm-field, when the action is executed.

    10.5.4. Disabling-fault

    Within this item you can force a server-action to automatically lower the severity state of a fault-field, when the action is executed.

    10.5.5. Implementation

    By this enumaration you can choose if you want to fill the server-action at your own, or if you want to use a predefined action

    Usually the generic default action satisfies all basic needs. Only if you need to e.g. perform some unique data-operations, you need do a custom-implementation.

    10.5.6. Action name

    Give a meaningful name to your action, which describes the activity it is made for.

    10.5.7. Description

    Here you can further explain the purpose of this action.

    11. Events

    Any type of event, and as well the corresponding event-sources can be defined here. Logical-events in FESA are used to trigger the execution of rt-actions.

    11.1. Event Sources

    A event source describes a source of a FESA-internal event. All sources, defined here will be instantiated.

    11.1.1. Timer-event-source

    The timer-event-source is a FESA internal "pulse-generator". For each defined logical-timer-event you can specify a period in the instantiation document of each front-end.

    11.1.2. Timing-event-source

    The timing-event-source uses the events of the accelerator-timing in order to trigger the execution of rt-actions. The binding between a FESA-internal logical-event and a real timing event is front-end-specific, and therefore done in the instantiation document.

    11.1.3. Custom-event-source

    If you need to implement a trigger for the execution of rt-actions at your own. (E.g. events sent by the equipment-harware), this event source allows you to do so. By choosing a custom-events-source, the framework will generate a empty event-source for you, which you can implement according to your own needs.

    11.1.4. On-demand-event-source

    The on-demand-event-source is used to trigger the execution of one rt-action by another rt-action, or by a set-server-action. The triggered-event-source item can be attached directly to the action in the class design.

    11.1.5. On-subscription-event-source

    The On-subscription-event-source allows to subscribe as client to properties of foreign FESA classes and to react on value-updates of these properties by executing a rt-actions. More information about this concept can be found here.

    11.2. Logical-events

    Holds a collection of all available logical-events of this class.

    11.3. Logical-event

    A logical event describes a FESA-internal event. The mapping to the concrete-event is done in the instantiation document.

    11.4. Custom-event

    This element describes an event which can be fired by a custom-event-source. If no custom-event is defined, the source only can fire the "defaultEvent".

    12. Scheduling-units

    Scheduling-units are used to freely map the different FESA-internal logical-events to rt-actions.

    12.1. Scheduling-unit

    A scheduling unit creates a 1 to 1 realtion between a logical-event and a rt-action. Whenever the choosen logical-event is triggered, the corresponding rt-action will be executed.

    12.1.1. Selection-criterion

    A selection criterion allows to execute a rt-action not for all device-instance of a class, but only for a choosen selection.

    12.1.1.1. Selection-rule

    Here a selection-rule can be defined in order to group a collection of device-instance for which the rt-action will be executed.

    12.1.1.2. Operand

    An operand either can be true or false for a specific device-instance. This either is defined by one of the device's fields, or by logically conected collection of sub-operands.

    12.1.1.2.1. Field-selection

    Here you can specify the field, which you want to check in order to figure out if a operand is "true" for a specific device-instance.

    12.2. Scheduling-units - shared definitions

    In order to avoid duplication, the context of the chapters below is used by different other chapters.

    12.2.1. Binary-operation

    For a device-instance the result of these two logical connected criteria(operands) needs to be true, to be part of the device-collection.

    12.2.2. Priority-order

    This optional attribute can be used to priorize the threads of the different scheduling-units.

    The lower the order-number, the higher the priority which will be used for the thread. The concrete priority of each thread can be further optimized in the instantiation-document.

    13. Equipment Model - Shared Definitions

    In order to avoid duplication, the context of the chapters below is used by different other chapters.

    13.1. Fesa data type

    All the basic C++ data types are supported by the framework. With the recent introduction of the 64-bit platform, FESA 3 uses a platform-independent representation for the integers. Currently the types that can be used in properties are restricted to those supported across the whole control system. The following table give list illustrated in the table below:

    Scalar types Array types Two-dimension array types
    bool bool bool
    int8_t int8_t int8_t
    int16_t int16_t int16_t
    int32_t int32_t int32_t
    int64_t int64_t int64_t
    uint8_t uint8_t uint8_t
    uint16_t uint16_t uint16_t
    uint32_t uint32_t uint32_t
    uint64_t uint64_t uint64_t
    float float float
    double double double
    - char (string) char (string[])

    13.1.1. Scalar

    The scalar-type is the most basic FESA-data type one can choose. It only represents a single data-element.

    13.1.2. Array

    The array-type is used to represent a array of scalars.

    13.1.3. Array2D

    Similar to the array, but for an additional dimension.

    13.1.4. Custom-type-scalar

    Represents a scalar value which defines a custom-type as data-type.

    13.1.5. Custom-type-array

    The array-type is used to represent a array of custom-type-scalar.

    13.1.6. Custom-type-array2D

    Similar to the custom-type-array, but for an additional dimension.

    13.1.7. Dim

    Allows you to specify directly the array dimension by providing an unsigned value.

    13.1.8. Custom-constant-dim

    Allows you to specify the array dimension by referring to a constant-unsigned-int, which was previously defined in the custom-types.

    13.1.9. Variable-dim

    Allows you to specify that the dimension is defined per device in the instantiation-document. Optionally, one can specify the maximum and minimum limit if it's relevant.

    13.2. Value-item-ref

    Used to indicate the value-item concerned by the meta information

    13.3. Data-field-ref

    Used to map this item to an existing internal data-field.

    13.4. Data-field-bit-ref

    Used to map this item to one bit of an existing internal data-field.

    13.5. Data-type-name-ref

    Contains the reference to the custom-type. Custom-types for value-items can be only constants, enumeration or bit-pattern. Therefore is not possible to refer a complex type, like C-structure. This restriction was brought by the middle ware layer which is able to transport only types shown in the above table. However, internal data-field doesn't have such a restriction.

    13.6. type

    Allows you to select a type from an enumeration which contains all the supported types as shown in the above table

    13.7. Concepts used in the FESA-Framework

    13.7.1. Meaning

    This item contains standardized values to add information about the state of the equipment. The different meanings are:

    13.7.2. Unit

    Allows to specify in which unit the value is expressed

    13.7.3. Setting

    The keyword "Setting" describes the direction of the data-flow which for a setting-property is "Client --> HardwareEquipment". The client as well can use "get" on a setting property in order to obtain the current pending setting-values.

    A mechanism, called double buffering is used to synchronize setting-fields between the server and the RT-side.

    Usually setting fields are filled in set-server-actions and read out by rt-actions.

    13.7.4. Acquisition

    The keyword "Acquisition" describes the direction of the data-flow which for an acquisition-property is "HardwareEquipment --> Client". Usually the data in an acquisition-property is measured by the hardware-equipment. Acquisition-fields usually are filled in rt-actions and read out by get-server-actions.

    13.7.5. Cycle (Virtual Accelerator)

    The accelerator complex provides beams for several experiments "in parallel". This makes the accelerator a shared resource which is managed by the central-timing system. The central-timing defines successive time-slots (so called cycles) during which the accelerator receives appropriate settings to achieve a particular beam with special characteristics for each cycle.

    13.7.6. Multiplexing

    Making a property, or a field “multiplexed”, tells that the corresponding setting or acquisition becomes specific per cycle.

    "Multiplexing" in FESA means, that a value is available more than once. To indentify a concrete entry of a multiplexed value a so called "cycle-selector" is used.

    The timing-system and the client both have to provide this cycle-selector.

    13.7.7. Rolling Buffer

    A rolling-buffer, as well called ring-buffer can be used for multiplexed acquisition-fields. Instead of storing one field-entry per cycle, it stores just a predefined number of cycles, and always overwrites the oldest field-entry.

    Especially for front-ends with low memory, the rolling-buffer can be usefull to manage huge multiplexed fields. E.g. Only the last played cycles can be stored, instead of providing a memory-segment per cycle, as the usual multiplexing does.

    13.7.8. Double Buffer

    FESA introduces a so called double-buffer mechanism, which is needed in order to synchronize setting-fields between the Server and the RT-Side. All setting-field data is stored twice, as "pending-data" and as "active-data".

    Whenever a server-action changes the pending-data of a field, a so called "hasChanged" flag is raised for this field. As soon as the next RT-Action for the corresponding device is played, the pending-data will be swapped with the active-data. (Not the data itself will be swapped, but only a pointer to the data, to avoid an additional time-consuming copy-operation)

    All that is done, in order to avoid priority inversion between server and rt-actions.

    13.7.9. Client

    A client, in the context of FESA is considered as middleware-user, who wants to communicate with a FESA-device. To do so, the client can use a big palette of middleware methods.

    Probably the most important ones are get,set and subscribe. In order to identify the needed information, the client has to specifiy a device-instance-name, a property-name and a cycle-context-string.

    13.7.10. Client-Get

    A "get" or "doGet" can be used by a client, in order to obtain data from a specific setting- or acquisition-property of a specific device-instance.

    Usually a device-reference-object can be obtained from the middleware, using the device-name. The property-name and the cycle-name can than be passed as parameters of the get-method. As well an additional parameter, called context can be used in order to more precisely describe the required data.

    The client-implementation of the "get" can be done via different languages, depending on the support of the middleware.

    Additionally it is possible to invoke the "get" either as synchronious or asynchronious call. That allows to avoid longer wait-times which can occur on complex server-actions.

    13.7.11. Client-Set

    A "set" or "doSet" can be used by a client, in order to send data to a specific setting-property of a specific device-instance, or to invoke a command-property.

    Usually a device-reference-object can be obtained from the middleware, using the device-name. The property-name, the cycle-name and the data which is to send can than be passed as parameters of the get-method. As well an additional parameter, called context can be used in order to more precisely describe the required data.

    The client-implementation of the "set" can be done via different languages, depending on the support of the middleware.

    Additionally it is possible to invoke the "set" either as synchronious or asynchronious call. That allows to avoid longer wait-times which can occur on complex server-actions.

    13.7.12. Subscription

    A "subscription" (monitorOn) can be used by a client, in order to receive a value from a specific property from a specific device automatically whenever it changes.

    Usually a device-reference-object can be obtained from the middleware, using the device-name. The property-name and the cycle-name can than be passed as parameters to the "subscribe" method. An additional parameter, called "context" can be used in order to more precisely describe the required data.

    The client-implementation of the "subscription" can be done via different languages, depending on the support of the middleware.

    13.7.13. Transactional

    The attribute "transactional" can be choosen on set-server-actions, in order to enable support for the "transaction" middleware-service. It allows to set new values to tousands of different devices on different front-ends simultaniously.

    A client can coordinate all the front-ends that participate in a transaction by proceeding two phases:

    13.7.14. Device-Handle

    A device-handle is a software object, which the client can obtain from the middleware in order to connect to the right software-device-instance. In order get the right handle, the client needs to know the name of the device.

    13.7.15. Instantiation Document

    The instantiation document keeps all configuration which is specific per front-end, or even per device-instance in a front-end-specific file. To create an empty instantiation document of your class, press "add FEC" and "create Instance" in the eclipse plugin.

    The documentation for the instantiation-unit can be found here.

    13.7.16. Deployment Unit

    A deployment-unit is a separate xml-document, which is used to cluster 1 to N FESA-classes together and to build a working binary-file out of them.

    The documentation for the deployment-unit can be found here.

    13.7.17. Class Lifecycle