OHF SODA Stepstone

Getting Started

The Stepstone subproject is aimed at providing a reference implementation for SODA development. Stepstone features the SODA programming environment for working with devices, an enterprise adapter transport mechanism, and a backend server/webapp based on Eclipse Equinox for access to device data.

Note: If you experience problems with this guide, please check for existing Stepstone bugs. If your problem has not been reported, please open a bug for OHF and assign it to the Stepstone component.

Prerequisites

Windows, Linux, or Mac OS X

Note: There is currently a bug in the Stepstone device simulator on Mac OS X.

Java 1.4.2 or above http://java.sun.com/j2se/1.4.2/download.html

Eclipse SDK 3.3.x http://archive.eclipse.org/eclipse/downloads/drops/R-3.3.2-200802211800/index.php

For Bluetooth Devices:

• Bluecove (WIDCOMM, BlueSoleil, Microsoft, and Mac OS X bluetooth stacks) http://code.google.com/p/bluecove

Note: There is now also a separate module to support the Linux Bluez stack

• AvetanaBluetooth (Linux) http://sourceforge.net/projects/avetanabt

Download and Install

Navigate to the Eclipse Update Manager (Help -> Software Updates -> Find and Install... -> Search for new features to install) and create a New Remote Site for SODA Stepstone with a URL of http://download.eclipse.org/technology/ohf/soda/stepstone/update-site. Select the new site, and proceed to download and install each of available features.

Stepstone: The SODA Reference Implementation

Stepstone builds on top of Device Kit to interface with a variety of medical devices. It leverages the Device Kit sample infrastructure to ship features for the following device models:

• The A&D Medical UC-321 Weight Scale (serial)
• The A&D Medical UA-767 Blood Pressure Cuff (serial)
• The A&D Medical UC-321PBT Bluetooth Weight Scale
• The A&D Medical UA-767BT Bluetooth Blood Pressure Cuff
• The Nonin Medical PO4100 Bluetooth Pulse Oximeter
• The QK145 Temperature Sensor

However, for those who don't have the physical device (or don't feel like taking their blood pressure repeatedly), Stepstone also includes a simple SWT-based device simulator. In order to import the sample projects, select New -> Examples -> Device Kit Samples. Next, click Deselect All and check the org.eclipse.soda.stepstone-launcher projects (which includes launchers projects for running the stepstone edge and backend) along with whichever devices you desire (simulator is recommended for first time users). Click Finish and you will see the projects being generated in your workspace.

You are now ready to run the end-to-end Stepstone solution. Open the Run -> Run... dialog, select the Backend Server launcher and click the Validate Plug-in Set to make sure the bundles are resolved correctly. If there are any problems, click the Add Required Plug-ins button. Click run and you should see the console begin to fill with log data, including [INFO] 2008-08-06 16:27:44.687 - Activator: Stepstone Servlet registered

Open the run dialog again, and select the Stepstone Edge – Simulated Devices – Muse Adapter – Targetable Backend launcher this time (to run with the Bluetooth Device launcher, you may need to add your desired bundles as well a new bundle which exports the javax.bluetooth package). Resolve the launch config (just like we did for the Backend launch) and Run the launcher to see the simulator devices window open.

When using real devices, it is generally a good idea to run the exerciser projects first to verify communication with the device is working.

