Getting Started

This quick 'Getting Started' should help you setup up a complete development environment. On finishing you will have a working instance of OpenEMS Edge, with simulated energy storage and photovoltaic system, as well as an OpenEMS UI for monitoring the simulator inside your web browser.

1. Download the source code

  1. Download any git client and install it. Our recommendation is Sourctree by Atlassian

  2. Clone the OpenEMS git repository

    1. In Sourcetree:

      1. press FileClone

      2. enter the git repository path https://github.com/OpenEMS/openems.git

      3. select a target directory, for example C:\Users\your.user\git\openems

      4. open Advanced Settings

      5. select the branch develop

      6. and press Clone.

        Cloning the git repository using Sourcetree
        Figure 1. Cloning the git repository using Sourcetree
    2. Alternatively: with the git command line utility

      1. open a console

      2. change to the target directory

      3. execute git clone https://github.com/OpenEMS/openems.git --branch develop

  3. Git is downloading the complete source code for you.

2. Setup Eclipse IDE for OpenEMS Edge and Backend

  1. Prepare Eclipse IDE

    1. Download Java SE Development Kit 8 and install it

    2. Download Eclipse for Java , install and start it

    3. On first start you will get asked to create a workspace. Select a directory - for example C:\Users\your.user\git\openems-workspace - and press Lauch. The directory needs to be different from your source code directory selected above.

      Creating a workspace in Eclipse IDE
      Figure 2. Creating a workspace in Eclipse IDE
    4. Install BndTools in Eclipse:

      Menu: HelpEclipse Marketplace…​Find: → enter Bndtools → press Install

  2. Import OpenEMS component projects (OSGi bundles):

    Menu: FileImport…​BndtoolsExisting Bnd Workspace → Root directory: Browse…​ → select the directory with the source code - for example C:\Users\your.user\git\openemsOKFinish → "Switch to Bndtools perspective?" yes

  3. Eclipse should have successfully built OpenEMS Edge and Backend, showing no entry in Problems.

    Eclipse IDE showing 'no problems'
    Figure 3. Eclipse IDE showing 'no problems'

