Eclipse Summit Europe 2008 Equinox Hackathon

The Eclipse Summit Europe presents a great opportunity to get together and look at and hack on code. This year we are doing an Equinox Hackathon. The idea is that given a base of Equinox code, folks at the conference (and elsewhere for that matter) can create their own bundles to add function or modify the base to do different things. You might be motivated just to play around, to put your project's technology to work or to use this as a reason to try some other project's technology. Whatever the reason, the goal is to hack Equinox code.

The application to be used is Toast, a telematics system that is being used as the example application for the upcoming Equinox OSGi book. Some folks may have seen previous versions of Toast demonstrated at various conferences (and undoubtedly it will be shown several times at ESE). Toast is a client / server architecture where the clients are vehicles and the server is a control center or "backend". Each piece is interesting in and of itself with examples of services, concurrency, bundling, server side, dependency injection, ... Combined they demonstrate some of the technology available at Eclipse including a UI that is all SWT, service interactions are done with DS, p2 is used to do provisioning, ... There is way more content on this in the Rough Cuts version of the book that just went up.

How to participate

So what can you do with this? The first level of involvement is to poke around the code, get it working, tell your friends and family that you can run Equinox clients and servers. The next level is to enhance Toast itself or write some extensions for Toast. Here are some ideas:

• Add a weather screen that reads the GPS location and displays the current temperature.
• Figure out a way of installing cars and give them a different id. (note currently the cars pretty much assume they are called ABC123 unless you pass in a property)
• Hook in EclipseLink to maintain a the set of cars in a data base
• Make the backend run in a WAR on top of Tomcat
• Use the ECF discovery mechanism to discover vehicles and servers when the system starts up. If you want to do this one, talk to Scott Lewis. He has done some work in this area
• Add chat or VOIP facilities to chat to someone on the server or another vehicle or stream audio from the server to the vehicles
• Integrate BIRT on the server to report some amount of vehicle activity
• Add Google Maps support to the client
• Pick your favorite project and add some related function
• ...

Who is participating

We ask that you add your name here to indicate what you are working on. There are set of people marked as Hackathon facilitators. Find them and talk about what you are doing.

• Jeff McAffer - Hackathon facilitation.
• Paul VanderLei - Hackathon facilitation & Toast expert.
• Patrick Dempsey - Hackathon facilitation & Toast expert.
• Scott Lewis - Hackathon facilitation. Adding ECF bits.
• Heiko Seeberger - Giving a weather screen a try ...
• <your name here>

Getting the code

To develop Toast you need three things,Eclipse IDE + PDE, the target and the code. Download the target archive (~50MB) and then use File > Import... > Existing projects into Workspace and specify the downloaded archive as the input. Once the target project is in your workspace, open toast.target and click on the Set as target platform link in the top right corner of the Overview page of the target editor.

The easiest way to get the Toast code is to check it out from the CVS repo. For the Hackathon we set up a SourceForge project. You don't need to have a SourceForge account to play, just add the following CVS repo location in Eclipse.

Host: equinoxosgi.cvs.sourceforge.net Repo path: /cvsroot/equinoxosgi (or simply copy the following connection (without the quotes) to the CVS Repository view ":pserver:anonymous@equinoxosgi.cvs.sourceforge.net:/cvsroot/equinoxosgi")

Using the CVS repo view, navigate to the "hackathon" folder and check out all the projects you find there (about 66).

You should now have a workspace full of Toast.

Running Toast

Toast has two parts, a client and a backend. The client is the in-dash display that you would have in a vehicle. The backend is a control center that administers and manages vehicles. To run Toast you need to start the backend, then start the client.

Launching

1. The client and backend are each described in a .product file. Open the files using Ctrl+Shift+R and filter *.product. Multi-select backend.product and client.product.
2. On the Overview page of backend.product, click the Launch an Eclipse Application" link. You should see a console open with various messages related to servlet registrations etc. Good. Note that at this point you'll see an exceptions saying something like "Unable to load repository file:/Users/hho/temp/EquinoxOSGi/ToastBuild/repository" depending on your OS and VM arguments
3. Now launch the client.product using the same technique. You should see a UI that looks something like the ones at the top of this page.
4. See the description below for descriptions of each function
5. When you are done, close the client window and kill the backend by typing "exit" in the console.

