Core

The core package provides all the low-level functionalities of pydoocs, which represents the Python bindings to the C++ DOOCS client API. The contents of this subpackage is shown below:

import doocspie

help(doocspie.core)

Help on package doocspie.core in doocspie:

NAME
    doocspie.core - Python bindings to the DOOCS client and ZeroMQ API (C/C++).

PACKAGE CONTENTS
    core

FUNCTIONS
    connect(...)
        Function to connect to given ZeroMQ DOOCS addresses.
    
    disconnect(...)
        Function to disconnect from connected ZeroMQ DOOCS addresses.
    
    getdata(...)
        Function to get data from connected ZeroMQ DOOCS addresses.
    
    names(...)
        Function to query names from a given DOOCS address domain.
    
    read(...)
        Function to read data from a given DOOCS address.
    
    write(...)
        Function to write data to a given DOOCS address.

DATA
    __LIBNO__ = '22.6.1'

VERSION
    3.0.4

FILE
    /home/cbehrens/Home/Repositories/gitlab/doocspie/doocspie/core/__init__.py

This documentation is extracted from pydoocs, and it is neither comprehensive nor complete. For more information refer to https://confluence.desy.de/display/DOOCS/Python+Client+Interface and/or its Git repository https://mcs-gitlab.desy.de/doocs/doocs-common-libraries/pydoocs.

We encourage users explicitly not to use pydoocs (or doocspie.core) directly any longer, but rather its successor doocspie with its own I/O functionalities. For those who wants to use doocspie in legacy code that is still using pydoocs or imported functions from it, the following hacks may be applied:

# to replace 'import pydoocs'
import doocspie.core as pydoocs

# to replace 'from pydoocs import names, read, write'
from doocspie.core import names, read, write

In the following, we briefly introduce the main I/O functions of pydoocs: names, read and write. The ZeroMQ API, despite being part of pydoocs, is omitted here and not part of this documentation.

names

The names function expects optional parts of a string with the 4-layer DOOCS address scheme facility/device/location/property and an additional wildcard character * included. Depending on the actual supplied address part, it returns then the available facilities, devices, locations and/or properties. The following examples return all location of the given device, and subsequently, all the properties of the given location that has the string TRUM in its property name as a Python list:

doocspie.core.names("TEST.DOOCS/UNIT_TEST_SUPPORT/*")

['MCSVDEV2._SVR',
 'PY_DOOCS',
 'PY_DOOCS_ALTERNATIVE',
 'DOOCSTOOLS',
 'DOOCSDAPILIB',
 'DOOCSDFSMLIB',
 'XFELKARABO',
 'UNDULATOR_DOSIMETER',
 'I_PHASE',
 'DOXRPC',
 'TASKOMAT',
 'SPEED_TEST',
 'CLIENTLIB',
 'SERVERLIB']

doocspie.core.names("TEST.DOOCS/UNIT_TEST_SUPPORT/PY_DOOCS/*TRUM")

['SPECTRUM spectrum data type', 'GSPECTRUM gspectrum data type']

read

The read function expects a DOOCS address in order to read from a corresponding server. Three optional parameters, parameters, macropulse and ignore_macropulse_mismatch, allow for a more specific readout and synchronization, but they are omitted here for the sake of clarity (refer to the pydoocs documentation mentioned above for more information). The read function returns a Python dict with the five keys: data, type, timestamp, macropulse and miscellaneous. The following examples show the output for a DOOCS FLOAT and SPECTRUM property, respectively:

doocspie.core.read("TEST.DOOCS/UNIT_TEST_SUPPORT/PY_DOOCS/FLOAT.BUFFER")

{'data': 28.229999542236328,
 'type': 'FLOAT',
 'timestamp': 1711375086.221303,
 'macropulse': 3524328,
 'miscellaneous': {}}

doocspie.core.read("TEST.DOOCS/UNIT_TEST_SUPPORT/PY_DOOCS/SPECTRUM")

{'data': array([[0.0000000e+00, 9.5440632e-01],
        [1.0000000e-01, 9.5435166e-01],
        [2.0000000e-01, 9.5430362e-01],
        ...,
        [2.4999701e+04, 3.5018027e-03],
        [2.4999801e+04, 3.5005528e-03],
        [2.4999900e+04, 3.4993018e-03]], dtype=float32),
 'type': 'SPECTRUM',
 'timestamp': 1711375086.263535,
 'macropulse': 0,
 'miscellaneous': {'comment': '',
  'timestamp': 1711017122,
  'status': 0,
  'start': 0.0,
  'incr': 0.10000000149011612}}

write

The write function expects two parameters, a DOOCS address and a data value, in order to write to a corresponding DOOCS server. The optional parameter allow_resizing of type bool allows the resizing of array-like DOOCS types. In the following example, the data content of a DOOCS INTEGER property will be changed, and its output data before and after writing gets printed out:

doocs_address = "TEST.DOOCS/UNIT_TEST_SUPPORT/PY_DOOCS/INTEGER"

output_before = doocspie.core.read(doocs_address)
doocspie.core.write(doocs_address, 42)  # the actual 'write' command
output_after = doocspie.core.read(doocs_address)

print("output data before 'write' command:", output_before["data"])
print("output data after 'write' command:", output_after["data"])

output data before 'write' command: 23
output data after 'write' command: 42