Signal Class Users Guide

# 2. Class Description

The signal class allows the creation of signal objects with a naming convention as:

> DOMAIN/FAMILY/MEMBER/SIGNAL

The signal name is an extension to the device name used in the ESRF control system. To create a signal object, a name with four fields must be used. This corresponds to signal naming as it is used in the history database and in general data display applications.

A signal object represents a simple long, float or double data value. Description resources allow a dynamic configuration for tracing and logging and archiving applications. Maximum and minimum values can be checked and alarm levels can be specified and verified.

## 2.1 The Configuration Resources

The configuration resources (properties) for a signal object are:

Signal Properties
Property | Description Name | The full signal name.
Label | A label for the signal value, which can be used in applications.
Unit | The unit of the signal value.
Format | The format in which the data should be displayed (printf() format).
Description | A text describing the signal.
Max | A maximum value. Can be used for data display or to check limits of set values.
Min | A minimum value. Can be used for data display or to check limits of set values.
AlHigh | Above this limit an alarm will be indicated.
AlLow | Under this limit an alarm will be indicated.
Delta | If the nominal value and the read value of the signal differ by +/- delta during the number of seconds specified by "Delta_t" , an alarm will be raised.
Delta_t | If the nominal value differs from the read value for a longer time than Dta_t seconds, an alarm will be raised.
Standard Unit | A multiplier factor to convert the given signal unit into a standard unit (V, A, W, bar ...).

All resource definitions are searched in three levels. First a set of default resources for the signal class will initialise a newly created object.

> #

> #------------------------------------------------------------------------

> # Signal Class Default Resources

> #------------------------------------------------------------------------

> #

> CLASS/SIGNAL/DEFAULT/Label: "No Label"

> CLASS/SIGNAL/DEFAULT/Unit: "No Unit"

> CLASS/SIGNAL/DEFAULT/Format: "No Format"

> CLASS/SIGNAL/DEFAULT/Descr: "No Description"

> #

> CLASS/SIGNAL/DEFAULT/AlHigh: "Not specified"

> CLASS/SIGNAL/DEFAULT/AlLow: "Not specified"

> CLASS/SIGNAL/DEFAULT/Max: "Not specified"

> CLASS/SIGNAL/DEFAULT/Min: "Not specified"

> CLASS/SIGNAL/DEFAULT/Delta: "Not specified"

> CLASS/SIGNAL/DEFAULT/Dta_t: "Not specified"

> CLASS/SIGNAL/DEFAULT/StdU: "1"

> #

To offer a second level of resources the function object_initialise() was modified from the standard device server template. A class_name argument was added to the function to allow the specification of signal resources for a whole class of devices.

> static long object_initialise (Dssignal ds, char *dev_class_name, long *error);

Every object of a device class will treat the same signals. A set of default resources for the device class can be specified. For example a set of resources for the signal "Voltage" of the "RF-Anode" class.

> CLASS/RF-Anode/DEFAULT/Voltage.Label: "Anode Voltage"

> CLASS/RF-Anode/DEFAULT/Voltage.Unit: kV

> CLASS/RF-Anode/DEFAULT/Voltage.Format: "%4.1f"

> CLASS/RF-Anode/DEFAULT/Voltage.Descr: "Voltage measurement of" \

> "the anode modulator" \

> "power supply."

> CLASS/RF-Anode/DEFAULT/Voltage.StdU: "100"

The resource database only provides four fields to set up resources. To simulate a fifth field a point is used to separate the signal name from the resource name of the signal.

The last level allows resource specification per signal. The resource path is the device name and the fourth field is used as described for the class resources. For example a set of resources for the signal "Voltage" of the device "SR/RF-ANODE/TRA3" of the "RF-Anode" class.

> SR/RF-ANODE/TRA3/Voltage.AlHigh: 100.0

> SR/RF-ANODE/TRA3/Voltage.AlLow: 20.0

> SR/RF-ANODE/TRA3/Voltage.Max: 120.0

> SR/RF-ANODE/TRA3/Voltage.Min: 0.0

> SR/RF-ANODE/TRA3/Voltage.Delta: 1.0

> SR/RF-ANODE/TRA3/Voltage.Dta_t: 20

## 2.2 Alarms on Signals

The signal class allows three different alarm specifications which can be applied one by one or all three at the same time by specifiying the necessary resource values. With the resources AlHigh and AlLow two limiters can be specified wich are checked by executing the method "DevMethodCheckAlarm" on page 6.

The other possible alarm is an alarm on the difference between a nominal value and the actual read value of a signal. If the read value differs from the nominal value by +/- "Delta" for a longer time than "Dta_t" seconds, an alarm will be returned when executing "DevMethodCheckAlarm" on page 6. The nominal value of a signal must be applied with the method "DevMethodCheckLimits" on page 5. Changing the nominal value resets the time counter to zero..

## 2.3 The Methods

### 2.3.1 DevMethodClassInitialise

- long class_initialise (long *error)

- Description:

  Method to initialise the signal class. Will be called automatically when an object of this class is created the first time. The routine will be called only once.

- Arg(s) In:

  None

- Arg(s) Out:

  long *error - Pointer to error code, in case routine fails.

### 2.3.2 DevMethodCreate

- long object_create (char *name, Dssignal *ds_ptr, long *error)

- Description:

  Method to create a signal object.

