Running universAAL in Karaf
Please note that we also support other ways to run universAAL, refer to page for more information.
Karaf is an implementation of OSGi based on Felix, in particular Karaf extends Felix with some extra features.
We recommend to use any our pre-configured Karaf distributions for the universAAL project (namely the universAAL release). but you may also build from source or your own, then follow this guide.
In the following, we will refer to the universAAL release 3.4.0 as the most recent one (at the time this page was written), check the latest universAAL realase version before you proceed.
The universAAL release requires:
- Java 1.6+, please configure also the JAVA_HOME environment variable
export JAVA_HOME=<PATH TO YOUR JAVA command, eg. usr/java/jdk1.6.0_07/bin/java>
PLEASE NOTE: Java 8 is not supported by Karaf 2.x.y, hence the universAAL release might not work properly. Java 8 is supported by Karaf 3.0.0+, so select the appropriate version accordingly.
The reader should have some basic knowledge of:
- OSGi and Apache Karaf, we suggest to the read Karaf manual and in particular the Karaf feature mechanism
The next steps will guide you in running the universAAL release.
- Download the universAAL preconfigured Karaf release. This link will take you to the latest stable version of universAAL (find other versions here, or you can use the latest development version, or you can build from source).
- Unzip the archive in you prefered location, as an example:
universaal-3.4.0-on-karaf
- Export the following environment variable to switch off the DEBUG mode of Karaf (if you want to debug Karaf at runtime please do not type the following command).
$ export KARAF_DEBUG=off
In Linux
SET KARAF_DEBUG=off
For Windows
NB: to make this command automatically execute every time you lanch karaf, add it to universaal-3.4.0-on-karaf/bin/setenv
- Run the Karaf run script according to you OS
universaal-3.4.0-on-karaf/bin/karaf clean [LINUX] universaal-3.4.0-on-karaf/bin/karaf.bat clean [WINDOWS]
NB: the clean argument, is a switch that tells karaf to clean the cache and any previous data of this instance. You may not need it if you don't need to change bundles or if you don't want to wipe the data (e.g: in production).
- At this time, you should see the Karaf prompt command (Branding may differ for versions prior to 3.4.0):
After a some time (depending if it is your first time, which maven and karaf need to automatically download everything), you should see something like this in the shell:
------------------------------------------------------------------- GMS: address=89d9d2b2-ce62-4123-bb60-d4a5a11f1d54, cluster=mw.modules.aalspace.osgi8888, physical address=X.X.X.X:36056 ------------------------------------------------------------------- ------------------------------------------------------------------- GMS: address=89d9d2b2-ce62-4123-bb60-d4a5a11f1d54, cluster=mw.bus.ui.osgi8888, physical address=X.X.X.X:40585 ------------------------------------------------------------------- ------------------------------------------------------------------- GMS: address=89d9d2b2-ce62-4123-bb60-d4a5a11f1d54, cluster=mw.brokers.control.osgi8888, physical address=X.X.X.X:58284 ------------------------------------------------------------------- ------------------------------------------------------------------- GMS: address=89d9d2b2-ce62-4123-bb60-d4a5a11f1d54, cluster=mw.bus.context.osgi8888, physical address=X.X.X.X:33388 ------------------------------------------------------------------- ------------------------------------------------------------------- GMS: address=89d9d2b2-ce62-4123-bb60-d4a5a11f1d54, cluster=mw.bus.service.osgi8888, physical address=X.X.X.X:42883 -------------------------------------------------------------------
So far so good! You just runned successfully the universAAL release!!!
however in versions prior to 3.4.0, the universAAL is not started by default.
First of all let's install the universAAL middleware feature on Karaf.
Type the following command:
feature:list | grep universAAL
The first part of the command (before "|") will show the list of all features, the second part filters only universAAL features, ready to be installed (actual version numbers may change):
karaf@uAAL>feature:list | grep universAAL uAAL-ctxt.CHe | 3.4.0 | | universAAL-Context | The Context History Entrepot. uAAL-ctxt.Profiling.Server | 3.4.0 | | universAAL-Context | The Profiling Server. uAAL-ctxt.Space.Server | 3.4.0 | | universAAL-Context | The Profiling Server. uAAL-ctxt.Drools.Reasoner | 0.0.0 | | universAAL-Context | uAAL-RI.RAPI | 3.4.0 | | universAAL-RemoteInteroperability | Remote API. uAAL-RI.RAPI.MySQL | 3.4.0 | | universAAL-RemoteInteroperability | Remote API MySQL. uAAL-RI.KeepAlive.Sender | 3.4.0 | | universAAL-RemoteInteroperability | Keep-Alive Event Sender uAAL-RI.KeepAlive.Receiver | 3.4.0 | | universAAL-RemoteInteroperability | Keep-Alive Event Receiver and Warning uAAL-RI.Gateway.Multitenant | 3.4.0 | | universAAL-RemoteInteroperability | AALSpace to AALSpace multitenant communicator. uAAL-RI.Ace.Target | 2.0.1 | | universAAL-RemoteInteroperability | The Apache Ace Target and its dependencies uAAL-RI.Service.Gateway | 3.4.0 | | universAAL-RemoteInteroperability | AALSpace to/from web services. uAAL-UI.handler.gui.swing | 3.4.0 | | universAAL-UI | The UI Swing Handler. uAAL-UI.handler.gui.swing.BluesteelLAF | 3.4.0 | | universAAL-UI | The UI Swing Handler's LAF plugin for BlueSteel lo uAAL-UI.handler.gui.swing.classicLAF | 3.4.0 | | universAAL-UI | The UI Swing Handler's LAF plugin for clasic look uAAL-UI.resource.server | 3.4.0 | | universAAL-UI | The UI Resource Server. uAAL-UI.handler.web.html | 3.4.0 | | universAAL-UI | The New UI Web Handler. uAAL-UI.Internationalization | 3.4.0 | | universAAL-UI | UI Internationalization utility. uAAL-UI.DM | 3.4.0 | | universAAL-UI | The UI Dialog Manager uAAL-Minimal.Coordinator | 3.4.0 | | universAAL-Feature | Feature collection of a coordinator node, containi uAAL-Platform.Servers | 3.4.0 | | universAAL-Feature | Feature collection containing typical platform ser uAAL-Basic.Coordinator | 3.4.0 | | universAAL-Feature | Feature collection typical of a coordinator node. uAAL-SingleNode.AALSpace | 3.4.0 | | universAAL-Feature | Feature collection for an AALSpace with just one n uAAL-SingleNode.Development | 3.4.0 | | universAAL-Feature | Feature collection for development; WARNING this i uAAL-Security.Authenticator.Profile | 3.4.0 | | universAAL-Security | Security Authenticator uAAL-Security.Authenticator.Dummy | 3.4.0 | | universAAL-Security | Security Authenticator (only use this in controlle uAAL-Security.Authenticator.UserPassword.Client | 3.4.0 | | universAAL-Security | Authenticator client, for user password credential uAAL-Ont.PhWorld | 3.4.0 | | universAAL-Ontologies | The Physical World Ontolgy. uAAL-Ont.Impairment | 3.4.0 | | universAAL-Ontologies | Description of user interaction impairments uAAL-Ont.Recommendation | 3.4.0 | | universAAL-Ontologies | UI Recommendation options. uAAL-Ont.Unit | 3.4.0 | | universAAL-Ontologies | The Unit Sistem. uAAL-Ont.Languages | 3.4.0 | | universAAL-Ontologies | List of All Human Languages. uAAL-Ont.Situation.Reasoner | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Drools | 3.4.0 | | universAAL-Ontologies | Drools reasoner Ontology uAAL-Ont.Profile | 3.4.0 | | universAAL-Ontologies | The Profile Ontology uAAL-Ont.SysInfo | 3.4.0 | | universAAL-Ontologies | The System Informtaion Ontology uAAL-Ont.gesturePointing | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Profile.ui.preferences | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Profile.contact | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Profile.ui.mainmenu | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Security | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.questionnaire | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Device | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Activityhub | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Device.Extra | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Measurement | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Health.Measurement | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.personalhealthdevice | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Health.Disease | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Profile.Health | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.AV | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Multimedia | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.ContinuaHealth | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.CHe | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Dependability | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Handgestures | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Furniture | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.Lightning | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.X73 | 3.4.0 | | universAAL-Ontologies | uAAL-Ont.ASOR | 3.4.0 | | universAAL-Ontologies | uAAL-MW | 3.4.0 | | universAAL-3.4.0 | The universAAL runtime based on the Middleware uAAL-srvc.ASOR | 3.4.0 | | universAAL-Service-Feature | AAL Service Orchestrator. ...
The list of features is pretty long, but don't worry it is not necessary to understand all the available features.
You just need to check the most important features, namely uAAL-MW the universAAL middleware (actual version numbers may change). If in the third colum there is no "x" then the feature is NOT installed (the representation of which features are, and are not installed, may change according to the karaf version).
The previous snippet shows that the the uAAL-MW feature is available and not installed. You need to install it before running other applications (like for example the Lighting example), to do this enter the following command:
feature:install uAAL-MW
NB: In versions prior to karaf 3.x, this command may vary, you'll need features:install (notice the plural usage).
To check the feature is installed, you may list the features again:
karaf@uAAL>feature:list | grep uAAL-MW uAAL-MW | 3.4.0 | x | universAAL-3.4.0 | The universAAL runtime based on the Middleware
Alternatively, the command to list all installed bundles may be used:
list
which will output something like (actual versions, representation, and IDs, might change according to version):
karaf@uAAL>list START LEVEL 100 , List Threshold: 50 ID | State | Lvl | Version | Name ---------------------------------------------------------------------------------------------- 64 | Active | 50 | 0 | wrap_mvn_org.bouncycastle_jce.jdk13_144 65 | Active | 50 | 3.4.0 | universAAL Thirdparty jslp library (OSGi) 66 | Active | 50 | 3.4.0.Final | JGroups 67 | Active | 50 | 2.2.4 | Gson 68 | Active | 50 | 4.1 | OSGi R4 Core Bundle 69 | Active | 50 | 4.1.0 | OSGi R4 Compendium Bundle 70 | Active | 50 | 3.4.0 | universAAL Middleware XSD Schemas 71 | Active | 50 | 3.4.0 | universAAL Middleware Container Interfaces (OSGi) 72 | Active | 50 | 3.4.0 | universAAL Middleware Interfaces (OSGi) 73 | Active | 50 | 3.4.0 | universAAL Middleware Connector API (OSGi) 74 | Active | 50 | 3.4.0 | universAAL Middleware Manager API (OSGi) 75 | Active | 50 | 3.4.0 | universAAL Middleware Module API (OSGi) 76 | Active | 50 | 3.4.0 | universAAL Middleware Broker API (OSGi) 77 | Active | 50 | 2.6 | Commons Lang 78 | Active | 51 | 3.4.0 | universAAL Middleware OSGi Container 79 | Active | 52 | 3.4.0 | universAAL Middleware Connector Communication JGroups (OSGi) 80 | Active | 52 | 3.4.0 | universAAL Middleware Connector Discovery SLP (OSGi) 81 | Active | 52 | 3.4.0 | universAAL Middleware Deploy Connector Karaf (OSGi) 82 | Active | 53 | 3.4.0 | universAAL Middleware Module Communication (OSGi) 83 | Active | 54 | 3.4.0 | universAAL Middleware Module AALSpace (OSGi) 84 | Active | 55 | 3.4.0 | universAAL Middleware Broker Control (OSGi) 85 | Active | 56 | 3.4.0 | universAAL Middleware Manager AALSpace (OSGi) 86 | Active | 57 | 3.4.0 | universAAL Middleware Manager Deploy (OSGi) 87 | Active | 57 | 3.4.0 | universAAL Middleware Manager Configuration (OSGi) 88 | Active | 57 | 3.4.0 | universAAL Middleware Manager Tenant (OSGi) 89 | Active | 52 | 3.4.0 | universAAL Middleware Data Representation (OSGi) 90 | Active | 53 | 3.4.0 | universAAL Middleware RDF Turtle serializer (OSGi) 91 | Active | 59 | 3.4.0 | universAAL Middleware Bus Model (OSGi) 92 | Active | 59 | 3.4.0 | universAAL Middleware Context Bus (OSGi) 93 | Active | 59 | 3.4.0 | universAAL Middleware Service Bus (OSGi) 94 | Active | 59 | 3.4.0 | universAAL Middleware User Interaction Bus (OSGi) 95 | Active | 59 | 3.4.0 | universAAL Middleware Karaf Shell 96 | Active | 60 | 3.4.0 | universAAL Middleware BusMember Tracker (OSGi) 97 | Active | 61 | 3.4.0 | universAAL Middleware Manager Distributed MW (OSGi)
Some explanations:
- since 3.4.0 uAAL-MW feature is started on boot automatically, therefore there is no need to start it.
- by installing a Karaf feature, you are provisioning your Karaf installation with all the OSGi bundles associated with the feature it-self. In our case, you just downloaded dozens of OSGi bundles from the universAAL repositories and you installed them in the right order.
- you are running the universAAL middleware, hence you've started a new node configured by default as COORDINATOR for the default AAL Space
- your COORDINATOR created some communication channels, each of them is listening on a specific IP (X.X.X.X) and port (ex. 42883):
------------------------------------------------------------------- GMS: address=89d9d2b2-ce62-4123-bb60-d4a5a11f1d54, cluster=mw.bus.service.osgi8888, physical address=X.X.X.X:42883 -------------------------------------------------------------------
- you can type the following command to see the properties of the default AAL Space:
karaf@uAAL>universaal:spaces Found: 1 AAL Spaces ---------------------------------------- * myHome3 - Super Domestic Home - 8888 - 89d9d2b2-ce62-4123-bb60-d4a5a11f1d54 - mw.modules.aalspace.osgi - http://aaloa.isti.cnr.it/udp.xml
- you can type the following Karaf command to list the nodes that join to the default AAL Space
karaf@uAAL>universaal:peers Found: 1 Peer ---------------------------------------- * Peer ID: 89d9d2b2-ce62-4123-bb60-d4a5a11f1d54 - Peer Role: COORDINATOR
- Lastly, you can find | here some more information on how to configure the universAAL middleware (configure the communication channels, discovery connectors or how to run universAAL without networks)
There are several ways to provision applications, throug one or more bundles, in karaf.
- If the application is listed already in the features (ie: by running the
feature:listcommand), you may install it directly by runningfeature:install {feature-name}command. - If it is not listed in the features you may need to add a feature repository that contains the desired feature. To add a feature repository use the command
feature:repo-add {URL}after which you should be able to install it. - Default feature repositories are listed in etc/org.apache.karaf.features.cfg file. You may even select there which features should the container install on boot (by adding the comma separated feature names to the featuresBoot property).
- If your application is just a single bundle you can copy the jar bundle to the deploy folder. In fact for any file created in this folder, karaf will automatically attempt to install it; if it is a bundle it will start it, if it is a library jar it will wrap it, if it is a feature xml it will install all features described in it.