3. Run OpenEMS Edge and start Simulator

  1. Run OpenEMS Edge

    1. In Eclipse IDE open the project io.openems.edge.application and double click on EdgeApp.run.

      io.openems.edge.application project in Eclipse IDE
      Figure 4. io.openems.edge.application project in Eclipse IDE
    2. Click on Run OSGi to run OpenEMS Edge. You should see log outputs on the console inside Eclipse IDE.

      OpenEMS Edge initial log output
      Figure 5. OpenEMS Edge initial log output
  2. Configure and start the Simulator

    1. Open the Apache Felix Web Console Configuration .

      Login with username admin and password admin.

      Apache Felix Web Console Configuration
      Figure 6. Apache Felix Web Console Configuration
    2. Configure a Scheduler

      The Scheduler is responsible for executing the control algorithms (Controllers) and defines the OpenEMS Edge application cycle
      1. Click on "Scheduler All Alphabetically"

        Configuration of All Alphabetically Scheduler
        Figure 7. Configuration of All Alphabetically Scheduler
      2. Accept the default values and click Save

      3. You created your first instance of an OpenEMS Component with ID "scheduler0". The log shows:

        INFO [onent.AbstractOpenemsComponent] [scheduler0] Activate AllAlphabetically [edge.scheduler.allalphabetically]

        Add any other OpenEMS Components in the same way:

    3. Configure debug outputs on the console: "Controller Debug Log". The default values can be accepted without changes.

      Configuration of Controller Debug Log
      Figure 8. Configuration of Controller Debug Log

      The log shows:

      INFO [onent.AbstractOpenemsComponent] [ctrlDebugLog0] Activate DebugLog [edge.controller.debuglog],

      followed once per second by

      INFO [e.controller.debuglog.DebugLog] [ctrlDebugLog0] _sum[Ess SoC:0 %|L:0 W Grid L:0 W Production L:0 W Consumption L:0 W].

      It is once per second because you accepted the default value of "1000 ms" for "Cycle time" in the Scheduler configuration.
    4. Configure the standard-load-profile datasource using the according input file in the csv-reader: "Simulator DataSource: CSVReader". The default values can be accepted without changes. The "Source" value is already set to the right input file.

      Configuration of Simulator DataSource: CSVReader as standard load profile datasource
      Figure 9. Configuration of Simulator DataSource: CSVReader as standard load profile datasource

      The log shows:

      INFO [onent.AbstractOpenemsComponent] [datasource0] Activate CSVDatasource [edge.simulator.datasource.csv],

      The data source was configured with the OpenEMS Component ID "datasource0" which will be used in the next step as reference.
    5. 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
      Figure 10. Configuration of Simulator GridMeter Acting

      This time some more logs will show up. Most importantly they show, that the Grid meter now shows a power value.

      INFO  [onent.AbstractOpenemsComponent] [meter0] Activate GridMeter [edge.simulator.meter.grid.acting]
      [onent.AbstractOpenemsComponent] [meter0] Deactivate GridMeter [edge.simulator.meter.grid.acting]
      [onent.AbstractOpenemsComponent] [meter0] Activate GridMeter [edge.simulator.meter.grid.acting]
      [e.controller.debuglog.DebugLog] [ctrlDebugLog0] _sum[Ess SoC:0 %|L:0 W Grid L:1423 W Production L:0 W Consumption L:1423 W] meter0[1423 W]
      This setup causes the simulated grid-meter to take the standardized load-profiles data as input parameter.
      'Acting' referrs to the fact, that this meter actively provides data - in opposite to a 'Reacting' device that is reacting on other components: for example the 'Simulator.EssSymmetric.Reacting' configured below.
    6. Configure a simulated reacting energy storage system: "Simulator EssSymmetric Reacting". The default values can be accepted without changes.

      Configuration of Simulator EssSymmetric Reacting
      Figure 11. Configuration of Simulator EssSymmetric Reacting

      The log shows:

      INFO [e.controller.debuglog.DebugLog] [ctrlDebugLog0] _sum[Ess SoC:50 %|L:0 W Grid L:864 W Production L:0 W Consumption L:864 W] ess0[SoC:50 %|L:0 W|OnGrid] meter0[864 W]

      Note, that the DebugLog 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.

    7. Configure the self-consumption optimization algorithm: "Controller Balancing Symmetric". Configure the Ess-ID "ess0" and Grid-Meter-ID "meter0" to refer to the components configured above.

      Configuration of Symmetric Balancing Controller
      Figure 12. Configuration of Symmetric Balancing Controller

      The log shows:

      INFO [e.controller.debuglog.DebugLog] [ctrlDebugLog0] _sum[Ess SoC:49 %|L:1167 W Grid L:-39 W Production L:0 W Consumption L:1128 W] ess0[SoC:49 %|L:1167 W|OnGrid] meter0[-39 W]

      Note, how the Controller now tells the battery to discharge (Ess SoC:49 %|L:1167 W), trying to balance the Grid power to "0 W" (Grid L:-39 W):
    8. Configure the websocket Api Controller: "Controller Api Websocket". The default values can be accepted without changes.

      Configuration of Controller Api Websocket
      Figure 13. Configuration of Controller Api Websocket

      The log shows:

      INFO  [onent.AbstractOpenemsComponent] [ctrlApiWebsocket0] Activate WebsocketApi [edge.controller.api.websocket]
      INFO  [ler.api.websocket.WebsocketApi] [ctrlApiWebsocket0] Websocket-Api started on port [8085].
      The Controller Api Websocket is required to enable access to OpenEMS Edge by a local OpenEMS UI.

