= Getting Started
:imagesdir: ../assets/images
:sectnums:
:sectnumlevels: 4
:toclevels: 4
:experimental:
:keywords: AsciiDoc
:source-highlighter: highlight.js
:icons: font

The Getting Started guide will show you how to run https://github.com/OpenEMS/openems/releases/[pre-built OpenEMS versions] and complete basic configuration tasks. You will learn how to run a simulated PV + battery system in OpenEMS Edge, use OpenEMS UI to monitor your instance and optionally integrate the OpenEMS Backend for remote monitoring.

We also provide https://hub.docker.com/u/openems[Docker images] as a convenient way to try out OpenEMS if you are familiar with container environments. How to run these images will not be covered in detail in this guide. However, many of the configuration steps will be the same as described below.

NOTE: If you want to actively develop and extend OpenEMS, follow the xref:development/overview.adoc[developer guide] to setup a development environment.

[IMPORTANT]
====
This setup is intended for testing purposes only. It is not recommended to run OpenEMS in production this way.

To use OpenEMS in production, choose one of the following options:

* Deploy OpenEMS Edge to xref:edge/deploy/systemd.adoc[Debian/Ubuntu] or to xref:edge/deploy/docker.adoc[Docker]
* Deploy OpenEMS Backend to xref:backend/deploy/systemd.adoc[Debian/Ubuntu] or to xref:backend/deploy/docker.adoc[Docker]
====

== Install Java

OpenEMS requires Java 21 to run. If it is not pre-installed on your system, we recommend using https://adoptium.net/de/temurin/releases?version=21[Eclipse Temurin by Adoptium].

You can check the installed version by running the following command from your terminal:

```
java -version
```

The output should look similar to this:

```
openjdk version "21.0.8" 2025-07-15 LTS
OpenJDK Runtime Environment Temurin-21.0.8+9 (build 21.0.8+9-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.8+9 (build 21.0.8+9-LTS, mixed mode, sharing)
```

== OpenEMS Edge

OpenEMS Edge is the actual energy management system running on your local device. It is the first component that you will set up.

=== Running the pre-built OpenEMS Edge

. Go to the https://github.com/OpenEMS/openems/releases/[OpenEMS release page] on GitHub and download the latest `openems-edge.jar`.
. Open up your Terminal and go to the directory you downloaded the packages to.
. Start OpenEMS Edge with the following command `java -jar openems-edge.jar`

If OpenEMS Edge starts successfully, you should see the below warning in the log. That is perfectly fine! We will take care of this in a moment when we configure your new instance.

```
WARN  [ms.edge.core.cycle.CycleWorker] [_cycle] There are no Schedulers configured!
```

=== Basic configuration

. Open the http://localhost:8080/system/console/configMgr[Apache Felix Web Console Configuration icon:external-link[]]
+
Login with username *admin* and password *admin*.
+
.Apache Felix Web Console Configuration
image::apache-felix-console-configuration.png[Apache Felix Web Console Configuration]

. Configure a Scheduler
+
NOTE: The Scheduler is responsible for executing the control algorithms (Controllers) in order and defines the OpenEMS Edge application cycle

.. Click on _**Scheduler All Alphabetically**_
+
.Configuration of All Alphabetically Scheduler
image::config-scheduler-all-alphabetically.png[Configuration of All Alphabetically Scheduler]

.. Accept the default values and click btn:[Save]

.. You created your first instance of an OpenEMS Component with ID "scheduler0". The log shows:
+
```
INFO  [onent.AbstractOpenemsComponent] [scheduler0] Activate Scheduler.AllAlphabetically
```
+
Add any other OpenEMS Components in the same way.
+
NOTE: Once everything is setup you can configure Components more easily via OpenEMS UI using the "Install components" feature in the Settings.

. Configure debug outputs on the console: _**Controller Debug Log**_. The default values can be accepted without changes.
+
.Configuration of Controller Debug Log
image::config-controller-debug-log.png[Configuration of Controller Debug Log]
+
The log shows:
+
```
INFO  [onent.AbstractOpenemsComponent] [ctrlDebugLog0] Activate Controller.Debug.Log
```
+
followed once per second by
+
```
INFO  [ntroller.debuglog.DebugLogImpl] [ctrlDebugLog0] _sum[State:Ok]
```
+
NOTE: It is 'once per second', because the Cycle-Time is defined as "1000 ms" by default. Adjust the setting in the _**Core Cycle (Core.Cycle)**_ component to change this.

. Configure the websocket Api Controller: _**Controller Api Websocket**_. The default values can be accepted without changes.
+
.Configuration of Controller Api Websocket
image::config-controller-api-websocket.png[Configuration of Controller Api Websocket]
+
The log shows:
+
```
INFO  [onent.AbstractOpenemsComponent] [ctrlApiWebsocket0] Activate Controller.Api.Websocket
INFO  [socket.AbstractWebsocketServer] Starting [Websocket Api] websocket server [port=8085]
```
+
NOTE: The Controller Api Websocket is required so that OpenEMS UI can connect to OpenEMS Edge locally.

