Skip to content

Commit

Permalink
[docs] use Example admonition
Browse files Browse the repository at this point in the history
  • Loading branch information
@rrodgeur
rrodgeur committed Apr 23, 2024
1 parent 3dbed24 commit d2d30d9
Show file tree
Hide file tree
Showing 7 changed files with 284 additions and 275 deletions.
119 changes: 60 additions & 59 deletions docs/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,65 +21,66 @@ To use it, you need to add the line below in the `platformio.ini` file.
control_lib = https://github.com/owntech-foundation/control_library.git
```


## Using the `Pid()` _`Controller`_.

The use of the `Pid` is based on **3 steps**.

1. Object instanciation (declaration).
2. Initialisation.
3. Execution.

=== "1. Object and parameters instanciation."

For each _`Controller`_ like (`Pid`, `Rst`, `Pr`) we have to define a parameter structure.

We define constants used to initialize the parameter structure.
```c++
#include "pid.h"

static float32_t Ti = 7.5175e-5F;
static float32_t Td = 0.0F;
static float32_t N = 0.0F;
static float32_t upper_bound = 1.0F;
static float32_t lower_bound = 0.0F;
static float32_t Ts = 100.0e-6F;
```

We define the parameter structure. Each parameter is defined [here](../../structPidParams).
```c++
static PidParams pid_params(Ts, kp, Ti, Td, N, lower_bound, upper_bound);
```


We define the variable `pid` which is a `Pid` object.
```c++
static Pid pid;
```

=== "2. Initialization."

In the **`setup_routine()`** of the OwnTech Power API,
you must initialize the `Pid` with its parameters.

```c++
pid.init(pid_params);
```

=== "3. Execution."
In the **`loop_critical_task()`** you can call the method `calculateWithReturn()`
which have two arguments:

1. the reference
2. the measure.

```
new_command = pid.calculateWithReturn(reference, measurement);
```

`new_command` is the result of the pid calculation for one step.

!!! note
Remind that the `loop_critical_task()` is called at the sampling time you define and
must be equal to $T_s$.
To introduce the control library, we propose to implement a PID regulator.

!!!Example "The use of the `Pid` is based on **3 steps**."

1. Object instanciation (declaration).
2. Initialisation.
3. Execution.

=== "1. Object and parameters instanciation."

For each _`Controller`_ like (`Pid`, `Rst`, `Pr`) we have to define a parameter structure.
We define constants used to initialize the parameter structure.
```c++
#include "pid.h"
static float32_t Ti = 7.5175e-5F;
static float32_t Td = 0.0F;
static float32_t N = 0.0F;
static float32_t upper_bound = 1.0F;
static float32_t lower_bound = 0.0F;
static float32_t Ts = 100.0e-6F;
```
We define the parameter structure. Each parameter is defined [here](../../structPidParams).
```c++
static PidParams pid_params(Ts, kp, Ti, Td, N, lower_bound, upper_bound);
```
We define the variable `pid` which is a `Pid` object.
```c++
static Pid pid;
```
=== "2. Initialization."

In the **`setup_routine()`** of the OwnTech Power API,
you must initialize the `Pid` with its parameters.
```c++
pid.init(pid_params);
```
=== "3. Execution."
In the **`loop_critical_task()`** you can call the method `calculateWithReturn()`
which have two arguments:
1. the reference
2. the measure.
```
new_command = pid.calculateWithReturn(reference, measurement);
```
`new_command` is the result of the pid calculation for one step.

!!! note
Remind that the `loop_critical_task()` is called at the sampling time you define and
must be equal to $T_s$.

50 changes: 26 additions & 24 deletions docs/use-firstorder.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,38 +32,40 @@ where:

$$
\begin{align}
a_1 &= -exp\left(-\dfrac{-Ts}{\tau}\right) \\ \\
a_1 &= -exp\left(-\dfrac{Ts}{\tau}\right) \\ \\
b_1 &= 1 + a_1
\end{align}
$$

## Use
## Use.

=== "Declaration."
```cpp
#include "filters.h"
!!! Example "3 steps to use the first order filter"

const float32_t tau = 1e-3; // constant time
const float32_t Ts = 100e-6; // sampling time
myfilter = LowPassFirstOrderFilter(Ts, tau);
```
=== "1. Declaration."
```cpp
#include "filters.h"

