TINE Control System

Often one needs to (or would like to) reorganize the namespace or hierarchy of an existing server or gather information from multiple servers and offer the same information under a logical naming structure from a central source. This is typical middle layer activity, and rather than spending time writing a dedicated server for this purpose you can make use of the TINE combobulator, which is itself a powerful, configurable middle layer server.

A common reason for using the Combobulator is to reorganize single channel access properties into a more easily digestable multi-channel array properties.

Another common reason to make use of the Combobulator is to collect common data from distributed sources and export them as multi-channel arrays for consumption by the archiver or other clients.

The TINE combobulator is a simple command line server. By typing 'combobulate' at the command line (after installing TINE) you should see output similar to the following:

combobulate
Usage:
 
    combobulate /s=<server name> [/f=<config file> /n=<fecname> c=<context> /u=<subsystem> /l=<location> /r=<responsible> /p=<port offset> /b=TRUE (run in background) /m=TRUE (run minimized) /e=TRUE (use default value on link error)]

The Combobulator is not limited to providing multi-channel arrays. It can as well offer single value attributes or waveform like trace arrays. And it can function as a full-blown middle layer by forwarding or redirecting WRITE commands to a target parent server.

The combobulator reads (and must read!) a configuration file, called combobulate.csv.

As a .csv File, combobulate.csv should offer the following columns (in any order):

SERVER (required) is the context qualified target server whose properties are to be combobulated. If the SERVER entry is one of "self", "this", or "me", then the entry is assumed to be a clone of another entry with a different PROPERTY_ALIAS.
PROPERTY (required) is the target property, or a property list .csv file, giving the property(ies) to be combobulated.
PROPERTY_ALIAS (optional)is the combobulated export property associated with the PROPERTY entry. If omitted, then the same property name found in the PROPERTY entry is used or, in the of a list file, the ALIAS names found in the list file will be used.
DEVICE (optional) is the target device, or a device list .csv file. If omitted or a wildcard '*' is used, then the device list is obtained from the target server.
DEVICE_ALIAS (optional) is the combobulated export device name associated with the DEVICE entry.
DESCRIPTION (optional) is the combobulated property description.
FORMAT (required) is the TINE format of the target property. It can be omitted in case a property list .csv file is use and format information is found there. If otherwise omitted, then the CF_NULL data type is used, which would only make sense in the case of a forwarded WRITE access command. The format entry can also specify the array type, if necessary. The combobulator typically produces CHANNEL arrays. However, when other array types need to be signaled, then such information should be configured with this parameter. e.g. float.SPECTRUM to indicate that the comobulated property delivers a spectrum (waveform) array of float values. Or float.SPECTRUM.DOUBLE.7 to indicate that the property delivers a spectrum double array of float values with a row size of 7. Note that the collective array length should be consist with an such additional row length information. Note: If TEXT is specified (or CHAR) then the FORMAT_EXPORT should be used to remap the acquired data into fixed length strings such as NAME64. Furthermore, the acquisition size of the TEXT data should be specified by appending a .size to the FORMAT (e.g. TEXT.16 to acquire a text field of 16 characters.
FORMAT_EXPORT (optional) is the combobulated export property prefered data format. If omitted, then the same value as given in the FORMAT column is used.
CAPACITY (required) is the data size of the target property acquisition. If omitted, then 0 is assumed, which which would only make sense in the case of a forwarded WRITE access command.
INTERVAL (optional) is the desired update interval of the target property data. Default = 1000 msec.
DISABLED (optional) is a boolean which if TRUE instructs the combobulator not to acquire the data for this entry. Default = FALSE.
SHIFT (optional) can be used to shift numerical input data by the given amount. Default = 0.
SCALE (optional) can be used to scale numerical input data by the given amount. Default = 1.
FIELD_INDEX (optional) can be used to specify which field index of a compound data type or structure is to be used in the resulting combobulated property.
DEFAULT_VALUE (optional) specifies a data value to use in case of link errors associated with the data acquisition of the target property. The signal to use this default value in lieu of actual data from the target should also be turned on in the command line which starts the combobulator or or (property specific) via the OPTION "USEONERROR".
STALE_VALUE (optional) specifies a data value to use in case the data acquisition of the target property does not show an increasing timestamp or system stamp. The signal to use this default value in lieu of actual data from the target should also be turned on in the command line which starts the combobulator or (property specific) via the OPTION "USESTALE".
OPTIONS (optional) can be used to specify additional data acquisition and export options. This should be a string which can be any of the following in combination (separated with a pipe symbol '|') :
- "LOCALTIME" specifies that the local timestamp and system stamp of the combobulator should be used to tag the incoming data in lieu the incoming time and system stamps.
- "REDIRECT" specifies that the combobulated property and device, when called, should redirect back to the original target and not acquire data from the target.
- "SCHEDULE" specifies that the combobulator should schedule the exported property when fresh data arrive.
- "FORWARD" specifies that the combobulator should forward a WRITE request back to the target property and device. (nominally useful for WRITE access commands on an attribute property).
- "WRITEONLY" specifies that the combobulated property only services WRITE commands and should forward all requests back to the target property and device.
- "MONOTONIC" specifies that the combobulated property is expected to have a monotonically increasing system stamp (e.g. event number or cycle number) in its data updates. The expected increment is by default '1'. If MONOTONIC is specified, then the connection quality statistics will count missed increments. To specify another expected increment, append ':' and the increment to the MONOTONIC option (e.g. "MONOTONIC:2")
- "USEONERROR" specifies that the combobulated property should apply the DEFAULT_VALUE to the acquired data in case of any link error. A threshold count requiring successive link errors prior to using the DEFAULT_VALUE can be specified by appending an @ followed by the threshold (e.g. "USEONERROR@5" will require 5 successive link errors before applying the DEFAULT_VALUE).
- "USESTALE" specifies that the combobulated property should apply the STALE_VALUE to the acquired data in case of stale (non-incrementing) timestamps or system stamps. A threshold count requiring successive stale timestamps prior to using the STALE_VALUE can be specified by appending an @ followed by the threshold (e.g. "USESTALE@3" will require 3 successive stale timestamps or systemstamps before applying the STALE_VALUE).)
- "STATIC" specifies that the combobulated property accesses static information and does not need to continuously acquire data from the targeted server(s). All links will then be closed following a successful data acquisition.
- "ENUM" specifes that the integer values of the combobulated property will also be made available as NAME64 text strings (i.e. the property will be overloaded to provide the enumerated strings associated with the current value). The enumeraton texts can be provided directly (e.g. "ENUM:ON:CHANGING:OFF" or "ENUM:ON#1:CHANGING#2:OFF#3" if the assoicated numerical values do not increase monotonically from 0) or the enumerations texts (and values) can be provided via an addition file, whose file name is indicated in the options and which must have the extension '.csv' (e.g. "ENUM:enumvalues.csv"). The given file must exist and provide column "KEYWORD". An optional column "VALUE" can provide the associated numerical values if they should not monotonically increase from 0.

