mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2026-11-13 01:03:45 +01:00
43cb0f04b2
Add a how-to page for the first setup with the EOSdash setup assistant and link it from the documentation index, the getting started tutorial and the README. The status of the measurements step is derived from the configuration only. Say what that means for a system that sends the state of charge on its own. Add the new Home Assistant step to the list of steps, say that the Home Assistant adapter needs EOS to run as an add-on and that an automation has to act on the instructions, and update the screenshot to the eleven steps. The devices step of the setup assistant now asks for the size of each unit, because the packaged battery and inverter profiles are generic and give no capacity or nominal power. Say so on the setup page, point to the Profiles page and link the battery configuration and the inverter profiles. Signed-off-by: SchaafAlexander <86607129+SchaafAlexander@users.noreply.github.com> Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
262 lines
8.3 KiB
Markdown
262 lines
8.3 KiB
Markdown
|
|
|
|
|
|
**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](https://github.com/Akkudoktor-EOS/EOS/issues): discuss ideas and features,
|
|
and report bugs.
|
|
|
|
- [Akkudoktor Forum](https://www.akkudoktor.net/c/der-akkudoktor/eos): 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](https://www.youtube.com/@Akkudoktor), uses
|
|
EOS integrated in his NodeRED home automation system for
|
|
[OpenSource Energieoptimierung](https://www.youtube.com/watch?v=sHtv0JCxAYk).
|
|
- Jörg, [meintechblog](https://www.youtube.com/@meintechblog), uses EOS for
|
|
day-ahead optimization for time-variable energy prices. See:
|
|
[So installiere ich EOS von Andreas Schmitz](https://www.youtube.com/watch?v=9XCPNU9UqSs)
|
|
|
|
## 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
|
|
|
|
### Upgrading an existing installation?
|
|
|
|
The next release includes a substantial energy-planning update: 15-minute GENETIC plans,
|
|
EV departure targets, flexible household loads, optional battery export, and better
|
|
measurement and PV-forecast tools. **These features are currently unreleased.**
|
|
|
|
Existing Home Assistant automations, Node-RED flows and custom API clients may need changes.
|
|
Devices now use stable IDs, the new optimizer reads hardware settings from EOS configuration,
|
|
and incomplete forecasts or outdated battery measurements can stop a run. The legacy
|
|
`POST /optimize` remains available with GENETIC0; the new `POST /v1/optimize` has a different
|
|
request format. Back up your configuration and data before updating.
|
|
|
|
Read the [upgrade guide](docs/akkudoktoreos/upgrade-genetic.md) and
|
|
[changelog](CHANGELOG.md#unreleased) before switching an existing installation.
|
|
|
|
### Start with Docker
|
|
|
|
Run EOS with Docker (access dashboard at `http://localhost:8504`):
|
|
|
|
```bash
|
|
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
|
|
|
|
![Supports aarch64 Architecture][aarch64-shield]
|
|
![Supports amd64 Architecture][amd64-shield]
|
|
|
|
[aarch64-shield]: https://img.shields.io/badge/aarch64-yes-green.svg
|
|
[amd64-shield]: https://img.shields.io/badge/amd64-yes-green.svg
|
|
|
|
To install the **Akkudoktor-EOS** add-on in Home Assistant:
|
|
|
|
[](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2FAkkudoktor-EOS%2FEOS)
|
|
|
|
1. **Add the repository URL**:
|
|
|
|
In Home Assistant, go to:
|
|
|
|
```
|
|
Settings → Add-ons → Add-on Store → ⋮ (top-right menu) → Repositories
|
|
```
|
|
|
|
and enter the URL of this Git repository:
|
|
|
|
```
|
|
https://github.com/Akkudoktor-EOS/EOS
|
|
```
|
|
|
|
2. **Install the add-on**:
|
|
|
|
After adding the repository, the add-on will appear in the Add-on Store. Click **Install**.
|
|
|
|
3. **Start the add-on**:
|
|
|
|
Once installed, click **Start** in the add-on panel.
|
|
|
|
4. **Access the dashboard**:
|
|
|
|
Click **Open Web UI** in the add-on panel.
|
|
|
|
5. **Configure EOS**:
|
|
In the dashboard, go to **Setup** for the first configuration step by step, or to **Config**
|
|
for all settings.
|
|
|
|
### Docker (Recommended)
|
|
|
|
1. **create docker compose file**:
|
|
|
|
```yaml
|
|
services:
|
|
eos:
|
|
image: akkudoktor/eos:latest
|
|
container_name: akkudoktoreos
|
|
restart: unless-stopped
|
|
environment:
|
|
- OPENBLAS_NUM_THREADS=1
|
|
- OMP_NUM_THREADS=1
|
|
- MKL_NUM_THREADS=1
|
|
- EOS_SERVER__HOST=0.0.0.0
|
|
- EOS_SERVER__PORT=8503
|
|
- EOS_SERVER__EOSDASH_HOST=0.0.0.0
|
|
- EOS_SERVER__EOSDASH_PORT=8504
|
|
# Change this to a random secret, e.g. output of: openssl rand -hex 32
|
|
- EOS_SERVER__EOSDASH_SESSKEY=change-me
|
|
ports:
|
|
- "8503:8503" # EOS API
|
|
- "8504:8504" # EOSdash
|
|
volumes:
|
|
- ./data:/data
|
|
```
|
|
|
|
2. **create a .env file with the secret**:
|
|
|
|
```bash
|
|
echo "EOS_SESSKEY=$(openssl rand -hex 16)" > .env
|
|
```
|
|
|
|
3. **pull image and start**:
|
|
|
|
```bash
|
|
docker pull akkudoktor/eos:latest
|
|
docker compose up -d
|
|
```
|
|
|
|
4. **Access EOS**:
|
|
|
|
- API: http://localhost:8503
|
|
- API docs: http://localhost:8503/docs
|
|
- EOSdash: http://localhost:8504
|
|
|
|
Configuration and data are stored in `./data`.
|
|
|
|
> **Note:** The `docker-compose.yaml` in the repository root is intended for development
|
|
> (it builds the image locally and relies on the repository's `.env`). Use the file above
|
|
> if you only want to run the published image.
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
git clone https://github.com/Akkudoktor-EOS/EOS.git
|
|
cd EOS
|
|
```
|
|
|
|
**Linux:**
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
.venv/bin/pip install -r requirements.txt
|
|
.venv/bin/pip install -e .
|
|
.venv/bin/python -m akkudoktoreos.server.eos
|
|
```
|
|
|
|
**Windows:**
|
|
|
|
```cmd
|
|
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
|
|
|
|
```bash
|
|
export EOS_DIR=/path/to/your/config
|
|
```
|
|
|
|
### Configuration Methods
|
|
|
|
1. **EOSdash** (Recommended) - Web interface at `http://localhost:8504`, with a setup assistant
|
|
for the first configuration (menu **Setup**)
|
|
2. **Manual** - Edit `EOS.config.json` directly
|
|
3. **API** - Use the [Server API](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json)
|
|
|
|
See the [documentation](https://akkudoktor-eos.readthedocs.io/) 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:
|
|
|
|
```bash
|
|
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](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json)
|
|
|
|
## Resources
|
|
|
|
- [Full Documentation](https://akkudoktor-eos.readthedocs.io/)
|
|
- [Installation Guide (German)](https://www.youtube.com/watch?v=9XCPNU9UqSs)
|
|
|
|
## Contributing
|
|
|
|
We welcome contributions! See [CONTRIBUTING](CONTRIBUTING.md) for guidelines.
|
|
|
|
[](https://github.com/Akkudoktor-EOS/EOS/graphs/contributors)
|
|
|
|
## License
|
|
|
|
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
|