Create a new project and Run it

Last modified by David Nestle on 2017/10/04 14:56

Standard options

In order to create a new OGEMA application in Eclipse, follow these steps:

  1. Go to File (top Menu Bar) -> New -> Project. A new dialog opens. Choose OGEMA -> App there. If this is the first OGEMA project in the workspace, the OGEMA SDK Plugin will be started. It creates, in particular, the project "stdRundir", which contains a run configuration for OGEMA.
  2. In the dialog that opens, enter the data as appropriate to your project (the screenshot on the right is for the window heat control app used in this tutorial). Under "Project type", choose whether a user page and/or a Resource Pattern shall be generated for your app (App with GUI, respsectively with Pattern). If you select "App with GUI", then you also need to specify an icon file for the app.
  3. Click next. On the second page you can set the Maven coordinates for the project; it is not required to make any changes there.
  4. Next: on the third page, you may want to select a Resource Pattern appropriate to the device type supported by your app. It is currently not possible to select more than one pattern type here, but you can add additional ones once the project has been generated. Select "Pattern Package" and "Use standard pattern", then identify the pattern for the desired device type.
  5. Click Finish. The SDK generates the project for you.

Eclipse-Wizard for the creation of a new OGEMA app.

Advanced Options

Besides the fields explained above, the wizard offers a few additional options. Their default choices should be fine for most apps:

  • page 1:
    • Location: here you can select where to store the new project. By default, a new folder is created in the working space directory for this purpose, but it is possible to select a different location (choose "File system" and browse to the desired location).
    • Add project to working sets: if you organized your projects into Eclipse working sets, you can specify a working set for the new app here.
  • page 2:
    • Dependencies to other OGEMA Apps: if your workspace contains further projects already, you can add them as Maven dependencies to your project.
  • page 3:
    • if your app has a GUI and/or resource pattern, you can specifiy several class names here. They can still be changed once the app has been created, by refactoring the respective class, though.
    • Model Class Name (for apps with patterns): here a known OGEMA resource type must be entered, matching the model type of the pattern. Examples are Thermostat, TemperatureSensor, Room, etc.

Add Maven dependencies

If your app requires access to some third party library, you can add a dependency in the project's pom.xml file. Dependencies should be available via Maven central (, otherwise they need to be bundled into the app. Furthermore, the dependency has to be added to the run configuration file (config.xml, see below), just like the app itself, unless it is already available in the standard run configuration. Below is an example of a dependency to OGEMA's resource-utils project; this one is available in any OGEMA run configuration, and can be safely added to a project's pom file:


In this particular case, the version could be skipped, because a default version is specified in a parent project of the apps generated by the SDK, in general they need to be included.

After adding a Maven dependency, refresh the project's Maven settings by either pressing Alt + F5, or right-click the project -> Maven -> Update project... -> Press Enter..

Build the app

Before you can run your app, it needs to be built. For this purpose, right-click on the project, select Run as -> Maven install. If there are no errors in the project, and all dependencies could be resolved, the build process should finish with a message "Build successful" in the Eclipse Console view.

When you have built your app once, and all dependencies have been downloaded by Maven, you can create a build configuration for it: right click on the project, Run as -> Maven build... A window opens, that lets you specify the build target: enter "clean install" there, and select the "Offline" and "Skip tests" checkboxes, for the most efficient build. Click "Run". The configuration will be executed and will be available for later executions from the Run and Debug menus (white arrow in green circle, respecitvely the bug symbol in the upper menu bar).


If the build fails, an error message will be printed.

Run the app

In order to run your application with OGEMA, you need to add it to the run configuration of the stdRundir project. The latter contains a subfolder config, where you can find the config.xml file. Open the file in Eclipse (after double-clicking the file, you may need to select "Show Source" in the editor, to view the actual content of the file). Add an entry to the list of bundles, of the form

<bundle dir="bin/apps" groupId="org.smartrplace.external" artifactId="example-app" version="1.0.0-SNAPSHOT" startLevel="30" />

