fix: automatic optimization (#596)

This fix implements the long term goal to have the EOS server run optimization (or energy management) on regular intervals automatically. Thus clients can request the current energy management plan at any time and it is updated on regular intervals without interaction by the client. This fix started out to "only" make automatic optimization (or energy management) runs working. It turned out there are several endpoints that in some way update predictions or run the optimization. To lock against such concurrent attempts the code had to be refactored to allow control of execution. During refactoring it became clear that some classes and files are named without a proper reference to their usage. Thus not only refactoring but also renaming became necessary. The names are still not the best, but I hope they are more intuitive. The fix includes several bug fixes that are not directly related to the automatic optimization but are necessary to keep EOS running properly to do the automatic optimization and to test and document the changes. This is a breaking change as the configuration structure changed once again and the server API was also enhanced and streamlined. The server API that is used by Andreas and Jörg in their videos has not changed. * fix: automatic optimization Allow optimization to automatically run on configured intervals gathering all optimization parameters from configuration and predictions. The automatic run can be configured to only run prediction updates skipping the optimization. Extend documentaion to also cover automatic optimization. Lock automatic runs against runs initiated by the /optimize or other endpoints. Provide new endpoints to retrieve the energy management plan and the genetic solution of the latest automatic optimization run. Offload energy management to thread pool executor to keep the app more responsive during the CPU heavy optimization run. * fix: EOS servers recognize environment variables on startup Force initialisation of EOS configuration on server startup to assure all sources of EOS configuration are properly set up and read. Adapt server tests and configuration tests to also test for environment variable configuration. * fix: Remove 0.0.0.0 to localhost translation under Windows EOS imposed a 0.0.0.0 to localhost translation under Windows for convenience. This caused some trouble in user configurations. Now, as the default IP address configuration is 127.0.0.1, the user is responsible for to set up the correct Windows compliant IP address. * fix: allow names for hosts additional to IP addresses * fix: access pydantic model fields by class Access by instance is deprecated. * fix: down sampling key_to_array * fix: make cache clear endpoint clear all cache files Make /v1/admin/cache/clear clear all cache files. Before it only cleared expired cache files by default. Add new endpoint /v1/admin/clear-expired to only clear expired cache files. * fix: timezonefinder returns Europe/Paris instead of Europe/Berlin timezonefinder 8.10 got more inaccurate for timezones in europe as there is a common timezone. Use new package tzfpy instead which is still returning Europe/Berlin if you are in Germany. tzfpy also claims to be faster than timezonefinder. * fix: provider settings configuration Provider configuration used to be a union holding the settings for several providers. Pydantic union handling does not always find the correct type for a provider setting. This led to exceptions in specific configurations. Now provider settings are explicit comfiguration items for each possible provider. This is a breaking change as the configuration structure was changed. * fix: ClearOutside weather prediction irradiance calculation Pvlib needs a pandas time index. Convert time index. * fix: test config file priority Do not use config_eos fixture as this fixture already creates a config file. * fix: optimization sample request documentation Provide all data in documentation of optimization sample request. * fix: gitlint blocking pip dependency resolution Replace gitlint by commitizen. Gitlint is not actively maintained anymore. Gitlint dependencies blocked pip from dependency resolution. * fix: sync pre-commit config to actual dependency requirements .pre-commit-config.yaml was out of sync, also requirements-dev.txt. * fix: missing babel in requirements.txt Add babel to requirements.txt * feat: setup default device configuration for automatic optimization In case the parameters for automatic optimization are not fully defined a default configuration is setup to allow the automatic energy management run. The default configuration may help the user to correctly define the device configuration. * feat: allow configuration of genetic algorithm parameters The genetic algorithm parameters for number of individuals, number of generations, the seed and penalty function parameters are now avaliable as configuration options. * feat: allow configuration of home appliance time windows The time windows a home appliance is allowed to run are now configurable by the configuration (for /v1 API) and also by the home appliance parameters (for the classic /optimize API). If there is no such configuration the time window defaults to optimization hours, which was the standard before the change. Documentation on how to configure time windows is added. * feat: standardize mesaurement keys for battery/ ev SoC measurements The standardized measurement keys to report battery SoC to the device simulations can now be retrieved from the device configuration as a read-only config option. * feat: feed in tariff prediction Add feed in tarif predictions needed for automatic optimization. The feed in tariff can be retrieved as fixed feed in tarif or can be imported. Also add tests for the different feed in tariff providers. Extend documentation to cover the feed in tariff providers. * feat: add energy management plan based on S2 standard instructions EOS can generate an energy management plan as a list of simple instructions. May be retrieved by the /v1/energy-management/plan endpoint. The instructions loosely follow the S2 energy management standard. * feat: make measurement keys configurable by EOS configuration. The fixed measurement keys are replaced by configurable measurement keys. * feat: make pendulum DateTime, Date, Duration types usable for pydantic models Use pydantic_extra_types.pendulum_dt to get pydantic pendulum types. Types are added to the datetimeutil utility. Remove custom made pendulum adaptations from EOS pydantic module. Make EOS modules use the pydantic pendulum types managed by the datetimeutil module instead of the core pendulum types. * feat: Add Time, TimeWindow, TimeWindowSequence and to_time to datetimeutil. The time windows are are added to support home appliance time window configuration. All time classes are also pydantic models. Time is the base class for time definition derived from pendulum.Time. * feat: Extend DataRecord by configurable field like data. Configurable field like data was added to support the configuration of measurement records. * feat: Add additional information to health information Version information is added to the health endpoints of eos and eosDash. The start time of the last optimization and the latest run time of the energy management is added to the EOS health information. * feat: add pydantic merge model tests * feat: add plan tab to EOSdash The plan tab displays the current energy management instructions. * feat: add predictions tab to EOSdash The predictions tab displays the current predictions. * feat: add cache management to EOSdash admin tab The admin tab is extended by a section for cache management. It allows to clear the cache. * feat: add about tab to EOSdash The about tab resembles the former hello tab and provides extra information. * feat: Adapt changelog and prepare for release management Release management using commitizen is added. The changelog file is adapted and teh changelog and a description for release management is added in the documentation. * feat(doc): Improve install and devlopment documentation Provide a more concise installation description in Readme.md and add extra installation page and development page to documentation. * chore: Use memory cache for interpolation instead of dict in inverter Decorate calculate_self_consumption() with @cachemethod_until_update to cache results in memory during an energy management/ optimization run. Replacement of dict type caching in inverter is now possible because all optimization runs are properly locked and the memory cache CacheUntilUpdateStore is properly cleared at the start of any energy management/ optimization operation. * chore: refactor genetic Refactor the genetic algorithm modules for enhanced module structure and better readability. Removed unnecessary and overcomplex devices singleton. Also split devices configuration from genetic algorithm parameters to allow further development independently from genetic algorithm parameter format. Move charge rates configuration for electric vehicles from optimization to devices configuration to allow to have different charge rates for different cars in the future. * chore: Rename memory cache to CacheEnergyManagementStore The name better resembles the task of the cache to chache function and method results for an energy management run. Also the decorator functions are renamed accordingly: cachemethod_energy_management, cache_energy_management * chore: use class properties for config/ems/prediction mixin classes * chore: skip debug logs from mathplotlib Mathplotlib is very noisy in debug mode. * chore: automatically sync bokeh js to bokeh python package bokeh was updated to 3.8.0, make JS CDN automatically follow the package version. * chore: rename hello.py to about.py Make hello.py the adapted EOSdash about page. * chore: remove demo page from EOSdash As no the plan and prediction pages are working without configuration, the demo page is no longer necessary * chore: split test_server.py for system test Split test_server.py to create explicit test_system.py for system tests. * chore: move doc utils to generate_config_md.py The doc utils are only used in scripts/generate_config_md.py. Move it there to attribute for strong cohesion. * chore: improve pydantic merge model documentation * chore: remove pendulum warning from readme * chore: remove GitHub discussions from contributing documentation Github discussions is to be replaced by Akkudoktor.net. * chore(release): bump version to 0.1.0+dev for development * build(deps): bump fastapi[standard] from 0.115.14 to 0.117.1 bump fastapi and make coverage version (for pytest-cov) explicit to avoid pip break. * build(deps): bump uvicorn from 0.36.0 to 0.37.0 BREAKING CHANGE: EOS configuration changed. V1 API changed. - The available_charge_rates_percent configuration is removed from optimization. Use the new charge_rate configuration for the electric vehicle - Optimization configuration parameter hours renamed to horizon_hours - Device configuration now has to provide the number of devices and device properties per device. - Specific prediction provider configuration to be provided by explicit configuration item (no union for all providers). - Measurement keys to be provided as a list. - New feed in tariff providers have to be configured. - /v1/measurement/loadxxx endpoints are removed. Use generic mesaurement endpoints. - /v1/admin/cache/clear now clears all cache files. Use /v1/admin/cache/clear-expired to only clear all expired cache files. Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
2025-10-30 14:26:21 +00:00 · 2025-10-28 02:50:31 +01:00
parent 20a9eb78d8
commit b397b5d43e
146 changed files with 22024 additions and 5339 deletions
--- a/docs/akkudoktoreos/configtimewindow.md
+++ b/docs/akkudoktoreos/configtimewindow.md
@@ -0,0 +1,849 @@
+% SPDX-License-Identifier: Apache-2.0
+(configtimewindow-page)=
+
+# Time Window Sequence Configuration
+
+## Overview
+
+The `TimeWindowSequence` model is used to configure allowed time slots for home appliance runs.
+It contains a collection of `TimeWindow` objects that define when appliances can operate.
+
+## Basic Structure
+
+A `TimeWindowSequence` is configured as a JSON object with a `windows` array:
+
+```json
+{
+  "windows": [
+    {
+      "start_time": "09:00",
+      "duration": "PT2H",
+      "day_of_week": null,
+      "date": null,
+      "locale": null
+    }
+  ]
+}
+```
+
+## TimeWindow Fields
+
+Each `TimeWindow` object has the following fields:
+
+- **`start_time`** (required): Time when the window begins
+- **`duration`** (required): How long the window lasts
+- **`day_of_week`** (optional): Restrict to specific day of week
+- **`date`** (optional): Restrict to specific calendar date
+- **`locale`** (optional): Language for day name parsing
+
+## Time Formats
+
+### Start Time (`start_time`)
+
+The `start_time` field accepts various time formats:
+
+#### 24-Hour Format
+
+```json
+{
+  "start_time": "14:30"        // 2:30 PM
+}
+```
+
+#### 12-Hour Format with AM/PM
+
+```json
+{
+  "start_time": "2:30 PM"      // 2:30 PM
+}
+```
+
+#### Compact Format
+
+```json
+{
+  "start_time": "1430"         // 2:30 PM
+}
+```
+
+#### With Seconds
+
+```json
+{
+  "start_time": "14:30:45"     // 2:30:45 PM
+}
+```
+
+#### With Microseconds
+
+```json
+{
+  "start_time": "14:30:45.123456"
+}
+```
+
+#### European Format
+
+```json
+{
+  "start_time": "14h30"        // 2:30 PM
+}
+```
+
+#### Short Formats
+
+```json
+{
+  "start_time": "14"           // 2:00 PM
+}
+```
+
+```json
+{
+  "start_time": "2PM"          // 2:00 PM
+}
+```
+
+#### Decimal Time
+
+```json
+{
+  "start_time": "14.5"         // 2:30 PM (14:30)
+}
+```
+
+#### With Timezones
+
+```json
+{
+  "start_time": "14:30 UTC"
+}
+```
+
+```json
+{
+  "start_time": "2:30 PM EST"
+}
+```
+
+```json
+{
+  "start_time": "14:30 +05:30"
+}
+```
+
+### Duration (`duration`)
+
+The `duration` field supports multiple formats for maximum flexibility:
+
+#### ISO 8601 Duration Format (Recommended)
+
+```json
+{
+  "duration": "PT2H30M"        // 2 hours 30 minutes
+}
+```
+
+```json
+{
+  "duration": "PT3H"           // 3 hours
+}
+```
+
+```json
+{
+  "duration": "PT90M"          // 90 minutes
+}
+```
+
+```json
+{
+  "duration": "PT1H30M45S"     // 1 hour 30 minutes 45 seconds
+}
+```
+
+#### Human-Readable String Format
+
+The system accepts natural language duration strings:
+
+```json
+{
+  "duration": "2 hours 30 minutes"
+}
+```
+
+```json
+{
+  "duration": "3 hours"
+}
+```
+
+```json
+{
+  "duration": "90 minutes"
+}
+```
+
+```json
+{
+  "duration": "1 hour 30 minutes 45 seconds"
+}
+```
+
+```json
+{
+  "duration": "2 days 5 hours"
+}
+```
+
+```json
+{
+  "duration": "1 day 2 hours 30 minutes"
+}
+```
+
+#### Singular and Plural Forms
+
+Both singular and plural forms are supported:
+
+```json
+{
+  "duration": "1 day"          // Singular
+}
+```
+
+```json
+{
+  "duration": "2 days"         // Plural
+}
+```
+
+```json
+{
+  "duration": "1 hour"         // Singular
+}
+```
+
+```json
+{
+  "duration": "5 hours"        // Plural
+}
+```
+
+#### Numeric Formats
+
+##### Seconds as Integer
+
+```json
+{
+  "duration": 3600             // 3600 seconds = 1 hour
+}
+```
+
+```json
+{
+  "duration": 1800             // 1800 seconds = 30 minutes
+}
+```
+
+##### Seconds as Float
+
+```json
+{
+  "duration": 3600.5           // 3600.5 seconds = 1 hour 0.5 seconds
+}
+```
+
+##### Tuple Format [days, hours, minutes, seconds]
+
+```json
+{
+  "duration": [0, 2, 30, 0]    // 0 days, 2 hours, 30 minutes, 0 seconds
+}
+```
+
+```json
+{
+  "duration": [1, 0, 0, 0]     // 1 day
+}
+```
+
+```json
+{
+  "duration": [0, 0, 45, 30]   // 45 minutes 30 seconds
+}
+```
+
+```json
+{
+  "duration": [2, 5, 15, 45]   // 2 days, 5 hours, 15 minutes, 45 seconds
+}
+```
+
+#### Mixed Time Units
+
+You can combine different time units in string format:
+
+```json
+{
+  "duration": "1 day 4 hours 30 minutes 15 seconds"
+}
+```
+
+```json
+{
+  "duration": "3 days 2 hours"
+}
+```
+
+```json
+{
+  "duration": "45 minutes 30 seconds"
+}
+```
+
+#### Common Duration Examples
+
+##### Short Durations
+
+```json
+{
+  "duration": "30 minutes"     // Quick appliance cycle
+}
+```
+
+```json
+{
+  "duration": "PT30M"          // ISO format equivalent
+}
+```
+
+```json
+{
+  "duration": 1800             // Numeric equivalent (seconds)
+}
+```
+
+##### Medium Durations
+
+```json
+{
+  "duration": "2 hours 15 minutes"
+}
+```
+
+```json
+{
+  "duration": "PT2H15M"        // ISO format equivalent
+}
+```
+
+```json
+{
+  "duration": [0, 2, 15, 0]    // Tuple format equivalent
+}
+```
+
+##### Long Durations
+
+```json
+{
+  "duration": "1 day 8 hours"  // All-day appliance window
+}
+```
+
+```json
+{
+  "duration": "PT32H"          // ISO format equivalent
+}
+```
+
+```json
+{
+  "duration": [1, 8, 0, 0]     // Tuple format equivalent
+}
+```
+
+#### Validation Rules for Duration
+
+- **ISO 8601 format**: Must start with `PT` and use valid duration specifiers (H, M, S)
+- **String format**: Must contain valid time units (day/days, hour/hours, minute/minutes, second/seconds)
+- **Numeric format**: Must be a positive number representing seconds
+- **Tuple format**: Must be exactly 4 elements: [days, hours, minutes, seconds]
+- **All formats**: Duration must be positive (greater than 0)
+
+#### Duration Format Recommendations
+
+1. **Use ISO 8601 format** for API consistency: `"PT2H30M"`
+2. **Use human-readable strings** for configuration files: `"2 hours 30 minutes"`
+3. **Use numeric format** for programmatic calculations: `9000` (seconds)
+4. **Use tuple format** for structured data: `[0, 2, 30, 0]`
+
+#### Error Handling for Duration
+
+Common duration errors and solutions:
+
+- **Invalid ISO format**: Ensure proper `PT` prefix and valid specifiers
+- **Unknown time units**: Use day/days, hour/hours, minute/minutes, second/seconds
+- **Negative duration**: All durations must be positive
+- **Invalid tuple length**: Tuple must have exactly 4 elements
+- **String too long**: Duration strings have a maximum length limit for security
+
+## Day of Week Restrictions
+
+### Using Numbers (0=Monday, 6=Sunday)
+
+```json
+{
+  "day_of_week": 0             // Monday
+}
+```
+
+```json
+{
+  "day_of_week": 6             // Sunday
+}
+```
+
+### Using English Day Names
+
+```json
+{
+  "day_of_week": "Monday"
+}
+```
+
+```json
+{
+  "day_of_week": "sunday"      // Case insensitive
+}
+```
+
+### Using Localized Day Names
+
+```json
+{
+  "day_of_week": "Montag",     // German for Monday
+  "locale": "de"
+}
+```
+
+```json
+{
+  "day_of_week": "Lundi",      // French for Monday
+  "locale": "fr"
+}
+```
+
+## Date Restrictions
+
+### Specific Date
+
+```json
+{
+  "date": "2024-12-25"         // Christmas Day 2024
+}
+```
+
+**Note**: When `date` is specified, `day_of_week` is ignored.
+
+## Complete Examples
+
+### Example 1: Basic Daily Window
+
+Allow appliance to run between 9:00 AM and 11:00 AM every day:
+
+```json
+{
+  "windows": [
+    {
+      "start_time": "09:00",
+      "duration": "PT2H"
+    }
+  ]
+}
+```
+
+### Example 2: Weekday Only
+
+Allow appliance to run between 8:00 AM and 6:00 PM on weekdays:
+
+```json
+{
+  "windows": [
+    {
+      "start_time": "08:00",
+      "duration": "PT10H",
+      "day_of_week": 0
+    },
+    {
+      "start_time": "08:00",
+      "duration": "PT10H",
+      "day_of_week": 1
+    },
+    {
+      "start_time": "08:00",
+      "duration": "PT10H",
+      "day_of_week": 2
+    },
+    {
+      "start_time": "08:00",
+      "duration": "PT10H",
+      "day_of_week": 3
+    },
+    {
+      "start_time": "08:00",
+      "duration": "PT10H",
+      "day_of_week": 4
+    }
+  ]
+}
+```
+
+### Example 3: Multiple Daily Windows
+
+Allow appliance to run during morning and evening hours:
+
+```json
+{
+  "windows": [
+    {
+      "start_time": "06:00",
+      "duration": "PT3H"
+    },
+    {
+      "start_time": "18:00",
+      "duration": "PT4H"
+    }
+  ]
+}
+```
+
+### Example 4: Weekend Special Hours
+
+Different hours for weekdays and weekends:
+
+```json
+{
+  "windows": [
+    {
+      "start_time": "08:00",
+      "duration": "PT8H",
+      "day_of_week": "Monday"
+    },
+    {
+      "start_time": "08:00",
+      "duration": "PT8H",
+      "day_of_week": "Tuesday"
+    },
+    {
+      "start_time": "08:00",
+      "duration": "PT8H",
+      "day_of_week": "Wednesday"
+    },
+    {
+      "start_time": "08:00",
+      "duration": "PT8H",
+      "day_of_week": "Thursday"
+    },
+    {
+      "start_time": "08:00",
+      "duration": "PT8H",
+      "day_of_week": "Friday"
+    },
+    {
+      "start_time": "10:00",
+      "duration": "PT6H",
+      "day_of_week": "Saturday"
+    },
+    {
+      "start_time": "10:00",
+      "duration": "PT6H",
+      "day_of_week": "Sunday"
+    }
+  ]
+}
+```
+
+### Example 5: Holiday Schedule
+
+Special schedule for a specific date:
+
+```json
+{
+  "windows": [
+    {
+      "start_time": "10:00",
+      "duration": "PT4H",
+      "date": "2024-12-25"
+    }
+  ]
+}
+```
+
+### Example 6: Localized Configuration
+
+Using German day names:
+
+```json
+{
+  "windows": [
+    {
+      "start_time": "14:00",
+      "duration": "PT2H",
+      "day_of_week": "Montag",
+      "locale": "de"
+    },
+    {
+      "start_time": "14:00",
+      "duration": "PT2H",
+      "day_of_week": "Mittwoch",
+      "locale": "de"
+    },
+    {
+      "start_time": "14:00",
+      "duration": "PT2H",
+      "day_of_week": "Freitag",
+      "locale": "de"
+    }
+  ]
+}
+```
+
+### Example 7: Complex Schedule with Timezones
+
+Multiple windows with different timezones:
+
+```json
+{
+  "windows": [
+    {
+      "start_time": "09:00 UTC",
+      "duration": "PT4H",
+      "day_of_week": "Monday"
+    },
+    {
+      "start_time": "2:00 PM EST",
+      "duration": "PT3H",
+      "day_of_week": "Friday"
+    }
+  ]
+}
+```
+
+### Example 8: Night Shift Schedule
+
+Crossing midnight (note: each window is within a single day):
+
+```json
+{
+  "windows": [
+    {
+      "start_time": "22:00",
+      "duration": "PT2H"
+    },
+    {
+      "start_time": "00:00",
+      "duration": "PT6H"
+    }
+  ]
+}
+```
+
+## Advanced Usage Patterns
+
+### Off-Peak Hours
+
+Configure appliance to run during off-peak electricity hours:
+
+```json
+{
+  "windows": [
+    {
+      "start_time": "23:00",
+      "duration": "PT1H"
+    },
+    {
+      "start_time": "00:00",
+      "duration": "PT7H"
+    }
+  ]
+}
+```
+
+### Workday Lunch Break
+
+Allow appliance to run during lunch break on workdays:
+
+```json
+{
+  "windows": [
+    {
+      "start_time": "12:00",
+      "duration": "PT1H",
+      "day_of_week": 0
+    },
+    {
+      "start_time": "12:00",
+      "duration": "PT1H",
+      "day_of_week": 1
+    },
+    {
+      "start_time": "12:00",
+      "duration": "PT1H",
+      "day_of_week": 2
+    },
+    {
+      "start_time": "12:00",
+      "duration": "PT1H",
+      "day_of_week": 3
+    },
+    {
+      "start_time": "12:00",
+      "duration": "PT1H",
+      "day_of_week": 4
+    }
+  ]
+}
+```
+
+### Seasonal Schedule
+
+Different schedules for different dates:
+
+```json
+{
+  "windows": [
+    {
+      "start_time": "08:00",
+      "duration": "PT10H",
+      "date": "2024-06-21"
+    },
+    {
+      "start_time": "09:00",
+      "duration": "PT8H",
+      "date": "2024-12-21"
+    }
+  ]
+}
+```
+
+## Common Patterns
+
+### 1. Always Available
+
+```json
+{
+  "windows": [
+    {
+      "start_time": "00:00",
+      "duration": "PT24H"
+    }
+  ]
+}
+```
+
+### 2. Business Hours
+
+```json
+{
+  "windows": [
+    {
+      "start_time": "09:00",
+      "duration": "PT8H",
+      "day_of_week": 0
+    },
+    {
+      "start_time": "09:00",
+      "duration": "PT8H",
+      "day_of_week": 1
+    },
+    {
+      "start_time": "09:00",
+      "duration": "PT8H",
+      "day_of_week": 2
+    },
+    {
+      "start_time": "09:00",
+      "duration": "PT8H",
+      "day_of_week": 3
+    },
+    {
+      "start_time": "09:00",
+      "duration": "PT8H",
+      "day_of_week": 4
+    }
+  ]
+}
+```
+
+### 3. Never Available
+
+```json
+{
+  "windows": []
+}
+```
+
+## Validation Rules
+
+- `start_time` must be a valid time format
+- `duration` must be a positive duration
+- `day_of_week` must be 0-6 (integer) or valid day name (string)
+- `date` must be a valid ISO date format (YYYY-MM-DD)
+- If `date` is specified, `day_of_week` is ignored
+- `locale` must be a valid locale code when using localized day names
+
+## Tips and Best Practices
+
+1. **Use 24-hour format** for clarity: `"14:30"` instead of `"2:30 PM"`
+2. **Keep durations reasonable** for appliance operation cycles
+3. **Test timezone handling** if using timezone-aware times
+4. **Use specific dates** for holiday schedules
+5. **Consider overlapping windows** for flexibility
+6. **Use localization** for international deployments
+7. **Document your patterns** for maintenance
+
+## Error Handling
+
+Common errors and solutions:
+
+- **Invalid time format**: Use supported time formats listed above
+- **Invalid duration**: Use ISO 8601 duration format (PT1H30M)
+- **Invalid day name**: Check spelling and locale settings
+- **Invalid date**: Use YYYY-MM-DD format
+- **Unknown locale**: Use standard locale codes (en, de, fr, etc.)
+
+## Integration Examples
+
+### Python Usage
+
+```python
+from pydantic import ValidationError
+
+try:
+    config = TimeWindowSequence.model_validate_json(json_string)
+    print(f"Configured {len(config.windows)} time windows")
+except ValidationError as e:
+    print(f"Configuration error: {e}")
+```
+
+### API Configuration
+
+```json
+{
+  "device_id": "dishwasher_01",
+  "time_windows": {
+    "windows": [
+      {
+        "start_time": "22:00",
+        "duration": "PT2H"
+      },
+      {
+        "start_time": "06:00",
+        "duration": "PT2H"
+      }
+    ]
+  }
+}
+```
--- a/docs/akkudoktoreos/configuration.md
+++ b/docs/akkudoktoreos/configuration.md
@@ -1,6 +1,7 @@
 % SPDX-License-Identifier: Apache-2.0
+(configuration-page)=

-# Configuration
+# Configuration Guideline

 The configuration controls all aspects of EOS: optimization, prediction, measurement, and energy
 management.
--- a/docs/akkudoktoreos/integration.md
+++ b/docs/akkudoktoreos/integration.md
@@ -32,8 +32,7 @@ emphasizes local control and user privacy.

 ### Home Assistant Resources

- Duetting's [EOS Home Assistant Addon](https://github.com/Duetting/ha_eos_addon) — Additional
-  details can be found in this [discussion thread](https://github.com/Akkudoktor-EOS/EOS/discussions/294).
+- Duetting's [EOS Home Assistant Addon](https://github.com/Duetting/ha_eos_addon).

 ## EOS Connect

--- a/docs/akkudoktoreos/logging.md
+++ b/docs/akkudoktoreos/logging.md
@@ -73,3 +73,9 @@ You can also control the log level by setting the `EOS_LOGGING__CONSOLE_LEVEL` a
 If the `file_level` configuration is set, log records are written to a rotating log file. The log
 file is in the data output directory and named `eos.log`. You may directly read the file or use
 the `/v1/logging/log` endpoint to access the file log.
+
+:::{admonition} Note
+:class: note
+The `/v1/logging/log` endpoint needs file logging to be enabled. Otherwise old or no logging
+information is provided.
+:::
--- a/docs/akkudoktoreos/measurement.md
+++ b/docs/akkudoktoreos/measurement.md
@@ -1,4 +1,5 @@
 % SPDX-License-Identifier: Apache-2.0
+(measurement-page)=

 # Measurements

@@ -12,14 +13,7 @@ accuracy.
 ## Storing Measurements

 EOS stores measurements in a **key-value store**, where the term `measurement key` refers to the
-unique identifier used to store and retrieve specific measurement data. Note that the key-value
-store is memory-based, meaning that all stored data will be lost upon restarting the EOS REST
-server.
-
-:::{admonition} Todo
-:class: note
-Ensure that measurement data persists across server restarts.
-:::
+unique identifier used to store and retrieve specific measurement data.

 Several endpoints of the EOS REST server allow for the management and retrieval of these
 measurements.
@@ -30,14 +24,14 @@ The measurement data must be or is provided in one of the following formats:

 A dictionary with the following structure:

-```python
-    {
-        "start_datetime": "2024-01-01 00:00:00",
-        "interval": "1 Hour",
-        "<measurement key>": [value, value, ...],
-        "<measurement key>": [value, value, ...],
-        ...
-    }
+```json
+{
+    "start_datetime": "2024-01-01 00:00:00",
+    "interval": "1 hour",
+    "<measurement key>": [value, value, ...],
+    "<measurement key>": [value, value, ...],
+    ...
+}
 ```

 ### 2. DateTimeDataFrame
@@ -51,43 +45,84 @@ The column name of the data must be the same as the names of the `measurement ke
 A JSON string created from a [pandas](https://pandas.pydata.org/docs/index.html) series with a
 `DatetimeIndex`. Use [pandas.Series.to_json(orient="index")](https://pandas.pydata.org/docs/reference/api/pandas.Series.to_json.html#pandas.Series.to_json).

+Creates a dictionary like this:
+
+```json
+{
+  "data": {
+     "2024-01-01T00:00:00+01:00": 1,
+     "2024-01-02T00:00:00+01:00": 2,
+     "2024-01-03T00:00:00+01:00": 3,
+     ...
+  },
+  "dtype": "float64",
+  "tz": "Europe/Berlin"
+}
+```
+
 ## Load Measurement

-The EOS measurement store provides for storing meter readings of loads. There are currently five loads
-foreseen. The associated `measurement key`s are:
+The EOS measurement store provides for storing energy meter readings of loads.

- `load0_mr`: Load0 meter reading [kWh]
- `load1_mr`: Load1 meter reading [kWh]
- `load2_mr`: Load2 meter reading [kWh]
- `load3_mr`: Load3 meter reading [kWh]
- `load4_mr`: Load4 meter reading [kWh]
+The associated `measurement key`s can be configured by:

-For ease of use, you can assign descriptive names to the `measurement key`s to represent your
-system's load sources. Use the following `configuration options` to set these names
-(e.g., 'Dish Washer', 'Heat Pump'):
-
- `load0_name`: Name of the load0 source
- `load1_name`: Name of the load1 source
- `load2_name`: Name of the load2 source
- `load3_name`: Name of the load3 source
- `load4_name`: Name of the load4 source
+```json
+{
+  "measurement": {
+    "load_emr_keys": ["load0_emr", "my special load", ...]
+  }
+}
+```

 Load measurements can be stored for any datetime. The values between different meter readings are
-linearly approximated. Since optimization occurs on the hour, storing values between hours is
-generally not useful.
+linearly approximated. Storing values between optimization intervals is generally not useful.

 The EOS measurement store automatically sums all given loads to create a total load value series
 for specified intervals, usually one hour. This aggregated data can be used for load predictions.

+:::{admonition} Warning
+:class: warning
+Only use **actual meter readings** in **kWh**, not energy consumption.
+Example: `112345.77`, `112389.23`, `112412.55`, …
+:::
+
 ## Grid Export/ Import Measurement

 The EOS measurement store also allows for the storage of meter readings for grid import and export.
-The associated `measurement key`s are:

- `grid_export_mr`: Export to grid meter reading [kWh]
- `grid_import_mr`: Import from grid meter reading [kWh]
+The associated `measurement key`s can be configured by:
+
+```json
+{
+  "measurement": {
+    "grid_export_emr_keys": ["grid_export_emr", ...],
+    "grid_import_emr_keys": ["grid_import_emr", ...],
+  }
+}
+```

 :::{admonition} Todo
 :class: note
 Currently not used. Integrate grid meter readings into the respective predictions.
 :::
+
+## Battery/ Electric Vehicle State of Charge (SoC) Measurement
+
+The state of charge (SoC) measurement of batteries and electric vehicle batteries can be stored.
+
+The associated `measurement key` is pre-defined by the device configuration. It can be
+determined from the device configuration by the read-only `measurement_key_soc_factor` configuration
+option.
+
+## Battery/ Electric Vehicle Power Measurement
+
+The charge/ discharge power measurements of batteries and electric vehicle batteries can be stored.
+Charging power is denoted by a negative value, discharging power by a positive value.
+
+The associated `measurement key`s are pre-defined by the device configuration. They can be
+determined from the device configuration by read-only configuration options:
+
+- `measurement_key_power_l1_w`
+- `measurement_key_power_l2_w`
+- `measurement_key_power_l3_w`
+- `measurement_key_power_3_phase_sym_w`
--- a/docs/akkudoktoreos/optimauto.md
+++ b/docs/akkudoktoreos/optimauto.md
@@ -0,0 +1,448 @@
+% SPDX-License-Identifier: Apache-2.0
+
+# Automatic Optimization
+
+## Introduction
+
+EOS offers two approaches to optimize your energy management system: `post /optimize optimization` and
+`automatic optimization`.
+
+The `post /optimize optimization` interface, based on a **POST** request to `/optimize`, is widely
+used. It was originally developed by Andreas at the start of the project and is still demonstrated
+in his instructional videos. This interface allows users or external systems to trigger an
+optimization manually, supplying custom parameters and timing.
+
+As an alternative, EOS supports `automatic optimization`, which runs automatically at configured
+intervals. It retrieves all required input data — including electricity prices, battery storage
+capacity, PV production forecasts, and temperature data — based on your system configuration.
+
+### Genetic Algorithm
+
+Both optimization modes use the same core optimization engine.
+
+EOS uses a [genetic algorithm](https://en.wikipedia.org/wiki/Genetic_algorithm) to find an optimal
+control strategy for home energy devices such as household loads, batteries, and electric vehicles.
+
+In this context, each **individual** represents a possible solution — a specific control schedule
+that defines how devices should operate over time. These individuals are evaluated using
+[resource simulations](#resource-page), which model the system’s energy behavior over a defined time
+period divided into fixed intervals.
+
+The quality of each solution (its *fitness*) is determined by how well it performs during
+simulation, based on objectives such as minimizing electricity costs, maximizing self-consumption,
+or meeting battery charge targets.
+
+Through an iterative process of selection, crossover, and mutation, the algorithm gradually evolves
+more effective solutions. The final result is an optimized control strategy that balances multiple
+system goals within the constraints of the input data and configuration.
+
+:::{note}
+You don’t need to understand the internal workings of the genetic algorithm to benefit from
+automatic optimization. EOS handles everything behind the scenes based on your configuration.
+However, advanced users can fine-tune the optimization behavior using additional settings like
+population size, penalties, and random seed.
+:::
+
+## Energy Management Plan
+
+Whenever the optimization is run, the energy management plan is updated. The energy management plan
+provides a list of energy management instructions in chronological order. The instructions lean on
+to the [S2 standard](https://docs.s2standard.org/) to have maximum flexibility and stay completely
+independent from any manufacturer.
+
+### Battery Instructions
+
+The battery control instructions assume an idealized battery model. Under this model, the battery
+can be operated in four discrete operation modes:
+
+| **Operation Mode ID** | **Description**                                                                      |
+| --------------------- | ------------------------------------------------------------------------------------ |
+| **IDLE**              | Battery neither charges nor discharges; holds its state of charge.                   |
+| **CHARGE**            | Charge at a specified power rate up to the allowable maximum.                        |
+| **DISCHARGE**         | Discharge at a specified power rate up to the allowable maximum.                     |
+| **ALLOW_DISCHARGE**   | Allow the battery to freely discharge depending on its instantaneous power setpoint. |
+
+The **operation mode factor** (0.0–1.0) specifies the normalized power rate relative to the
+battery's nominal maximum charge or discharge power. A value of 1.0 corresponds to full-rate
+charging or discharging, while 0.0 indicates no power transfer. Intermediate values scale the power
+proportionally.
+
+### Electric Vehicle Instructions
+
+The electric vehicle control instructions assume an idealized EV battery model. Under this model,
+the EV battery can be operated in two operation modes:
+
+| **Operation Mode ID** | **Description**                                                                      |
+| --------------------- | ------------------------------------------------------------------------------------ |
+| **IDLE**              | Battery neither charges nor discharges; holds its state of charge.                   |
+| **CHARGE**            | Charge at a specified power rate up to the allowable maximum.                        |
+
+The **operation mode factor** (0.0–1.0) specifies the normalized power rate relative to the
+battery's nominal maximum charge power. A value of 1.0 corresponds to full-rate charging, while 0.0
+indicates no power transfer. Intermediate values scale the power proportionally.
+
+### Home Appliance Instructions
+
+The home appliance instructions assume an idealized home appliance model. Under this model,
+the home appliance can be operated in two operation modes:
+
+| **Operation Mode ID** | **Description**                                                                      |
+| --------------------- | ------------------------------------------------------------------------------------ |
+| **RUN**               | The home appliance is started and runs until the end of it's power sequence.         |
+| **IDLE**              | The home appliance does not run.                                                     |
+
+The **operation mode factor** (0.0–1.0) is ignored.
+
+## Configuration
+
+### Energy management configuration
+
+The energy management is run on configured intervals with some startup delay after server start.
+Both values are given in seconds.
+
+:::{admonition} Note
+:class: note
+If no interval is configured (`None`, `null`) there will be only one energy management run at
+startup.
+:::
+
+The energy management can be run in two modes:
+
+- **OPTIMIZATION**: A full optimization is done. This includes update of predictions.
+- **PREDICTION**: Only the predictions are updated.
+
+**Example:**
+
+```json
+{
+    "ems": {
+        "startup_delay": 5.0,
+        "interval": 300.0,
+        "mode": "OPTIMIZATION"
+    }
+}
+```
+
+### Optimization Configuration
+
+#### Optimization Time Configuration
+
+- **horizon_hours**:
+    The optimization horizon parameter defines the default time window — in hours — within which
+    the energy optimization goal shall be achieved.
+
+    Specific devices, like the home appliance, have their own configuration for time windows. If
+    the time windows are not configured the simulation uses the default time window.
+
+    Each device simulation run must ensure that all tasks or appliance cycles (e.g., running a
+    dishwasher) are completed within the configured time windows.
+
+- **interval**: Defines the time step in seconds between control actions
+    (e.g. `3600` for one hour, `900` for 15 minutes).
+
+:::{warning}
+**Current Limitation**
+
+At present, the `interval` setting is **not used** by the genetic algorithm. Instead:
+
+- The control interval is fixed to **1 hour**.
+
+Support for configurable intervals (e.g. 15-minute steps) may be added in a future release.
+:::
+
+#### Genetic Algorithm Parameters
+
+The behavior of the genetic algorithm can be customized using the following configuration options:
+
+- **individuals** (`int`, default: `300`):
+  Sets the number of individuals (candidate solutions) in the (first) generation. A higher number
+  increases solution diversity and the chance of finding a good result, but also increases
+  computation time.
+
+- **generations** (`int`, default: `400`):
+  Sets the number of generations to evaluate the optimal solution. In each generation, solutions are
+  evaluated and evolved. More generations can improve optimization quality but increase computation
+  time. Best results are usually found within a moderate number of generations.
+
+- **seed** (`int` or `null`, default: `null`):
+  Sets the random seed for reproducible results.
+
+  - If `null`, a random seed is used (non-reproducible).
+  - If an integer is provided, it ensures that the same optimization input yields the same output.
+
+    A fixed seed to ensure reproducibility. Runs with the same seed and configuration will
+    produce the same results.
+
+- **penalties** (`dict`):
+  Defines how penalties are applied to solutions that violate constraints (e.g., undercharged
+  batteries). Penalty function parameter values influence the fitness score, discouraging
+  undesirable solutions.
+
+:::{note}
+**Supported Penalty Functions**
+
+Currently, the only supported penalty function parameter is:
+
+- `ev_soc_miss`:
+  Applies a penalty when the **state of charge (SOC)** of the electric vehicle battery falls below
+  the required minimum. This encourages the optimizer to ensure sufficient EV charging.
+:::
+
+#### Value Formats
+
+- **Time-related values**:
+  - `hours`: specified in **hours** (e.g. `24`)
+  - `interval`: specified in **seconds** (e.g. `3600`)
+
+- **Genetic algorithm parameters**:
+  - `individuals`: must be an **integer**
+  - `seed`: must be an **integer** or `null` for random behavior
+
+- **Penalty function parameter values**: may be `float`, `int`, or `string`, depending on the type
+  of penalty function.
+
+#### Optimization configuration example
+
+```json
+{
+    "optimization": {
+        "hours": 24,
+        "interval": 3600,
+        "genetic" : {
+            "individuals": 300,
+            "generations": 400,
+            "seed": null,
+            "penalties": {
+                "ev_soc_miss": 10
+            }
+        }
+    }
+}
+```
+
+### Device simulation configuration
+
+The device simulations are used to evaluate the fitness of the individuals of the solution
+population.
+
+The GENETIC algorithm supports 4 devices:
+
+- **inverter**: A photovoltaic power inverter that can export to the grid and charge a battery.
+  The inverter is mandatory.
+- **electric_vehicle**: An electric vehicle, basically the battery of an electric vehicle. The
+  The electrical vehicle is optional.
+- **battery**: A battery that can be charged by the inverter. The battery is mandatory.
+- **home_appliance**: A home appliance, like a washing machine or a dish washer. The home
+  appliance is optional.
+
+:::{admonition} Warning
+:class: warning
+The GENETIC algorithm can only use the first inverter, electrical vehicle, battery, home appliance
+that is configured, even if more devices are configured.
+:::
+
+#### Inverter simulation configuration
+
+**Example:**
+
+```json
+{
+    "devices": {
+        "max_inverters": 1,
+        "inverters": [
+            {
+                "device_id": "inv1",
+                "max_power_w": 10000,
+                "battery_id": "bat1"
+            }
+        ]
+    }
+}
+```
+
+#### Electric vehicle simulation configuration
+
+**Example:**
+
+```json
+{
+    "devices": {
+        "max_electric_vehicles": 1,
+        "electric_vehicles": [
+            {
+                "device_id": "ev1",
+                "capacity_wh": 50000,
+                "max_charge_power_w": 10000,
+                "charge_rates": [0.0, 0.25, 0.5, 0.75, 1.0],
+                "min_soc_percentage": 10,
+                "max_soc_percentage": 80
+            }
+        ]
+    },
+    "measurement": {
+        "electric_vehicle_soc_keys": ["ev1_soc"]
+    }
+}
+```
+
+#### Battery simulation configuration
+
+**Example:**
+
+```json
+{
+    "devices": {
+        "max_batteries": 1,
+        "batteries": [
+            {
+                "device_id": "battery1",
+                "capacity_wh": 8000,
+                "charging_efficiency": 0.88,
+                "discharging_efficiency": 0.88,
+                "levelized_cost_of_storage_kwh": 0.12,
+                "max_charge_power_w": 8000,
+                "min_charge_power_w": 50,
+                "charge_rates": null,
+                "min_soc_percentage": 5,
+                "max_soc_percentage": 95
+            }
+        ]
+    }
+}
+```
+
+#### Home appliance simulation configuration
+
+**Example:**
+
+```json
+{
+    "devices": {
+        "max_home_appliances": 1,
+        "home_appliances": [
+            {
+                "device_id": "washing machine",
+                "consumption_wh": 600,
+                "duration_h": 3,
+                "time_windows": null,
+            }
+        ]
+    }
+}
+```
+
+The time windows the home appliance may run can be [configured](#configtimewindow-page) in several
+ways. See the [time window configuration](#configtimewindow-page) for details.
+
+## Predictions configuration
+
+The device simulation may rely on predictions to simulate proper behaviour. E.g. the inverter needs
+to know the PV forecast.
+
+Configure the [predictions](#prediction-page) as described on the [prediction page](#prediction-page).
+
+### Providing your own prediction data
+
+If EOS does not have a suitable prediction provider you can provide your own data for a prediction.
+Configure the respective import provider (ElecPriceImport, LoadImport, PVForecastImport,
+WeatherImport) and use one of the following endpoints to provide your own data:
+
+- **PUT** `/v1/prediction/import/ElecPriceImport`
+- **PUT** `/v1/prediction/import/LoadImport`
+- **PUT** `/v1/prediction/import/PVForecastImport`
+- **PUT** `/v1/prediction/import/WeatherImport`
+
+## Measurement configuration
+
+Predictions and device simulations often rely on **measurement data** to produce accurate results.
+For example:
+
+- A **load forecast** requires past energy meter readings.
+- A **battery simulation** needs the current **state of charge (SoC)** to start from the correct
+  condition.
+
+Before using these features, make sure to configure the [measurement](#measurement-page) as
+described on the [measurement page](#measurement-page).
+
+### Providing your own measurement data
+
+You can provide your own measurement data to the prediction and simulation engine through the
+following REST endpoints (see the [measurement page](#measurement-page) for details on the data
+format):
+
+- **PUT** `/v1/measurement/data`
+- **PUT** `/v1/measurement/dataframe`
+- **PUT** `/v1/measurement/series`
+- **PUT** `/v1/measurement/value`
+
+### Example: Supplying Battery and EV SoC
+
+For **batteries** and **electric vehicles**, it is strongly recommended to provide
+**current SoC**. This ensures that simulations start with the correct state.
+
+The simplest way is to use the `/v1/measurement/value` endpoint.
+Assuming the battery is named `battery1` and the EV is named `ev11`:
+
+1. **Use the measurement keys** that are pre-configured for your **devices**. For example:
+
+    ```json
+    {
+        "devices": {
+            "batteries": [
+                {
+                "device_id": "battery1", "capacity_wh": 8000,  ...
+                "measurement_key_soc_factor": "battery1-soc-factor", ...
+                }
+            ],
+            "electric_vehicles": [
+                {
+                "device_id": "ev11", "capacity_wh": 8000,  ...
+                "measurement_key_soc_factor": "ev11-soc-factor", ...
+                }
+            ]
+        }
+    }
+    ```
+
+2. **Record your SoC readings** to these keys.
+
+   - Enter the values as **factor of total capacity** of the respective **battery**.
+
+In these examples:
+
+- datetime specifies the timestamp of the measurement.
+- key is the measurement key (e.g. battery1-soc-factor).
+- value is the numeric measurement value (e.g. SoC as factor of total capacity).
+
+#### Raw HTTP request
+
+```http
+PUT http://127.0.0.1:8503/v1/measurement/value?datetime=2025-09-26T16%3A39&key=battery1-soc-factor&value=0.57
+PUT http://127.0.0.1:8503/v1/measurement/value?datetime=2025-09-26T16%3A39&key=ev11-soc-factor&value=0.22
+```
+
+#### Equivalent curl commands
+
+```bash
+curl -X PUT "http://127.0.0.1:8503/v1/measurement/value?datetime=2025-09-26T16%3A39&key=battery1-soc-factor&value=0.57"
+curl -X PUT "http://127.0.0.1:8503/v1/measurement/value?datetime=2025-09-26T16%3A39&key=ev11-soc-factor&value=0.22"
+```
+
+### Example: Supplying Load Data
+
+To provide your actual load measurements in Akkudoktor-EOS:
+
+1. **Configure the measurement keys** for your load energy meters. For example:
+
+    ```json
+    {
+        "measurements": {
+            "load_emr_keys": ["my_load_meter_reading", "my_other_load_meter_reading"]
+        }
+    }
+    ```
+
+2. **Record your meter readings** to these keys.
+
+   - Enter the values exactly as your energy meters report them, in **kWh**.
+   - Use the same approach as when supplying battery or EV SoC data.
--- a/docs/akkudoktoreos/optimization.md
+++ b/docs/akkudoktoreos/optimization.md
@@ -1,12 +1,22 @@
 % SPDX-License-Identifier: Apache-2.0

-# Optimization
+# `POST /optimize` Optimization

 ## Introduction

 The `POST /optimize` API endpoint optimizes your energy management system based on various inputs
 including electricity prices, battery storage capacity, PV forecast, and temperature data.

+The `POST /optimize` optimization interface is the "classical" interface developed by Andreas at the
+start of the projects and used and described in his videos. It allows and requires to define all the
+optimization paramters on the endpoint request.
+
+:::{admonition} Warning
+:class: warning
+The `POST /optimize` endpoint interface does not regard configurations set for the parameters
+passed to the request. You have to set the parameters even if given in the configuration.
+:::
+
 ## Input Payload

 ### Sample Request
@@ -14,38 +24,70 @@ including electricity prices, battery storage capacity, PV forecast, and tempera
 ```json
 {
    "ems": {
-        "preis_euro_pro_wh_akku": 0.0007,
-        "einspeiseverguetung_euro_pro_wh": 0.00007,
-        "gesamtlast": [500, 500, ..., 500, 500],
-        "pv_prognose_wh": [300, 0, 0, ..., 2160, 1840],
-        "strompreis_euro_pro_wh": [0.0003784, 0.0003868, ..., 0.00034102, 0.00033709]
+        "preis_euro_pro_wh_akku": 0.0001,
+        "einspeiseverguetung_euro_pro_wh": [
+          0.00007, 0.00007, 0.00007, 0.00007, 0.00007, 0.00007, 0.00007,
+          0.00007, 0.00007, 0.00007, 0.00007, 0.00007, 0.00007, 0.00007,
+          0.00007, 0.00007, 0.00007, 0.00007, 0.00007, 0.00007, 0.00007,
+          0.00007, 0.00007, 0.00007, 0.00007, 0.00007, 0.00007, 0.00007,
+          0.00007, 0.00007, 0.00007, 0.00007, 0.00007, 0.00007, 0.00007,
+          0.00007, 0.00007, 0.00007, 0.00007, 0.00007, 0.00007, 0.00007,
+          0.00007, 0.00007, 0.00007, 0.00007, 0.00007, 0.00007
+        ],
+        "gesamtlast": [
+          676.71, 876.19, 527.13, 468.88, 531.38, 517.95, 483.15, 472.28,
+          1011.68, 995.00, 1053.07, 1063.91, 1320.56, 1132.03, 1163.67,
+          1176.82, 1216.22, 1103.78, 1129.12, 1178.71, 1050.98, 988.56, 912.38,
+          704.61, 516.37, 868.05, 694.34, 608.79, 556.31, 488.89, 506.91,
+          804.89, 1141.98, 1056.97, 992.46, 1155.99, 827.01, 1257.98, 1232.67,
+          871.26, 860.88, 1158.03, 1222.72, 1221.04, 949.99, 987.01, 733.99,
+          592.97
+        ],
+        "pv_prognose_wh": [
+          0, 0, 0, 0, 0, 0, 0, 8.05, 352.91, 728.51, 930.28, 1043.25, 1106.74,
+          1161.69, 6018.82, 5519.07, 3969.88, 3017.96, 1943.07, 1007.17,
+          319.67, 7.88, 0, 0, 0, 0, 0, 0, 0, 0, 0, 5.04, 335.59, 705.32,
+          1121.12, 1604.79, 2157.38, 1433.25, 5718.49, 4553.96, 3027.55,
+          2574.46, 1720.4, 963.4, 383.3, 0, 0, 0
+        ],
+        "strompreis_euro_pro_wh": [
+          0.0003384, 0.0003318, 0.0003284, 0.0003283, 0.0003289, 0.0003334,
+          0.0003290, 0.0003302, 0.0003042, 0.0002430, 0.0002280, 0.0002212,
+          0.0002093, 0.0001879, 0.0001838, 0.0002004, 0.0002198, 0.0002270,
+          0.0002997, 0.0003195, 0.0003081, 0.0002969, 0.0002921, 0.0002780,
+          0.0003384, 0.0003318, 0.0003284, 0.0003283, 0.0003289, 0.0003334,
+          0.0003290, 0.0003302, 0.0003042, 0.0002430, 0.0002280, 0.0002212,
+          0.0002093, 0.0001879, 0.0001838, 0.0002004, 0.0002198, 0.0002270,
+          0.0002997, 0.0003195, 0.0003081, 0.0002969, 0.0002921, 0.0002780
+        ]
    },
    "pv_akku": {
        "device_id": "battery1",
-        "capacity_wh": 12000,
-        "charging_efficiency": 0.92,
-        "discharging_efficiency": 0.92,
-        "max_charge_power_w": 5700,
-        "initial_soc_percentage": 66,
-        "min_soc_percentage": 5,
-        "max_soc_percentage": 100
+        "capacity_wh": 26400,
+        "max_charge_power_w": 5000,
+        "initial_soc_percentage": 80,
+        "min_soc_percentage": 15
    },
    "inverter": {
        "device_id": "inverter1",
-        "max_power_wh": 15500
-        "battery_id": "battery1",
+        "max_power_wh": 10000,
+        "battery_id": "battery1"
    },
    "eauto": {
-        "device_id": "auto1",
-        "capacity_wh": 64000,
-        "charging_efficiency": 0.88,
-        "discharging_efficiency": 0.88,
+        "device_id": "ev1",
+        "capacity_wh": 60000,
+        "charging_efficiency": 0.95,
+        "discharging_efficiency": 1.0,
        "max_charge_power_w": 11040,
-        "initial_soc_percentage": 98,
-        "min_soc_percentage": 60,
-        "max_soc_percentage": 100
+        "initial_soc_percentage": 54,
+        "min_soc_percentage": 0
    },
-    "temperature_forecast": [18.3, 18, ..., 20.16, 19.84],
+    "temperature_forecast": [
+      18.3, 17.8, 16.9, 16.2, 15.6, 15.1, 14.6, 14.2, 14.3, 14.8, 15.7, 16.7, 17.4,
+      18.0, 18.6, 19.2, 19.1, 18.7, 18.5, 17.7, 16.2, 14.6, 13.6, 13.0, 12.6, 12.2,
+      11.7, 11.6, 11.3, 11.0, 10.7, 10.2, 11.4, 14.4, 16.4, 18.3, 19.5, 20.7, 21.9,
+      22.7, 23.1, 23.1, 22.8, 21.8, 20.2, 19.1, 18.0, 17.4
+    ],
    "start_solution": null
 }
 ```
@@ -58,7 +100,8 @@ including electricity prices, battery storage capacity, PV forecast, and tempera

 - Unit: €/Wh
 - Purpose: Represents the residual value of energy stored in the battery
- Impact: Lower values encourage battery depletion, higher values preserve charge at the end of the simulation.
+- Impact: Lower values encourage battery depletion, higher values preserve charge at the end of the
+  simulation.

 #### Feed-in Tariff (`einspeiseverguetung_euro_pro_wh`)

@@ -162,23 +205,24 @@ Verify prices against your local tariffs.

 #### Battery Control

- `ac_charge`: Grid charging schedule (0-1)
+- `ac_charge`: Grid charging schedule (0.0-1.0)
 - `dc_charge`: DC charging schedule (0-1)
 - `discharge_allowed`: Discharge permission (0 or 1)

 0 (no charge)
 1 (charge with full load)

-`ac_charge` multiplied by the maximum charge power of the battery results in the planned charging power.
+`ac_charge` multiplied by the maximum charge power of the battery results in the planned charging
+power.

 #### EV Charging

- `eautocharge_hours_float`: EV charging schedule (0-1)
+- `eautocharge_hours_float`: EV charging schedule (0.0-1.0)

 #### Results

-The `result` object contains detailed information about the optimization outcome.
-The length of the array is between 25 and 48 and starts at the current hour and ends at 23:00 tomorrow.
+The `result` object contains detailed information about the optimization outcome. The length of the
+array is between 25 and 48 and starts at the current hour and ends at 23:00 tomorrow.

 - `Last_Wh_pro_Stunde`: Array of hourly load values in Wh
  - Shows the total energy consumption per hour
--- a/docs/akkudoktoreos/prediction.md
+++ b/docs/akkudoktoreos/prediction.md
@@ -8,21 +8,21 @@ optimization is executed. In EOS, a standard set of predictions is managed, incl

 - Household Load Prediction
 - Electricity Price Prediction
+- Feed In Tariff Prediction
 - PV Power Prediction
 - Weather Prediction

 ## Storing Predictions

 EOS stores predictions in a **key-value store**, where the term `prediction key` refers to the
-unique key used to retrieve specific prediction data. The key-value store is in memory. Stored
-data is lost on re-start of the EOS REST server.
+unique key used to retrieve specific prediction data.

 ## Prediction Providers

 Most predictions can be sourced from various providers. The specific provider to use is configured
 in the EOS configuration and can be set by prediction type. For example:

-```python
+```json
 {
  "weather": {
    "provider": "ClearOutside"
@@ -48,7 +48,7 @@ The prediction data must be provided in one of the following formats:

 A dictionary with the following structure:

-```python
+```json
    {
        "start_datetime": "2024-01-01 00:00:00",
        "interval": "1 Hour",
@@ -170,6 +170,26 @@ The electricity proce forecast data must be provided in one of the formats descr
 The data may additionally or solely be provided by the
 **PUT** `/v1/prediction/import/ElecPriceImport` endpoint.

+## Feed In Tariff Prediction
+
+Prediction keys:
+
+- `feed_in_tarif_wh`: Feed in tarif per Wh (€/Wh).
+- `feed_in_tarif_kwh`: Feed in tarif per kWh (€/kWh)
+
+Configuration options:
+
+- `feedintarif`: Feed in tariff configuration.
+
+  - `provider`: Feed in tariff provider id of provider to be used.
+
+    - `FeedInTariffFixed`: Provides fixed feed in tariff values.
+    - `FeedInTariffImport`: Imports from a file or JSON string.
+
+  - `provider_settings.feed_in_tariff_kwh`: Fixed feed in tariff (€/kWh).
+  - `provider_settings.import_file_path`: Path to the file to import feed in tariff forecast data from.
+  - `provider_settings.import_json`: JSON string, dictionary of feed in tariff value lists.
+
 ## Load Prediction

 Prediction keys:
--- a/docs/akkudoktoreos/resource.md
+++ b/docs/akkudoktoreos/resource.md
@@ -0,0 +1,258 @@
+% SPDX-License-Identifier: Apache-2.0
+(resource-page)=
+
+# Resources (Device Simulations)
+
+## Concepts
+
+The simulations for resources are leaning on general concepts of the [S2 standard].
+
+### Control Types
+
+The control of resources and such what a resource simulation will simulate follows three
+basic control principles:
+
+- Operation Mode Based Control (OMBC)
+- Fill Rate Based Control (FRBC)
+- Demand Driven Based Control (DDBC)
+
+Although these control principles differ enough to separate them into three distinct control types,
+there are some common aspects that make them similar:
+
+- Operation Modes
+- Transitions and
+- Timers.
+
+The objective for a control type is under which circumstances what things can be adjusted, and what
+the constraints are for these adjustments. The three control types model a virtual, abstract resource
+for simulation.
+
+The abstract resource ignores all details of pyhsical device that are not relevant to energy
+management. In addition, physical devices have an enormous variety in parameters, sensors, control
+strategies, concerns, safeguards, and so on. It would be practically impossible to develop a
+simulation that can
+understand all the parameters of all the physical devices on the market. By making the resource more
+abstract, its concepts can be translated to all sorts of physical devices, even though internally
+they function very differently. As a consequence, it not always possible to make a 100% accurate
+description of all the behaviors and constraints in these abstractions. But the abstractions used
+in the control types are quite powerful, and should allow you to come pretty close.
+
+The control types basically define how the simulated resource can be described. The user in the end
+selects the proper desciption of a physical device using the configuration options provided for
+resource simulations. The configuration sets how the simulated resource functions, what it can do and
+what kind of constraints it has.
+
+### Resource Simulation
+
+Based on the description of this virtual resource, the resource simulation can make predictions of
+what the physical device will do in certain situations, and when it is allowed to execute
+instructions generated by the optimization as part of the energy management plan evaluation.
+
+### Resource Status
+
+Once the physical device has changed it's behavior, the resource simulation should be informed
+to make the simulation change it's state accordingly.
+
+The actual state of a pyhsical device may be reported to the resource simulation by the
+**PUT** `/v1/resource/status` API endpoint.
+
+## Battery
+
+There is a wealth of possible battery operation modes:
+
+<!-- pyml disable line-length -->
+| Mode                      | Purpose / Behavior                                                                      | Typical Trigger / Context                                        |
+| ------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| **IDLE**                  | Battery neither charges nor discharges (SOC stable).                                    | No active control objective or power imbalance below thresholds. |
+| **SELF_CONSUMPTION**      | Charge from PV surplus and discharge to cover local load.                               | PV generation > load (charge) or load > PV (discharge).          |
+| **NON_EXPORT**   | Charge from on-site or local surplus with the goal of minimizing or preventing energy export to the external grid. Discharging to the grid is not allowed. | Export limit reached and SOC < SOC_max.                          |
+| **PEAK_SHAVING**          | Discharge to keep grid import below a target threshold.                                 | Predicted or measured site load exceeds peak limit.              |
+| **GRID_SUPPORT_EXPORT**   | Discharge energy to grid for revenue (V2G, wholesale market, flexibility service).      | Market or signal permits profitable export.                      |
+| **GRID_SUPPORT_IMPORT**   | Charge from grid to absorb surplus or provide up-regulation service.                    | Low-price or grid-support signal detected.                       |
+| **FREQUENCY_REGULATION**  | Rapid charge/discharge response to grid frequency deviations.                           | Active participation in frequency control.                       |
+| **RAMP_RATE_CONTROL**     | Smooth site-level power ramp rates by buffering fluctuations.                           | Sudden PV/load change exceeding ramp limit.                      |
+| **RESERVE_BACKUP**        | Maintain SOC ≥ reserve threshold to ensure backup capacity.                             | Resilience mode active, grid operational.                        |
+| **OUTAGE_SUPPLY**         | Islanded operation: power local loads using stored energy (and PV if available).        | Grid failure detected.                                           |
+| **FORCED_CHARGE**         | Manual or external control command to charge (e.g., pre-event, maintenance). No discharge.  | Operator or optimizer command. |
+| **FORCED_DISCHARGE**      | Manual or external control command to discharge. No charge.                             | Operator or optimizer command.                                   |
+| **FAULT**                 | Battery unavailable due to fault, safety, or protection state.                          | Fault detected (thermal, voltage, comms, etc.).                  |
+<!-- pyml enable line-length -->
+
+The optimization algorithm, the device simulation and the configuration properties only support the
+most important of these modes.
+
+### Battery Simulation
+
+The battery simulation assumes an idealized battery model. Under this model, the battery can be
+operated in three discrete operation modes with fill rate based control (FRBC):
+
+| **Operation Mode ID**    | **Description**                                                       |
+| ------------------------ | --------------------------------------------------------------------- |
+| **SELF_CONSUMPTION**     | Charge from local surplus and discharge to cover local load.          |
+| **NON_EXPORT**           | Charge from local surplus and do not discharge.                       |
+| **FORCED_CHARGE**        | Charge.                                                               |
+
+The **operation mode factor** (0.0–1.0) specifies the normalized power rate relative to the
+battery's nominal maximum charge or discharge power. A value of 1.0 corresponds to full-rate
+charging or discharging, while 0.0 indicates no power transfer. Intermediate values scale the power
+proportionally.
+
+The **fill level** (0.0–1.0) specifies the normalized fill level relative to the
+battery's nominal maximum charge. A value of 1.0 corresponds to full while 0.0 indicates empty.
+Intermediate values scale the fill level proportionally.
+
+### Battery Configuration
+
+### Battery Stati
+
+To keep the battery simulation in synchonization with the actual stati of the battery the following
+resource stati may be reported to EOS by the **PUT** `/v1/resource/status` API endpoint.
+
+#### Battery FRBCActuatorStatus
+
+The operation mode the battery is currently operated.
+
+```json
+{
+  "type": "FRBCActuatorStatus",
+  "active_operation_mode_id": "GRID_SUPPORT_IMPORT",
+  "operation_mode_factor": "0.375",
+  "previous_operation_mode_id": "SELF_CONSUMPTION",
+  "transistion_timestamp": "20250725T12:00:12"
+}
+```
+
+#### Battery FRBCStorageStatus
+
+The current battery state of charge (SoC).
+
+```json
+{
+  "type": "FRBCStorageStatus",
+  "present_fill_level": "0.88"
+}
+```
+
+#### Battery PowerMeasurement
+
+The current power that the battery is charged or discharged with \[W\].
+
+```json
+{
+  "type": "PowerMeasurement",
+  "measurement_timestamp": "20250725T12:00:12",
+  "values": [
+    {
+      "commodity_quantity": "ELECTRIC.POWER.L1",
+      "value": "887.5"
+    },
+    {
+      "commodity_quantity": "ELECTRIC.POWER.L2",
+      "value": "905.5"
+    },
+    {
+      "commodity_quantity": "ELECTRIC.POWER.L2",
+      "value": "1100.7"
+    },
+  ]
+}
+```
+
+For symmetric (or unknown) power distribution:
+
+```json
+{
+  "type": "PowerMeasurement",
+  "measurement_timestamp": "20250725T12:00:12",
+  "values": [
+    {
+      "commodity_quantity": "ELECTRIC.POWER.3_PHASE_SYM",
+      "value": "1000"
+    }
+  ]
+}
+```
+
+## Electric Vehicle
+
+The electric vehicle is basically a battery with a reduced set of operation modes.
+
+### Electric Vehicle Instructions
+
+The electric vehicle control instructions assume an idealized EV battery model. Under this model,
+the EV battery can be operated in two operation modes:
+
+| **Operation Mode ID** | **Description**                                                         |
+| --------------------- | ----------------------------------------------------------------------- |
+| **IDLE**              | Battery neither charges nor discharges; holds its state of charge.      |
+| **FORCED_CHARGE**     | Charge at a specified power rate up to the allowable maximum.           |
+
+The **operation mode factor** (0.0–1.0) specifies the normalized power rate relative to the
+battery's nominal maximum charge power. A value of 1.0 corresponds to full-rate charging, while 0.0
+indicates no power transfer. Intermediate values scale the power proportionally.
+
+## Home Appliance
+
+The optimization algorithm supports one start of the home appliance within the optimization
+horizon.
+
+### Home Appliance Simulation
+
+### Home Appliance Configuration
+
+Home appliance to run within the optimization horizon.
+
+```json
+[
+  {
+    "device_id": "dishwasher1",
+    "consumption_wh": 2000,
+    "duration_h": 3
+  }
+]
+```
+
+Home appliance to run within a time window of 5 hours starting at 8:00 every day and another time
+window of 3 hours starting at 15:00 every day. See
+[Time Window Sequence Configuration](configtimewindow-page) for more information.
+
+```json
+[
+  {
+    "device_id": "dishwasher1",
+    "consumption_wh": 2000,
+    "duration_h": 3,
+    "time_windows": {
+      "windows": [
+        {
+          "start_time": "08:00",
+          "duration": "5 hours"
+        },
+        {
+          "start_time": "15:00",
+          "duration": "3 hours"
+        }
+      ]
+    }
+  }
+]
+```
+
+:::{admonition} Note
+:class: note
+The optimization algorithm always restricts to one start within the optimization horizon per
+energy management run.
+:::
+
+### Home Appliance Instructions
+
+The home appliance instructions assume an idealized home appliance model. Under this model,
+the home appliance can be operated in two operation modes:
+
+| **Operation Mode ID** | **Description**                                                         |
+|-----------------------|-------------------------------------------------------------------------|
+| **RUN**               | The home appliance is started and runs until the end of it's power      |
+|                       | sequence.                                                               |
+| **IDLE**              | The home appliance does not run.                                        |
+
+The **operation mode factor** (0.0–1.0) is ignored.
--- a/docs/akkudoktoreos/serverapi.md
+++ b/docs/akkudoktoreos/serverapi.md
@@ -1,4 +1,5 @@
 % SPDX-License-Identifier: Apache-2.0
+(server-api-page)=

 # Server API