diff --git a/README-DE.md b/README-DE.md index a3bde4c..77a4fca 100644 --- a/README-DE.md +++ b/README-DE.md @@ -9,10 +9,29 @@ Die Diskussion findet im [Forum](https://www.akkudoktor.net/forum/diy-energie-op ## Installation Gute Install Anleitung: -https://meintechblog.de/2024/09/05/andreas-schmitz-joerg-installiert-mein-energieoptimierungssystem/ + Das Projekt erfordert Python 3.10 oder neuer. +## Konfiguration + +Dieses Projekt verwendet eine `config.json`, um Konfigurationseinstellungen zu verwalten. + +### Standardkonfiguration + +Eine Standardkonfigurationsdatei `default.config.json` wird bereitgestellt. Diese Datei enthält alle notwendigen Konfigurationsschlüssel mit ihren Standardwerten. + +### Benutzerdefinierte Konfiguration + +Benutzer können ein benutzerdefiniertes Konfigurationsverzeichnis angeben, indem sie die Umgebungsvariable `EOS_USER_DIR` setzen. + +- Wenn das im Verzeichnis angegebene `config.json` bereits existiert, wird diese Konfigurationsdatei verwendet. +- Wenn die Datei `config.json` im angegebenen Verzeichnis nicht existiert, wird die `default.config.json` in dieses Verzeichnis als `config.json` kopiert. + +### Konfigurationsupdates + +Wenn in der `config.json` Konfigurationsschlüssel fehlen oder von denen in `default.config.json` abweichen, werden sie automatisch aktualisiert, um den Standardschlüsseln zu entsprechen und sicherzustellen, dass alle erforderlichen Schlüssel vorhanden sind. + ### Schnellanleitung Unter Linux (Ubuntu/Debian): @@ -27,8 +46,7 @@ Unter Macos (benötigt [Homebrew](https://brew.sh)): brew install make ``` -Nun `config.py` anpassen. -Anschließend kann der Server über `make run` gestartet werden. +Der Server kann über `make run` gestartet werden. Eine vollständige Übersicht über die wichtigsten Kurzbefehle gibt `make help`. ### Ausführliche Anleitung @@ -39,6 +57,7 @@ Alle notwendigen Abhängigkeiten können über `pip` installiert werden. Klonen git clone https://github.com/Akkudoktor-EOS/EOS cd EOS ``` + Als Nächstes legen wir ein virtuelles Environment an. Es dient zur Ablage der Python-Abhängigkeiten, die wir später per `pip` installieren: @@ -70,20 +89,19 @@ source .venv/bin/activate Sollte `pip install` die mariadb-Abhängigkeit nicht installieren können, dann helfen folgende Kommandos: -* Debian/Ubuntu: `sudo apt-get install -y libmariadb-dev` -* Macos/Homebrew: `brew install mariadb-connector-c` +- Debian/Ubuntu: `sudo apt-get install -y libmariadb-dev` +- Macos/Homebrew: `brew install mariadb-connector-c` gefolgt von einem erneuten `pip install -r requirements.txt`. ## Nutzung -Einstellungen in `config.py` anpassen. Um das System zu nutzen, führen Sie `flask_server.py` aus, damit wird der Server gestartet - ```bash ./flask_server.py ``` + ## Klassen und Funktionalitäten In diesem Projekt werden verschiedene Klassen verwendet, um die Komponenten eines Energiesystems zu simulieren und zu optimieren. Jede Klasse repräsentiert einen spezifischen Aspekt des Systems, wie nachfolgend beschrieben: @@ -106,86 +124,95 @@ Diese Klassen arbeiten zusammen, um eine detaillierte Simulation und Optimierung Jede Klasse ist so gestaltet, dass sie leicht angepasst und erweitert werden kann, um zusätzliche Funktionen oder Verbesserungen zu integrieren. Beispielsweise können neue Methoden zur genaueren Modellierung des Verhaltens von PV-Anlagen oder Batteriespeichern hinzugefügt werden. Entwickler sind eingeladen, das System nach ihren Bedürfnissen zu modifizieren und zu erweitern. - # Input für den Flask Server (Stand 30.07.2024) + Beschreibt die Struktur und Datentypen des JSON-Objekts, das an den Flask-Server gesendet wird. Hier mit einem Prognosezeitraum von 48 Stunden! ## Felder des JSON-Objekts ### strompreis_euro_pro_wh + - **Beschreibung**: Ein Array von Floats, das den Strompreis in Euro pro Wattstunde für verschiedene Zeitintervalle darstellt. - **Typ**: Array - **Element-Typ**: Float - **Länge**: 48 ### gesamtlast + - **Beschreibung**: Ein Array von Floats, das die Gesamtlast (Verbrauch) in Watt für verschiedene Zeitintervalle darstellt. - **Typ**: Array - **Element-Typ**: Float - **Länge**: 48 ### pv_forecast + - **Beschreibung**: Ein Array von Floats, das die prognostizierte Photovoltaik-Leistung in Watt für verschiedene Zeitintervalle darstellt. - **Typ**: Array - **Element-Typ**: Float - **Länge**: 48 ### temperature_forecast + - **Beschreibung**: Ein Array von Floats, das die Temperaturvorhersage in Grad Celsius für verschiedene Zeitintervalle darstellt. - **Typ**: Array - **Element-Typ**: Float - **Länge**: 48 ### pv_soc + - **Beschreibung**: Ein Integer, der den Ladezustand des PV Akkus zum START der aktuellen Stunde anzeigt, das ist nicht der aktuelle!!! - **Typ**: Integer ### pv_akku_cap + - **Beschreibung**: Ein Integer, der die Kapazität des Photovoltaik-Akkus in Wattstunden darstellt. - **Typ**: Integer ### einspeiseverguetung_euro_pro_wh + - **Beschreibung**: Ein Float, der die Einspeisevergütung in Euro pro Wattstunde darstellt. - **Typ**: Float ### eauto_min_soc + - **Beschreibung**: Ein Integer, der den minimalen Ladezustand (State of Charge) des Elektroautos in Prozent darstellt. - **Typ**: Integer ### eauto_cap + - **Beschreibung**: Ein Integer, der die Kapazität des Elektroauto-Akkus in Wattstunden darstellt. - **Typ**: Integer ### eauto_charge_efficiency + - **Beschreibung**: Ein Float, der die Ladeeffizienz des Elektroautos darstellt. - **Typ**: Float ### eauto_charge_power + - **Beschreibung**: Ein Integer, der die Ladeleistung des Elektroautos in Watt darstellt. - **Typ**: Integer ### eauto_soc + - **Beschreibung**: Ein Integer, der den aktuellen Ladezustand (State of Charge) des Elektroautos in Prozent darstellt. - **Typ**: Integer ### start_solution + - **Beschreibung**: Kann null sein oder eine vorherige Lösung enthalten (wenn vorhanden). - **Typ**: null oder object ### haushaltsgeraet_wh + - **Beschreibung**: Ein Integer, der den Energieverbrauch eines Haushaltsgeräts in Wattstunden darstellt. - **Typ**: Integer ### haushaltsgeraet_dauer + - **Beschreibung**: Ein Integer, der die Dauer der Nutzung des Haushaltsgeräts in Stunden darstellt. - **Typ**: Integer - - - - - - # JSON-Output Beschreibung Dieses Dokument beschreibt die Struktur und Datentypen des JSON-Outputs, den der Flask-Server zurückgibt. Hier mit einem Prognosezeitraum von 48h @@ -193,12 +220,14 @@ Dieses Dokument beschreibt die Struktur und Datentypen des JSON-Outputs, den der ## Felder des JSON-Outputs (Stand 30.7.2024) ### discharge_hours_bin + - **Beschreibung**: Ein Array von Binärwerten (0 oder 1), das anzeigt, ob in einer bestimmten Stunde Energie entladen wird. - **Typ**: Array - **Element-Typ**: Integer (0 oder 1) - **Länge**: 48 ### eauto_obj + - **Beschreibung**: Ein Objekt, das Informationen über das Elektroauto enthält. - **charge_array**: Ein Array von Binärwerten (0 oder 1), das anzeigt, ob das Elektroauto in einer bestimmten Stunde geladen wird. - **Typ**: Array @@ -224,12 +253,14 @@ Dieses Dokument beschreibt die Struktur und Datentypen des JSON-Outputs, den der - **Typ**: Integer ### eautocharge_hours_float + - **Beschreibung**: Ein Array von Binärwerten (0 oder 1), das anzeigt, ob das Elektroauto in einer bestimmten Stunde geladen wird. - **Typ**: Array - **Element-Typ**: Integer (0 oder 1) - **Länge**: 48 ### result + - **Beschreibung**: Ein Objekt, das die Ergebnisse der Simulation enthält. - **E-Auto_SoC_pro_Stunde**: Ein Array von Floats, das den Ladezustand des Elektroautos für jede Stunde darstellt. - **Typ**: Array @@ -277,6 +308,7 @@ Dieses Dokument beschreibt die Struktur und Datentypen des JSON-Outputs, den der - **Länge**: 35 ### simulation_data + - **Beschreibung**: Ein Objekt, das die simulierten Daten enthält. - **E-Auto_SoC_pro_Stunde**: Ein Array von Floats, das den simulierten Ladezustand des Elektroautos pro Stunde darstellt. - **Typ**: Array @@ -324,10 +356,12 @@ Dieses Dokument beschreibt die Struktur und Datentypen des JSON-Outputs, den der - **Länge**: 35 ### spuelstart + - **Beschreibung**: Kann `null` sein oder ein Objekt enthalten, das den Spülstart darstellt (wenn vorhanden). - **Typ**: null oder object ### start_solution + - **Beschreibung**: Ein Array von Binärwerten (0 oder 1), das eine mögliche Startlösung für die Simulation darstellt. - **Typ**: Array - **Element-Typ**: Integer (0 oder 1) diff --git a/README.md b/README.md index 45422a3..9db2778 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,29 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). ## Installation Good installation guide: -https://meintechblog.de/2024/09/05/andreas-schmitz-joerg-installiert-mein-energieoptimierungssystem/ + The project requires Python 3.10 or newer. +## Configuration + +This project uses a `config.json` file to manage configuration settings. + +### Default Configuration + +A default configuration file `default.config.json` is provided. This file contains all the necessary configuration keys with their default values. + +### Custom Configuration + +Users can specify a custom configuration directory by setting the environment variable `EOS_USER_DIR`. + +- If the directory specified by `EOS_USER_DIR` contains an existing `config.json` file, the application will use this configuration file. +- If the `config.json` file does not exist in the specified directory, the `default.config.json` file will be copied to the directory as `config.json`. + +### Configuration Updates + +If the configuration keys in the `config.json` file are missing or different from those in `default.config.json`, they will be automatically updated to match the default settings, ensuring that all required keys are present. + ### Quick Start Guide On Linux (Ubuntu/Debian): @@ -27,8 +46,7 @@ On MacOS (requires [Homebrew](https://brew.sh)): brew install make ``` -Next, adjust `config.py`. -The server can then be started with `make run`. A full overview of the main shortcuts is given by `make help`. +The server can be started with `make run`. A full overview of the main shortcuts is given by `make help`. ### Detailed Instructions @@ -56,23 +74,24 @@ To always use the Python version from the virtual environment, you should activa ```bash source .venv/bin/activate ``` + (for Bash users, the default under Linux) or ```zsh . .venv/bin/activate ``` + (if using zsh, primarily for MacOS users). If `pip install` fails to install the mariadb dependency, the following commands may help: -* Debian/Ubuntu: `sudo apt-get install -y libmariadb-dev` -* MacOS/Homebrew: `brew install mariadb-connector-c` +- Debian/Ubuntu: `sudo apt-get install -y libmariadb-dev` +- MacOS/Homebrew: `brew install mariadb-connector-c` Followed by a renewed `pip install -r requirements.txt`. ## Usage -Adjust `config.py`. To use the system, run `flask_server.py`, which starts the server: ```bash @@ -101,7 +120,6 @@ These classes work together to enable a detailed simulation and optimization of Each class is designed to be easily customized and extended to integrate additional functions or improvements. For example, new methods can be added for more accurate modeling of PV system or battery behavior. Developers are invited to modify and extend the system according to their needs. - # Input for the Flask Server (as of 30.07.2024) Describes the structure and data types of the JSON object sent to the Flask server, with a forecast period of 48 hours. @@ -109,75 +127,88 @@ Describes the structure and data types of the JSON object sent to the Flask serv ## JSON Object Fields ### `strompreis_euro_pro_wh` + - **Description**: An array of floats representing the electricity price in euros per watt-hour for different time intervals. - **Type**: Array - **Element Type**: Float - **Length**: 48 ### `gesamtlast` + - **Description**: An array of floats representing the total load (consumption) in watts for different time intervals. - **Type**: Array - **Element Type**: Float - **Length**: 48 ### `pv_forecast` + - **Description**: An array of floats representing the forecasted photovoltaic output in watts for different time intervals. - **Type**: Array - **Element Type**: Float - **Length**: 48 ### `temperature_forecast` + - **Description**: An array of floats representing the temperature forecast in degrees Celsius for different time intervals. - **Type**: Array - **Element Type**: Float - **Length**: 48 ### `pv_soc` + - **Description**: An integer representing the state of charge of the PV battery at the **start** of the current hour (not the current state). - **Type**: Integer ### `pv_akku_cap` + - **Description**: An integer representing the capacity of the photovoltaic battery in watt-hours. - **Type**: Integer ### `einspeiseverguetung_euro_pro_wh` + - **Description**: A float representing the feed-in compensation in euros per watt-hour. - **Type**: Float ### `eauto_min_soc` + - **Description**: An integer representing the minimum state of charge (SOC) of the electric vehicle in percentage. - **Type**: Integer ### `eauto_cap` + - **Description**: An integer representing the capacity of the electric vehicle battery in watt-hours. - **Type**: Integer ### `eauto_charge_efficiency` + - **Description**: A float representing the charging efficiency of the electric vehicle. - **Type**: Float ### `eauto_charge_power` + - **Description**: An integer representing the charging power of the electric vehicle in watts. - **Type**: Integer ### `eauto_soc` + - **Description**: An integer representing the current state of charge (SOC) of the electric vehicle in percentage. - **Type**: Integer ### `start_solution` + - **Description**: Can be `null` or contain a previous solution (if available). - **Type**: `null` or object ### `haushaltsgeraet_wh` + - **Description**: An integer representing the energy consumption of a household device in watt-hours. - **Type**: Integer ### `haushaltsgeraet_dauer` + - **Description**: An integer representing the usage duration of a household device in hours. - **Type**: Integer - - # JSON Output Description This document describes the structure and data types of the JSON output returned by the Flask server, with a forecast period of 48 hours. @@ -187,9 +218,11 @@ This document describes the structure and data types of the JSON output returned ### Explanation of the Output Fields #### 1. **discharge_hours_bin** + An array that indicates for each hour of the forecast period (in this example, 48 hours) whether energy is discharged from the battery or not. The values are either `0` (no discharge) or `1` (discharge). #### 2. **eauto_obj** + This object contains information related to the electric vehicle and its charging and discharging behavior: - **charge_array**: Indicates for each hour whether the EV is charging (`0` for no charging, `1` for charging). @@ -202,6 +235,7 @@ This object contains information related to the electric vehicle and its chargin - **start_soc_prozent**: The state of charge of the battery in percentage at the start of the simulation. #### 3. **result** + This object contains the results of the simulation and provides insights into various parameters over the entire forecast period: - **E-Auto_SoC_pro_Stunde**: The state of charge of the EV for each hour.