Commit 67f893a6 authored by Lucas Felix's avatar Lucas Felix
Browse files

Add closed loop documentation

parent 5263b067
Pipeline #75106 passed with stages
in 139 minutes and 13 seconds
......@@ -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
......
# 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.
......@@ -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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment