Developing Kura Applications

Kura provides a set of services that runs on the Equinox OSGi framework for the IoT (Internet of Things) . With Reactive Blocks, you can develop OSGi bundles using Kura as described in this article.

Updates

If you have used Reactive Blocks for Kura feature before, you simply need to update. Do the following steps: (Error markings during the update prosess are OK)

  • Choose Help → Check for Updates from the Eclipse menu.
  • Continue with the update as shown in Eclipse.
  • Delete the target-definition-with-rb project in your workspace
  • Download the zip file containing Reactive Blocks library bundles.
  • Import the projects in the zip file into your Eclipse workspace (make sure you choose Existing Projects into Workspace in the Import Wizard).
  • In the target-definition-with-rb project, open the file rb-kura-equinox_3.8.1.target.
  • Select the link Set as Target Platform on the top right of the target editor.

If you have developed OSGi applications with Reactive Blocks before, you may need to rebuild them.

Install Reactive Blocks for Kura

To install the Reactive Blocks for Kura feature, do the following steps:

  • Choose Help → Eclipse Marketplace from the Eclipse menu.
  • Search for reactive blocks.
  • Choose button Install.
  • Select Reactive Blocks for Kura feature and follow further instruction.

Install mToolkit

mToolkit is an Eclipse plugin that enables creation of deployment package and connection to a Kura-enabled target device.

This plugin can be install from its update site:

  • Choose Help → Install New Software… from the Eclipse menu.
  • Fill in the update site http://mtoolkit-neon.s3-website-us-east-1.amazonaws.com.
  • Uncheck the option Group items by category.
  • Choose mToolkit and follow further instruction.

Development Environment Setup

In order to create a bundle for the Kura framework, you need to change the target platform in your Eclipse workspace to include bundles for Kura and Reactive Blocks libraries. It is advisable to first switch to a new workspace.

  • Download Kura developer’s workspace zip file.
  • Also download the zip file containing Reactive Blocks library bundles
  • Import the projects in those two zip files into your Eclipse workspace (make sure you choose Existing Projects into Workspace in the Import Wizard).
  • In the target-definition-with-rb project, open the file rb-kura-equinox_3.8.1.target.
  • Select the link Set as Target Platform on the top right.

Create a Kura Application Block

Before making an OSGi bundle for Kura framework, we first create a Reactive Blocks plug-in project.

Then, create a Kura application by invoking the new building block wizard. You can choose between two types of block depending whether the application is a configurable application.

  • Application Block
  • Kura Application with Configuration

If you choose application block with configuration option, you will get, in addition, a ‘metatype’ file for describing the configuration properties for your bundle. This file contains examples that you can modify.

Specify your application as usual, by connecting blocks and activity nodes. Import building blocks that you need from our collection. We provide also blocks to utilize Kura services.

To make the application receive configuration updates from the Kura platform, use the Config Update block. For more information, checkout this blogpost and tutorial.

Verify your specification with the analysis and animation tools.

Note that a Plug-in project must contain maximal one application block.

Depending on your application, you might need to import packages from other bundles, like californium for CoAP. Read About Dependency section to see how to add a bundle as project dependency.

Build a Kura Application

  • Right click on the application block and select Build → Re-Build for Java OSGi Bundle for Eclipse Kura

You can also choose Select Build Target Platfrom… and then Java OSGi Bundle for Eclipse Kura in the Platform selection dialog to change build parameters.

When the build process is completed, you should see a new source folder gen containing generated code from your application and also the corresponding component definition component.xml in the folder OSGI-INF

Depending on your application, the generated code may also need dependency to other packages or bundles. Read About Dependency section to see how to add a bundle as project dependency.

Run a Kura Application

Kura provides an emulator so that you can start Kura and your application in Eclipse. This emulator runs locally on your computer and currently supports OS X and Linux only.

You can also run your application on a remote target device, like Raspberry Pi.

Local Emulation Mode

A launch configuration to run Kura with Reactive Blocks libraries from within Eclipse is already provided.

  • In the target-definition-with-rb project, find a suitable launch configuration inside the launch folder.
  • Right-click and select Run As → 1 Kura_with_RB_Emulator_xxx.

You should see that Kura is running from the Console view. Your application is automatically run on the emulator.

On a Remote Target Device

To run your application on a remote target device, you need to install Kura on the device. This documentation shows how you can install Kura on a Raspberry Pi and a BeagleBone.

There are many ways to deploy a bundle on Kura. Here, we will use deployment packages and Kura’s web console.

Make a deployment package from your application as follows:

  • Find a .dpp file in your application project.
  • Do a right-click and choose Quick Build.
  • You should find a .dp file in the same project.

To deploy the package on Kura, follow these steps:

  • Open Kura’s web console using the IP address of your device. The default username and pasword is admin/admin.
  • From the menu on the left hand-side, choose Packages.
  • Remove other package you made with Reactive Blocks.
  • Choose the + Install/Upgrade button.
  • Navigate to the .dp file (not .dpp!) containing your application bundle.
  • You might need to use the Refresh button in order to see the package you installed.

If you add logging messages in your application, the messages are shown in Kura log file. In a Raspberry Pi, the file is located in /var/log/kura.log. So, use the command tail -f /var/log/kura.log to follow messages in the log file.

You can also change which log level you want to see. See here.

Missing Dependency at Runtime

One way to find out whether your application bundle is running is to put a log (info level) message at the start of your application, i.e., after an initial node ().

If you don’t see the log message in the Kura log, chances are your application is not started due to missing dependencies. That is, additional bundle(s) must be installed in the OSGi framework you are using.

If you use the local emulation mode, see here.

If you run your application on a remote target device, find out the status of your bundle:

  • login to your device using ssh
  • open the OSGi console by using the command telnet localhost 5002
  • Use commands ss and diag <bundle-id> as shown in the following figure

The figure above shows that bundle br.mqtt.sender (bundle id 95) has unresolved constraints. You need to solve the leaf constraints first, i.e., bunde com.bitreactive.library.mqtt (bundle id 90) needs other bundle(s) that export packages (org.eclipse.paho.client.mqttv3 and org.eclipse.paho.client.mqttv3.persist)

To solve this problem, you need to find a bundle that exports package org.eclipse.paho.client.mqttv3 and basically install the bundle in the OSGi framework.

  • Find the deployment package definition (.dpp file) in your application project and open it with the Deployment editor
  • On the Bundles tab, add the missing bundle by using the New button

  • Rebuild the dpp file to get the deployment package (.dp) and redeploy the package on your target device as described in the previous section.