After generating a few sample readings, open a browser to the Stepstone backend ( http://localhost:8080/stepstone/index by default). Click on the devices in the left hand menu and make sure the readings appear as expected. You have now finished a complete end-to-end run!

Contributing to Stepstone

Developers wishing to contribute to Stepstone may opt to check out the source from the Eclipse Technology CVS repository. Both the edge and backend projects (found with the Device Kit samples under the launcher category) contain project sets for loading various parts of stepstone from CVS.

If requested, provide the username “anonymous” and leave the password blank.

Alternatively, in order to check out the files without installing the Stepstone plugins, it is possible to check out the development artifacts directly from CVS by following the instructions below.

Installing The Edge

In order to access the repository from Eclipse, switch to the CVS Repository Exploring perspective and create a new location for the eclipse OHF project:

• hostname: dev.eclipse.org
• path: /cvsroot/technology

If requested, provide the username “anonymous” and leave the password blank. Stepstone is primarily divided into two separate applications, the edge and the backend. The edge code is designed to run on a device with network connectivity and serves as a gateway for data between the sensor/actuator devices and the backend. The Stepstone backend leverages the Equinox server project to provide a webapp that can be ran in the workspace or built into a .war file and deployed to a standard application server such as Apache Tomcat.

Browse to org.eclipse.ohf/plugins/org.eclipse.soda.stepstone/runtime/common and checkout the org.eclipse.soda.stepstone project. This project contains a number of useful launchers and project set (.psf) files. In order to import a project set, switch back to a Java perspective, right-click on the selected .psf file(s) and choose Import Project Set... from the package explorer.

Open the project sets for loading directory and import the following project sets:

1. stepstone_edge_prereqs.psf
2. stepstone_edge_core_runtime.psf
3. stepstone_edge_devices_simulated.psf
4. stepstone_edge_applications.psf

In order to link the edge to the backend, you must import a set of adapter projects. In its current state, Stepstone contains only one such adapter--a web services adapter implemented using Apache Muse. In order to use the Muse adapter, you must first import the necessary Muse bundles and their prereqs. To do this, unzip the binary Muse release to ${MUSE_HOME} and, from the edge workspace, select File -> Import -> Plug-in development -> Plug-ins and Fragments, click Browse to select a Plug-in Location and browse to ${MUSE_HOME}/lib/eclipse-osgi. Click next and import the following prerequisite plugins:

• javax.saaj.api
• org.apache.xalan
• org.apache.xerces

Note: These bundles are also available from Orbit.

Follow the same steps to import each of the Muse OSGi bundles from

${MUSE_HOME}/modules/osgi/core and ${MUSE_HOME}/modules/osgi/mini

Alternatively, you could place these bundles in the target platform.

Navigate to the project sets for loading directory in org.eclipse.soda.stepstone once again and this time import:

1. stepstone_edge_backend_adapter_muse.psf

Because Device Kit does not have native bluetooth support, it is necessary to obtain a bundle which exports javax.bluetooth and javax.microedition.io in order to exercise the bluetooth devices properly. Note that it is sometimes possible to simply use OS-level drivers to expose your bluetooth device as a virtual COM port, eliminating the need for this step. There are a number of freely available javax.bluetooth (JSR-82) implementations for various platforms, including Bluecove for Windows XP (SP2) and Mac OS-X (http://code.google.com/p/bluecove) and AvetanaBluetooth for Linux (http://sourceforge.net/projects/avetanabt).

After downloading the necessary project, you may need to compile the native support for your particular OS/architecture. Once you have created a working jar, wrap this jar in an OSGi bundle by creating a new project with File -> New -> Project... and selecting the Plug-in Development -> New Plug-in from Existing JAR Archives wizard. Use the Add External... button to import the necessary jar file and click next. Name the bundle project, change the target platform to a standard OSGi platform and uncheck the Unzip feature. Click finish and navigate to the Runtime tab of the project's META-INF/MANIFEST.MF file to make sure that it exports the necessary javax.bluetooth and javax.microedition.io packages. It may be necessary to append a "uses" attribute to the javax.bluetooth export. This will tell OSGi bundle to use the javax.microedition.io from this bundle whenever they import javax.bluetooth. On Eclipse 3.3 and later, you may simply click the "Calculate Uses" button from the Runtime tab of the MANIFEST.MF editor.

Next, open the project sets for loading directory from the org.eclipse.soda.stepstone project and import the following project sets:

1. stepstone_edge_bluetooth.psf
2. stepstone_edge_devices_real.psf
3. stepstone_edge_devices_real_xtras.psf

Installing and Building The Backend

If you have not already, import org.eclipse.soda.stepstone from the Eclipse Technology CVS at org.eclipse.ohf/plugins/org.eclipse.soda.stepstone/runtime/common. This project contains a number of useful launchers and project set (.psf) files. In order to import a project set, switch back to a Java perspective, right-click on the selected .psf file(s) and choose Import Project Set... from the package explorer.

Open the project sets for loading directory and import the following project sets:

Note: due to bug 231929, if you would like to build/export the backend you will need to download the necessary 3rd party bundles (instead of checking them out of cvs or importing the .psf) from orbit and install them to your target platform (eg. by dropping into your plugins directory)

1. stepstone_backend_prereqs.psf
2. stepstone_backend.psf

Note: due to bug 237795, you may see errors in the org.eclipse.soda.stepstone.backend.communications.webservices project. As a temporary workaround, please point your workspace to a 1.4 VM by adding it to the list at Preferences->Java->Installed JREs. You may need to Project->Clean...->Clean all projects for the new settings to take effect.

Verify that there is no red in your workspace and proceed to build the backend by selecting Run -> External Tools... and running the Stepstone backend build – war - STEP 1 launcher. This launcher will run the PDE -> Export Plugins task and will take a minute or two to complete. When the PDE Export is complete, proceed to run the Stepstone backend build – war - STEP 2 launcher. This launcher results in a new war file named stepstone.war which can be found in the build directory of the org.eclipse.soda.stepstone.build project.

Deploy this stepstone.war to your application server (tested with Tomcat 5.5), and if it is not already running, start the server. After a brief startup period, you should see the OSGi prompt in the console from where you launched the server. Although this getting started guide will not teach you to work with the OSGi console, try typing a couple of common commands such as “ss” (short status) to get a feel for the running system. All bundles should be in a state of RESOLVED or ACTIVE. Open a browser and navigate to http://localhost:8080/stepstone/index in order to see the public view of the backend system.

Alternatively, usually for developement, it is better to launch the Backend Server from Eclipse. Note that in the current implementation it is necessary to run the ant (build-service.xml) script from the communications.webservices project so that the backend service is compiled into a .aar file for axis2. To run, simply open the run dialog and select the Backend Server equinox launcher. Navigate to the Arguments tab and look at the default VM properties. Validate the runtime bundles and select Run.