1. Introduction

The instantiation-unit is used to store all front-end specific parameters which are needed by a FESA-class. The XML-schema for this file is created dynamically, according to the class-design of the equipment.

2. Instantiation Unit

The Instantiation-Unit Schema is subdivided into several complementary areas, for which the equipment specialist has to make design choices:

• Attributes:
  • information
  • prio-management
  • classes

3. Information

All basic information for the instantiation unit is indicated here.

• Attributes:
  • deploy-unit-name: The name of the deploy unit for which this instantiation unit can be used
  • deploy-unit-version: The version of the deploy unit for which this instantiation unit can be used
  • server-name: The desired name of the middleware-server can be chosen here
  • timestamp: The timestamp indicates when the instantiation unit was created

4. Prio-Management

All priorities among all thread can be specified here.

4.1. Classes

All priorities threads regarding their classes can be managed here.

4.1.1. Client-notification-threads

The priorities for the client notification threads are indicated here. Client notification threads are used to update all middleware-clients. On each property one can change the notif-order attribute of the used client-notification thread.

All the priorities have to consistent regarding the order of the threads. For example, thread-1 has to be higher priority than thread-2 or thread-default. The default thread has the lowest priority regarding the rest of the thread priorities.

Moreover, the highest priority among the client notifications threads has to be lower than the server-notif-thread priority.

• Attributes:
  • prio: Priority of the client thread.

4.1.2. Custom-event-sources

All priorities for each custom-event-source are managed here.

• Attributes:
  • prio: Priority per each custom-event-source. If not defined, a default value will be assigned by the framework.

4.2. Deploy unit

All common priorities for the classes can be managed here.

4.2.1. Concurrency-layers

Priorities for each concurrency layer are configured here.

• Attributes:
  • prio: Priority of the layer

4.2.2. Common-event-sources

All priorities for the events-sources are managed here.

• Attributes:
  • prio: Priority of the event-source. If not defined, a default value will be assigned by the framework.

4.2.3. Common-management-threads

All priorities for the common management threads are managed here.

4.2.3.1. Signal-handler-thread

The priority of a signal handler thread is managed here. The signal handler thread takes care about all incoming signals.

• Attributes:
  • prio: Priority of the thread. If not defined, a default value will be assigned by the framework.

4.2.3.2. Server-notification-thread

The priority for the server notification thread is indicated here. This thread is used in order to consume and process all notification-messages which are sent by the RT-Side in order to notify clients.

This priority has to be greater than the client-notification-threads priority and also lower than the rda-server-thread priority.

• Attributes:
  • prio: Priority of the server thread pool. If not defined, a default value will be assigned by the framework.

4.2.3.3. RDA-server-thread

The priority for the RDA server thread is indicated here. The RDA-server-thread processes all client get/ set requests and as well manages new subscribers.

This priority has to be greater than the server-notif-thread priority.

• Attributes:
  • prio: Priority of the RDA server thread. If not defined, a default value will be assigned by the framework.

4.2.3.4. Persistence-thread

The priority for the persistence thread is indicated here. The persistance thread periodically stores all setting-field data and re-stores it whenever the equipment-software is re-started.

• Attributes:
  • prio: Priority of the persistence thread. If not defined, a default value will be assigned by the framework.

5. Classes

Each Fesa-Class requires some configuration that is managed here.

5.1. Events-Mapping

If logical events are defined in the design, it is necessary to map these logical-events to real hardware-events.

In this section, all types of event-configurations can be defined. Later the different devices can use some of these configurations.

Every device can use a different event-configuration for every event (including the "unused-event-configuration", identified by its name: "NONE"; this disables the event for this device).

All devices must have an event-configuration for every logical-event, unless the logical-event is marked as optional in the design. It is allowed to map required logical-events to "NONE".

• Children:
  • event-configuration
  • unused-event-configuration

5.2. Device-Instance

A device-instance is an software-instance of the corresponding underlying physical device. Since a FESA-class can manage many physical devices of the same type, for each of these physical devices one device-instance has to be defined in the instantiation-document.

In actions device-instances are needed in order to identify the right device. As well a client needs a device-handle in order to connect to the right devie-instance.

• Attributes:
  • name: The unique name of the device
  • state: The state of the device as seen by the high level control system
    • development: The device and/or the underlying class/DU is under development and the API/behavior may change without further notice. It cannot be used in workingsets and knobs and no settings are stored (in InCA/LSA).
    • operation: The device is operational, it is available for use in used in workingsets and knobs and settings can be stored (in InCA/LSA). Changes to this devices have to be done in an organized way.
    • expert: The device is for experts only. It cannot be used in workingsets and knobs and no settings are stored (in InCA/LSA).
    • obsolete: The device should not be used in new applications as it is scheduled for removal. Nor should it be used in standard applications (workingsets and knobs). If it is, a warning is issued.
• Children:
  • configuration
  • setting
  • acquisition
  • events-mapping

5.3. Global-Instance

A global-instance in FESA is used to describe all parts of the class, which are not device-specific. There is only one global-instance in each FESA-class.

In actions a global-instance is needed in order to use the global-device. As well a client needs a device-handle of the global-device if he wants to connect to it.

• Attributes:
  • name: The unique name of the global-device
  • state: The state of the device as seen by the high level control system
    • development: The device and/or the underlying class/DU is under development and the API/behavior may change without further notice. It cannot be used in workingsets and knobs and no settings are stored (in InCA/LSA).
    • expert: The device is for experts only. It cannot be used in workingsets and knobs and no settings are stored (in InCA/LSA).
