How-To: Configure ZetaFramework step-by-step

Through this guide, we will be able to create a ZetaFramework from the scratch, where we will be able to deploy our ZetaApps.

1. Getting Apache Karaf

ZetaFramework is based on the OSGi framework Apache Karaf, so first step is to get it. It can be downloaded from Karaf’s download page, version as of time of writing this is 2.2.7. You can choose between Windows and Linux distribution, depending on your OS.

Note: Karaf is a JAVA application, so in order to run it, you must have installed in your system a Java SE environment, and it is recommended to set the JAVA_HOME variable to point the path where java is installed, altough it is not mandatory.

Have a look at the Quick Started Guide to get familiar with Karaf (less than 5 minutes).

2. Configure Karaf

Next step is to configure Karaf in order to prepare it for the deployment of the ZetaFramework bundles. ZetaFramework development is based on Apache Maven, which greatly eases dependency resolution and distribution management. Karaf supports also working with Maven, so we only have to tell karaf where to find the ZetaFramework bundles, i.e., the Openlab Repository.

To do so, we have to edit the <KARAF_HOME>/etc/org.ops4j.pax.url.mvn.cfg file, look for the org.ops4j.pax.url.mvn.repositories key, and include the URL of the Openlab Releases repository: http://openlab.unizar.es/repo/software/releases.

It should look something like this:

org.ops4j.pax.url.mvn.repositories= \
    http://repo1.maven.org/maven2, \
    http://repository.apache.org/content/groups/snapshots-group@snapshots@noreleases, \
    http://svn.apache.org/repos/asf/servicemix/m2-repo, \
    http://repository.springsource.com/maven/bundles/release, \
    http://repository.springsource.com/maven/bundles/external, \
    http://oss.sonatype.org/content/repositories/releases/, \
    http://openlab.unizar.es/repo/software/releases/

After that, we will be able of start karaf, as indicated on the kick start guide, and deploy ZetaFramework bundles.

3. Install ZetaFramework bundles

Final step is to install the bundles comprising the ZetaFramework (which requires internet connection). To do so, under the karaf console, we must type:

1. >osgi:install mvn:es.unizar.howlab.easyjavalib/easyjavalib-core/1.1
2. >osgi:install mvn:es.unizar.howlab.thirdparty/rxtx-lib/1.2
3. >osgi:install mvn:es.unizar.howlab.core.io.serial/serial-api/1.8
4. >osgi:install mvn:es.unizar.howlab.core.io.serial/serial-impl/1.8
5. >osgi:install mvn:es.unizar.howlab.core.zigbee.telegesis/telegesis-gateway-api/1.6
6. >osgi:install mvn:es.unizar.howlab.core.zigbee.telegesis/telegesis-gateway-impl/1.6
7. >osgi:install mvn:es.unizar.howlab.core.zigbee.telegesis/telegesis-driver-api/1.6
8. >osgi:install mvn:es.unizar.howlab.core.zigbee.telegesis/telegesis-driver-impl/1.6

After each of these commands, we will get a message like:

Bundle ID: 50

which indicates that the bundle has been sucessfully installed and has id 50 (the ID may vary on your case, and will be different for each bundle).

Command 1 will install easyjavalib-core bundle, which provides common utility snippets used by the other bundles. Commands 2-4 install bundles related to the Serial Layer (native libraries, Serial API and Serial Implementation). Commands 5-8 will install bundles related to the Zigbee Layer (Gateway APIGateway ImplementationDriver API and Driver Implementation).

We can install any other bundle following the same procedure, by executing:

>osgi:install mvn:groupId/artifactId/version

indicating the groupId and the artifactId of the bundle we are interested (version can be ommitted to install last available version). We may list the bundles installed by executing:

>osgi:list

what will produce:

karaf@root> list
START LEVEL 100 , List Threshold: 50
 ID State Blueprint Level Name
[ 42] [Active ] [ ] [ 80] Howlab::Serial Layer::API OSGi Bundle (1.8.0)
[ 43] [Active ] [ ] [ 80] Howlab::EasyJavaLib::Core snippets OSGi Bundle (1.1.0)
[ 44] [Active ] [ ] [ 80] Howlab::RX-TX lib wrapper (1.2.0)
[ 45] [Active ] [ ] [ 80] Howlab::Zigbee Telegesis::Driver API (1.6.0)
[ 46] [Active ] [ ] [ 80] Howlab::Zigbee Telegesis::Gateway API (1.6.0)
[ 47] [Active ] [ ] [ 80] Howlab::Serial Layer::Implementation OSGi Bundle (1.8.0)
[ 48] [Active ] [ ] [ 80] Howlab::Zigbee Telegesis::Driver Implementation (1.6.0)
[ 49] [Active ] [ ] [ 80] Howlab::Zigbee Telegesis::Gateway Implementation (1.6.0)
karaf@root>

(actual bundle versions and names may vary on your case)

For starting the framework, we need to start the bundles, by executing:

>osgi:start bundleID

where bundleID refers to each of the previously installed bundles. We may start all the bundles we install, but only Serial Implementation, Gateway Implementation and Driver Implementation are required to start.

We can also installing and starting bundles at once by executing:

>osgi:install -s mvn:groupId/artifactId/version

At this point, we will have the ZetaFramework operative, and we will be ready to start deploying our own applications using ZetaFramework services.

There are other ways to install the bundles, such as copying the jar files directly into the <KARAF_HOME>/deploy directory, or using OBR, but when you start to play with Karaf, you will discover them by yourself.