The xcomm Communication Interface for MATLAB

Xcomm is the standard control system interface which is used for High-level controls application written in MATLAB at DESY. Xcomm is based on the TINE protocol which is the standard communication protocol at the XFEL and PETRA III. It can also be used for DOOCS servers at FLASH if the TINE thread is enabled on the server.

Syntax

The standard syntax to read data from or write data to control system addresses is:

   result = xcomm(<tine_address>, [<input_data>,] [ <option_key, option_value>, ...]); 

As an option, multiple addresses can be used in one call:

   result = xcomm(<target_cell_array>, [<default_input_data>,] [ <option_key, option_value>, ...]); 

Example:

Read an x position from a BPM:

  result = xcomm('/TTF2.DIAG/BPM/10DUMP/Z_POS');
  if ~isempty(result.error)
      xposition = result.data;
  else
      error(['Communication error: ' result.error]);
  end

Address Schemes

Xcomm can use TINE or DOOCS address schemes. The TINE address scheme is

  /<facility>/<server>/<device>[property]

The DOOCS address scheme is

  <facility>/<device>/<location>/<property>

The leading slash is optional in both cases. For device and property, wildcards can be used (see below).

Return Value

The return value of xcomm is a structure which contains the fields:

An xcomm call is successful if the error string is empty. If an error message is returned in the error field, the data field is normally empty.

Returned Data

Returned data are stored in the field 'data' of the result structure. TINE knows simple types, string types and structure types which are mapped to MATLAB types according to the following rules.

Simple Types

Simple property types are mapped to the corresponding MATLAB types.

Simple data types can be scalars or arrays, dependent on what the server returns.

String Types

TINE provides different string types. The Type TEXT or CHAR is a character array with a maximal length. The types NAME8, NAME16,...NAME64 are fixed-length character types which can also be used for arrays of strings. The type STRING is used for variable-length strings in variable-length arrays.

In the current version, xcomm maps string types in different ways, depending on the type:

This behaviour may possibly be changed in a future version, in order to become more consistent.

Compound Types

TINE Compound types (predefined structures) are mapped to MATLAB structures. A MATLAB structure which corresponds to a TINE structure has the same field names as the TINE structure. Fields of simple data types are mapped as described above. String fields are always char arrays. If a single record of a compound type is returned, the data field contains a MATLAB structure. In case of multiple records it is a cell array of structures. Please note that the compound types in TINE have different field names than the corresponding compound types in DOOCS. Xcomm accepts only the TINE field names, see TINE documentation.

Tagged Structures

Tagged structures (user defined structures) are mapped in the same way as compound types, except that they can have substructures.

Arrays

Xcomm always returns arrays or cell arrays as column vectors.

Input Data

Input data are mapped in the same way as output data. Numeric types are converted wherever possible, so that MATLAB users do not have to care about different numeric types. Input data arrays can be either row or column vectors. If structures are provided as input data, the field names must exactly match the TINE field names, and all fields of a structure must be present and contain valid data.

Options

Options are supplied as arguments in the xcomm function call.

Note: TINE format types can be written in the form 'INT32', 'DOUBLE', 'SPECTRUM', etc., with the CF_-Prefix removed.

Example:

  result = xcomm('/TTF.DIAG/BPM/10DUMP/Z_POS', 'CONNECTION', 'SYNC', 'TIMEOUT', 100);

Exceptions

Xcomm checks input parameters before opening connections. It throws an exception when it detects mistakes in the function call, e.g. when invalid parameters or data have been supplied or when the address syntax is not correct. Note that connection errors do not throw exceptions as the example shows.

Example:

% Invalid Parameter
>> result = xcomm('TTF2.DIAG/ORBIT/1GUN/X.FLASH1', 'DEMO', false)
Error using xcomm
unknown parameter DEMO

% Invalid address syntax
>> result = xcomm('THIS/ADDRESS/IS/NOT/VALID')
Error using xcomm
error parsing device part of link name