• Children:
  • configuration
  • setting
  • acquisition

5.4. Multiplexing

• Children:
  • rolling: Here you can specify the depth of all ring-buffers, used by this class. ( Ring-buffers are used for multiplexed acquisition-fields. )

5.5. event-configuration

An event-configuration describes one explicit logical-event-setup. This setup can be used by the defined devices. (Each device may use a different setup for the same logical-event)

Dependent on which type you chose for the logical-event, you will have different sub-options.

• Attributes:
  • name: The unique name of this event-configuration.
• Children:
  • Timing
  • Timer
  • OnDemand
  • OnSubscription
  • Custom

5.6. unused-event-configuration

This event-configuration can be used by each device, which does not want to schedule this event.

• Attributes:
  • name: fixed as ""NONE"

5.7. Timing

Here you can specify any number of concrete timing-events which should fire this logical-event.

• Attributes:
  • hardware-event: Choose a hardware-event from the given enumeration.
  • offset
  • beam-in-flag

  1. Hardware-event

  Hardware-event definitions.

  • Optional Attributes:
    • Offset
    • Beam-in-flag

  1. Offset

  Offset in ns for delaying the treatment of an event.

  2. Beam-in-flag

  Flag to define whether beam is available or not during a whole beam process.

  • true: beam is hopefully available
  • false: beam is probably not available

5.8. Timer

Here you can specify any number concrete timer-periods which will fire this logical-event.

• Children:
  • timer-event

5.9. timer-event

• Attribute:
  • period: Specify the wait-time between two instances of the event in milliseconds.

5.10. OnDemand

Here you can specify any number of on-demand-event-sources which should fire this logical-event.

• Children:
  • on-demand-event-source-ref: Choose an on-demand event-source from the enumeration

5.11. OnSubscription

Here you can specify any number of subscription-setups, which will fire this logical event, whenever they are updated.

• Children:
  • on-subscription-event

5.12. on-subscription-event

• Attributes:
  • context: Multiplexing-context, which is used for the subscription.
  • device: Device to subscribe to.
  • property: Property to subscribe to.

5.13. Custom

Here you can specify any number of custom-event-sources which should fire this logical-event.

• Children:
  • ExampleEventSource: Choose any number of custom-event-sources. In the next level a enumeration will show you all custom-events which can be fired from the source. Just pick one!

5.14. Device-specific events-mapping

Here you can choose an event-configuration per logical-event, which should be used for this specific device.

• Children:
  • event-configuration-ref: Choose an event-configuration from this enumeration.

6. Shared Definitions

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

6.1. configuration

All configuration data which is specific for this device can be configured here. As well all configuration-fields with default-node will appear here. A initial value has to be passed to these fields. For more complex types, a bracket-notation can be used.

• Children:
  • description
  • acceleratorZone
  • accelerator
  • timingDomain
  • mainMuxCriterion
  • hw-address

6.2. setting

All setting fields with default-node will appear here. A initial value has to be passed to these fields. For more complex types, a bracket-notation can be used.

6.3. acquisition

All acquisition fields with default-node will appear here. A initial value has to be passed to these fields. For more complex types, a bracket-notation can be used.

6.4. description

• Attributes:
  • value: Here one can add a description about the specifics of this device

6.5. acceleratorZone

You need to specify the accelerator zone this device belongs to here. You have to select a valid value from the list

• Attributes:
  • value:Choose the right accelerator zone from the enumeration

6.6. accelerator

Here you need to put in the accelerator to which this device is attached to. You always have to select a valid value from the list.

• Attributes:
  • value: Choose the right accelerator from the enumeration

6.7. timingDomain

Here you need to put in the timing domain, which should be used by your device. If your device does not rely on timing, choose "NONE".

• Attributes:
  • value: Choose the right timing-domain from the enumeration

6.8. mainMuxCriterion

If your device is multiplexed, you can choose a criterion here, in order to specify the depth of the buffers and the names of the slots. If your device is not multiplexed, choose "NONE" here.

• Attributes:
  • value: Choose the right mainMuxCriterion from the enumeration

6.9. hw-address

If you declared configuration data fields in the class design of type hw-address, you have to complete their specification in the instantiation file.

• host (The name of this field is NOT fixed. It is specified in the class design):
  • port-number: Set the port number of your device. Depending on your choice in the design step, this attribute can be mandatory
  • host-name Set the name of your host. This field can not be left empty.
• logical-address (The name of this field is NOT fixed. It is specified in the class design.):
  • logical-unit-number: (Formerly known simply as LUN) Specify the logical number of your (hw) device. This attribute is mandatory.
  • channel: Specify the channel of your device (optional)
  • module type: Specify the module type of your device (optional)

6.10. Bracket Notation

For more complex types, like arrays, strings or structures, a bracket notation has to be used to initialize the data container. For multidimensional arrays all rows must have the same number of elements initialized. Here some examples, how the different data-types can be initialized:

Field data type	Example default value
bool	true
int	1234
double	1.234e-10
char array(string) of size 8	myString
int array of size 4	{1,2,3,4}
char array-2D of size 4x8	{1,2,3,myString}
2D double-Array of size 2x3	{{1,2,3},{3,4.567,8.9}}
Structure (int[2], char[8],bool)	{{1,2},myString,true}
Array of structure(inr,bool) of size 2	{{1,true},{2,false}}
Bit enumeration	{true,1,0,true,0} or 1234(decimal) or 0xAB34(hex)