frappy/doc/source/tutorial_helevel.rst

HeLevel - a Simple Driver

Coding the Driver

For this tutorial we choose as an example a cryostat. Let us start with the helium level meter, as this is the simplest module. As mentioned in the introduction, we have to code the access to the hardware (driver), and the Frappy framework will deal with the SECoP interface. The code for the driver is located in a subdirectory named after the facility or institute programming the driver in our case frappy_psi. We create a file named from the electronic device CCU4 we use here for the He level reading.

CCU4 luckily has a very simple and logical protocol:

• <name>=<value>\n sets the parameter named <name> to the value <value>
• <name>\n reads the parameter named <name>
• in both cases, the reply is <name>=<value>\n

frappy_psi/ccu4.py:

# the most common Frappy classes can be imported from frappy.core
from frappy.core import Readable, Parameter, FloatRange, BoolType, StringIO, HasIO


class CCU4IO(StringIO):
    """communication with CCU4"""
    # for completeness: (not needed, as it is the default)
    end_of_line = '\n'
    # on connect, we send 'cid' and expect a reply starting with 'CCU4'
    # 'cid' is a CCU4 command returning the current version prefixed with CCU4
    identification = [('cid', r'CCU4.*')]


# inheriting HasIO allows us to use the communicate method for talking with the hardware
# 'Readable' as base class defines the value and status parameters
class HeLevel(HasIO, Readable):
    """He Level channel of CCU4"""

    # define the communication class for automatic creation of the IO module
    ioClass = CCU4IO

    # define or alter the parameters
    # as Readable.value exists already, we give only the modified property 'unit'
    value = Parameter(unit='%')

    def read_value(self):
        # method for reading the main value
        reply = self.communicate('h')  # send 'h\n' and get the reply 'h=<value>\n'
        name, txtvalue = reply.split('=')
        assert name == 'h'  # check that we got a reply to our command
        return float(txtvalue)

The class frappy_psi.ccu4.CCU4IO, an extension of (frappy.stringio.StringIO) serves as communication class.

Note

You might wonder why the parameter value is declared here as class attribute. In Python, usually class attributes are used to set a default value which might be overwritten in a method. But class attributes can do more, look for Python descriptors or properties if you are interested in details. In Frappy, the Parameter class is a descriptor, which does the magic needed for the SECoP interface. Given lev as an instance of the class HeLevel above, lev.value will just return its internal cached value. lev.value = 85.3 will try to convert to the data type of the parameter, put it to the internal cache and send a messages to the SECoP clients telling that lev.value has got a new value. For getting a value from the hardware, you have to call lev.read_value(). Frappy has replaced your version of read_value with a wrapped one which also takes care to announce the change to the clients. Even when you did not code this method, Frappy adds it silently, so calling <module>.read_<parameter> will be possible for all parameters declared in a module.

Above is already the code for a very simple working He Level meter driver. For a next step, we want to improve it:

• We should inform the client about errors. That is what the status parameter is for.
• We want to be able to configure the He Level sensor.
• We want to be able to switch the Level Monitor to fast reading before we start to fill.

Let us start to code these additions. We do not need to declare the status parameter, as it is inherited from Readable. But we declare the new parameters empty_length, full_length and sample_rate, and we have to code the communication and convert the status codes from the hardware to the standard SECoP status codes.

...
# the first two arguments to Parameter are 'description' and 'datatype'
# it is highly recommended to define always the physical unit
empty_length = Parameter('warm length when empty', FloatRange(0, 2000, unit='mm'),
                         readonly=False)
full_length = Parameter('warm length when full', FloatRange(0, 2000, unit='mm'),
                        readonly=False)
sample_rate = Parameter('sample rate', EnumType(slow=0, fast=1), readonly=False)

...

Status = Readable.Status