Below is a simple example of a combobulate.csv file

So the single entries, with registered properties 'Value1', etc. have been combobulated into a middle layer server offering a more descriptive and intuitive multi-channel array :

Consider the example combobulate.csv file below, representing 26 distributed RF modulator servers :

SERVER, PROPERTY, PROPERTY_ALIAS, DEVICE, DEVICE_ALIAS, DESCRIPTION, FORMAT, CAPACITY, OPTIONS
/XFEL/MOD01.DUMMIES, Mod-Dummies.csv, , device0, GUN.I1,  Mod for Kryo, single, 30,
/XFEL/MOD02.DUMMIES, Mod-Dummies.csv, , device0, A1.I1,  Mod for Kryo, single, 30,
/XFEL/MOD03.DUMMIES, Mod-Dummies.csv, , device0, A2.L1,  Mod for Kryo, single, 30,
/XFEL/MOD04.DUMMIES, Mod-Dummies.csv, , device0, A3.L1,  Mod for Kryo, single, 30,
/XFEL/MOD05.DUMMIES, Mod-Dummies.csv, , device0, A4.L1,  Mod for Kryo, single, 30,
/XFEL/MOD06.DUMMIES, Mod-Dummies.csv, , device0, A5.L1,  Mod for Kryo, single, 30,
/XFEL/MOD07.DUMMIES, Mod-Dummies.csv, , device0, A6.L3,  Mod for Kryo, single, 30,
/XFEL/MOD08.DUMMIES, Mod-Dummies.csv, , device0, A7.L3,  Mod for Kryo, single, 30,
/XFEL/MOD09.DUMMIES, Mod-Dummies.csv, , device0, A8.L3,  Mod for Kryo, single, 30,
/XFEL/MOD10.DUMMIES, Mod-Dummies.csv, , device0, A9.L3,  Mod for Kryo, single, 30,
/XFEL/MOD11.DUMMIES, Mod-Dummies.csv, , device0, A10.L3,  Mod for Kryo, single, 30,
/XFEL/MOD12.DUMMIES, Mod-Dummies.csv, , device0, A11.L3,  Mod for Kryo, single, 30,
/XFEL/MOD13.DUMMIES, Mod-Dummies.csv, , device0, A12.L3,  Mod for Kryo, single, 30,
/XFEL/MOD14.DUMMIES, Mod-Dummies.csv, , device0, A13.L3,  Mod for Kryo, single, 30,
/XFEL/MOD15.DUMMIES, Mod-Dummies.csv, , device0, A14.L3,  Mod for Kryo, single, 30,
/XFEL/MOD16.DUMMIES, Mod-Dummies.csv, , device0, A15.L3,  Mod for Kryo, single, 30,
/XFEL/MOD17.DUMMIES, Mod-Dummies.csv, , device0, A16.L3,  Mod for Kryo, single, 30,
/XFEL/MOD18.DUMMIES, Mod-Dummies.csv, , device0, A17.L3,  Mod for Kryo, single, 30,
/XFEL/MOD19.DUMMIES, Mod-Dummies.csv, , device0, A18.L3,  Mod for Kryo, single, 30,
/XFEL/MOD20.DUMMIES, Mod-Dummies.csv, , device0, A19.L3,  Mod for Kryo, single, 30,
/XFEL/MOD21.DUMMIES, Mod-Dummies.csv, , device0, A20.L3,  Mod for Kryo, single, 30,
/XFEL/MOD22.DUMMIES, Mod-Dummies.csv, , device0, A21.L3,  Mod for Kryo, single, 30,
/XFEL/MOD23.DUMMIES, Mod-Dummies.csv, , device0, A22.L3,  Mod for Kryo, single, 30,
/XFEL/MOD24.DUMMIES, Mod-Dummies.csv, , device0, A23.L3,  Mod for Kryo, single, 30,
/XFEL/MOD25.DUMMIES, Mod-Dummies.csv, , device0, A24.L3,  Mod for Kryo, single, 30,
/XFEL/MOD26.DUMMIES, Mod-Dummies.csv, , device0, A25.L3,  Mod for Kryo, single, 30,