=== Starting a simulation

. Configure a simulated standard-load-profile datasource using _**Simulator DataSource: CSV Predefined**_. Select `H0_HOUSEHOLD_SUMMER_WEEKDAY_STANDARD_LOAD_PROFILE` as the `Source`.
+
.Configuration of Simulator DataSource: CSV Predefined as standard load profile datasource
image::config-simulator-datasource-standard-load-profile.png[Configuration of Simulator DataSource: CSV Predefined as standard load profile datasource]
+
The log shows:
+
```
INFO  [onent.AbstractOpenemsComponent] [datasource0] Activate Simulator.Datasource.CSV.Predefined
```
+
NOTE: The data source was configured with the OpenEMS Component ID `datasource0` which will be used in the next step as the `Datasource-ID` reference.

. Configure a simulated grid meter: _**Simulator GridMeter Acting**_. Configure the `Datasource-ID 'datasource0'` to refer to the data source configured above.
+
.Configuration of Simulator GridMeter Acting
image::config-simulator-grid-meter-acting.png[Configuration of Simulator GridMeter Acting]
+
This time some more logs will appear. Most importantly they show, that the Grid meter now measures (simulates) a power value and the Consumption is derived directly from this value, because no PV system or energy storage system is configured yet.
+
```
INFO  [onent.AbstractOpenemsComponent] [meter0] Activate Simulator.GridMeter.Acting
INFO  [onent.AbstractOpenemsComponent] [meter0] Deactivate Simulator.GridMeter.Acting
INFO  [onent.AbstractOpenemsComponent] [meter0] Activate Simulator.GridMeter.Acting
INFO  [ntroller.debuglog.DebugLogImpl] [ctrlDebugLog0] _sum[State:Ok Grid:1336 W Consumption:1336 W] meter0[1336 W]
```
+
NOTE: This setup causes the simulated grid-meter to take the standardized load-profiles data as input parameter.
+
NOTE: 'Acting' in the name 'Simulator GridMeter Acting' refers to the fact, that this meter actively provides data - in opposite to a 'Reacting' simulated device that is reacting on other components: for example the 'Simulator.EssSymmetric.Reacting' configured below.

. Configure a simulated reacting energy storage system: _**Simulator EssSymmetric Reacting**_. The default values can be accepted without changes.
+
.Configuration of Simulator EssSymmetric Reacting
image::config-simulator-esssymmetric-reacting.png[Configuration of Simulator EssSymmetric Reacting]
+
The log shows:
+
```
INFO  [onent.AbstractOpenemsComponent] [ess0] Activate Simulator.EssSymmetric.Reacting
INFO  [ntroller.debuglog.DebugLogImpl] [ctrlDebugLog0] _sum[State:Ok Ess SoC:50 % Grid:1560 W Consumption:1560 W] ess0[SoC:50 %|L:UNDEFINED] meter0[1560 W]
INFO  [ntroller.debuglog.DebugLogImpl] [ctrlDebugLog0] _sum[State:Ok Ess SoC:50 %|L:0 W Grid:1502 W Consumption:1502 W] ess0[SoC:50 %|L:0 W] meter0[1502 W]
```
+
NOTE: The debug log now shows data for the battery, but the charge/discharge power stays at "0 W" and the state of charge stays at "50 %" as configured. Next step is to configure a control algorithm that tells the battery to charge or discharge depending on the power measured by the simulated grid meter.

. Configure the self-consumption optimization algorithm: _**Controller Ess Balancing**_. Configure the `Ess-ID` `'ess0'` and `Grid-Meter-ID` `'meter0'` to refer to the components configured above.
+
.Configuration of Controller Ess Balancing
image::config-controller-ess-balancing.png[Configuration of Controller Ess Balancing]
+
The log shows:
+
```
INFO  [onent.AbstractOpenemsComponent] [ctrlBalancing0] Activate Controller.Symmetric.Balancing
...
INFO  [ntroller.debuglog.DebugLogImpl] [ctrlDebugLog0] _sum[State:Ok Ess SoC:50 %|L:593 W Grid:15 W Consumption:608 W] ess0[SoC:49 %|L:593 W|DebugSetActivePower:593 W] meter0[15 W]
```
+
NOTE: Values will differ slightly for you, but note how the Controller now tells the battery to discharge (`Ess SoC:49 %|L:593 W`), trying to balance the Grid power to "0 W" (`Grid L:15 W`):

== Run OpenEMS UI

