Lightning example

Running the Lighting example with Karaf

The Lighting example is a simple application developed to show how to use the universAAL platform. You can find here a detailed description of the Lighting example.

It is composed by 2 parts: the client side and the server side, both of them require the universAAL middleware in order to run.

In particular:

• the server side shows a simple GUI with 4 lamps that can be turned on/off
• the client side shows a simple GUI with some buttons to: retrieve the list of lamps, select one lamp, turn it on/off

We will guide you in installing the Lighting example in 2 different scenarions:

• run the client and server side on the same Karaf instance
• run the client and the server on two distinct Karaf instances

Before running the Lighting example, it is required to start the universAAL release.

Running the Lighting Example of one Karaf instance

Now we can run the Lighting example, but before you need to add some configurations to the universAAL release. In particular:

• configure the karaf feature management so it finds the feature containing the Lighting example (You may need to adjust the version number, replace 3.2.0 with the universAAL version you are running):

 karaf@uAAL>features:addurl mvn:org.universAAL.samples/mw.karaf.feature.lighting-uAAL.osgi/3.2.0/xml/features

• install the Lighting example:

 karaf@uAAL>features:install Lighting-uAAL

Now you downloaded the bundles associated to the Lighting example. Ok, now run first the Lighting server side and then the Lighting client side:

 start 86

 start 87

Where 86 and 87 are the IDs of the bundles Lighting Server and Lighting client. You can check that such IDs match with your configuration by typing:

 list

Now you can play with the GUI:

1. retrieves the Lamps (click on the client button Get Lamps)
2. select one lamp (select one of the four items on the text box)
3. switch on/off (click ON or OFF buttons)

Running the Lighting example on 2 Karaf instances

To configure a more complicated scenario, where the server and client are not running in the same network node. The scenario is composed by:

• one node configured as COORDINATOR that creates the default AAL Space
• the COORDINATOR runs the Lighting server side
• one node configured as PEER that discovers and joins (automatically) the default AAL Space
• the PEER runs the Lighting client side

Please note that COORDINATOR and PEER will run on 2 different Karaf instances on the same host, but you can do the same if you run COORDINATOR and PEER on different hosts (on the same network).

Follow these steps:

• crate 2 universAAL releases named differently, for example

 universaal-3.2.0-on-karaf-C  [COORDINATOR]
 universaal-3.2.0-on-karaf-P  [PEER]

• remove, if it already exists, the data folders (can also be done by adding the "clean" flag uppon starting karaf)

 universaal-3.2.0-on-karaf-C/data
 universaal-3.2.0-on-karaf-P/data

• remove the following files

 universaal-3.2.0-on-karaf-C/etc/mw.managers.aalspace.osgi/peer.ids
 universaal-3.2.0-on-karaf-P/etc/mw.managers.aalspace.osgi/peer.ids

• (optional) switch off the debug mode :

 export KARAF_DEBUG=OFF

Note that the peer.ids file stores the ID of the node, since you are want to run 2 instances you have to remove such file in order to let the instance create a random ID (if peer.ids exists the instance will read it).

• configure the PEER instance by appending the following 2 variables at the end of the file:

 universaal-3.2.0-on-karaf-P/etc/system.properties
 org.universAAL.middleware.peer.is_coordinator=false
 org.universAAL.middleware.peer.member_of=urn:org.universAAL.aal_space:test_env

Note that in both the PEER and COORDINATOR you appended the previous two variable, but the COORDINATOR has

 org.universAAL.middleware.peer.is_coordinator=true

while the PEER has:

 org.universAAL.middleware.peer.is_coordinator=false

This is a sort of constraint of the Lighting example application, your own application will be smarter!

• Run the COORDINATOR

 universaal-3.2.0-on-karaf-C/bin/karaf clean

• Install the universAAL Middleware:

 karaf@uAAL>features:install uAAL-MW

• Check the uSpace and the number of nodes present:

 karaf@uAAL>universaal:spaces
 karaf@uAAL>universaal:peers

• Add and install the Lighting example:

 karaf@uAAL>features:addurl mvn:org.universAAL.samples/mw.karaf.feature.lighting-uAAL.osgi/3.1.1-SNAPSHOT/xml/features
 karaf@uAAL>features:install Lighting-uAAL 

• Run the Lighting Server:

 start 86
 Check the ID of your Lighting Server bundle with the command:
 list

Ok, now do the same with the PEER node

• open a new terminal and move to

 '''universaal-3.2.0-on-karaf-P'''/bin

• Run the PEER

 '''universaal-3.2.0-on-karaf-P'''/bin/karaf clean

• Install the universAAL Middleware:

 karaf@uAAL>features:install uAAL-MW

• Check the uSpace and the number of nodes present:

 karaf@uAAL>universaal:spaces
 karaf@uAAL>universaal:peers

Note that now the result of the command karaf@uAAL>universaal:peers (typed from the COORDINATOR or from the PEER consoles) is more interesting:

 karaf@uAAL>universaal:peers 
 Found: 1 Peers
 ----------------------------------------
 Peer ID: 03e4660f-183c-4227-9488-e034e153961c - Peer Role: PEER
 * Peer ID: aba78067-8f5d-4e82-a7d2-80bd205098d5 - Peer Role: COORDINATOR
 The character '''*''' tells you the ID of the instance you are seeing

• Add and install the Lighting example:

 karaf@uAAL>features:addurl mvn:org.universAAL.samples/mw.karaf.feature.lighting-uAAL.osgi/3.1.1-SNAPSHOT/xml/features
 karaf@uAAL>features:install Lighting-uAAL 

• Run the Lighting Client:

 start 87
 Check the ID of your Lighting Client bundle with the command:
 list

Now you should see the Server and Client GUIs and you can play with the commands explained previously:

• Get Lamps
• Select one lamp and push ON or OFF button

The main difference is that you are running an uSpace composed by 2 nodes. One node is the COORDINATOR of the uSpace and it runs the Lighting Server, the other node is a PEER that runs the Lighting Client.

As soon as you invoke Get Lamps or ON/OFF buttons, the nodes exchange message over the universAAL busses.