openems icon indicating copy to clipboard operation
openems copied to clipboard
Published 2 months ago • verified publisher icon OpenEMS

Docs: Getting Started Guide for Newbies

Open janklostermann opened this issue 1 month ago • 10 comments

This is a new Getting Started for Newbies guide, as inspired by the conversation at https://community.openems.io/t/aller-anfang-ist-schwer/5667. It is supposed to help someone completely new to OpenEMS to get a first user experience, even if not daring to start developing - to get a first familiarity with the system.

As I am still new to OpenEMS myself, I might be able to take care of pain-points of newbies. But it also means, that I made some assumptions here and there, that might not be fully correct. Please be aware and fix.

I have integrated @DerWahreKlinki 's script for a setup without docker. It might need a better place for it.

One strange thing I had to do: Make the factor in the datasource2 for the non-regulated consumption negative (-10000) to achieve positiv consumption in the example. I hope that makes sense. If not, please fix.

Beyond that: I wanted to explain, what the colored ring segments of the energy meter mean, but I could not find out myself...

TL;DR: There is still room for improvement. Thanks for considering anyhow.

janklostermann avatar Dec 07 '25 14:12 janklostermann

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests.

Additional details and impacted files 
@@              Coverage Diff              @@
##             develop    #3468      +/-   ##
=============================================
- Coverage      59.43%   59.42%   -0.00%     
  Complexity       112      112              
=============================================
  Files           2912     2912              
  Lines         125401   125401              
  Branches        9394     9394              
=============================================
- Hits           74516    74506      -10     
- Misses         48054    48058       +4     
- Partials        2831     2837       +6
:rocket: New features to boost your workflow:
  • :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • :package: JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

codecov[bot] avatar Dec 07 '25 14:12 codecov[bot]

to make the PR name a bit shorter I move the reference here: This PR is following my proposal in https://community.openems.io/t/aller-anfang-ist-schwer/5667/22

janklostermann avatar Dec 07 '25 15:12 janklostermann

Hi @janklostermann, thanks for the contribution. Did you already check PR #3268? Do your changes relate or overlap with it?

da-Kai avatar Dec 12 '25 06:12 da-Kai

@da-Kai As far as I can see, there is no overlap, as this contribution here is not addressing developers, but starting users (quasi a pre-Getting-Started, to get familiar with the system, with an invitation at the end to consider contributing as developer, or otherwise), while the other is solely focused on getting a develpment environment up and running. I didn't touch the existing Getting-Started guide. The proposed changes might result in some link/xref-changes, which would need to be resolved, depending on which gets merged first.

janklostermann avatar Dec 14 '25 19:12 janklostermann

I can see your point and understand why it can seem to be mainly identical. And it misses the point I wanted to make. It's definitely not about docker vs. jar.

My intention was significantly different to how I experienced the existing Getting Started. The existing seemed to me more like getting prepared to develop - not to explain the usage of the system. But maybe this was due to the place I came from, my perspective.

With this Newbie guide I wanted to help the user to get a system up-and-running with as little hussle as possible (therefore docker), just because you need that to start with. Then the important part starts:

  • Get to a system to play with, complex enough to become relevant for someone with a desire to set-up a real system.
  • Guide the user on the path of exploration, show possibilities and potential traps...
  • How to explore the simulated system and
  • step-by-step transform it into a real system with real components.
  • (and if needed or helpful consider joining the development)

... the path of getting familiar with OpenEMS and having your own OpenEMS working for your local environment. In the end understanding the fundamental inner workings of OpenEMS and how you can make use of it to manage your real local energy system. (As I somehow missed it and where I also resonated with the original posts of the mentioned forum thread.)

If this purpose is not achieved, please let's improve it to get there.

janklostermann avatar Dec 15 '25 09:12 janklostermann

and yes, the integration into the existing docu (incl. nav.adoc) is still missing, as I wanted your feedback, on content as much as on where to put it and how to integrate it with the existing to get a consistent whole.

janklostermann avatar Dec 15 '25 09:12 janklostermann

My intention was significantly different to how I experienced the existing Getting Started. The existing seemed to me more like getting prepared to develop - not to explain the usage of the system. But maybe this was due to the place I came from, my perspective.

With this Newbie guide I wanted to help the user to get a system up-and-running with as little hussle as possible (therefore docker), just because you need that to start with. Then the important part starts:

Get to a system to play with, complex enough to become relevant for someone with a desire to set-up a real system. Guide the user on the path of exploration, show possibilities and potential traps... How to explore the simulated system and step-by-step transform it into a real system with real components. (and if needed or helpful consider joining the development)

