Mirrors/EOS
1
0
Fork 0
mirror of https://github.com/Akkudoktor-EOS/EOS.git synced 2026-11-13 09:13:30 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

docs(eosdash): describe the setup assistant (#1516)

Browse Source 
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>
This commit is contained in:
SchaafAlexander
2026-11-12 14:47:10 +01:00
committed by GitHub
co-authored by Claude Fable 5.2
parent fca524a913
commit 43cb0f04b2
5 changed files with 116 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+5 -7
View File
@@ -128,12 +128,9 @@ To install the **Akkudoktor-EOS** add-on in Home Assistant:
Click **Open Web UI** in the add-on panel.
5. **Configure EOS** (optional):
In the dashboard, go to:
```
Config
```
5. **Configure EOS**:
In the dashboard, go to **Setup** for the first configuration step by step, or to **Config**
for all settings.
### Docker (Recommended)
@@ -225,7 +222,8 @@ export EOS_DIR=/path/to/your/config
### Configuration Methods
1. **EOSdash** (Recommended) - Web interface at `http://localhost:8504`
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)
docs/_static/eosdash_setup.png
Vendored
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 64 KiB

docs/akkudoktoreos/setup.md
+108
View File
@@ -0,0 +1,108 @@
% SPDX-License-Identifier: Apache-2.0
(setup-page)=
# First Setup with the Setup Assistant
A freshly installed EOS runs, but it does not know your home yet: where it is, what your PV system
looks like, what electricity costs and which devices it may plan for. The **setup assistant** of
EOSdash takes you through these settings step by step.
Open EOSdash - by default at [http://localhost:8504](http://localhost:8504), or with **Open Web UI**
in the Home Assistant add-on - and select **Setup** in the menu.
![EOSdash setup assistant](../_static/eosdash_setup.png)
## How the Assistant Works
Each step consists of
- an **explanation** of the settings of the step,
- an **example**,
- a **status** that tells you what is still to do in the step,
- the **configuration cards** of the settings of the step.
The configuration cards are the same as on the **Config** page of EOSdash:
- Click a card to open it. It shows the description, the type and the default of the setting.
- Type the new value into the **update** field and press Enter, or choose a value and press **Set**.
EOS checks the value. If EOS rejects it, the card shows why.
The list at the top shows all steps. A check mark means EOS has what it needs from the step, a
warning sign means something is left to do. Click a step to go there directly, or use **Back** and
**Next**.
The assistant keeps no state of its own. It reads what is done and what is missing from the EOS
configuration. You can therefore leave it at any time, change settings on the **Config** page or by
the [server API](#server-api-page), and come back later.
:::{admonition} Note
:class: note
A changed setting is used by EOS right away. By default EOS also saves it to the EOS configuration
file on its own (`general.config_save_mode` is `AUTOMATIC`). If you set the save mode to `MANUAL`,
save the configuration in the last step of the assistant. See the
[configuration guideline](#configuration-page).
:::
## The Steps
1. **Start** explains the assistant.
2. **Location**: latitude and longitude of your home. EOS looks up the time zone from them.
3. **Horizons and energy management**: how far EOS predicts and plans ahead, whether the energy
management runs and how often. See [automatic optimization](optimauto.md).
4. **PV system**: the PV forecast provider and what it needs, e.g. the planes of your PV system. See
[predictions](#prediction-page).
5. **Weather**: the weather forecast provider.
6. **Prices and fees**: the electricity price, the fees added to it and the feed-in tariff.
7. **Load**: the forecast of your consumption.
8. **Devices**: batteries, inverters, electric vehicles and home appliances, and the size of each
unit. See [battery configuration](resource.md#battery-configuration) and
[inverter profiles](#inverter-profiles).
9. **Measurements**: how the current state of charge and the meter readings get to EOS, and the
choice of the adapter. See [measurements](#measurement-page) and the
[Node-RED adapter](#adapter-nodered-page).
10. **Home Assistant**: what EOS reads from and writes to Home Assistant, with a template sensor
and an automation as example. See the [Home Assistant adapter](#adapter-homeassistant-page).
11. **Finish** shows the status of all steps and a button to save the configuration.
You do not need every step. Skip the **PV system** step if you have no PV system, the **Home
Assistant** step if you do not use Home Assistant, and set up only the devices you have.
## Things to Know
- **The energy management is off by default.** Outside of Home Assistant `ems.mode` is `DISABLED`
and EOS neither predicts nor optimizes on its own. Set it to `OPTIMIZATION` in the step **Horizons
and energy management**. `PREDICTION` only updates the predictions, which is useful while you are
still setting up the forecasts.
- **Market prices come without fees.** The market price providers deliver the raw price. Add your
fees per kWh and the VAT with the electricity fee provider in the step **Prices and fees**.
- **The packaged device profiles know no size.** Batteries, electric vehicles and inverters take
their technical data from a profile (`generic-lfp`, `generic-hybrid` by default), which the
**Profiles** page of EOSdash shows and edits. These generic profiles have no capacity and no
nominal power, so set `profile_adjustment.nominal_capacity_wh` for each battery and electric
vehicle and `profile_adjustment.nominal_power_w` for each inverter. The step **Devices** reports
a unit without a size.
- **The state of charge is a factor.** The measurement `<device_id>-soc-factor` of a battery or an
electric vehicle goes from `0.0` (empty) to `1.0` (full), not from 0 to 100.
- **The state of charge must be fresh.** The GENETIC optimization does not use a state of charge
older than `optimization.genetic.measurement_max_age_seconds` (300 seconds by default) and then
plans with an empty battery.
- **The status of the Measurements step only looks at the configuration.** The assistant does not
check whether measurements actually arrive at EOS. If your own system sends the state of charge
with `PUT /v1/measurement/value` and no adapter is selected, the step keeps reporting that no
source for the state of charge is known - you can ignore this. The other way round, a step
without a warning does not prove that the state of charge arrives: the **Home Assistant** step
only checks that an entity is mapped, not that it delivers a value. Look at the **Plan** page or
the EOS log to see whether EOS plans with the real state of charge.
- **The Home Assistant adapter needs the add-on.** It reaches Home Assistant only when EOS runs as
a Home Assistant add-on; there is no setting for an address or a token. If EOS runs elsewhere,
let Home Assistant send the measurements with `PUT /v1/measurement/value`, e.g. with a
`rest_command`.
- **EOS does not switch your devices.** With the Home Assistant adapter EOS writes its instruction
for a device to the entity `sensor.eos_<device_id>`. An automation in Home Assistant has to act
on it.
## After the Setup
Look at the **Prediction** page of EOSdash to check the forecasts and at the **Plan** page for the
result of the optimization. All settings, including those the assistant does not show, are on the
**Config** page and described in the [configuration guideline](#configuration-page).
docs/develop/getting_started.md
+2 -1
View File
@@ -49,7 +49,8 @@ export EOS_DIR=/path/to/your/config
There are three ways to configure AkkudoktorEOS:
1. **EOSdash (Recommended)** - The easiest method is to use the web-based dashboard at
[http://localhost:8504](http://localhost:8504)
[http://localhost:8504](http://localhost:8504). Its [setup assistant](#setup-page) takes you
through the first configuration step by step.
2. **Manual editing** - Create or edit the `EOS.config.json` file directly in your preferred text
editor
docs/index.md
+1
View File
@@ -28,6 +28,7 @@ develop/getting_started.md
develop/CONTRIBUTING.md
develop/install.md
akkudoktoreos/setup.md
akkudoktoreos/configuration.md
develop/update.md
akkudoktoreos/upgrade-genetic.md