T controller tutorial and improve documentation

add tutorial for Berlin hands-on workshop

+ improve the documentation (hints for structure welcome)
+ remove 'optional' parameter property
  (is not yet used - should not appear in doc)
+ added test property in frappy_demo.cryo alters Parameter class
  ('test' property appears in Parameter doc)

Change-Id: I3ea08f955a92f72451fd23a5ff00d1185c7fb00e

frappy_demo/cryo.py

@@ -31,7 +31,9 @@ from frappy.modules import Command, Drivable, Parameter
 # test custom property (value.test can be changed in config file)
 from frappy.properties import Property
 
-Parameter.propertyDict['test'] = Property('A Property for testing purposes', StringType(), default='', export=True)
+
+class TestParameter(Parameter):
+    test = Property('A Property for testing purposes', StringType(), default='', export=True)
 
 
 class CryoBase(Drivable):
@@ -73,9 +75,9 @@ class Cryostat(CryoBase):
     target = Parameter("target temperature",
                        datatype=FloatRange(0), default=0, unit="K",
                        readonly=False,)
-    value = Parameter("regulation temperature",
-                      datatype=FloatRange(0), default=0, unit="K",
-                      test='TEST')
+    value = TestParameter("regulation temperature",
+                          datatype=FloatRange(0), default=0, unit="K",
+                          test='TEST')
     pid = Parameter("regulation coefficients",
                     datatype=TupleOf(FloatRange(0), FloatRange(0, 100),
                                      FloatRange(0, 100)),

frappy_demo/lakeshore.py

@@ -39,7 +39,7 @@ class TemperatureSensor(HasIO, Readable):
     # internal property to configure the channel
     channel = Property('the Lakeshore channel', datatype=StringType())
     # 0, 1500 is the allowed range by the LakeShore controller
-    # this range should be restricted in the configuration (see below)
+    # this range should be further restricted in the configuration (see below)
     value = Parameter(datatype=FloatRange(0, 1500, unit='K'))
 
     def read_value(self):
@@ -79,6 +79,8 @@ class TemperatureLoop(TemperatureSensor, Drivable):
         self.communicate(f'RANGE {self.loop},{self.heater_range};RANGE?{self.loop}')
         reply = self.communicate(f'SETP {self.loop},{target};SETP? {self.loop}')
         self._driving = True
+        # Setting the status attribute triggers an update message for the SECoP status
+        # parameter. This has to be done before returning from this method!
         self.status = BUSY, 'target changed'
         return float(reply)
 
@@ -102,7 +104,7 @@ class TemperatureLoop(TemperatureSensor, Drivable):
             if self._driving:
                 return BUSY, 'approaching setpoint'
             return WARN, 'temperature out of tolerance'
-        else:
+        else:  # within tolerance: simple convergence criterion
             self._driving = False
             return IDLE, ''
         return ERROR, text