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:
The metamodel is subdivided into several complementary areas, for which the equipment specialist has to make design choices:
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.
All basic informational attributes of a FESA class are defined here:
Here a class ownership is defined in terms of responsible, creator and optionally a list of editors having some specific rights.
Describes a long term responsibility, less ephemeral than a creator or an editor (departure, moving,..).
Defines the class design creator in terms of user's login.
Allows to manage user privileges for different editors of the class.
FESA defines three types of relationship between FESA classes.
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.
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:
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.
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.
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 properties can be found here.
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 properties can be found here.
The global-interface groups all global properties which can be thought of as static methods in object-oriented languages. Accessing a global-interface property will require the use of the global-instance.
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 properties can be found here.
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 properties can be found here.
In the subset interfaces section subsets of a FESA class may be defined. Each subset of a single FESA class may consist of a certain number of properties. A subset of a FESA class exposes the desired properties only for application clients. A configuration element allows to select the desired subset at runtime: device-instance. Technically it is possible to select a subset of a properties value- and filter-items as well (relying on partial-setting).
Allows to define a property for the subset.
In order to avoid duplication, the context of the chapter below is used by different other chapters.
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:
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.
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.
An acquisition-property can be accessed only in read(get,subscription) mode.
The diagnostic-property can be used in order to control which log messages are forwarded to the diagnostic client GUI ( e.g. the FESA-Navigator or the FESA-Explorer ). Exactly one diagnostic-property is available on each FESA-class. The diagnostic-property is always a global 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.
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” )
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.
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.
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.
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.
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
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The description provides a short explanation of what the property does.
The name of a property is unique within a FESA class
"TRUE" means that this property supports the usage of multiplexed data.
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.
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:
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.
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.
List of the systems where the device property data can be exported to when notified
Post-Mortem parameters
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.
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.
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.
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.
A meta value item giving information about the lower bound of a numerical value item in the same property. This metainformation is needed by the generic tools (InCA/LSA), such as the function editor
A meta value item giving information about the upper bound of a numerical value item in the same property. This metainformation is needed by the generic tools (InCA/LSA), such as the function editor
A meta value item giving information about the units of a value item in the same property. This metainformation is needed by the generic tools (InCA/LSA), such as the function editor. It is different from the units sub-element of a value item, which is used by Navigator and for documentation
A meta value item giving information about the lower bound of the X axis of a value item represening a function in the same property. This metainformation is needed by the generic tools (InCA/LSA), such as the function editor
A meta value item giving information about the upper bound of the X axis of a value item represening a function in the same property. This metainformation is needed by the generic tools (InCA/LSA), such as the function editor
A meta value item giving information about the units of the X axis of a value item representing a function in the same property. This metainformation is needed by the generic tools (InCA/LSA), such as the function editor. It is different from the units sub-element of a value item, which is used by Navigator and for documentation
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).
Within the priority offset of a property one can adjust the priority level which will be used to execute the connected server-actions.
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.
The cycle-name-item contains the name of the cycle in which the acquisition was done. It is only relevant for multiplexed properties.
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)
The acquisition-stamp-item describes the concrete time when the acquisition-data was measured.
Used in order to enable/disable diagnostic logging in a FESA class.
Specifies the host to which all diagnostic messages are sent (usually the diagnostic GUI automatically fills the host-item).
Specifies the port to which all diagnostic messages are sent (usually the diagnostic GUI automatically fills the port-item).
This item is not used any more. It will be removed in one of the next FESA releases (see FESA-6548).
This item is not used any more. It will be removed in one of the next FESA releases (see FESA-6548).
Log-topics on which the FESA-framework itself logs diagnostic messages.
Log-topics which can be added by the class developer.
Devices for which the diagnostic logging should be enabled. Use no device for "all devices". Device names need to be separated by comma.
Actions for which the diagnostic logging should be disabled. Action names need to be separated by comma.
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.
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.
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.
TODO: What does optional mean?
Defines the data-type, used for this item.
A value-item's role indicate to the high-level applications that the value-item plays a special role in the class. The role can be:
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.
Defines the direction of the data-flow. Possible options:
Builtin-types are custom-types which are predefined by the FESA framework. The different builtin-types are not meant to be modified by FESA class developers.
Used when subscribed clients are notified in order to give information on the context of the notification.
Log-topics for diagnostic logging which are used by the FESA-framework itself (See diag-custom-topic for class-specific log-topics ).
Enumeration listing the available fault severities used by fault fields.
Besides the fesa-data-types, it is possible to define "custom data types" in FESA.
This Type allows to define any type of constant.(only unsigned int constants are treat seperately for historical reasons)
This type allows to specify an enumeration by adding items for each possible enumerated value.
This type allows to specify an device-status enumeration. A state-enum contains some predefined states which may be used by the class-developer.
This item allows to specifiy a state in detail.
This custom-type allows to define bit pattern of 16 and 32 bits.
Log-topics for diagnostic logging which can be used to log class-specific diagnostic messages. A maximum of 32 class-specific log-topics can be specified.
In order to avoid duplication, the context of the chapters below is used by different other chapters.
"Access" describes the access type which can be used for an item.
The name of the custom-type, constrained by the pattern: ([_A-Za-z])([_A-Za-z0-9:])*
This item contains the value which is used for this constant.
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:
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.
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.
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.
Here you can fill in detailed information about a hardware-address.
Here you can specify a logical-address which may be necessary to use the defined hardware-address.
Used for the association-relationship. ( TODO: add useful info here )
Setting-fields are used to store values which are needed to control the hardware-equipment.
Acquisition-fields are used to store data, which was produced by the hardware-equipment.
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.
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.
Setting-fields are used to store values which are needed to control the hardware-equipment.
Acquisition-fields are used to store data, which was produced by the hardware-equipment.
Accelerator facilities are often separated into different timing domains to separate between the timing of different sub-accelerators which need to work together. Here fields which are timing-domain specific can be stored.
Configuration-fields are only initialized once. The values for initialization are provided by the instantiation-document
In order to avoid duplication, the context of the chapters below is used by different other chapters.
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:
Configuration-fields are only initialized once. The values for initialization are provided by the instantiation-document
Setting-fields are used to store values which are needed to control the hardware-equipment.
Acquisition-fields are used to store data, which was produced by the hardware-equipment.
A fault-field is used to indicate a internal status. (Similar to the alarm-field, but only for internal usage)
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.
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.
A Cycle-name-field can store the name of a cycle. The cycle-name e.g. can be obtained from the multiplexing-context.
A Cycle-name-field can store the name of a cycle. The cycle-name e.g. can be obtained from the multiplexing-context.
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.
A Cycle-stamp-field can store the value of a cycle-stamp. The cycle-stamp e.g. can be obtained from the multiplexing-context.
Configuration field used to define which subset to expose at runtime. Needs to be filled in an instance file with a valid subset name.
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:
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:
More information on how to use the field in an RT-Action can be found here
This GSI specific field describes the summary of the device status.
The enumeration "DEVICE_STATUS" allows the following mutually exclusive values:
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.
If a device is not operational because of a hardware failure (e.g. missing cooling water) the state must be signaled as an interlock in the Status property. The interlock is a device-specific state which depends on the device’s features. Additional information about the device’s state should be displayed using the detailed status bits.
Depending on the severity of the interlock, the fields status, detailedStatus and opReady should be updated.
A device is considered ready for operation if it is fully usable by applications and neither in a failure state nor operated locally. If the device is in a failure state or set to local operation the applications must be aware of this by information in the state of the opReady-bit. Whether a device is considered ready for operation must be confirmed per device. Some devices, e.g. bending magnets, may be powered off if they are ready for operation.
Usually that implies that the field status signals "OK" or "WARNING", the field control signals "REMOTE" and the field modulesReady signals "true".
If the usual logic does not apply for a specific device, exceptional logic should be described in the documentation of the related FESA class.
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.
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.
This GSI specific field describes the current power state of the device.
The enumeration "DEVICE_POWER_STATE" allows the following values (mutually exclusive):
Please note that the status of a device can still be "OK" when the powerState is different from "ON" !
This GSI specific field describes if the device is controlled remotely or local.
The bit-enumeration "DEVICE_CONTROL" allows the following values:
Please note that the status of a device can still be "OK" when controlled locally!
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:
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:
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.
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.
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.
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:
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.
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:
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.
Here you can specify the name of this field.
Boolean value. Persistence 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.
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.
Boolean value
Optional attribute for acquisition fields. Default value is false.
When set to true, getting the value of an acquisition field is guaranteed not to throw if the context is correct: if the field has no data, 0 is returned. In a real-time action, the value from the last execution is returned (or 0 for the first execution).
When set to false (or not set), getting a value of an empty acquisition field throws. A real-time action can only get a value that was set within the same event.
Boolean value
Enumeration, which describes the seriousness of something. Possible values:
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.
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.
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.
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.
An abstract RealTime-action has no implementation in the base-class. However, the child-class needs to provide an implementation for the action.
In order to avoid duplication, the context of the chapters below is used by different other chapters.
Whenever this action is executed, the defined properties will trigger a client-update for all clients which have a subscription to the property.
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.
Within this item you can force a server-action to automatically lower the alarm state of an alarm-field, when the action is executed.
Within this item you can force a server-action to automatically lower the severity state of a fault-field, when the action is executed.
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
Give a meaningful name to your action, which describes the activity it is made for.
Here you can further explain the purpose of this action.
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.
A event source describes a source of a FESA-internal event. All sources, defined here will be instantiated.
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.
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.
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.
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.
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.
Holds a collection of all available logical-events of this class.
A logical event describes a FESA-internal event. The mapping to the concrete-event is done in the instantiation document.
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".
Scheduling-units are used to freely map the different FESA-internal logical-events to rt-actions.
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.
A selection criterion allows to execute a rt-action not for all device-instance of a class, but only for a choosen selection.
Here a selection-rule can be defined in order to group a collection of device-instance for which the rt-action will be executed.
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.
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.
In order to avoid duplication, the context of the chapters below is used by different other chapters.
For a device-instance the result of these two logical connected criteria(operands) needs to be true, to be part of the device-collection.
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.
In order to avoid duplication, the context of the chapters below is used by different other chapters.
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[]) |
The scalar-type is the most basic FESA-data type one can choose. It only represents a single data-element.
The array-type is used to represent a array of scalars.
Similar to the array, but for an additional dimension.
Represents a scalar value which defines a custom-type as data-type.
The array-type is used to represent a array of custom-type-scalar.
Similar to the custom-type-array, but for an additional dimension.
Allows you to specify directly the array dimension by providing an unsigned value.
Allows you to specify the array dimension by referring to a constant-unsigned-int, which was previously defined in the custom-types.
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.
Used to indicate the value-item concerned by the meta information
Used to map this item to an existing internal data-field.
Used to map this item to one bit of an existing internal data-field.
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.
Allows you to select a type from an enumeration which contains all the supported types as shown in the above table
This item contains standardized values to add information about the state of the equipment. The different meanings are:
Allows to specify in which unit the value is expressed
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.