255 lines
9.7 KiB
ReStructuredText
255 lines
9.7 KiB
ReStructuredText
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``:
|
|
|
|
.. code:: python
|
|
|
|
# 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 :class:`frappy_psi.ccu4.CCU4IO`, an extension of (:class:`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.
|
|
|
|
.. code:: python
|
|
|
|
...
|
|
# 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:
|
|
|
|
.. code:: python
|
|
|
|
...
|
|
|
|
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 :class:`frappy.datatypes.StructOf` with members *empty_length* and *full_length*:
|
|
|
|
.. code:: python
|
|
|
|
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: :class:`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``:
|
|
|
|
.. code:: python
|
|
|
|
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:
|
|
|
|
.. code:: python
|
|
|
|
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*
|