In this case, the PROPERTY column provides a property list .csv file Mod-Dummies.csv (and the associated PROPERTY_ALIAS column can be safely left empty. The Mod-Dummies.csv File looks like :

PROPERTY, PROPERTY_ALIAS, DESCRIPTION, FORMAT, SHIFT, SCALE, DEFAULT
ACTUAL_STATE, State_ACTUAL, [0:5] State of State-Machine, int32, 0, 1, -1
SUM_FAULT, Alarms_FAULT, [0:150] Sum of Faults, int32, 0, 1, -1
SUM_TRIP, Alarms_TRIP, [0:150] Sum of trips, int32, 0, 1, -1
SUM_WARNING, Alarms_WARNING, [0:150] Sum of Warnings, int32, 0, 1, -1
#
ALARM_VECTOR, Alarms_GUI, [0:150] All alarms, int32, 0, 1, -1
#
# Write Commands!
RESET_ALARMS, Alarms_RESET, [0:150] Reset Alarm Vectors, int32, 0, 1, -1
TARGET_STATE, State_TARGET, [0:150] Target State of State Machine, int32, 0, 1, -1
#

This allows setting alias properties, descriptions, formats, etc. for a common list of properties all to be acquired from the same target server and device, with the given capacity. Note that a data format included in the property list .csv file supersedes that given in the combobulate.csv file.

Now consider the following combobulate.csv snippet, again representing 26 RF modulator server, but now focusing on pulse traces :

SERVER, PROPERTY, PROPERTY_ALIAS, DEVICE, DEVICE_ALIAS, DESCRIPTION, FORMAT, CAPACITY, OPTIONS
/XFEL/MOD01.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, GUN.I1,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD02.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A1.I1,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD03.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A2.L1,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD04.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A3.L1,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD05.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A4.L1,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD06.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A5.L1,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD07.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A6.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD08.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A7.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD09.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A8.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD10.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A9.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD11.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A10.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD12.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A11.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD13.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A12.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD14.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A13.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD15.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A14.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD16.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A15.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD17.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A16.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD18.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A17.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD19.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A18.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD20.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A19.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD21.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A20.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD22.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A21.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD23.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A22.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD24.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A23.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD25.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A24.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC
/XFEL/MOD26.FAST_CHANNEL, Mod-FastChannelTrace.csv, , device0, A25.L3,  Mod for Kryo, single.SPECTRUM, 2000,SCHEDULE|MONOTONIC

Once again a property list is specified via Mod-FastChannelTrace.csv :

PROPERTY, PROPERTY_ALIAS, DESCRIPTION, FORMAT, SHIFT, SCALE, DEFAULT, OPTIONS
SCIG_CURR_KLY_FAST, Kly_Current, [0:150 A] Klystron Current Trace, float.SPECTRUM, 0, 1, -1, SCHEDULE|MONOTONIC
SCIG_VOLT_KLY_FAST, Kly_Voltage, [0:120 kV] Klystron Voltage Trace, float.SPECTRUM, 0, 1, -1, SCHEDULE|MONOTONIC
SCIG_CURR_RHVPS_FAST, Mod_Current, [0:2000 A] Mod Current Trace, float.SPECTRUM, 0, 1, -1, SCHEDULE|MONOTONIC
SCIG_VOLT_RHVPS_FAST, Mod_Voltage, [0:150 kV] Mod Voltage Trace, float.SPECTRUM, 0, 1, -1, SCHEDULE|MONOTONIC

The Combobulator server itself offers service properties to retrieve the source information (property).SRC and additional connection quality statistics (property).CQS.

The connection quality statistics are provided as a multi-channel array of an integer quartet (INTINTINTINT) whose integer fields have the following meanings:

number timeouts since (combobulator) server start
callback misses (skips) since (combobulator) server start. If MONOTONIC has been specified then this can refer to skipped system (event number) stamps. In the example here, the modulator pulses are scheduled at 10 Hz.
delta timestamp between the current data set and the previous data set
delta system stamp between the current data set and the previous data set

In the above example, we expect delta timestamp to be 100 msec and delta system stamp to be 1. The image was taken two and a half weeks after the combobulator start up.