NOTE: If you plan to actively develop on OpenEMS UI, you can now also setup a development environment for it using xref:ui/setup-ide.adoc[this guide]. Otherwise you can use the prebuilt UI as described below, or xref:ui/deploy/docker.adoc[deploy the OpenEMS UI as docker image].

. To use the prebuilt UI, go to the https://github.com/OpenEMS/openems/releases/[OpenEMS release page] on GitHub and download the latest `openems-ui.tar.xz`. Extract it to a local directory.

. Set up a web server serving this directory on port 4200 and start it. Any web server can be used. You can find information on how to set up the nginx webserver xref:ui/deploy/nginx.adoc[here].

. Make sure OpenEMS Edge is running locally, and the port of the websocket matches the port the UI is expecting. For the prebuilt UI it is port `8075`.

. Open the UI URL, e.g. http://localhost:4200. If the UI is running on a remote machine, replace `localhost` by the IP address of that machine.

. You should see OpenEMS UI. Log in as user "guest" by leaving the standard password and clicking the login button. Alternatively type "admin" in the password field to log in with extended permissions.
+
.OpenEMS UI Login screen
image::openems-ui-login.png[OpenEMS UI Login screen]

. You should see the Energymonitor showing the same data as the DebugLog output on the console.
+
.OpenEMS UI Energymonitor screen
image::openems-ui-edge-overview.png[OpenEMS UI Energymonitor screen]

.OpenEMS UI Energymonitor screen
image::openems-ui-edge-overview2.png[OpenEMS UI Energymonitor screen]

== Integrate OpenEMS Backend

Instead of having Edge and UI talk to each other directly, the communication can also be proxied via Backend.

=== Running the pre-built OpenEMS Backend

. Go to the https://github.com/OpenEMS/openems/releases/[OpenEMS release page] on GitHub and download the latest `openems-backend.jar`.
. Open up your Terminal and go to the directory you downloaded the packages to.
. Start OpenEMS Backend with the following command `java -jar openems-backend.jar`

=== Configure OpenEMS Backend

. Open the http://localhost:8079/system/console/configMgr[Apache Felix Web Console Configuration icon:external-link[]].
+
NOTE: Apache Felix Web Console for OpenEMS Backend is started on port 8079 by default. This is configured using the `org.osgi.service.http.port` setting in BackendApp.bndrun.
+
Login with username *admin* and password *admin*.

. Configure Edge.Websocket
+
NOTE: The _**Edge.Websocket**_ service is responsible for the communication between OpenEMS Backend and OpenEMS Edge.
+
In the example we are configuring the `Port '8081'`. This port needs to match with what we configure later in OpenEMS Edge. The `Debug Mode 'DETAILED'` setting helps us to get some more details on the internal behaviour. 
+
.Configuration of Backend Edge.Websocket
image::config-backend-edge.websocket.png[Configuration of Backend Edge.Websocket]

. Configure Ui.Websocket
+
NOTE: The _**Ui.Websocket**_ service is responsible for the communication between OpenEMS Backend and OpenEMS UI.
+
In the example we are configuring the `Port '8082'`. This port needs to match with what we configure later in the OpenEMS UI environment file. We are again setting `Debug Mode 'DETAILED'`
+
.Configuration of Backend Ui.Websocket
image::config-backend-ui.websocket.png[Configuration of Backend Ui.Websocket]

