Skip to content

Commit 0e66ada

Browse files
matthias-wende-frequenzmatthias-wende-frequenz
committed
Add tutorials
Signed-off-by: Matthias Wende <[email protected]>
1 parent d3814a7 commit 0e66ada

File tree

3 files changed

+233
-0
lines changed

3 files changed

+233
-0
lines changed

‎docs/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
* [Home](index.md)
22
* [API Reference](reference/)
3+
* [Tutorials](tutorials/)
34
* [Contributing](CONTRIBUTING.md)

‎docs/tutorials/tutorials_first_app.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Build Your First App
2+
3+
## Prerequisites
4+
5+
1. Python installed on your system.
6+
2. Access to a microgrid system supported by the `frequenz.sdk` or you can use
7+
the sandbox.
8+
3. Basic knowledge of microgrid concepts.
9+
4. Familiarity with
10+
[Channels](https://frequenz-floss.github.io/frequenz-channels-python/latest/).
11+
12+
## Set up your Frequenz development environment
13+
14+
### Setting up a Python environment
15+
16+
Before you begin, make sure you have a working Python environment. You can
17+
create a virtual environment to manage dependencies.
18+
19+
```bash
20+
# Create a virtual environment (optional but recommended)
21+
python -m venv frequenz_sdk_env
22+
source frequenz_sdk_env/bin/activate
23+
# On Windows, use 'frequenz_sdk_env\Scripts\activate'
24+
```
25+
26+
### Install the Frequenz SDK
27+
28+
Install the Frequenz SDK. For this tutorial, this is all you need, but in the
29+
future, you might also need additional packages based on your project
30+
requirements.
31+
32+
```bash
33+
pip install frequenz-sdk # Install the Frequenz SDK
34+
```
35+
36+
## Create a project
37+
38+
### Create a Python file
39+
40+
You can start by simply creating a Python script (e.g., `pv_optimization.py`)
41+
using your favorite text editor.
42+
43+
### Use Frequenz repo config
44+
45+
As an alternative and for larger projects, it's recommended to set up the
46+
project using the [Frequenz repo
47+
configuration](https://frequenz-floss.github.io/frequenz-repo-config-python/latest).
48+
49+
## Import necessary modules
50+
51+
You can now open the app's main file and start adding content. Begin by
52+
importing the necessary libraries.
53+
54+
```python
55+
import asyncio
56+
import os
57+
58+
from datetime import timedelta
59+
from frequenz.sdk import microgrid
60+
from frequenz.sdk.actor import ResamplerConfig
61+
```
62+
63+
## Create the application skeleton
64+
65+
The main logic of your application will run within an async function. Let's
66+
create a skeleton that contains all the necessary code to initialize a
67+
microgrid.
68+
69+
```python
70+
async def run() -> None:
71+
# Configuration from environment variables
72+
microgrid_host = os.getenv(
73+
"MICROGRID_HOST", default="microgrid.sandbox.api.frequenz.io"
74+
)
75+
microgrid_port = int(os.getenv("MICROGRID_PORT", default="62060"))
76+
77+
# Initialize the microgrid
78+
await microgrid.initialize(
79+
microgrid_host,
80+
microgrid_port,
81+
ResamplerConfig(resampling_period=timedelta(seconds=1)),
82+
)
83+
84+
# Define your application logic here
85+
# ...
86+
```
87+
88+
## Define the `main()` function
89+
90+
Create a `main()` function that will set up and run the `run()` function using
91+
asyncio.
92+
93+
```python
94+
def main() -> None:
95+
asyncio.run(run())
96+
97+
if __name__ == "__main__":
98+
main()
99+
```
100+
101+
## Implement the application logic
102+
103+
Inside the `run()` function, implement the core logic of your application. This
104+
will include creating receivers for data streams, processing the data, making
105+
decisions, and eventually sending control messages to the microgrid system. We
106+
will cover more details in the following tutorials. For now, let's simply read
107+
the power measurements from the microgrid's grid meter and print them on the
108+
screen. The grid meter is a meter that is directly connected to the grid
109+
connection point.
110+
111+
```python
112+
async def run() -> None:
113+
# Configuration from environment variables
114+
...
115+
116+
# Define your application logic here
117+
grid_meter = microgrid.logical_meter().grid_power.new_receiver()
118+
119+
async for power in grid_meter:
120+
print(power.value)
121+
```
122+
123+
## Run your application
124+
125+
You're now ready to run your application. When working on an existing
126+
microgrid, make sure to set the necessary environment variables, i.e.,
127+
`MICROGRID_HOST` and `MICROGRID_PORT`, before running the script.
128+
129+
```bash
130+
# Example usage with environment variables
131+
export MICROGRID_HOST="your_microgrid_host"
132+
export MICROGRID_PORT=62060
133+
134+
python pv_optimization.py
135+
```

‎docs/tutorials/tutorials_second.md

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Second Tutorial
2+
3+
## Prerequisites
4+
5+
1. Python installed on your system.
6+
2. Access to a microgrid system that is supported by the `frequenz.sdk` or you can use the sandbox.
7+
3. Basic knowledge of microgrid concepts.
8+
4. Being familiar with [Channels](https://frequenz-floss.github.io/frequenz-channels-python/latest/)
9+
10+
## Set Up Your Development Environment
11+
12+
Before you begin, make sure you have a working Python environment. You can create a virtual environment to manage dependencies.
13+
14+
```bash
15+
# Create a virtual environment (optional but recommended)
16+
python -m venv frequenz_sdk_env
17+
source frequenz_sdk_env/bin/activate # On Windows, use 'frequenz_sdk_env\Scripts\activate'
18+
19+
## Install the Frequenz SDK
20+
21+
Install the Frequenz SDK.
22+
For this tutorial this is all you need but in the future you might also need additional
23+
packages based on your project requirements.
24+
25+
```bash
26+
pip install frequenz-sdk # Install the frequenz SDK
27+
```
28+
29+
## Create a New Python Script
30+
31+
Create a new Python script (e.g., `pv_optimization.py`) using your favorite editor.
32+
33+
## Import Necessary Modules
34+
35+
```python
36+
import asyncio
37+
import os
38+
39+
from datetime import timedelta
40+
from frequenz.sdk import microgrid
41+
from frequenz.sdk.actor import ResamplerConfig
42+
from frequenz.sdk.timeseries import Power
43+
```
44+
45+
## Create the application skeleton
46+
47+
The main logic of your application will run within an async function. Let's create
48+
a skeleton that contains all the necassery code to initialize a microgrid.
49+
50+
```python
51+
async def run() -> None:
52+
# Configuration from environment variables
53+
microgrid_host = os.getenv(
54+
"MICROGRID_HOST", default="microgrid.sandbox.api.frequenz.io"
55+
)
56+
microgrid_port = int(os.getenv("MICROGRID_PORT", default="62060"))
57+
58+
# Initialize the microgrid
59+
await microgrid.initialize(
60+
microgrid_host,
61+
microgrid_port,
62+
ResamplerConfig(resampling_period=timedelta(seconds=1)),
63+
)
64+
65+
# Define your application logic here
66+
# ...
67+
```
68+
## Define the main() Function
69+
70+
Create a main() function that will set up and run the `run()` function using asyncio.
71+
72+
73+
```python
74+
def main() -> None:
75+
asyncio.run(run())
76+
77+
if __name__ == "__main__":
78+
main()
79+
```
80+
81+
## Implement the Application Logic
82+
83+
Inside the run() function, implement the core logic of your application. This will include creating receivers, processing data, making decisions, and interacting with the microgrid system. Refer to your existing code for guidance.
84+
85+
## Run Your Application
86+
87+
You're now ready to run your application. When working on an existing microgrid, make
88+
sure to set the necessary environment variables, i.e. `MICROGRID_HOST`,
89+
`MICROGRID_PORT` before running the script.
90+
91+
```bash
92+
# Example usage with environment variables
93+
export MICROGRID_HOST="your_microgrid_host"
94+
export MICROGRID_PORT=62060
95+
96+
python pv_optimization.py
97+
```

0 commit comments

Comments
 (0)