Standard properties and value-items for GSI-template

In the GSI control system, each device should have a common set of properties. This set of properties is established when a FESA-class is defined according to the GSI template. The meaning of the proeprties is descibed in the following lists.

Setting Properties

Common Setting-Value-Items

Upon read back, all setting-properties provide a common set of value-items, as follows.

value-item	type	comment
updateFlags	enum	Relevant for subscriptions only, 1: IMMEDIATE, indicates response is sent when subscription is set-up 2: SET, indicates response is sent when new data are available
cycleName	char 32	Multiplexing slot, for which data are provided Indicates either non-multiplexed, beam-process or sequence

Property Init

Control property.(no data).

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” )

---

Property Reset

Control property (no data).

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 for non-multiplexed settings.

In case of multiplexed settings the settings should be provided by the data supply after FESA software reset.

---

Property Setting

Device specific property

Takes setting data which is relevant for operation of the machine

value-item	type	comment
<set of specific value-items>		Depends on the specific device.
common-items	- -	Common value-items, see common setting value-items

---

Property Power

Sets the device's main power to the given state. Generally switching of the power state is done only when the property is called. The value of the Power-property may not reflect the actual power state of the device: When the device is switched off manually of by failure, the device may be OFF while the property still shows ON, and vice versa.

The present power state of a device is given in the powerState value-item of the property Status

value-item	type	comment
power	int	1=ON, 2=OFF Additional values like 3=STANDBY may be defined, depending on the type of equipment
common-items	- -	Common value-items, see common setting value-items

---

---

Acquisition-Properties

Common Acquisition-Value-Items

All Acquisition-properties provide a common set of value-items, as follows.

value-item	type	comment
acqStamp	long	time of most recent data acquisition
updateFlags	enum	Relevant for subscriptions only, 1: IMMEDIATE, indicates Response is sent when subscription is set-up 2: SET, indicates response is sent when new data are available
cycleName	char 32	Name of the multiplexing context, for which data are acquired may be beam-process or sequence
cycleStamp	long	for multiplexed data only: time when multiplexing slot (beam-process or sequence) has started For more information use the GSI-specific stamps below.

---

Common GSI Acquisition-Context

All GSI-acquisition-properties provide a common acquisition context, as follows.

Most value-items are relevant for multiplexed data only. However, acqStampGSI should give relevant data also for non-multiplexed GSI acquisition properties.

value-item	type	comment
acquisitionStamp	int64	time of data acquisition as scheduled by the Timing Master (White Rabbit timestamp)
eventStamp	int64	time of data acquisition as executed by the Timing Receiver (White Rabbit timestamp)
processIndex	int32	key (identifying number) of the beam-process, from the Timing Message
sequenceIndex	int32	key (identifying number) of the sequence, from the Timing Message
chainIndex	int32	identifier of the Beam Production Chain, from the Timing Message Payload
eventNumber	int32	Timing Event Number from the Timing Message
timingGroupID	int32	Timing Group Number from the Timing Message
processStartStamp	int64	White Rabbit Timestamp of the most recent BP_START event
sequenceStartStamp	int64	White Rabbit Timestamp of the most recent SEQ_START event
chainStartStamp	int64	White Rabbit Timestamp of the Beam Production Chain start

---

Property Status

Returns information on the present state of the device.

value-item	type	comment
status	int	Displays the (cycle independent) overall Status of the device. Please note that the status of a device can still be "OK" when control is set to "LOCAL" or powerState is different from "ON" 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
detailedStatus	bool array	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. Each bit: True=OK
detailedStatus_labels	2DCharArray (string array)	Labelings (mnemonics) for the bits in the detailedStatus value-item For each bit in the detailedStatus value-item at the corresponding position a label has to be provided which describes meaning of the status bit
detailedStatus_severity	enum array	Severity of the corresponding bits in the detailedStatus value-item 0=INFO, 1=WARNING_ON_FALSE, 2=ERROR_ON_FALSE
powerState	int	Reflects the present state of the device's main power. 0=UNKNOWN, 1=ON, 2=OFF, 3=STANDBY, 4=POWER_DOWN, 5=POWER_UP Generally the device has to be in the ON-powerState for operational usage. The state of STANDBY generally indicates an intermediate state, i.g. warmed up, in which it is not powered for operation but can be switched to the ON-powerState much faster then from the OFF-powerState. POWER_UP and POWER_DOWN generally are transition modes, indicating that the device is in a power change sequence
control	int	0=REMOTE, 1=LOCAL REMOTE: Device is controled by the control system, LOCAL: Device ist operated locally, control system has no access to modify the device (while acquisition data in general will be available)
interlock	bool	True: Device is in interlock-state Additional documentation can be found here
opReady	bool	True: Device is ready for usage in the facility (ready for operation). False: Device is not in a state where it can be used. In such case the detailedStatus-item should display the reason of the cause. Remark: In the state opReady=True the device may be powered down, but opReady=True then indicates that the power can be switched on by the control system. Additional documentation can be found here
modulesReady	bool	True: All required hardware and software modules in the control system interface are ready to be used. False: At least one module is not OK, the device cannot be operated properly. The property ModuleStatus should give detailed information on the failing components.
error_codes	int32_t array	Error codes, for all errors which are in the front-end software detected for the device. Error codes are read from an internal ring-buffer
error_messages	2DCharArray (string array)	Error Messages, labelling the corresponding error number in the value-item error_code
error_timestamps	int64_t array	Timestamps, when the error code was inserted in the internal error ring buffer
error_cycle_names	2DCharArray (string array)	Name of the cycle in which the corresponding error code was detected What is contained in the cycle Name? Is it the Multiplexing context??
common-acquisition-items	- -	Common value-items, see common acquisition value-items

---

Property Version

Return version numbers for FESA-class, deploy-unit and FESA framework.

value-item	type	comment
classVersion	char[256]	Version of FESA class, e.g. 0.1.0*
deployUnitVersion	char[256]	Version of FESA deploy-unit, e.g. 0.1.0*
fesaVersion	char[256]	Version of FESA framework,e.g. 2.0.1*

* Three digit version scheme: major, minor, tiny. Below is a schematic explanation.

2.0.1
│ │ └───────── Tiny: Revision, e.g. internal changes, bug fixes
│ └─────────── Minor: Functional extensions
└───────────── Major: Significant changes, API changes

---

Property ModuleStatus

Optional property.

Returns information on the present state of controls interfacing components which are needed to operate the device.

The structure of the property depends on the specific layout of the interface to the equipment. E.g. for interfacing by SCU-bus slave cards, the ModuleStatus property may, for each such slave card, the operational status (card OK, error detected, card missing, ...). The ModuleStatus property may also be used to return information on required software components.

value-item	type	comment
moduleStatus	enum array	Each element contains the state of a controls interfacing component, which is needed to operate the device
moduleStatus_labels	2DCharArray (string array)	Labelings (mnemonics) for the corresponding elements in the module_status value-item
common-acquisition-items	- -	Common value-items, see common acquisition value-items

---

Property Acquisition

Device specific GSI-acquisition property

Returns acquisition data which is relevant for operation of the machine.

value-item	type	comment
<set of specific value-items>		Depends on the specific device.
common-acquisition-items	- -	Common value-items, see common acquisition value-items
acquisition-context	- -	Common value-items, see common acquisition context