. Configure Timedata
+
NOTE: The *Timedata* service provider is responsible for holding the current and historic data of each connected Edge device.
+
In the example we are configuring the _**Timedata.Dummy**_ service. The default value for _Component-ID` can be accepted without changes, so just press btn:[Save]. In a production system you would want to use a real implementation like *Timedata.InfluxDB*.
+
.Configuration of Backend Timedata.Dummy
image::config-backend-timedata.dummy.png[Configuration of Backend Timedata.Dummy]

. Configure Metadata
+
NOTE: The *Metadata* service provider is responsible for authentication of Edge devices and Users connecting via UI.
+
.Configuration of Backend Metadata.Dummy
image::config-backend-metadata.dummy.png[Configuration of Backend Metadata.Dummy]
+
NOTE: In the example we are configuring the _**Metadata.Dummy**_ service. It takes no configuration parameters, so just press btn:[Save]. In a production system you would want to use a real implementation like _**Metadata.File**_, which uses a static JSON file as input, or _**Metadata.Odoo**_, which uses the *Odoo* business software for authentication and IoT device management. This will require the https://github.com/OpenEMS/odoo-openems[Odoo-OpenEMS-Addon] to be installed on your Odoo instance. See the https://gitpod.io/#https://github.com/OpenEMS/openems/tree/main[OpenEMS Live-Demo Gitpod workspace] for a full, production ready example configuration. For more information see → xref:simulation/gitpod.adoc[Gitpod Workspace]

. Backend is ready
+
You should have seen some important log messages by now, that indicate that the OpenEMS Backend is ready to accept connections:
```
INFO  [d.timedata.dummy.TimedataDummy] [Timedata.Dummy] Activate
INFO  [d.metadata.dummy.MetadataDummy] [Metadata.Dummy] Activate
INFO  [socket.AbstractWebsocketServer] [Ui.Websocket] Starting websocket server [port=8082]
INFO  [socket.AbstractWebsocketServer] [Edge.Websocket] Starting websocket server [port=8081]
```

=== Configure OpenEMS Edge

Next we will configure OpenEMS Edge to connect to the OpenEMS Backend _**Edge.Websocket**_ service. 

. Switch back to the http://localhost:8080/system/console/configMgr[Apache Felix Web Console Configuration for OpenEMS Edge icon:external-link[]].

. Configure the _**Controller Api Backend**_ Component. The default values can be accepted without changes right now.
+
.Configuration of Controller Api Backend
image::config-controller-api-backend.png[Configuration of Controller Api Backend]
+
Some configuration parameters are still noteworthy here:
+
.. _Apikey_ is used to authenticate this Edge at the Backend Metadata service. It has to be unique for each Edge.
.. _Uri_ is set to `ws://localhost:8081`. This defines an unencrypted websocket (`ws://`) connection to the local computer on port `8081` like we configured before for the _**Edge.Websocket**_. For a production setup you would want to use a TLS encrypted websocket with a `wss://` uri.
+
Once you press btn:[save] you should see logs in OpenEMS Edge
+
```
INFO  [onent.AbstractOpenemsComponent] [ctrlBackend0] Activate Controller.Api.Backend
INFO  [socket.AbstractWebsocketClient] [ctrlBackend0] Opening connection to websocket server [ws://localhost:8081]
INFO  [socket.ClientReconnectorWorker] [ctrlBackend0] Connecting WebSocket... [NOT_YET_CONNECTED]
INFO  [socket.ClientReconnectorWorker] [ctrlBackend0] Connected WebSocket successfully [0s]
INFO  [.controller.api.backend.OnOpen] [ctrlBackend0] Connected to OpenEMS Backend
```
+
and OpenEMS Backend
+
```
INFO  [s.backend.common.metadata.Edge] Edge [edge0]: Update version from [0.0.0] to [...]
INFO  [mon.metadata.SimpleEdgeHandler] Edge [edge0]. Update config: ...
INFO  [dgewebsocket.EdgeWebsocketImpl] [monitor] Edge-Connections: 1
```

=== Connect OpenEMS UI with Backend

_(You need to have completed the xref:ui/setup-ide.adoc[OpenEMS UI guide] for the following steps)_

. In the Visual Studio Code terminal stop the running `ng serve...` by pressing btn:[ctrl] + btn:[c]

. Restart OpenEMS UI in 'local backend mode':
+
`ng serve -c openems-backend-dev`
+
NOTE: OpenEMS UI can work both for local connections to OpenEMS Edge as well as cloud connections to OpenEMS Backend. The switch requires some basic parameters that are defined in 'environment' files `ui/src/themes/openems/environments`. The possible parameters for `ng serve -c...` are defined in the `ui/angular.json` file. 
+
. Open a browser at http://localhost:4200

. You should see OpenEMS UI Login. Log in with any email / username and password.
+
NOTE: _**Metadata.Dummy**_ accepts any user/password combination. For production use, switch to a different *Metadata* implementation as described above.
+
.OpenEMS UI Login screen
image::openems-ui-backend-login.png[OpenEMS UI Login screen]

. You will be presented an overview list of all connected OpenEMS Edge devices you have permissions for:
+
.OpenEMS UI Overview screen
image::openems-ui-backend-overview.png[OpenEMS UI Overview screen]

. Click on *OpenEMS Edge #0* to see the same live-view as before on the local connection.
+
.OpenEMS UI Live screen
image::openems-ui-backend-live.png[OpenEMS UI Live screen]

== Next steps

Congratulations! You now have a working local simulation of OpenEMS Edge, OpenEMS Backend and OpenEMS UI. We encourage you to play around with it on your own to get more familiar with how everything works.

You may want to remove the simulated components and connect real devices to OpenEMS Edge. To do this, it is recommended to setup OpenEMS using the xref:edge/deploy/systemd.adoc[deployment guide] mentioned at the top of this page. Follow the same approach that you used to add simulated components, but make sure your Edge instance has access to the devices and configure the components with needed parameters (i.e. IP address, etc.).

Alternatively, read the xref:development/overview.adoc[developer guide] to learn how to set up a development environment for OpenEMS. This will allow you to implement your own device drivers and extend OpenEMS functionality.

== Help

If you experienced any problems or doubts, please get in touch with us on the https://community.openems.io/[OpenEMS Community] forum.
