From BUG Wiki

Contents 1 Overview 2 Tutorial 3 Walk Through the Code 4 Publish it to BUGnet

Overview

This tutorial is designed for new users to BUG that have an understanding of Java. The BUG SDK is used to write an OSGi-based application "hello world".

Tutorial

1. First create a BUG app using the application wizard. You can call up the wizard in a variety of ways but it's probably easiest to just click on the icon on the toolbar, highlighted below:

2. The wizard dialog will present two selections, Name and Author. For name enter HelloWorld.
3. Click next and the 2nd wizard page will have some interesting options:

4. Start a Virtual Bug with the Start Virtual BUG button. After a few seconds Dragonfly should discover the new BUG on the network.
5. Select the Virtual BUG from the list and active OSGi services become available from the selected BUG.

• These services are retrieved via a HTTP Web Service call from the SDK to the Virtual BUG. This list of services can be used to generate a simple ServiceTracker object that will track the services as long as the application is active.

• OSGi has a concept of the “Service Registry” which is a way for components, or bundles, to access functionality from other bundles. The service registry consists of a name (String), an implementation reference, and a set of properties (Dictionary). A bundle can listen to service registry events via the BundleContext object (BundleContext.addServiceListener()) in addition to using the ServiceTracker and ServiceTrackerCustomizer. BUG applications, when generated via the wizard, use ServiceTracker to get access to services provided by other bundles, most notably services provided by BUG modules.
  
  

ServiceTrackerCustomizer | com.buglabs.device

  public interface ServiceTrackerCustomizer
  {
   public abstract Object addingService(ServiceReference reference);
   public abstract void modifiedService(ServiceReference reference, Object service);
  public abstract void removedService(ServiceReference reference, Object service);
   }

6. You will write a simple message to the monochrome BUGbase LCD display for the application. The OSGi service that offers that capability is the IStatusBarProvider service. Scroll down until you find it in the Requested Services list.
7. Select it as shown here and click Finish:

• The SDK will now generate a BUG application project including some Java code based on the selections and text entries made in the application wizard. Two classes will be generated: Activator.java and HelloWorldServiceTracker.java:

• The Activator is an OSGi specific class that serves as the entry point to your application from the running OSGi framework. In this class, a start() method is called by the framework with a BundleContext object. This context serves as the interface by which your application can interact with the framework. An HelloWorldServiceTracker instance is created by the Activator when this bundle is started during runtime. The tracker (actually a ServiceTrackerCustomizer) uses a Filter to determine which OSGi service events are relevant. This filter was generated by selections made in the BUG application wizard. HelloWorldServiceTracker.doStart() gets called when we have a reference to a IStatusBarProvider service.
  

8. Make sure the following line is in the import block at the top of the file. If it's not, put it in:

import com.buglabs.status.IStatusBarProvider;

9. Substitute the default code for this:

public void doStart() { 
IStatusBarProvider sb = (IStatusBarProvider) this.getService(IStatusBarProvider.class);
String key = sb.acquireRegion(6);	
if (key != null) { 
sb.write(key, "oh hai"); 
}
}

10. restart the Virtual BUG. You should see the message on the Virtual BUG LCD screen:

• Note that there are some problems on some operating systems regarding redraw on the AWT control, such that the canvas may not be repainted if it falls behind another window.
  

Walk Through the Code

• To get a better understanding of what happened, the following will step you through the code. First, you will set a breakpoint in the entry point of the helloworld application: Activator.start().
  

1. In Eclipse, right click in the small column to the right of the text editor as shown below:

2. Set a breakpoint in HelloWorldServiceTracker.doStart().
3. Re-run the Virtual BUG.
4. Switch to the Debug perspective when prompted.
5. Use the code navigation buttons in the Debug view to move through the code until you get to the breakpoint in HelloWorldServiceTracker.

• Eventually you'll hit the breakpoint in HelloWorldServiceTracker. You can set into the core BUG bundles that implement the Virtual BUG's LCD screen. The real BUG implements the same service interface of course, so there is no need to change code between either the virtual or real BUG.

• The BUG provides a dedicated console interface to the Concierge OSGi runtime. The VirtualBUG exposes this interface in the Eclipse console view. The real BUG opens port 8090 for telnet connections. The console prompts is the beginning parenthesis followed by a colon “(:”, similar to the Concierge logo. The console provides some simple commands to inspect and modify the runtime environment. Help provides a list of available commands:

• The bundles command lists the currently installed bundles. This gives some insight into the running environment:
  

• Let's take a brief tour of the more important of these default bundles to get an idea of how the runtime environment is composed. A note about the state: some bundles are 'passive' in that they only contribute code to the environment, others are active in that code is executed when they are started and stopped. Passive bundles are denoted by the 'resolved' state.
  

Publish it to BUGnet

• This allows us to (potentially) share it with others.

1. Right click on it in the Project Explorer view
2. Select 'Send to BUGnet'. A dialog will appear.
3. Assuming you do not already have a BUGnet account, select the link at the bottom of the dialog.
4. A web page inside of Eclipse will appear asking you for the usual details of your account.
5. Once your account is created, you can upload the app again and enter your authentication details.
6. After the application has finished uploading, a Version Notes page will open where you can add specific details for the version you uploaded.

• The BUGnet view will also refresh to display your application under My Apps. If you left click on the application title a page will load that will allow you to edit the details, such as adding a description or setting it to publicly viewable:
  

• To summarize, in this step, we've created a simple BUG application and covered the basics with OSGi: bundles, service trackers, and the bundles running on the BUG.