EOS/docs/akkudoktoreos/setup.md

% 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).