- Arg(s) In:

  char *name - Name of the signal object in the form: "DOMAIN/FAMILY/MEMBER/SIGNAL"

- Arg(s) Out:

  Dssignal *ds_ptr - Pointer to the created signal object.

  long *error - Pointer to error code, in case routine fails.

### 2.3.3 DevMethodDestroy

- long object_destroy (Dssignal *ds_ptr, long *error)

- Description:

  Method to destroy a signal object and to free all memory occupied by the object.

- Arg(s) In:

  Dssignal ds - Signal object to destroy.

- Arg(s) Out:

  long *error - Pointer to error code, in case routine fails.

### 2.3.4 DevMethodInitialise

- long object_initialise (Dssignal ds, char *dev_class_name, long *error)

- Description:

  Method to initialise the signal object. Reads all levels of specified resources or initialises to default values if no resources were found.

- Arg(s) In:

  Dssignal ds - Signal object to initialise.

  char *dev_class_name - Name of the device class the signal object belongs to.

- Arg(s) Out:

  long *error - Pointer to error code, in case routine fails.

### 2.3.5 DevMethodReadProperties

- long read_properties (Dssignal ds, DevVarStringArray *properties, long *error)

- Description:

  Method to read an array of signal properties. The array is of fixed lenght with all possible property fields initialised. The strings of the array and the sequence pointer are allocated by malloc and must be freed.

> properties.length = 12

> properties.sequence[0] = Name of signal

> properties.sequence[1] = Label

> properties.sequence[2] = Unit

> properties.sequence[3] = Format

> properties.sequence[4] = Description

> properties.sequence[5] = Maximum value

> properties.sequence[6] = Minimum value

> properties.sequence[7] = Alarm high

> properties.sequence[8] = Alarm low

> properties.sequence[9] = Delta value

> properties.sequence[10] = Time interval

> properties.sequence[11] = Multilier for standard units.

- Arg(s) In:

  Dssignal ds - Signal object to use.

- Arg(s) Out:

  DevVarStringArray *properties - Array of strings containing the signal properties.

  long *error - Pointer to error code, in case routine fails.

### 2.3.6 DevMethodCheckLimits

- long check_limits (Dssignal ds, double set_value, long *limit_state, long *error)

- Description:

  Method to check whether the set or nominal value exceeds the specified range for the signal. The range is given by the resources "Max" and "Min".

  At the same time the new set or nominal value is stored and will be used for the alarm check as described in "Alarms on Signals" on page 3.

  The parameter limit_state returns the result of the check. The returned value might be:

> DEVHIGH = Exceeded maximum value.

> DEVLOW = Exceeded minimum value

> DEVRUN = Signal is in the given range.

- Arg(s) In:

  Dssignal ds - Signal object to use.

  double set_value - Signal value to check.

- Arg(s) Out:

  long *limit_state - Result of the limit check.

  long *error - Pointer to error code, in case routine fails.

### 2.3.7 DevMethodCheckAlarm

- long check_alarm (Dssignal ds, double read_value, long *alarm_state, long *error)

- Description:

  Method to check the specified alarms on a signal. The signal read_value might exceed the alarm levels which are set by the resources "AlHigh" and "AlLow". Or the signal read_value might differ from its nominal value as described in "Alarms on Signals" on page 3.

  The parameter alarm_state returns the result of the check. The returned value might be:

> DEVHIGH = Exceeded high alarm level.

> DEVLOW = Exceeded low alarm level.

> DEVEXTRACTED = Difference between read and set (nominal) value.

> DEVRUN = Signal is in the given range.

- Arg(s) In:

  Dssignal ds - Signal object to use.

  double read_value - Signal value to check.

- Arg(s) Out:

  long *alarm_state - Result of the alarm check.

  long *error - Pointer to error code, in case routine fails.

### 2.3.8 DevMethodReadAlarm

- long read_alarm (Dssignal ds, char **alarm_msg, long *error)

- Description:

  Method to read the last alarm message.

  The alarm message is stored when an alarm condition was detected executing "DevMethodCheckAlarm". The stored message will be deleted when calling "DevMethodCheckAlarm" without pending alarm condition. The returned alarm message is allocated with malloc() and must be freed.

  Alarm messages are constructed as:

> "%s higher as alarm level\n", Label

> "%s lower as alarm level\n", Label

- Arg(s) In:

  Dssignal ds - Signal object to use.

- Arg(s) Out:

  char **alarm_msg - Last stored alarm message.

  long *error - Pointer to error code, in case routine fails.

### 2.3.9 DevMethodSignalReset

- long reset (Dssignal ds, long *error)

- Description:

  Method to reinitialise the signal object. All resources are read and all object fields are reinitialised. A stored alarm message is deleted.

- Arg(s) In:

  Dssignal ds - Signal object to use.

- Arg(s) Out:

  long *error - Pointer to error code, in case routine fails.

2.1 - The Configuration Resources
2.2 - Alarms on Signals
2.3 - The Methods
2.3.1 - DevMethodClassInitialise
2.3.2 - DevMethodCreate
2.3.3 - DevMethodDestroy
2.3.4 - DevMethodInitialise
2.3.5 - DevMethodReadProperties
2.3.6 - DevMethodCheckLimits
2.3.7 - DevMethodCheckAlarm
2.3.8 - DevMethodReadAlarm
2.3.9 - DevMethodSignalReset

Generated with Harlequin WebMaker