Adapt the groupId, artifactId and version entries according to the properties in the pom.xml file of your project. Then start the rundir by right-clicking the file "default_clean.launch" -> "Run as" -> "default_clean". It may take some time on the first start until the framework is up and running (cf. the console output in the screenshot below).


Console output at first OGEMA start

Finding the Console Window and Stopping your App

To stop the execution of the Rundir you can use:

  • The red stop button in the Eclipse main menu bar or in the console ('hard stop')
  • Type 'stop 0' into the console. This will shutdown the framework gracefully and takes a bit more time than a hard stop. This way of stopping is recommended when a restart without cleaning the database is planned afterwards.

If you lost the console window of your Rundir there are two ways to get back to it:

  • Open the Debug View. There you will see all running Java applications. You can terminate the Rundir directly there (via the contect menu)  or activate your console by clicking on the respective application entry. This way should always work.
  • In the Console View open the Dropdown 'Display Selected Console" and choose your Rundir. Sometimes you might have trouble to get back a Console View with your application, though.

Access the OGEMA user interface

Once the framework has started, you can access the user pages at


in a 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, and also your own app if it has a GUI and could be started successfully.

Lifecycle management using the OSGi shell

You can interact with the running framework through the Eclipse console. Some useful commands:

  • lb - short for "list bundles". Shows all OSGi bundles. Every bundle has a unquie bundle id, which is just a number starting at 0 (the "framework bundle"), and which will be needed for several of the commands below. Add some filter text to show only selected bundles. E.g., if your app's Maven artifact id is "window-heat-control", enter "lb window". The status of the app should be active, otherwise a dependency could not be resolved, or something else went wrong. In this case, try starting the app using "start <Bundle-Id>", where <Bundle-Id> is the numerical id of your app shown by the "lb" command. If the start fails, an error message is shown, which should help you identify the problem.
  • start <Bundle-Id>, stop <Bundle-Id> - start and stop selected bundles
  • update <Bundle-Id> - when the framework is running, and you made some changes to your app, rebuilt it, then you can update the app using this command. It is hence not necessary to stop the framework and restart it. If you need to update a bundle that is a dependency of other bundles, you should also run refresh, so that the dependencies will be updated as well, but for most apps this should not be relevant.
    Note: The standard OSGI update method is overriden by OGEMA to provide a safe update mechanism including dependencies on custom resources. If the updated bundle contains only minor changes and no changes in OGEMA resource model definitions then a quicker update can be performed with 'felix:update <Bundle-Id>' (if framework is not based on Apache Felix, check with help for update command options).
  • uninstall <Bundle-Id>: completely remove a bundle
  • install file:path/to/file.jar: install a bundle (jar file) from the disk. The newly installed bundle will be in the state "installed". Run the lb command to find out its bundle id (typically it is the last bundle listed), and start <Bundle-ID> to activate it.
  • help - list all available commands

Managing your development environment

During development on your PC we recommend to start in "clean mode" usually meaning that all OGEMA (and other OSGi) bundles are re-installed and the OGEMA database (also log data etc.) is deleted. If you do not start clean the automated update of bundles you have changed is tricky and you also want to start from the same starting point of the database usually. But you do want to start with an empty database every time, of course. For this reason you can save the resources from the database you need for your development into an XML file and automatically reload it on every clean start. To do this (with the rundir up as developed before and open the ResAdminBackup:


To backup the entire database in XML files just select 'include all resources except the selected" and do not mark any resources. In this case you are only interested in the resource windowHeatControlConfig, so we just backup this resource:


After clicking "Backup to directory" go to the directory set (directory 'backup' in your rundir), which should now be created by the App. Try to see it in Eclipse by hitting F5 (Update) on the project, but sometimes Eclipse takes some time to recognize it. You can open it in your windows/system explorer by right-clicking on the project->Show in->System explorer. Here you should find a directory backup and a subdirectory based on date and time containing an .ogx file (OGEMA XML) containing your backup. Copy this file into the directory 'replay-on-clean' of your rundir and the resource will be reloaded by the application.

Note: More details of this app are given on its Appstore page.


Created by Christoph Nölle on 2017/01/25 19:55