BeTelGeuse logo



User Manual

Developers' Guide

BeTelGeuse Protocol



BeTelGeuse - User Manual

Table of contents

  1. System requirements
  2. Installation and running the program
  3. Setting up Bluetooth devices
  4. Transmitting data to a server
  5. User interface

System requirements

The core of BeTelGeuse requires Java 1.3 or MIDP 2.0. Running BeTelGeuse requires additionally a JSR-82 compliant Bluetooth stack.

Windows XP

On Windows XP, we have tested BeTelGeuse using the Bluesock stack. Bluesock requires that Microsoft Windows Bluetooth stack is installed and that the Bluetooth transmitter supports the Microsoft stack. Thus Bluetooth dongles that support only Widcomm or Bluesoleil drivers can not be used with Bluesock. Microsoft Bluetooth stack is part of Windows XP Service Package 2. Bluesock is freely available.


BeTelGeuse has been tested on GNU/Linux (2.6.13-1 FC4-based, IA32). In Linux, we have used the Avetana Bluetooth stack, which requires additionally the BlueZ library. The Linux version of Avetana Bluetooth stack is freely available.

Mobile phones

BeTelGeuse should work on all mobile phones that support MIDP 2.0, CLDC 1.1 and JSR-82. BeTelGeuse has been tested with Nokia 6680, Nokia N80 and Sony Ericsson W800i devices.

Pocket PC with Microsoft Windows Mobile

On Pocket PC, a Java virtual machine, such as the IBM J9 or CrEme needs to be installed to the device. Currently we are not aware of any freely available Bluetooth stacks for Pockets PCs. We have tested BeTelGeuse using the IBM J9 JVM and Avetana Bluetooth stack. Note, while the Linux version is freely available, the Pocket PC (and Windows) version of Avetana Bluetooth stack are not free.

Installation and running the program

PC version

To run the PC version of BeTelGeuse, please ensure that a JSR-82 implementation for your operating system has been installed and that the jar file of the JSR-82 implementation is part of the Java classpath. You also need to ensure that the betelgeuse-core.jar and the betelgeuse-gui.jar are part of the Java classpath. After these steps you can run BeTelGeuse with the following command:

    java -cp [CLASSPATH] hiit.BeTelGeusePC

Mobile phones

On mobile phones, you need to download the approriate jar and jad files or to package the files youself using, e.g., the Sun Java Wireless Toolkit for CLDC. Once you have the jar and jad files, transfer them to the device, after which the device should be able to automatically install the application. To run the application, click on the BeTelGeuse icon in the appropriate folder (phone dependent).

Setting up Bluetooth devices

Currently BeTelGeuse supports the following Bluetooth sensors:

  • GPS
  • Alive Heart Monitor from Alive Technologies. Gives ECG and 3-axis acceleration measurements.
  • The I-Cube X WiMicroDig sensor box from Infusion Systems. Various possible sensor configurations can be created using the sensor box; our configuration includes 3-axis acceleration, orientation, temperature, humidity, ambient light and ultrasound distance sensors.
  • Local sensors on the device using sockets on the local device. As an example, on Symbian S60 phones (version 2.0) we can read GSM cell information from the Place Lab GSM server.
  • Bluetooth proximity information.

Although most JSR-82 stacks support on-the-fly authentication, the implementations usually have their own quircks. For this reason, we recommend pairing all sensors before launching BeTelGeuse using the operating systems own Bluetooth tools.

By default, BeTelGeuse discovers Bluetooth devices automatically and on-the-fly. In order to use a sensor in BeTelGeuse, you need to map the sensor to a suitable reader. This can be done from the GUI by letting BeTelGeuse discover your device and then assigning a reader to it. Alternatively, you can input a (sub)string that must be contained in the friendly name of the device for it to be mapped to a particular sensor, or you can manually insert the Bluetooth address of the device and assign it to a reader. The user interface section gives more information on how to map a sensor to a reader. Once the sensor mapping has been specified, BeTelGeuse automatically instantiates the appropriate parser on the next device inquiry. The mappings are stored on the device and thus they need to be specified once per device. BeTelGeuse can be simultaneously connected with seven Bluetooth devices. This limitation is caused by Bluetooth specification, which says that a maximum of seven devices can be connected at the same time.

Automatic device discovery can be turned off from the GUI and it is also possible to manually trigger the device discovery. If you use device discovery only for connecting sensors, we recommend turning off the automatic device discovery, especially if you are moving around in areas with a large amount of Bluetooth devices. This is because the device discovery can take a long time, especially if some of the devices are moving, and because device discovery might interfere with the sensors that are used to gather data.

If you wish to use the Place Lab GSM Cell server, you need to install and start the server before you start BeTelGeuse. You also need to configure the local device reader that is used by BeTelGeuse. This can be done from the options menu of the GUI.

Transmitting data to a server

BeTelGeuse includes a Transmitter plugin, which can be used to send data to a server. The default Transmitter implementation uses HTTP socket connections on both the MIDP and the PC versions of the program. The Transmitter is offline by default when the program is started. On both versions, the plugin can be accessed through the GUI. In order to use the transmitter, you need to set the address of the server that you want to use and to save the address. Next you need to turn on the plugin from the GUI, after which the transmitter will attempt to transmit data to the location you have specified.

User interface

On both the PC and the MIDP versions, the BeTelGeuse GUI shows values received by readers in tabbed panels. The panel for a single reader show the names of the parameters the reader supports and the last received value for each parameter.


On the phone version of BeTelGeuse, the options menu can be accessed by opening the menu and selecting options. On the PC version, the options are integrated with the devices discovered screen, which can be found from the file menu.

From the options menu, you can configure whether you wish to use automatic device discovery or not. You can also configure the time that is waited between subsequent device discovery attempts. This naturally has an effect only when the automatic device discovery is used. On the phone version, the options menu also allows selecting the kind of local device reader to use. This option does not need to be modified unless you want to use the Place Lab GSM server.

Reader timeouts

On the MIDP version, the timeouts for a particular reader can be accessed by selecting the reader, whose timeout you want to edit and selecting timeouts from the menu. On the PC version, the timeouts are visible on each readers information panel. The read interval defines the time that is waited between subsequent messages from the device. The start and stop timeouts govern how often the program tries to restore a lost connection, if the connection dies out. The time between subsequent retry attempts is always doubled until the value specified by stop is reached or exceeded. If the give up flag has been checked, BeTelGeuse stops retrying once the maximum value (stop) has been reached. Otherwise BeTelGeuse uses the value of stop for subsequent retry attempts.

Discovered devices

The discovered devices screen shows the list of Bluetooth devices found in the previous device discovery. You can specify a mapping rule for a specific device by selecting the Bluetooth address of the device.

Mapper rules

In the MIDP version, Mapper options can be accessed pressing the menu button and choosing Device mappings. In the PC version, Mapper options are under the Options menu. The mapper options screen shows information about currently available rules. The user can add new rules and delete old ones from this screen.

Last modified 2007-05-14