257 lines
11 KiB
ReStructuredText
257 lines
11 KiB
ReStructuredText
Frappy Programming Guide
|
|
========================
|
|
|
|
Introduction
|
|
------------
|
|
|
|
*Frappy* is a Python framework for creating Sample Environment Control Nodes (SEC Node) with
|
|
a SECoP interface. A *SEC Node* is a service, running usually a computer or microcomputer,
|
|
which accesses the hardware over the interfaces given by the manufacturer of the used
|
|
electronic devices. It provides access to the data in an abstracted form over the SECoP interface.
|
|
`SECoP <https://github.com/SampleEnvironment/SECoP/tree/master/protocol>`_ is a protocol for
|
|
communicating with Sample Environment and other mobile devices, specified by a committee of
|
|
the `ISSE <https://sampleenvironment.org>`_.
|
|
|
|
The Frappy framework deals with all the details of the SECoP protocol, so the programmer
|
|
can concentrate on the details of accessing the hardware with support for different types
|
|
of interfaces (TCP or Serial, ASCII or binary). However, the programmer should be aware of
|
|
the basic principle of the SECoP protocol: the hardware abstraction.
|
|
|
|
Hardware Abstraction
|
|
--------------------
|
|
|
|
The idea of hardware abstraction is to hide the details of hardware access from the SECoP interface.
|
|
A SECoP module is a logical component of an abstract view of the sample environment.
|
|
It is one independent value of measurement like a temperature or physical output like a current or voltage.
|
|
This corresponds roughly to an EPICS channel or a NICOS device. On the hardware side we may have devices
|
|
with several channels, like a typical temperature controller, which will be represented individual SECoP modules.
|
|
On the other hand a SECoP channel might be linked with several hardware devices, for example if you imagine
|
|
a superconducting magnet controller built of seperate electronic devices like a power supply, switch heater
|
|
and coil temperature monitor. The latter case does not mean that we have to hide complete the details in the
|
|
SECoP interface. For an expert it might be useful to give at least read access to hardware specific data
|
|
by providing them as seperate SECoP modules. But the magnet module should be usable without knowledge of
|
|
all the inner details.
|
|
|
|
A SECoP module has:
|
|
|
|
* **properties**: static information describing the module, for example a human readable *description* of
|
|
the module or information about the intended *visibiliy*.
|
|
* **parameters**: changing information about the state of a module (for example the *status* containing
|
|
information about the state of the module )or modifiable information influencing the measurement
|
|
(for example a "ramp" rate)
|
|
* **commands**: actions, for example *stop*
|
|
|
|
A SECoP module belongs to an interface class, mainly *Readable* or *Drivable*. A *Readable* has at least the
|
|
parameters *value* and *status*, a *Drivable* in addition *target*. *value* is the main value of the module
|
|
and is read only. *status* is a tuple (status code, status text), and *target* is the target value.
|
|
When the *target* parameter value of a *Drivable* changes, the status code changes normally to a busy code.
|
|
As soon as the target value is reached, the status code changes back to an idle code, if no error occurs.
|
|
|
|
**Programmers Hint:** before starting to code, choose carefully the main SECoP modules you have to provide
|
|
to the user.
|
|
|
|
|
|
Tutorial Example
|
|
----------------
|
|
For this tutorial we choose as an example a cryostat with a LakeShore 336 temperature controller, a level
|
|
meter and a motorized needle value. Let us start with the level meter, as this is the simplest module.
|
|
|
|
|
|
Coding the HeLevel Driver
|
|
-------------------------
|
|
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 *secop_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``
|
|
|
|
``secop_psi/ccu4.py``:
|
|
|
|
.. code:: python
|
|
|
|
# the most common classes can be imported from secop.core
|
|
from secop.core import Readable, Parameter, Override, FloatRange, BoolType, \
|
|
StringIO, HasIodev
|
|
|
|
|
|
# the class used for communication
|
|
class CCU4IO(StringIO):
|
|
# on connect, we send 'cid' and expect a reply starting with 'CCU4'
|
|
identification = [('cid', r'CCU4.*')]
|
|
end_of_line = '\n'
|
|
|
|
|
|
# inheriting the HasIodev mixin creates us the things needed for talking
|
|
# with a device by means of the sendRecv method
|
|
# Readable as a base class defines the value and status parameters
|
|
class HeLevel(HasIodev, Readable):
|
|
"""He Level channel of CCU4"""
|
|
|
|
# define or alter the parameters
|
|
parameters = {
|
|
# we are changing the 'unit' parameter property of the inherited 'value'
|
|
# parameter, therefore 'Override'
|
|
'value': Override(unit='%'),
|
|
}
|
|
# define the communication class to create the IO module
|
|
iodevClass = CCU4IO
|
|
|
|
def read_value(self):
|
|
# method for reading the main value
|
|
reply = self.sendRecv('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 txtvalue # the framework will automatically convert the string to a float
|
|
|
|
This is already 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*, *full* and *fast*,
|
|
and we have to code the communication and convert the status codes from the hardware to
|
|
the standard SECoP status codes.
|
|
|
|
.. code:: python
|
|
|
|
...
|
|
# define or alter the parameters
|
|
parameters = {
|
|
|
|
...
|
|
|
|
# the first two arguments to Parameter are 'description' and 'datatype'
|
|
# it is highly recommended to define always the physical unit
|
|
'empty': Parameter('warm length when empty', FloatRange(0, 2000),
|
|
readonly=False, unit='mm'),
|
|
'full': Parameter('warm length when full', FloatRange(0, 2000),
|
|
readonly=False, unit='mm'),
|
|
'fast': Parameter('fast reading', BoolType(),
|
|
readonly=False),
|
|
}
|
|
|
|
...
|
|
|
|
Status = Readable.Status
|
|
|
|
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.sendRecv('hsf').split('=')
|
|
assert name == 'hsf'
|
|
return self.STATUS_MAP(int(txtvalue))
|
|
|
|
def read_emtpy(self):
|
|
name, txtvalue = self.sendRecv('hem').split('=')
|
|
assert name == 'hem'
|
|
return txtvalue
|
|
|
|
def write_empty(self, value):
|
|
name, txtvalue = self.sendRecv('hem=%g' % value).split('=')
|
|
assert name == 'hem'
|
|
return txtvalue
|
|
|
|
...
|
|
|
|
Here we start to realize, that we will repeat similar code for other parameters, which means it might be
|
|
worth to create our own *_sendRecv* method, and then the *read_<param>* and *write_<param>* methods
|
|
will become shorter:
|
|
|
|
.. code:: python
|
|
|
|
...
|
|
|
|
def _sendRecv(self, cmd):
|
|
# method may be used for reading and writing parameters
|
|
name, txtvalue = self.sendRecv(cmd).split('=')
|
|
assert name == cmd.split('=')[0] # check that we got a reply to our command
|
|
return txtvalue # the framework will automatically convert the string to a float
|
|
|
|
def read_value(self):
|
|
return self._sendRecv('h')
|
|
|
|
...
|
|
|
|
def read_status(self):
|
|
return self.STATUS_MAP(int(self._sendRecv('hsf')))
|
|
|
|
def read_empty(self):
|
|
return self._sendRecv('hem')
|
|
|
|
def write_empty(self, value):
|
|
return self._sendRecv('hem=%g' % value)
|
|
|
|
def read_full(self):
|
|
return self._sendRecv('hfu')
|
|
|
|
def write_full(self, value):
|
|
return self._sendRecv('hfu=%g' % value)
|
|
|
|
def read_fast(self):
|
|
return self._sendRecv('hf')
|
|
|
|
def write_fast(self, value):
|
|
return self._sendRecv('hf=%s' % value)
|
|
|
|
|
|
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 finally be loaded. We choose the name *example_cryo*
|
|
and create therefore a configuration file *example_cryo.cfg* in the *cfg* subdirectory:
|
|
|
|
``cfg/example_cryo.cfg``:
|
|
|
|
.. code:: ini
|
|
|
|
[NODE]
|
|
description = this is an example cryostat for the Frappy tutorial
|
|
id = example_cryo.sampleenvironment.org
|
|
|
|
[INTERFACE]
|
|
uri = tcp://5000
|
|
|
|
[helev]
|
|
description = He level of the cryostat He reservoir
|
|
class = secop_psi.ccu4.HeLevel
|
|
uri = linse-moxa-4.psi.ch:3001
|
|
empty = 380
|
|
full = 0
|
|
|
|
A configuration file contains several sections with a header encloded by rectangular brackets.
|
|
|
|
The *NODE* section describes the main properties of the SEC Node: a description of the node and
|
|
an id, which should be globally unique.
|
|
|
|
The *INTERFACE* section defines 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. A module section at least contains a
|
|
human readable *description*, and the Python *class* used. 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* and *full* from the client by defining:
|
|
|
|
.. code:: ini
|
|
|
|
empty.export = False
|
|
full.export = False
|
|
|
|
However, we do not do this here, as it is nice to try out chaning parameters for a test!
|
|
|