=== "Initialisation."
Before to run, we advise to `reset` the filter, in the **`setup_routine()`** of the
OwnTech Power API.
const float32_t tau = 1e-3; // constant time
const float32_t Ts = 100e-6; // sampling time
myfilter = LowPassFirstOrderFilter(Ts, tau);
```

```
myfilter.reset();
```
=== "2. Initialisation."
Before to run, we advise to `reset` the filter, in the **`setup_routine()`** of the
OwnTech Power API.

=== "Execution."
In the **`loop_critical_task()`** you can call the method `calculateWithReturn()`.
```
myfilter.reset();
```

```cpp
signal_filtered = myfilter.calculateWithReturn(signal_to_filter);
```
=== "3. Execution."
In the **`loop_critical_task()`** you can call the method `calculateWithReturn()`.

It returns the data filtered.
!!! note
Remind that the `loop_critical_task()` is called at the sampling time you define and
must be equal to $T_s$.
```cpp
signal_filtered = myfilter.calculateWithReturn(signal_to_filter);
```

It returns the data filtered.
!!! note
Remind that the `loop_critical_task()` is called at the sampling time you define and
must be equal to $T_s$.
47 changes: 24 additions & 23 deletions docs/use-notchfilter.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,33 +35,34 @@ $$

## Use of the `NotchFilter` object.

=== "Declaration."
```cpp
#include "filters.h"
!!!Example "3 steps to use the notchfilter."
=== "1. Declaration."
```cpp
#include "filters.h"

const float32_t f0 = 50.0; // notch frequency [Hz]
const float32_t bandwidth = 5.0; // notch bandwidth [Hz]
const float32_t Ts = 100e-6; // sampling time [s]
myfilter = NotchFilter(Ts, f0, bandwidth);
```
const float32_t f0 = 50.0; // notch frequency [Hz]
const float32_t bandwidth = 5.0; // notch bandwidth [Hz]
const float32_t Ts = 100e-6; // sampling time [s]
myfilter = NotchFilter(Ts, f0, bandwidth);
```

=== "Initialisation."
Before to run, we advise to `reset` the filter, in the **`setup_routine()`** of the
OwnTech Power API.
=== "2. Initialisation."
Before to run, we advise to `reset` the filter, in the **`setup_routine()`** of the
OwnTech Power API.

```
myfilter.reset();
```
```
myfilter.reset();
```

=== "Execution."
In the **`loop_critical_task()`** you can call the method `calculateWithReturn()`.
=== "3. Execution."
In the **`loop_critical_task()`** you can call the method `calculateWithReturn()`.

```cpp
signal_filtered = myfilter.calculateWithReturn(signal_to_filter);
```
```cpp
signal_filtered = myfilter.calculateWithReturn(signal_to_filter);
```

It returns the data filtered.
It returns the data filtered.

!!! note
Remind that the `loop_critical_task()` is called at the sampling time you define and
must be equal to $T_s$.
!!! note
Remind that the `loop_critical_task()` is called at the sampling time you define and
must be equal to $T_s$.
77 changes: 39 additions & 38 deletions docs/use-pid.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,57 +51,58 @@ The use of the `Pid` is based on **3 steps**.
2. Initialisation.
3. Execution.

=== "1. Object and parameters instanciation."
!!!Example
=== "1. Object and parameters instanciation."

For each _`Controller`_ like (`Pid`, `Rst`, `Pr`) we have to define a parameter structure.
For each _`Controller`_ like (`Pid`, `Rst`, `Pr`) we have to define a parameter structure.

We define constants used to initialize the parameter structure.
```c++
#include "pid.h"
We define constants used to initialize the parameter structure.
```c++
#include "pid.h"

static float32_t Ti = 7.5175e-5F;
static float32_t Td = 0.0F;
static float32_t N = 0.0F;
static float32_t upper_bound = 1.0F;
static float32_t lower_bound = 0.0F;
static float32_t Ts = 100.0e-6F;
```
static float32_t Ti = 7.5175e-5F;
static float32_t Td = 0.0F;
static float32_t N = 0.0F;
static float32_t upper_bound = 1.0F;
static float32_t lower_bound = 0.0F;
static float32_t Ts = 100.0e-6F;
```

We define the parameter structure. Each parameter is defined [here](../../structPidParams).
```c++
static PidParams pid_params(Ts, kp, Ti, Td, N, lower_bound, upper_bound);
```
We define the parameter structure. Each parameter is defined [here](../../structPidParams).
```c++
static PidParams pid_params(Ts, kp, Ti, Td, N, lower_bound, upper_bound);
```


We define the variable `pid` which is a `Pid` object.
```c++
static Pid pid;
```
We define the variable `pid` which is a `Pid` object.
```c++
static Pid pid;
```

=== "2. Initialization."
In the **`setup_routine()`** of the OwnTech Power API,
you must initialize the `Pid` with its parameters.
=== "2. Initialization."
In the **`setup_routine()`** of the OwnTech Power API,
you must initialize the `Pid` with its parameters.

```c++
pid.init(pid_params);
```
```c++
pid.init(pid_params);
```

=== "3. Execution."
In the **`loop_critical_task()`** you can call the method `calculateWithReturn()`
which have two arguments:
=== "3. Execution."
In the **`loop_critical_task()`** you can call the method `calculateWithReturn()`
which have two arguments:

1. the reference
2. the measure.
1. the reference
2. the measure.

!!! note
Remind that the `loop_critical_task()` is called at the sampling time you define and
must be equal to $T_s$.
!!! note
Remind that the `loop_critical_task()` is called at the sampling time you define and
must be equal to $T_s$.

```
new_command = pid.calculateWithReturn(reference, measurement);
```
```
new_command = pid.calculateWithReturn(reference, measurement);
```

`new_command` is the result of the pid calculation for one step.
`new_command` is the result of the pid calculation for one step.

## Example
You can find a _pid_ use with the [buck voltage mode example](../../../examples/TWIST/DC_AC/grid_following) which
Expand Down
Loading

0 comments on commit d2d30d9

Please sign in to comment.