BeTelGeuse logo



User Manual

Developers' Guide

BeTelGeuse Protocol



BeTelGeuse - Developers' Guide

Developers guide

Adding support for a new sensor type

It is possible that there is no parser for your device. In that case you need to add support for the new device type by programming a parser and adding it to the program. Parser classes are called Readers in BeTelGeuse. Different data types produced by the Readers are called parameters (for example, longitude, latitude).

Before creating a new Reader implementation, check if you have to implement the Reader interface directly or if you can extend an abstract Reader. You might only need to extend the ReaderSkeleton class. The Reader interface defines a common class for reading data from sensing devices. It does not restrict the Readers only to Bluetooth devices.

BeTelGeuse creates a Reader by calling empty constructor for it and then initializing it with the initialize method specified in the Reader interface. The interface extends Runnable, so every Reader implementation must have a run() method. BeTelGeuse creates a thread from each Reader object.

Connection to a Bluetooth sensor is provided in the initialize method. It is up to the Reader to open input and output streams to the sensor, close the connection when Reader is closed and call restoreConnection() method if the connection to the sensor is lost. ReaderFactory class offers a method for connection restoration.

Readers support two different ways of transferring data forward; objects can subscribe to the Reader or they can poll the Readers. Polling returns only one sample of data from a parameter. Subscribing objects need to implement the Observer interface. The subscribing objects' update() method is called when the Reader receives new data. The update() method has two parameters: a Vector array and the Reader that is updating the subscriber. The Vector array holds the current data from the Reader. First index in the array is a Vector that holds the data corresponding to the first parameter name. Method getParamerNames() returns the parameter names in a String array. Paremeter names, actual data, parameter types, etc, are expected to be in the same order in arrays.

Objects stored in the Vectors can be Strings, Integers, Floats or Doubles. However, only one type is allowed per Vector (or per parameter). Method getParameterTypes() returns an integer array describing what type of an object is used for each parameter. A zero in the parameter type array means that the parameter in question is saved as a String object in the Vector. One correspods to an Integer object, two to a Double and three to a Float object.

Readers should always update an internal counter when they receive new data batch from the sensor. This internal counter can be inquired with getLastDataNumber(). On some Bluetooth implementations, connections can fail without being closed and throwing an exception. Should this happen, getLastDataNumber() method is the only way of determining that the Reader has disconnected from the sensor.

After you have implemented a new parser for your device, you need to add the name of the parser's class to the Properties class that can be found in the hiit.mapper package. The Properties class maps name of the parser's class and a description to an identification number. Both mappings are saved in Hashtables. First you need to reserve an identification number for the parser. The devices are identified with hexadecimal numbers which currently include:

  1. UNKNOWN_DEVICE          0x0000
  2. SERIAL_PORT_READER      0x0001
  3. BT_PORT_READER          0x0002
  4. LOCAL_READER            0x0003
  5. JNI_READER              0x0004
  6. GSM_READER              0x0005
  7. GPS_READER              0x0100
  9. ECG_ACC_READER          0x0104
  10. ECG_ACC_BYTE_READER     0x0105
  11. ICUBEX_READER           0x0106

After reserving a number add it and the class name to the getIdClassName method:

table.put(new Integer(YOUR_DEVICE_ID), "hiit.reader.YourParserClass");

and the id number and a description to the getNameId method:

table.put("A short description", new Integer(YOUR_DEVICE_ID));

Once you have programmed a parser and added it to the Properties class, BeTelGeuse needs to be recompiled.

If you decide to extend ReaderSkeleton class, you need only implement sensor data parsing and methods that define and access the parameters. See the BeTelGeuse Javadoc from more information about the methods.

Adding a plugin to BeTelGeuse

It is possible to program plugins and attach them to the GUI. For example the Transmitter, which is used to send data to a server, is a plugin. The plugin's GUI needs to implement the PCPlugin or the MIDPPlugin interface, depending on the BeTelGeuse version (PC and MIDP, respectively). To add a plugin to the program, create it in the initializePlugins() method in the BeTelGeuseMIDP class or TabGUI in the PC version. The plugin should announce its GUI to BeTelGeuse using addPlugin(..) method. This GUI should be of the type Displayable in the MIDP version and of type JPanel in the PC version.

Porting BeTelGeuse to a new platform

The core of BeTelGeuse only uses Java features that are compatible with CLDC 1.1 and MIDP 2.0, Java 1.3, and Personal Profile. The GUI, device mapping implementations (Mapper and Recorder), some Readers and plugins are platform dependent and may need to be reimplemented when porting BeTelGeuse to another platform. In addition to Java runtime environment, BeTelGeuse requires a JSR-82 Bluetooth stack to run. Since there are minor differences in JSR-82 Bluetooth stacks, some platform - JSR-82 combinations might require reimplementation of some parts of the core. For example, on HP iPAQ hx4700 PDA with the commercial version of Aventana stack, Bluetooth connection creation works only if Avetana stack's own Connector object is used.

Last modified 2007-02-26