4. Setup Visual Studio Code for OpenEMS UI

  1. Download node.js LTS and install it.

  2. Download Visual Studio Code , install and start it.

  3. Open OpenEMS UI source code in Visual Studio Code:

    Menu: FileOpen directory…​ → Select the ui directory inside the downloaded source code (for example C:\Users\your.user\git\openems\ui) → Select directory

  4. Open the integrated terminal:

    Menu: ShowIntegrated terminal

  5. Install Angular CLI :

    npm install -g @angular/cli

  6. Resolve and download dependencies:

    npm install

5. Run OpenEMS UI

  1. In Visual Studios integrated terminal type…​

    ng serve

    The log shows:

    NG Live Development Server is listening on localhost:4200, open your browser on http://localhost:4200/

  2. Open a browser at http://localhost:4200

  3. You should see OpenEMS UI. Log in as user "guest" by clicking on the tick mark. Alternatively type "admin" in the password field to log in with extended permissions.

    OpenEMS UI Login screen
    Figure 14. OpenEMS UI Login screen
  4. Change to the Energymonitor by clicking on the arrow.

    OpenEMS UI Overview screen
    Figure 15. OpenEMS UI Overview screen
  5. You should see the Energymonitor showing the same data as the DebugLog output on the console.

    OpenEMS UI Energymonitor screen
    Figure 16. OpenEMS UI Energymonitor screen
    OpenEMS UI will complain that "no timedata source is available". Because of this the historic chart is not yet functional.

6. Connect the Edge App to the Backend and transfer data to the Backend

  1. Start the Backend and connect the Edge App to it

    1. Select the Backend Application in Eclipse io.openems.backend.application in eclipse project

    2. Start the Backend App Start the Backend Application in Eclipse

    3. Open the Felix Web interface of the Backend: http://localhost:8079/system/console/configMgr Username: admin, Password: admin

      1. Select the Metadata.Dummy Bundle and save it Save the Metadata.Dummy

      2. Select the EdgeWebsocket Bundle and specify the Port: e.g. 8084 Start the EdgeWebsocket to listen on port 8084

    4. Start the client connection from the Edge App in the Felix Web interface. The uri has to be changed to the backend address and port: ws://localhost:8084 Connect to Edge App to the Backend Application Server

  2. Install InfluxDB and Chronograf: https://www.influxdata.com It is recommended from the Influx Developers to use a Unix system such as Liunx, thus support for Windows is experimental: https://www.influxdata.com/blog/running-the-tick-stack-on-windows/

    1. Set up a Linux system if not already running.

    2. On Ubuntu 18.04LTS run the following commands as sudo to add the influxdata repository and install influxdb and Chronograf:

      # curl -sL https://repos.influxdata.com/influxdb.key | apt-key add -

      # source /etc/lsb-release

      # echo "deb https://repos.influxdata.com/${DISTRIB_ID,,} ${DISTRIB_CODENAME} stable" | tee /etc/apt/sources.list.d/influxdb.list

      # apt update && apt install influxdb chronograf

      # systemctl enable influxdb

      # systemctl start influxdb

      # systemctl enable chronograf

      # systemctl start chronograf

  3. Start data local data collection in the Edge App

    1. Open the installed Chronograf in the Web Browser: http://IP:8888 and set up a new Influx Database with the InfluxDB Admin Section in Chronograf for the Edge Application: OpenEMS. A newly installed Chronograf ask for username and password: use User: admin Password: admin

    2. Set up the connection to the InfluxDB in the Felix Web Interface in the Edge App. Enter the IP of the InfluxDB System. The standard port for Influx is 8086. Enter admin as Username and Password and specify the Database for the Edge OpenEMS. Configure the Edge Influx Connection Now in Chronograf the Data Explorer can be used to inspect the collected data of the Edge App

  4. Enable the Backend to save data as well

    1. Set up a new database in Chronograf: OpenEMSBackend

    2. Set up the connection the Backend Felix Web Interface: Configure the Backend Influx Connection

As there is now a connection between the backend and edge component as well as database connections on both ends the data is now transferred into the backend influx database.