Merge branch 'doc_motion_feedback' into 'master'

Doc motion feedback

See merge request bliss/bliss!1260

doc/docs/beacon_db.md

@@ -89,13 +89,14 @@ The following database files:
 -
   name: object_2
   param: 43
-```            
+```
 
 Produce the following internal representation:
 
 ```py
 >>> from bliss.config.static import get_config
->>> config = get_config() # load YAML tree from Beacon server, and parse it to create a 'config' object
+>>> config = get_config()  # loads YAML tree from Beacon server,
+                           # and parse it to create a 'config' object
 >>> config.pprint()
 
 { filename: None
@@ -137,9 +138,43 @@ children:
 my_global: hello
 ```
 
-```py
+```python
 >>> config.reload() # since the files changed, reload all config from server
 >>> object_1 = config.get("object_1") #indexing by name (flattened dictionary)
 >>> object_1.get_inherited("my_global")
 hello
 ```
+
+## SPEC vs BLISS
+
+When restarting a SPEC session, all the config was reloaded and
+parameters taken into account automatically.
+
+For performance considerations, in BLISS:
+
+* the config is reloaded:
+    * on-demand: `config.reload()`
+    * at the (re)start of a session
+* the parameters **from config** of an object are taken into account:
+    * at first start of a session
+    * on demand with `obj.apply_config()`
+* it is possible to mix both reload and apply with: `obj.apply_config(reload=True)`
+
+
+## configuration behavior
+
+Changing a configuration parameter, example of the velocity of a BlissAxis.
+
+![Changing a configuration parameter](img/apply_config.png)
+
+
+## Saving parameters
+
+Example to save the velocity of an axis into YAML configuration file:
+
+```python
+DEMO [1]: m1.config.set("velocity", 9)
+DEMO [2]: m1.config.save()
+```
+
+

doc/docs/config_slits.md

@@ -51,7 +51,7 @@ Second part is the configuration of new **virtual axes**  based on **real axes**
     - `front`, `back`, `hgap`, `hoffset` are specifiers for each axis
 * The plugin is not specified in `secondary_slits.yml`, because a
   `__init__.yml` with `plugin: emotion` already exists in the directory
-* `slit_type`: can be ```horizontal``` or ```vertical```
+* `slit_type`: can be `horizontal` or `vertical` or `both` (default value)
 
         -
           controller:

doc/docs/dev_write_calc_ctrl.md

@@ -22,18 +22,18 @@ For example: N-legs tables, energy motor, slits, rotated translations.
 ## example of code
 
 Example of code to create a calculational controller to link 2 axes
-with a factor of 42.
+with a 3.1415 factor.
 
 ```python
 def calc_from_real(self, positions_dict):
     calc_mot_axis = self._tagged["calc_mot"][0]
-    calc_pos = 42 * positions_dict["real_mot"]
+    calc_pos = 3.1415 * positions_dict["real_mot"]
 
     return {"calc_mot": calc_pos}
 
 def calc_to_real(self, positions_dict):
     calc_mot_axis = self._tagged["calc_mot"][0]
-    real_pos = positions_dict["calc_mot"] / 42
+    real_pos = positions_dict["calc_mot"] / 3.1415
 
     return {"real_mot": real_pos}
 ```
@@ -56,7 +56,7 @@ controller:
         -
           name: calc_mot
           tags: calc_mot
-          s_param: 3.1415
+
 ```
 
 example of usage:
@@ -69,6 +69,7 @@ Current Positions (user, dial)
 ----------  -------
    3.14150  1.00000
    3.14150  1.00000
+
 CYRIL [2]: mv(m1,2)
 CYRIL [3]: wa()
 Current Positions (user, dial)
