encoder doc

bliss/common/axis.py

@@ -662,7 +662,7 @@ class Axis(AliasMixin, LogMixin):
 
     @property
     def tolerance(self):
-        """Current tolerance in dial units (:obj:`float`)"""
+        """Current Axis tolerance in dial units (:obj:`float`)"""
         return self.config.get("tolerance", float, 1e-4)
 
     @property

bliss/common/encoder.py

@@ -45,6 +45,9 @@ class Encoder(object):
 
     @property
     def tolerance(self):
+        """
+        Returns Encoder tolerance in user units.
+        """
         return self.config.get("tolerance", float, 0)
 
     @lazy_init

doc/docs/config_encoder.md

+
+For encoder usage and info for developers, see: [Encoder
+Usage](motion_encoder.md)
+
+An encoder can be defined on its own, or can be associated to an axis
+to add some extra checks before and after a movement.
+
+## Example of standalone encoder
+
+```
+controller:
+  class: icepap
+  host: iceid42
+  encoders:
+      - name: m4enc
+        address: 25
+        steps_per_unit: 1e5
+```
+
+## Example of axis encoder
+
+An encoder associated to an Axis is defined in `controller` section
+and referenced in `axes` section.
+
+
+```yaml
+controller:
+  class: icepap
+  host: iceid42
+  axes:
+      - name: m4mot
+        address: 1
+        steps_per_unit: 817
+        velocity: 0.3
+        acceleration: 3
+        tolerance: 0.001
+        encoder: $m4enc
+  encoders:
+      - name: m4enc
+        address: 25
+        steps_per_unit: 1e5
+```
+
+
+## configuration parameters
+
+* `name`
+    * Encoder object's name.
+* `steps_per_unit`
+    * This value is used to define the conversion factor between
+    encoder steps value and real position in user unit. It must be
+    accurate to allow comparison between position required by user and
+    real position.
+* `tolerance`
+    * Value in **user_units**.
+    * At end of a movement, the encoder value is read and compared to
+    the target position of the movement. If the difference is outside
+    the limit fixed by the **encoder tolerance** (beware to not
+    confuse with Axis tolerance), an exception is raised with message:
+    `"didn't reach final position"`
+
+
+## Icepap encoder
+
+For specific details about icepap encoders, see
+[Icepap Encoder Configuration](config_icepap.md#encoder-configuration)
+
+

doc/docs/dev_write_motctrl.md

@@ -421,7 +421,7 @@ Methods to implement in the controller:
 * `set_encoder(self, encoder, new_value)`
     * Must set the encoder position to ``new_value``
     * ``new_value`` is in encoder_steps
-    * Called by `encoder.set(new_value)` 
+    * Called by `encoder.set(new_value)`
 
 ### Information methods
 * `get_id(self, axis)`

doc/docs/motion_axis.md

@@ -453,6 +453,27 @@ stop a movement:
     - send a stop command to the controller
     - the move loop will exit
 
+
+*Before* a movement, the position of the axis is read and compared to
+the BLISS Axis internal position. In case of difference outside the
+limit fixed by **Axis tolerance** configuration parameter, an
+exception is raised with message:
+
+```
+"discrepancy between dial (0.123) and controller position (0.100), aborting"
+```
+
+*After* a movement, if an [encoder is associated to the
+axis](motion_encoder.md), the encoder position is read and compared to
+the target position of the movement. In case of difference outside the
+limit fixed by **Encoder tolerance**, an exception is raised with
+message:
+
+```
+"didn't reach final position"
+```
+
+
 ### Move loop
 
 ![Move procedure](img/move_loop.svg)

doc/docs/motion_encoder.md

+
+# Encoder
+
+An encoder (`bliss.common.encoder.Encoder` object) can be defined on
+its own, or can be associated to an axis to add some extra checks
+before and after a movement.
+
+* For configuration, see: [Encoder Configuration](config_encoder.md)
+* For specific details about icepap encoders, see
+[Icepap Encoder Configuration](config_icepap.md#encoder-configuration)
+
+!!! note
+    There are 2 `tolerance` parameters in configuration: one for
+    `Axis` and the other for `Encoder`.
+
+If an encoder is associated to the axis:
+
+* *after* a movement, the encoder position is read and compared to the
+  target position of the movement. In case of difference outside the
+  limit fixed by **Encoder tolerance**, an exception is raised with
+  message: `"didn't reach final position"`
+
+* the method `measured_position()` uses `encoder.read()` to calculate
+  the value returned *in user units*.
+
+!!! note
+    This `measured_position()` method is used in particular by
+    TangoDS and can be easily compared to the target position with
+    atk-moni for tuning purposes.
+
+* `dial_measured_position()` returns the dial encoder position *in
+  user units*.
+
+
+An encoder can be used to define events to trig on special positions.
+See: [Writing a motor controller -
+position-triggers](dev_write_motctrl.md#position-triggers)
+
+
+## development
+
+For details on how to implement an encoder in a new motor controller,
+see [Writing a motor controller / Encoder
+methods](dev_write_motctrl.md#encoder-methods)
+

doc/mkdocs.yml

@@ -34,6 +34,7 @@ nav:
                             - Smaract: config_smaract.md
                             - Symetrie Hexapod: config_shexapod.md
                             - Vscanner: config_vscanner.md
+                      - Encoders: config_encoder.md
                       - Slits: config_slits.md
                       - Energy and Wavelength: config_enwl.md
                       - 2D detectors (Lima): config_lima.md

tests/scans/test_publishing.py

@@ -100,7 +100,7 @@ def test_interrupted_scan(session, redis_data_conn, scan_tmpdir):
     scan_saving.base_path = str(scan_tmpdir)
     parent = scan_saving.get_parent_node()
     m = getattr(setup_globals, "roby")
-    m.velocity = 10
+    m.velocity = 2
     diode = getattr(setup_globals, "diode")
 
     chain = AcquisitionChain()