Add closed loop documentation

doc/docs/motion_axis.md

@@ -33,6 +33,7 @@ the `Axis` constructor.
 Parameter name                              |  Required | Setting?  | Type   | Description
 ------------------------------------------- |-----------|-----------|--------|------------
 [name](motion_axis.md#name)                 |  yes      | no        | string | An unique name to identify the `Axis` object
+[unit](motion_axis.md#unit)                 |  no       | no        | string | *Informative only* - Unit (for steps per unit), e.g. mm, deg, rad, etc.
 [steps_per_unit](motion_axis.md#position)   |  yes      | no        | float  | Number of steps to send to the controller to make a *move of 1 unit* (eg. 1 mm, 1 rad)
 [velocity](motion_axis.md#velocity)         |  yes      | yes       | float  | Nominal axis velocity in *units.s<sup>-1</sup>*
 [acceleration](motion_axis.md#acceleration) |  yes      | yes       | float  | Nominal acceleration value in *units.s<sup>-2</sup>*
@@ -42,7 +43,7 @@ Parameter name                              |  Required | Setting?  | Type   | D
 [backlash](motion_axis.md#backlash)         |  no       | yes       | float  | Axis backlash in user units ; *defaults to 0*
 [tolerance](motion_axis.md#tolerance)       |  no       | no        | float  | Accepted discrepancy between controller position and last known axis dial position when starting a move ; *defaults to 1E-4*
 [encoder](motion_axis.md#encoder)           |  no       | no        | string | Name of an existing **Encoder** object linked with this axis
-[unit](motion_axis.md#unit)                 | no        | no        | string | *Informative only* - Unit (for steps per unit), e.g. mm, deg, rad, etc.
+[closed loop](motion_axis.md#closed_loop)   |  no       | -         | dict   | Axis subsection to configure closed loop (see [closed loop](motion_closed_loop.md))
 
 !!! note
     Motor controllers with extra features may require more parameters. See the
@@ -426,6 +427,8 @@ Default value is 1E-4
 
 ### encoder
 
+Encoders are standalone objects which can be referred by axes.
+Thus they have a dedicated section here: [Encoder](motion_encoder.md).
 
 ### Axis state
 

doc/docs/motion_closed_loop.md

+# Closed loop
+
+Every axis can define a closed loop, provided they are built on top of a controller which supports it.
+At the moment, only hardware closed loops are supported.
+
+
+## Configuration
+
+A closed loop is defined by creating a **closed_loop** section under an axis.
+
+The section should always contain a **state**.
+Then, each type of motor controller requires a specific set of parameters, known as
+[controller requirements](motion_closed_loop.md#controller-requirements).
+
+```yaml
+controller:
+  - class: Mockup
+    module: mockup
+    axes:
+      - name: servo1
+        steps_per_unit: 1000
+        velocity_high_limit: 500
+        velocity_low_limit: 10
+        velocity: 100
+        acceleration: 200
+        low_limit: -1000
+        high_limit: 1000
+        unit: mm
+        closed_loop:
+            state: on
+            kp: 0.1 # <─┬ controller specific
+            ki: 0.2 # <─┤
+            kd: 0.3 # <─┘
+```
+
+### Controller requirements
+
+Each motor controller provides the list of parameters it needs to instantiate a closed loop.
+One should refer to the particular controller documentation to find the list and description
+for these parameters.
+
+When a parameter is missing, an error provides details on what is missing:
+```
+!!! === RuntimeError: For device servo1:closed_loop configuration must
+contains {'kp', 'ki', 'kd'}. === !!! ( for more details type cmd 'last_error' )
+```
+
+Alternatively, it is possible to ask the controller directly with *get_closed_loop_requirements()*:
+```python
+TEST_SESSION [1]: servo1.controller.get_closed_loop_requirements()
+         Out [1]: ['kp', 'ki', 'kd']
+```
+
+## Usage
+
+Closed loops are always related to an axis, thus they have no name and are located under their axis.
+
+```python
+TEST_SESSION [2]: servo1.closed_loop
+         Out [2]: CLOSED LOOP:
+                       state: ON
+                       kp: 0.1
+                       ki: 0.2
+                       kd: 0.3
+```
+
+They can be turned on and off with the so-named functions. The controller specific parameters
+are also accessible this way.
+```python
+TEST_SESSION [3]: servo1.closed_loop.off()
+TEST_SESSION [4]: servo1.closed_loop.ki = 0.75
+TEST_SESSION [5]: servo1.closed_loop
+         Out [5]: CLOSED LOOP:
+                       state: OFF
+                       kp: 0.1
+                       ki: 0.75
+                       kd: 0.3
+```
+
+**Note:** Every parameters (state included) are stored in redis, consequently the closed loop will always
+start in the same state it has been left in.

doc/mkdocs.yml

@@ -173,6 +173,7 @@ nav:
         - Motion:
                 - Axis: motion_axis.md
                 - Encoder: motion_encoder.md
+                - Closed loop: motion_closed_loop.md
                 - Soft Axis: motion_softaxis.md
                 - Hook: motion_hook.md
                 - Stack: motion_stack.md