Markus Zolliker
bc33933a1a
- add properties, parameters and commands to the doc string autoatically - change names to "Frappy" - started tutorial - changed doc structure slightly Change-Id: I87bef91384d138c738d12ddcf3a1de7f758a0973
229 lines
10 KiB
ReStructuredText
229 lines
10 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.
|
|
|
|
Configuration
|
|
-------------
|
|
Before we start coding, we create a configuration file. The frappy framework usually has all present code
|
|
in the directory tree, and the server is started with the configuration as an argument, determining which
|
|
modules are to be configured, ans which code is effectively to be used. We choose the name *example_cryo*
|
|
and create therefore a configuration file *example_cryo.cfg* in the *cfg* subdirectory.
|
|
|
|
Let us start with a simple configuration for the level meter only:
|
|
|
|
``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
|
|
|
|
# TO BE MOVED
|
|
[tmain]
|
|
description = main (heat exchange) temperature
|
|
class = secop_psi.ls336.ControlledChannel
|
|
iodev = lsio
|
|
|
|
The configuration file contains several section starting with a line in 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 contain 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.
|
|
|
|
Code the Python Class for the 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 *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
|
|
|
|
# inheriting 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='%'),
|
|
}
|
|
# tells us how to communicate. StringIO is using \n as line end, which fits
|
|
iodevClass = StringIO
|
|
|
|
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 tell the client, when there is an error. That is what the *status* parameter is for.
|
|
We do not need to declare the status parameter, as it is inherited from *Readable*.
|
|
* We want to be able to configure the He Level sensor and 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:
|
|
|
|
.. 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
|
|
|
|
...
|
|
|
|
We realize now, 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)
|
|
|