# conversion of the code from the CCU4 parameter 'hsf'
STATUS_MAP = {
    0: (Status.IDLE, 'sensor ok'),
    1: (Status.ERROR, 'sensor warm'),
    2: (Status.ERROR, 'no sensor'),
    3: (Status.ERROR, 'timeout'),
    4: (Status.ERROR, 'not yet read'),
    5: (Status.DISABLED, 'disabled'),
}

def read_status(self):
    name, txtvalue = self.communicate('hsf').split('=')
    assert name == 'hsf'
    return self.STATUS_MAP(int(txtvalue))

def read_empty_length(self):
    name, txtvalue = self.communicate('hem').split('=')
    assert name == 'hem'
    return float(txtvalue)

def write_empty_length(self, value):
    name, txtvalue = self.communicate('hem=%g' % value).split('=')
    assert name == 'hem'
    return float(txtvalue)

...

Here we start to realize, that we will repeat similar code for other parameters, which means it might be worth to create a query method, and then the read_<param> and write_<param> methods will become shorter:

...

class HeLevel(Readable):

    ...


    def query(self, cmd):
        """send a query and get the response

        :param cmd: the name of the parameter to query or '<parameter>=<value'
                    for changing a parameter
        :returns: the (new) value of the parameter
        """
        name, txtvalue = self.communicate(cmd).split('=')
        assert name == cmd.split('=')[0]  # check that we got a reply to our command
        return float(txtvalue)

    def read_value(self):
        return self.query('h')

    def read_status(self):
        return self.STATUS_MAP[int(self.query('hsf'))]

    def read_empty_length(self):
        return self.query('hem')

    def write_empty_length(self, value):
        return self.query('hem=%g' % value)

    def read_full_length(self):
        return self.query('hfu')

    def write_full_length(self, value):
        return self.query('hfu=%g' % value)

    def read_sample_rate(self):
        return self.query('hf')

    def write_sample_rate(self, value):
        return self.query('hf=%d' % value)

Note

It make sense to unify empty_length and full_length to one parameter calibration, as a frappy.datatypes.StructOf with members empty_length and full_length:

calibration = Parameter(
    'sensor calibration',
    StructOf(empty_length=FloatRange(0, 2000, unit='mm'),
             full_length=FloatRange(0, 2000, unit='mm')),
    readonly=False)

For simplicity we stay with two float parameters for this tutorial.

The full documentation of the example can be found here: frappy_psi.ccu4.HeLevel

Configuration

Before we continue coding, we may try out what we have coded and create a configuration file. The directory tree of the Frappy framework contains the code for all drivers, but the configuration file determines, which code will be loaded when a server is started. We choose the name example_cryo and create therefore a configuration file example_cryo_cfg.py in the cfg subdirectory:

cfg/example_cryo_cfg.py:

Node('example_cryo.psi.ch',
     'this is an example cryostat for the Frappy tutorial',
      interface='tcp://5000')
Mod('helev',
    'frappy_psi.ccu4.HeLevel',
    'He level of the cryostat He reservoir',
    uri='linse-moxa-4.psi.ch:3001',
    empty_length=380,
    full_length=0)

A configuration file contains a node configuration and one or several module configurations.

Node describes the main properties of the SEC Node: an id and a description of the node which should be globally unique, and an interface defining the address of the server, usually the only important value here is the TCP port under which the server will be accessible. Currently only tcp is supported.

All the other sections define the SECoP modules to be used. This first arguments of Mod( are:

• the module name
• the python class to be used for the creation of the module
• a human readable description is its

Other properties or parameter values may follow, in this case the uri for the communication with the He level monitor and the values for configuring the He Level sensor. We might also alter parameter properties, for example we may hide the parameters empty_length and full_length from the client by defining:

Mod('helev',
    'frappy_psi.ccu4.HeLevel',
    'He level of the cryostat He reservoir',
    uri='linse-moxa-4.psi.ch:3001',
    empty_length=Param(380, export=False),
    full_length=Param(0, export=False))

As we configure more than just an initial value, we have to call Param and give the value as the first argument, and additional properties as keyworded arguments.

to be continued