@@ -80,7 +81,7 @@ Current Positions (user, dial)
 ```
 
 !!! note
-    For efficiency considerations, real motors can be moved as *grouped axes*
+    For efficiency considerations, real motors can be moved as *grouped axes*.
 
 ![Screenshot](img/axis_group_calc.svg)
 
@@ -88,4 +89,4 @@ Current Positions (user, dial)
 
 !!! note
     Real axis position will be emitted during a step scan on a calculated axis unless
-    "emit_real_position" is set to False in the controller configuration
\ No newline at end of file
+    "emit_real_position" is set to False in the controller configuration

doc/docs/dev_write_motctrl.md

@@ -20,11 +20,113 @@ some of them are needed only if implementation of these
 functionalities is wanted. In addition, some *custom commands* can be
 defined to implement very specific features of a motor controller.
 
+!!! note
+    About units management
+
+    * On the user point of view, axes are moved in **user units**,
+      whatever unit is used in the controller API
+    * On the programmer point of view, the BLISS plugin is dealing with
+      controller units (steps, microns, ...)
+    * The programmer should not have to deal with units conversions.
+    * see [motion axis / position](motion_axis.html#position) for more details.
+
 ---
 
 ## Example and skeleton of BLISS motor plugin
 
-* `bliss/controllers/motors/mockup.py` is an example of simulated motor
+Template for motor controller:
+
+```python
+
+from bliss.controllers.motor import Controller
+from bliss.comm.util import get_comm
+from bliss.common.axis import AxisState
+
+"""
+Bliss controller for XXX.
+"""
+
+class XXX(Controller):
+    def __init__(self, *args, **kwargs):
+        Controller.__init__(self, *args, **kwargs)
+
+    def initialize(self):
+        self.comm = get_comm(self.config)
+
+    def initialize_axis(self, axis):
+        """
+        Reads specific config
+        Adds specific methods
+        """
+        pass
+
+    def read_position(self, axis):
+        """
+        Returns position's setpoint or measured position.
+
+        Args:
+            - <axis> : bliss axis.
+            - [<measured>] : boolean : if True, function returns
+              measured position in ???
+        Returns:
+            - <position> : float : axis setpoint in ???.
+        """
+        raise NotImplementedError
+
+    def read_encoder(self, encoder):
+        raise NotImplementedError
+
+    def read_velocity(self, axis):
+        """
+        Args:
+            - <axis> : Bliss axis object.
+        Returns:
+            - <velocity> : float
+        """
+
+    def set_velocity(self, axis, new_velocity):
+        pass
+
+    def state(self, axis):
+        _ans = self.comm.write_read("state")
+        if _ans == "moving":
+            return AxisState("MOVING")
+        else:
+            return AxisState("READY")
+
+    def prepare_move(self, motion):
+        pass
+
+    def start_one(self, motion):
+        """
+        sdf
+        """
+        self.comm.write("MOVE")
+
+    def stop(self, axis):
+        # Halt a scan (not a movement ?)
+        self.comm.write("STOP")
+
+    def raw_write(self, axis, cmd):
+        self.comm.write(cmd)
+
+    def raw_write_read(self, axis, cmd):
+        return self.comm.write_readline(cmd)
+
+    def get_id(self, axis):
+        """
+        Returns firmware version.
+        """
+        return self.comm.write_readline("?VER")
+
+    def get_info(self, axis):
+        """
+        Returns information about controller as a string.
+        """
+        return 'IcePapMotorController - FW 2.71'
+```
+
+
 
 ## Minimal set of functions to implement
 
@@ -169,7 +271,7 @@ following methods (further detailed) are mandatory:
 
     Motion object: this object holds requested motion parameters:
     
-        * motion.axis:       axis to be moved
+        * motion.axis:       axis object to be moved
         * motion.target_pos: absolute motion target position (in controller units)
         * motion.delta:      corresponding relative motion delta (in controller units)
         * motion.backlash:   backlash (in controller units ?)
@@ -182,12 +284,27 @@ following methods (further detailed) are mandatory:
     * Called in a group move
         * `move(m1, 3, m2, 1)` is a group move
         * `move(m1, 3)` is a group move as well as `umvr()` `mvr()`
-        * `m1.move(3)` is a single move
+            * it uses `Group.move()`
+        * `m1.move(3)` is a single move (uses `Axis.move()`)
 
 * `stop_all(self, *motions)`
     * Must stop all movements defined in `motions`
     * Called on a `ctrl-c` during a group move
 
+
+!!! note
+    If `start_all()` is not defined, the movement is performed with `start_one()`
+    ```
+    def _start_one_controller_motions(self, controller, motions):
+        try:
+            controller.start_all(*motions)
+        except NotImplementedError:
+            for motion in motions:
+                controller.start_one(motion)
+    ```
+
+
+
 ### Jog motion
 A Jog motion is a movement controlled in velocity instead of being
 controller in position.
@@ -349,21 +466,3 @@ Example of custom command:
 by the created controller command.
 
 
-## NOTES
-
-* Steps per unit is in *unit-1* (1 per default)
-* Backlash is in *user_unit*
-* *user_unit* can be millimeter, micron, degree etc..
-* *encoder_steps*
-* developer of the plugin and units management
-    * On the user point of view, motors are driven in *user units*,
-      whatever unit is used in the controller API
-    * On the programmer point of view, the BLISS plugin is dealing with
-      controller units (steps, microns, ...)
-    * The programmer should not have to deal with units conversions.
-
-
-*`move(m1, 3)`: uses `Group.move()`
-*`m1.move(3)`: uses `Axis.move()`
-
-