What you describe is essentially what the existing Getting Started guide should already cover. I am also not convinced that using Docker is necessarily simpler than working with the .jar files.

My suggestion for introducing users to OpenEMS would be:

  1. Getting Started: Run a simple configuration and experiment in a purely simulated environment.
  2. Deployment: Set up a deployment (via Docker or actual hardware) for longer-running tests.
  3. Development: Dive into development once the user is comfortable with the setup.

Your current draft feels like it sits somewhere between steps 1 and 2.

I would suggest extending the Getting Started guide if needed and creating a separate Deployment/Installation guide that explains an OpenEMS setup and links to the relevant deploy.adoc files.

Are we aligned on this?

da-Kai avatar Dec 15 '25 16:12 da-Kai

Regarding Docker: Simply running docker compose up -d in a folder with the provided docker-compose.yml to me seems the simplest possible way to get Edge and UI up and running. No Eclipse, no Java installation, no node and angular - no development environment: Too many points of variability and potential mistakes.

To provide the user with a playground (and a fast first success feeling), a simple but complete working config (with simulators) could be provided for a start. That could make your Step 1 very easy reachable. Building the config by hand has the advantage of showing/learning more about the system's mechanics early on, with an effort I find ok. Therefore I would leave that in, maybe providing an option of a shortcut of loading the (provided) config, which would also have the advantage of a safety net, if it does not work due to whatever mistakes. -> But is this not already basic deployment?

I would suggest the following steps:

  1. Get up and running, incl. a working (simulation) configuration (easiest possible deployment with least errors to be made) - the step I spoke about above
  2. Experimenting with that environment - showing around, what can you do, where can you find which information (live, history, ...), ways to interact with the system and where the information comes from (just naming roughly - just the source, not the path).
  3. Transforming that system into a real system (by replacing it with components connected to physical devices) - explaining the underlying concepts of components, bridges, channels. The explanations short (but more detailed than in 2), introducing the concepts of the underlying dataflow - what is done where, which parts are involved.
  4. What to do if it doesn't "just work"? Finding components that get your physical devices connected (maybe already step 3), debugging strategies for non-programmers (log, channel view, REST-API?, ...)
  5. Outlook to really diving into the system internals, debugging with dev-tools, possibilities of contributing as developer, tester, documenter/communicator, ...

To avoid the repelling of non-programmers, I would keep out deployment alternatives and setting up the dev environment, as provided in the current GettingStarted and provide that elsewhere, but linked. I would leave the Getting started completely on the user level. (Maybe a separate GettingStarted for Devs, building upon the system understanding build up in the GettingStarted for Users, focussing on what you need to start developing in OpenEMS, integrating the guide for building a device, maybe enhancing the UI part.) If the first step with the system is setting up an IDE like Eclipse and Java, many non-programmers might already say "That's not for me.", never actually seeing the system running. It leaves the impression OpenEMS is a system for programmers, not users or system builders. (A question I have seen in the forum as well, without a clear answer.) Or is that selection of people that what you want to achieve?

janklostermann avatar Dec 16 '25 08:12 janklostermann

Regarding Docker: Simply running docker compose up -d in a folder with the provided docker-compose.yml to me seems the simplest possible way to get Edge and UI up and running. No Eclipse, no Java installation, no node and angular - no development environment: Too many points of variability and potential mistakes.

That is true if you already have Docker installed and are familiar with it. For beginners, however, Docker introduces an additional layer that can be confusing on its own.

I would suggest using the prebuilt artifacts attached to each release: https://github.com/OpenEMS/openems/releases/latest. This way, users only need a Java installation and a simple HTTP server to get everything running.

To provide the user with a playground (and a fast first success feeling), a simple but complete working config (with simulators) could be provided for a start. That could make your Step 1 very easy reachable. Building the config by hand has the advantage of showing/learning more about the system's mechanics early on, with an effort I find ok. Therefore I would leave that in, maybe providing an option of a shortcut of loading the (provided) config, which would also have the advantage of a safety net, if it does not work due to whatever mistakes.

In many projects, this is solved by offering a running, read-only preview environment. I’m not sure whether this is feasible here, but it might be worth discussing.

-> But is this not already basic deployment?

I would suggest the following steps:

Get up and running, incl. a working (simulation) configuration (easiest possible deployment with least errors to be made) - the step I spoke about above Experimenting with that environment - showing around, what can you do, where can you find which information (live, history, ...), ways to interact with the system and where the information comes from (just naming roughly - just the source, not the path). Transforming that system into a real system (by replacing it with components connected to physical devices) - explaining the underlying concepts of components, bridges, channels. The explanations short (but more detailed than in 2), introducing the concepts of the underlying dataflow - what is done where, which parts are involved. What to do if it doesn't "just work"? Finding components that get your physical devices connected (maybe already step 3), debugging strategies for non-programmers (log, channel view, REST-API?, ...) Outlook to really diving into the system internals, debugging with dev-tools, possibilities of contributing as developer, tester, documenter/communicator, ...

To avoid the repelling of non-programmers, I would keep out deployment alternatives and setting up the dev environment, as provided in the current GettingStarted and provide that elsewhere, but linked. I would leave the Getting started completely on the user level. (Maybe a separate GettingStarted for Devs, building upon the system understanding build up in the GettingStarted for Users, focussing on what you need to start developing in OpenEMS, integrating the guide for building a device, maybe enhancing the UI part.) If the first step with the system is setting up an IDE like Eclipse and Java, many non-programmers might already say "That's not for me.", never actually seeing the system running. It leaves the impression OpenEMS is a system for programmers, not users or system builders. (A question I have seen in the forum as well, without a clear answer.)

The current Getting Started already skips most of the setup by referring to the separate developer guide: https://openems.github.io/openems.io/openems/latest/development/overview.html

However, i just noticed the UI setup is currently missing, which breaks the otherwise clean separation and should be addressed.

da-Kai avatar Dec 17 '25 10:12 da-Kai

Starting backwards:

  • The UI setup is not missing. It's included in the docker compose -d. That's what makes it so appealing to me: Installing docker, running the command and all ready to go. (Or do I miss functionality that I have not seen yet? I worked through the guide step-by-step and it worked.)
  • I enjoyed that the existing GettingStarted already cares for a smooth path to get up and running and separate out the distracting variables and details. But to my perception it still sets up an environment aimed for a developer, not a user: Eclipse & Java instead of setup.exe (Docker is the closest platform independent way to go on a local machine, that I can see right now. And yes, Docker can be confusing, but you can guide people quite good towards a running system, without the need to understand the heavy lifting in the background - almost no-one knows what it needs behind the scenes to start e.g. Google Docs.)
  • Having a pre-configured Live-System in the cloud could provide a very first contact with the system, but to my understanding compromises a fundamental value of OpenEMS users: having a locally run system. Therefore the step of early local deployment is needed anyhow, I guess. And yes, the OpenEMS gitpod-dev-deployment was very helpful for me to get started and keep the morale up, as I could not get it up and running locally at first... Therefore this could definitely an additional path, but not a substitute, I think.
  • The pre-built artefacts could indeed be an alternative to the docker path, but I think only, if they are accompanied by a script that makes them fly. If I see these artefacts as a non-programmer/user, I do not see what to do with them. Nothing familiar, and even with explanation: too many steps to go, where every step I can make mistakes or things get out-dated and do not fit anymore, and nobody beside me to get around them. (Even the most helpful forum cannot not provide instant help.)

janklostermann avatar Dec 17 '25 10:12 janklostermann

The way your current doc is written i would argue that if someone is tech-savvy enough, to setup linux and use the bash shell, they should be able to work with artifacts like .jar or .zip.

If one manged to setup, by only following docs and AI-generated instructions, they are likely to hit a wall sooner rather than later.

The only genuinely easy alternatives I see would be setting up via Docker Desktop or actually providing portable .exe and .AppImage files.

da-Kai avatar Dec 17 '25 12:12 da-Kai

I agree, if the whole process needed is something like (just out of memory to illustrate my point, not tested through):

  • follow the guide to install your RaspberryPi, then open terminal and sudo apt update && sudo apt upgrade
  • sudo apt install docker
  • mkdir myopenems && cd myopenems && git clone https://github.com/OpenEMS/openems.git
  • cd openems/tools/docker/edge/ && docker up -d`
  • open you browser and go to http://localhost:8080/system/console/configMgr for Edge and http://localhost:4200/ for UI

No strings attached. It should not be much more complicated than sending of these commands. And there should not be trouble with things not working together. (And yes, cloning the whole project is not needed for that... The docker-compose.yml would be sufficient. The configuration of the platform-specific config path might be missing above.) If you can achieve that with the artefacts, fair enough... (Actually, I do have my doubts, as I cannot remember having seen it working without quirks. Might be due to mental bias ;-))

janklostermann avatar Dec 17 '25 12:12 janklostermann