Project and Rundir Management

Last modified by David Nestle on 2019/04/25 14:32


This page provides information how to use and extend existing OGEMA projects and how to create/manage standard OGEMA projects that are most suitable for collaboration with other developers and re-use of existing apps, drivers and other components.

All the relevant settings for an OGEMA system are provided in so-called run directories (Rundir). The entire framework including the OGEMA core frameworks and all apps, drivers is from a run directory, using the OGEMA launcher. When starting from scratch using the OGEMA SDK tutorial you will use and extend the basic SDK rundir. Of you are starting to collaborate with an existing project you will get access to an existing rundir of the project.

Setting up a devlopment environment

This concept assumes that OGEMA development is done based on the OGEMA development kit (or at least using Eclipse). To get started you should install the OGEMA SDK:, you do not have to go through the entire tutorial if you just want to use existing OGEMA projects or plan to make minor changes.

Start using a project

If you are using an existing project with a Rundir different from the standard SDK Rundir you should check the page of the project which repositories you need to build, which properties you have to set etc.

Usually each project describes the Git repositories required. A basic tutorial how to access the projects in Eclipse can be found here:
If you are not familiar with using Git follow the tutorial for using Git with Eclipse for organizing your daily Commit/Push/Pull of code.

For building the projects checked out and starting a Rundir from Eclipse follow instructions Create a project and run it. Start from the description how to build an app or a project in "Build the app".

Some more general recommendations:

Basic Components of each Project Rundir

  • Each Project should have a Wiki page or similar document providing the information listed here
  • Each productive Rundir should have a development copy in a Git repository that is used for development purposes. In some cases two or more variants may exist in order to provide versions of the Rundir with hardware simulation and a version that has exactly the same bundles as the productive rundir (other reasons for different Rundir versions exist). Usually just different versions of configuration files are provided in the same Rundir, though. The path to the development Rundir(s) should always be given.
  • Information how to access the productive system (Linux shell, web interface if applicable, any other if relevant)
    For gateways in the field that are situated behind a firewall this typically includes a documentation how a Reverse Proxy/VPN ("WAN-Gateway") connection is configured and can be accessed.
  • If a project uses a specific gateway and OGEMA server instances for each instance a separate development Rundir and documentation should be provided. Each documentation should have a link to the respective project "partner" documentation, though.
    Also the communication interaction between gateway and server instances shall be documented here.
  • How to perform software updates. Currently 3 standard ways for updates exist:
    • (1) Direct update: This is the default if no other documentation is given. See Section "Update OGEMA productive system from local development PC" below for a documentation. This is usually used for OGEMA server instances and gateway projects that have not more than one or two instances in the field. The effort for setup is low, but the effort to distribute updates to various instances is relatively high.
      In this case the productive systems use the same method to configure the bundles used as the development Rundirs (config/config.xml).
    • (2) Update distribution via Git: This works very similar to (1), but the transfer of the bundles is done via Git repositories and the local update procedure is supported via simple bash scripts, may also be automated using Cronjobs.
    • (3) Perform updates via the OGEMA Appstore: Setting up an appstore and preparation of gateways for the appstore is relatively complex, but updates can be provided by different developers very easily then and are distributed fully automated. The configuration of bundles used is determined via the Appstore here and not via the config/config.xml file anymore.
  • Additional configuration information as required shall be provided.

Update OGEMA produtive system from local development PC

Note: The following Step-by-Step guide assumes you are developing with Eclipse on Windows. The same procedure can be done with minor adjustments in other environements also.

  • Finalize development on PC and test the rundir on the PC. Make sure you have the latest source code built of all projects that are used on the productive system, especially if you fully replace the bin directory (see below).
  • Run launch configuration that performs build (Program Arguments -build -offline)
    Now you have to update the bin directory of the productive system rundir. If you know which bundles have been updated you can replace them manually, otherwise you rename the bin directory on the productive system (/ogema/bin ) to binbak and copy the entire bin directory from the development rundir on your PC. If there is already a binbak directory you may delete it, but make sure the latest version of binbak is a working correctly.
    From Microsoft windows you can typically perform this taks using WinSCP.
  • Maybe you have to update the config.xml file. If it's neccessary rename the file /config/config.xml to config.xml.bak and copy the /config/config.xml file from your local rundir to the /config folder of the productive system rundir.
  • Log into the productive system using Putty (using the same data as above):
    Open the ogema screen with
    screen -r ogema
    Stop the running OGEMA instance with
    stop 0
    wait until it fully stopped, then restart with
    ./ -uro -ub
    or (if the productive systemr shall be started with security activated)
    ./ -uro -ub
  • Check if all bundles can be resolved. If you see a message that a bundle could not be resolved check config.xml or the main server bundle manager.
  • Observe the console whether everything looks fine during startup
    After startup finished test the web interface of the productive system if it looks fine

User Management

To add a new natural user to an OGEMA system you should open the OGEMA Administration, go to User Administration and add the user. If the user shall have access to all apps and resources the user can be an administration user. Otherwise you have to give the app permissions according to the app web pages the user shall be able to open. The preselected apps are required for all users in order to enable the log in process, the widget framework and the home screen. The user also needs to get resource permissions - if the access shall only be limited by the app web pages you should give all permissions via the OGEMA console:

addresourcepermission -u <userName> -p "*"

Note: A typical setting for a user is that the user gets access to an app giving access to monitoring data and control. Typically you also need to give access to the app .

Additional Information

  • On your development PC you can setup the resources statically by reading ogj- and ogx-files from the replay-on-clean directory. You have to perform a Perform a backup of the OGEMA database on the productive system and restore it on the development PC: See Create a project and run it -> Managing your development environment
    This can represent information provided by hardware drivers on the productive system.
    If you just want to add or update a single resource to a productive instance you can process the respective ogj/ogx file via the Resource Backup and Cleaner web interface uploading the file via "Upload backup file". You also put the file into the replay-on-clean directory so that the updated versio would be loaded in case of a later clean start.
  • If you need a more dynamic representation of the hardware and hardware driver(s) you want to setup a variant of the Rundir containing simulation components. This is described int the Setup a simulated development environment for your OGEMA Gateway tutorial.
Created by David Nestle on 2019/02/02 10:20