% BUT: Syntax OK, but wrong address
>> result = xcomm('THIS/ADDRESS/IS/NOTEXISTING')

result =

            data: []
           error: 'LCL: address unknown'
      matlabtime: []
        linkname: '/THIS/ADDRESS/IS'
    linkproperty: 'NOTEXISTING'
       timestamp: []
       arraytype: []

Sychronous and Asychronous Communication

The connection mode can be synchronous or asynchronous. It is specofied by the 'CONNECTION' option. By default, the asynchronous mode is used. In asynchronous mode, xcomm uses the buffered client model. Once an address has been accessed, a TINE thread runs in the background and continually updates a buffer. Each time xcomm is subsequently called with the same address, it reads the content of the local buffer. The option TIMEOUT specifies at which rate the buffer is updated.

Important Notes: A locally buffered connection is bound to an address. As soon as it has been opened once, the access and connection modes for this address cannot be changed anymore as long as the asynchronous connection is active in the background. Therefore

• it is not possible to open a synchonous connection to the same address in subsequent calls. Xcomm would automatically use the buffered data.
• The update interval cannot be changed in subsequent calls.

Closing asynchronous connections

Asynchronous connections which run in the background are closed automatically if no data have been requested for more than 5 minutes. They cannot be managed explicitly. However, a 'clear all' ends all active TINE threads.

Using multiple Addresses

xcomm can be used to read to or write from multiple addresses in one call. Instead of a single address string, a cell array of addresses and input data must be provided. If N addresses are used, the cell array must be an N x M matrix, with 1<=M<=3. The first column contains the address strings, the second (optional) contains the input data and the third (optional) contains the input data formats.

The default input data, if specified (see syntax), is used for all addresses where no or empty input data are given.

The result of an xcomm call with multiple addresses is an array of result structures, one for each address.

Example:

>> result = xcomm({'/TTF2/BLM/12ORS[Z_POS]'; '/TTF2/BLM/11BC3[Z_POS]'})

result =

1x2 struct array with fields:

    data
    error
    matlabtime
    linkname
    linkproperty
    timestamp
    arraytype

Using Wildcards

Wildcards can be used to query properties of muliple devices or mutliple properties of one device. There is a difference in the way how wildcards are treated.

Device Wildcard

The wildcard '*' for the device name (i.e. the location name in a DOOCS address) is interpreted by the server. It returns the values of a given property for all devices that provide that property. The result is an array of type USTRING stored in the 'data' field of the returned structure. Each USTRING contains the device name in the 'str' field and the data of the corresponding devices in a suitable field like f1val or ival, depending on the property type.

Example:

>> result = xcomm('TTF2.DIAG/ORBIT/*/X.FLASH1')

result =

            data: [1x65 struct]
           error: []
      matlabtime: 7.3568e+05
        linkname: '/TTF2.DIAG/ORBIT/*'
    linkproperty: 'X.FLASH1'
       timestamp: '19.03.14 10:30:14.408 CET'
       arraytype: ''

>> result.data(1)

ans =

     ival: 0
    f1val: 0.7222
    f2val: 0
       tm: 1395221413
      str: '1GUN'

Other Wildcards

Xcomm also has the possibility to filter devices and properties on the client side. The difference that xcomm interprets the wildcard and turns it into a set of addresses. In opposite to the device wildcard '*', it opens multiple connections and returns an array of results, in the same way as a call with multiple addresses. Such client-interpreted wildcards can be time-consuming.

Example:

>> result = xcomm('TTF2.DIAG/ORBIT/1*/X.FLASH1')

result =

1x20 struct array with fields:

    data
    error
    matlabtime
    linkname
    linkproperty
    timestamp
    arraytype

>> result(1)

ans =

            data: 0.7810
           error: []
      matlabtime: 7.3568e+05
        linkname: '/TTF2.DIAG/ORBIT/1GUN'
    linkproperty: 'X.FLASH1'
       timestamp: '19.03.14 10:31:15.230 CET'
       arraytype: ''