diff --git a/README.md b/README.md index 4c085d14..7d6784fb 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docs/_static/eosdash_setup.png b/docs/_static/eosdash_setup.png new file mode 100644 index 00000000..8307590a Binary files /dev/null and b/docs/_static/eosdash_setup.png differ diff --git a/docs/akkudoktoreos/setup.md b/docs/akkudoktoreos/setup.md new file mode 100644 index 00000000..f18a1c05 --- /dev/null +++ b/docs/akkudoktoreos/setup.md @@ -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 `-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_`. 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). diff --git a/docs/develop/getting_started.md b/docs/develop/getting_started.md index 20069af0..9d949f1d 100644 --- a/docs/develop/getting_started.md +++ b/docs/develop/getting_started.md @@ -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 diff --git a/docs/index.md b/docs/index.md index c1c5e70b..e2e688af 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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