BeTelGeuse manual

1. 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. The mobile phones we have tested BeTelGeuse on include Nokia 6680, N80, N91, N95, E61i, E71, and Sony Ericsson W800i.

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 require a license.

Python extensions

The Python extensions require Python for S60 (PyS60) version 1.4.2 or later. PyS60 is available as a free download from its project page at Symbian S60 2nd edition or later is required.

For GSM cell data to be accessible the PyS60 installation needs to be signed with a developer license for the device in question.

2. Installation and running the program

2.1 Mobile phone

On mobile phones, you need to download the appropriate jar and jad files or to package the files yourself using, e.g., the Sun Java Wireless Toolkit for CLDC. Once you have the jar and jad files, transfer them to the device (e.g., over Bluetooth). Opening the jad file should automatically start the installation. To run the application, click on the BeTelGeuse icon in the appropriate application folder (phone dependent).

Initialization of BeTelGeuse can take a while especially in environments with many Bluetooth active devices, since BeTelGeuse runs a Bluetooth scan at startup. BeTelGeuse has not been signed with a certificate, so the user has to approve use of Bluetooth and 3G connections, and approve access to each file read or written by BeTelGeuse. Once BeTelGeuse has run a device discovery, a log-in screen will be displayed. The user is asked to enter a username and a password. BeTelGeuse does not authenticate the user. The username is used when saving or transmitting the data. Any authentication and password checks have to be made on, for example, an external server.

2.2 Installing Python scripts

The Python for S60 script shell looks for scripts in the directory /Python on the memory card, so scripts can be installed just by creating the directory on the memory card and copying your scripts there. They are then accessible from the Run script menu item in Python.

The script acts as an extension for BeTelGeuse and provides information about the current GSM cell, signal strength, user interaction with the phone and other contextual data. When you run the script it automatically also starts BeTelGeuse using the push registry feature.

2.3 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

3. Setting up Bluetooth devices

Although most JSR-82 stacks support on-the-fly authentication, the implementations usually have their own quirks. Pairing the sensors before launching BeTelGeuse using the operating systems own Bluetooth tools may resolve some issues.

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 parser. This can be done from the GUI by letting BeTelGeuse discover your device and then assigning a parser 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 parser. 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 does not allow more than seven devices connected at the same time.

Automatic device discovery can be turned off from the GUI after which it is possible to manually trigger the device discovery. If you use device discovery only for connecting to sensors, we recommend turning off the discovery, especially if you are moving around in areas with a many Bluetooth active 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 already connected to BeTelGeuse.

4. 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 Readerís 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.

5. Transmitting data to a server

BeTelGeuse comes with two Transmitter plugins: the BoardTransmitter that sends the data to an external server, and the LocalTransmitter that saves the data on mobile phone's memory card. The BeTelGeuse distribution package uses the LocalTransmitter, since the server's address needs to be specified for the BoardTransmitter. If you wish to use the BoardTransmitter, you need to recompile BeTelGeuse with the correct Transmitter plug-in (see the Developer's Guide). The BoardTransmitter uses a custom light-weight protocol to transmit the data to a server (see the BeTelGeuse protocol specification).

6. Subscribing to the data from another application

Other applications running on the client device can connect to the BeTelGeuse blackboard via a local socket. The default port for the blackboard is 10004. Applications, or components, can subscribe to data sources after connecting to the blackboard. See the blackboard protocol specification for more details.