NormannandGitHub
6849b731b0
### Significant changes / EOS impact The dependency bumps are mostly patch/tooling updates, but a few are worth explicit review: - **`pydantic-settings` 2.14.2 → 2.15.0 — highest runtime impact.** EOS directly subclasses `pydantic_settings.BaseSettings` for `SettingsEOS` / `ConfigEOS`, with `case_sensitive` left at its default. In 2.15.0, `case_sensitive` now also applies to init kwargs and config-file sources, so top-level setting keys are now matched case-insensitively by default where those sources previously did not behave that way. This can change how differently-cased config keys are accepted/resolved. The release also adds warnings for unresolved forward references and changes strict non-JSON env-value failures to `ValidationError`. **Recommended:** exercise JSON config loading, init/update paths, env overrides, and config round-trips. - **`tzfpy` 1.3.2 → 1.3.3 — runtime correctness change.** EOS uses `tzfpy.get_tz()` in `to_timezone()` and exposes the result through `GeneralSettings.timezone`. Queries exactly on timezone polygon borders now resolve instead of returning an empty result, and the `America/Argentina/Ushuaia` boundary is corrected. This can intentionally change timezone output for users on/near affected boundaries. - **`cachebox` 6.2.2 → 6.2.5 — runtime cache correctness/safety.** EOS uses `cachebox.LRUCache` and `cachebox.cached` for the energy-management cache. The update fixes iterator lifetime safety, LRU iterator invalidation when reads promote entries, and a potential `setdefault_with` locking issue. EOS does not appear to rely on those edge cases directly, so this is expected to be low-risk and mostly corrective; existing cache tests are the relevant regression coverage. - **`GitPython` 3.1.58 → 3.1.59 — dev/tooling security hardening.** This release blocks file-reading Git options, separate git-directory use during clone, and hardens config parsing. It appears to be a dev/docs dependency rather than EOS runtime code, but CI/tooling that intentionally passes unusual Git options could be affected. - **`pre-commit` 4.6.1 → 4.6.2 — dev-only bug fix.** Fixes a regression in Node-language hooks using npm 11.x build scripts. - **`mypy` 2.3.1, `commitizen` 4.17.1, and `types-PyYaml` stub update** are tooling/type-checking changes with no expected EOS runtime behavior change. Overall, the main compatibility focus should be **configuration handling (`pydantic-settings`)**, followed by **timezone edge cases (`tzfpy`)**. The remaining updates are primarily correctness, security, or developer-tooling fixes.
Build optimized energy management plans for your home automation
AkkudoktorEOS is a comprehensive solution for simulating and optimizing energy systems based on renewable sources. Optimize your photovoltaic systems, battery storage, load management, and electric vehicles while considering real-time electricity pricing.
Why use AkkudoktorEOS?
AkkudoktorEOS can be used to build energy management plans that are optimized for your specific setup of PV system, battery, electric vehicle, household load and electricity pricing. It can be integrated into home automation systems such as NodeRED, Home Assistant, EVCC.
🏘️ Community
We are an open-source community-driven project and we love to hear from you. Here are some ways to get involved:
-
GitHub Issue Tracker: discuss ideas and features, and report bugs.
-
Akkudoktor Forum: get direct suppport from the community.
What do people build with AkkudoktorEOS
The community uses AkkudoktorEOS to minimize grid energy consumption and to maximize the revenue from grid energy feed in with their home automation system.
- Andreas Schmitz, the Akkudoktor, uses EOS integrated in his NodeRED home automation system for OpenSource Energieoptimierung.
- Jörg, meintechblog, uses EOS for day-ahead optimization for time-variable energy prices. See: So installiere ich EOS von Andreas Schmitz
Why not use AkkudoktorEOS?
AkkudoktorEOS does not control your home automation assets. It must be integrated into a home automation system. If you do not use a home automation system or you feel uncomfortable with the configuration effort needed for the integration you should better use other solutions.
Quick Start
Run EOS with Docker (access dashboard at http://localhost:8504):
docker run -d \
--name akkudoktoreos \
-p 8503:8503 \
-p 8504:8504 \
-e OPENBLAS_NUM_THREADS=1 \
-e OMP_NUM_THREADS=1 \
-e MKL_NUM_THREADS=1 \
-e EOS_SERVER__HOST=0.0.0.0 \
-e EOS_SERVER__EOSDASH_HOST=0.0.0.0 \
-e EOS_SERVER__EOSDASH_PORT=8504 \
--ulimit nproc=65535:65535 \
--ulimit nofile=65535:65535 \
--security-opt seccomp=unconfined \
akkudoktor/eos:latest
System Requirements
- Python: 3.11 or higher
- Architecture: amd64, aarch64 (armv8)
- OS: Linux, Windows, macOS
Note
: Other architectures (armv6, armv7) require manual compilation of dependencies with Rust and GCC.
Installation
Home Assistant add-on
To install the Akkudoktor-EOS add-on in Home Assistant:
-
Add the repository URL:
In Home Assistant, go to:
Settings → Add-ons → Add-on Store → ⋮ (top-right menu) → Repositoriesand enter the URL of this Git repository:
https://github.com/Akkudoktor-EOS/EOS -
Install the add-on:
After adding the repository, the add-on will appear in the Add-on Store. Click Install.
-
Start the add-on:
Once installed, click Start in the add-on panel.
-
Access the dashboard:
Click Open Web UI in the add-on panel.
-
Configure EOS (optional): In the dashboard, go to:
Config
Docker (Recommended)
docker pull akkudoktor/eos:latest
docker compose up -d
Access the API at http://localhost:8503 (docs at http://localhost:8503/docs)
From Source
git clone https://github.com/Akkudoktor-EOS/EOS.git
cd EOS
Linux:
python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e .
.venv/bin/python -m akkudoktoreos.server.eos
Windows:
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
.venv\Scripts\pip install -e .
.venv\Scripts\python -m akkudoktoreos.server.eos
Configuration
EOS uses EOS.config.json for configuration. If the file doesn't exist, a default configuration is
created automatically.
Custom Configuration Directory
export EOS_DIR=/path/to/your/config
Configuration Methods
- EOSdash (Recommended) - Web interface at
http://localhost:8504 - Manual - Edit
EOS.config.jsondirectly - API - Use the Server API
See the documentation for all configuration options.
Port Configuration
Default ports: 8503 (API), 8504 (Dashboard)
If running on shared systems (e.g., Synology NAS), these ports may conflict with system services. Reconfigure port mappings as needed:
docker run -p 8505:8503 -p 8506:8504 ...
API Documentation
Interactive API docs available at:
- Swagger UI:
http://localhost:8503/docs - OpenAPI Spec: View Online
Resources
Contributing
We welcome contributions! See CONTRIBUTING for guidelines.
License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.