Emergency

• Trigger an emergency in one of the following ways:
  • Press the emergency button on the top button bar of the client.
  • Deploy the airbag from the device simulator.
    • Point your web browser at localhost:8081/client/devices
    • Select the Airbag from the device list and press the execute button
• On the client, you should see a pop-up indicating that help is on its way.

Audio

• Click the audio button on the top button bar of the client.
• You can manipulate the various buttons and switch between the radio and CD subscreens.
• Keep in mind that the controls are not connected to your computers audio hardware.

Climate

• Click the climate button on the top button bar of the client.
• You can manipulate the various buttons and switches.

Navigation Mapping

• Click the navigation button on the top button bar of the client.
• It takes a few seconds for the client to download the map data from the server. After that, you should see a red dot representing your vehicle on a map of Washington, DC.
• The follow-vehicle button causes the map to rotate according to the vehicle’s heading.
• The center-on-vehicle button keeps the vehicle in the center of the map.
• The info button allows you to click various points of interest on the map to reveal their label.
• The center-on-click button allows you to click the map to center it on any point.
• The zoom buttons allows you to zoom the map in or out.
• Try moving your vehicle around the map by moving the GPS on the device simulator.
  • Point your web browser at localhost:8081/client/devices
  • Select the GPS device and click the buttons under Latitude/Longitude/Heading
  • You should see the car moving around on the map

Navigation Guidance

• From the navigation screen, click the guidance button on the bottom of the control panel on the left.
• A list of destinations will appear. Select a destination.
• You should see a route appear as a yellow line on the map.
• The vehicle immediately starts to drive along that route at 50 kph.
• You can adjust the vehicle’s speed and location from the device simulator.
  • Point your web browser at localhost:8081/client/devices
  • Select the Routing device and click the various buttons to alter the vehicle’s behavior.
• To stop the routing, click on the guidance button again. Then instead of selecting another destination, click the cancel button .

Building/Exporting Toast

Running from the workspace is fun but does not give you a chance to exercise the provisioning support etc. To export Toast you really just have to export the products plus some support code.

1. Close the client.product file to avoid confusion and then open base_client.product and build.product.
2. For each of the three products (do build.product last)
   1. Click on the Eclipse Product export wizard link on the Overview page
   2. Clear the Root Directory field
   3. Set the destination to an archive file /EquinoxOSGi/ToastBuild/toast.zip
   4. Uncheck the Synchronize before exporting box
   5. Check the Generate metadata repository box
   6. Click Finish NOTE: We actually don't care about the archive file that is produced so you can safely use the same zip file name for each export and simply answer 'yes' when asked to overwrite the existing file.
3. Having done all three, run the Toast Backend Deployer launch config. NOTE: Assuming you used the ToastBuild specified above, you should not have to change anything and will end up with a ToastBackend dir beside ToastBuild. The ToastBackend has your backend server. If you're on a Mac or Linux and want to use a different location check the VM arguments and change /EquinoxOSGi/... to whatever you like
4. Run the backend server (double click on the Toast Backend executable (e.g., Toast Backend.exe on Windows) in /EquinoxOSGi/ToastBackend), you should see a number of servlets being registered in console
5. Using a web browser browse to http://localhost:8080/toast
6. Fill in ABC123 in the text box and click Create. This provisions a new vehicle in the /EquinoxOSGi/ToastClient/ABC123 dir
7. Start /EquinoxOSGi/ToastClient/ABC123/Crust.exe. Notice now that the vehicle UI comes up empty.
8. In the browser, note that the management portal is now showing your various installation functions for the vehicle. You can go and look at the vehicle profile and manage the install.
9. Now you can subscribe and unsubscribe features (e.g. audio, emergency, etc) from the management portal and things should show up correctly in the client user interface.