Getting started with the OGEMA SDK

Last modified by David Nestle on 2017/10/03 10:29

Set up your first project

After finishing the installation, we will take a quick tour of the SDK:

  • Go to File (top Menu Bar)->New->Project. A new dialog opens. Choose OGEMA ->App there. Only now the OGEMA SDK Plugin is started by Eclipse.
  • The plugin generates the standard rundir in the workspace (this is only done with the first start up as you usually need only one rundir even if you develop several apps that run together.
  • You can enter data as given in the screenshot below


  • Click next. On the second page you do not need any changes, on the third page select "Pattern Package" and "Use standard pattern". Select the GenericWindowContactPattern, otherwise keep default values
  • Click Finish. The SDK generates the project for you.

Recommendation: Close the views "Task List" and "Outline" on the right side of the Eclipse window. They are usually not very helpful when getting started with OGEMA and just cost you space on the screen.

Note: After creation of the project Eclipse has to build the project. During this phase the project may be marked red for errors. Wait until the status (at the right bottom of the Eclipse window) does not show "building workspace" anymore. Now Eclipse still may show several errors within the new project. To get rid of them you have to download more dependencies via MAVEN by building the project - but even if you have no errors, you have to build the project before you can start it with your rundir. Right-click on the project->Run as->Maven install, which should download everything you need. Afterwards you might need a Right click->Maven->Update project (or mark the project and press Alt+F5) to get a project without marked errors.

Your workspace should now look like this:

Eclipse initial screen


To start the run configuration for the first time, right click on stdRundir->default_clean.launch, choose Run As->default clean. Later on the run configuration will also be shown when opening run/debug in the menu icon bar at the top of the Eclipse Window (the green arrow). The first time you start the run configuration it downloads several open source binaries via MAVEN that are required to run the OGEMA framework, so be patient.

After starting the rundir you should get several messages in the Console window of Eclipse. You can now open the user web interface by entering


into the address field of a web browser of your choice. On the first start, the browser will display a message that the certificate of the page is invalid: this is a problem that occurs with every web page loaded from your own computer (address localhost) - it is not possible to create a trusted certificate for this address, but it is not a security risk either to ignore the warning. While OGEMA can be configured to run without https, in which case all data is transferred unencrypted and the warning disappears, we recommend to rather add an exception for the local site.In Firefox or Chrome click on Advanced, and proceed to localhost.

Login with the standard credentials "master / master". Now you should see the OGEMA Home Screen with several apps that are part of the standard rundir:


Understand the Resource tree and prepare the standard rundir for the first project

 From the OGEMA Home Screen open "OGEMA framework administration". Here you see all OGEMA apps installed, not only those offering a web GUI. You can perform several administration tasks on this page. Go to tab "Resource View". This presents the content of the OGEMA Database to you. Database entries are called "Resources" in OGEMA. Several top-level resources you see now are custom configuration models of apps installed (we will come back to this later).


OGEMA Framework Administration Tile in the Home Screen.

The initial resource database contains several empty configuration resources and test resources. The resource testRoom describes a room, which also has a name, type identifier, and contains a temperature sensor.


Important to understand for now:

  • Every Resource has a type, a name and a path (see right hand side of the screenshot). Furthermore, every Resource can have subresources. The path of a subresource consists of its parent's path, the path separator "/" and the resource's name. For instance, a Resource path could be "/myRoom/temperatureSensor", then a subresource named "reading" would have path "/myRoom/temperatureSensor/reading".
  • The Resource types are defined as interfaces in OGEMA; applications can define their own types as well. All resource types inherit from the base  interface Resource.
  • There are ValueResources like StringResource, FloatResource, IntegerResource, TimeResource and BooleanResource that contain the actual values, and complex resources that only define the structure of a resource (here you can see the resource 'testRoom' of type Room and 'OGEMA_GATEWAY', which has the type OGEMA_GATEWAY.
  • All data elements (subresources) within a resource interface are optional. In the resource view you only see the elements that actually have been created whereas in the interface definition for a model you see all potential data elements (it is also possible to add data elements that are not in the interface as "decorators", but we will come to this later).
  • A Resource can reference another Resource, in which case it inherits all of the relevant properties from the reference target, such as its value and its subresources.
  • You can find additional examples of resource structures with an explaination what they do in the OGEMA Model reference cases. Grabbing a screen shot from the Resouce View with the resources expanded for a documentation case is a very quick way to let others know what the relevant resource structures of your application or project are.

Note: A detailed explanation of the Resource concepts, i.e. the OGEMA database, and the Resource Patterns, can be found in OGEMA Wiki:

For Time Series special classes (RecordedData, TimeSeries) and resource types (Schedule) are provided. Details are explained on the page Time Series. Configuration of log data is described in Data Logging and Analysis, an example for using schedules is provided in the CSV sample driver.

To check all elements that are specified for a certain resource type, go to the Javadoc of the OGEMA model. Let's take the example of our "testRoom", whose type is "org.ogema.model.locations.Room". The quickest way to see the Javadoc for the model is to open the OGEMA search in Eclipse via Ctrl+H, choose tab "OGEMA Search", enter "Room" and click on "Search".


Google will show you the publicly available results in the OGEMA Javadoc:


Note that you get the latest released documentation here although Google may tell you an older version. In this case the first hit is the model documentation we are looking for, which looks like this:


Regarding the usage of extended models still under review within the OGEMA Alliance see OGEMA Alliance Extensions.


Created by Jan Lapp on 2016/06/28 11:39