Gtk-G-Rays2 Manual

Introduction

Knowing how things work is the basis for appreciation, and is thus a source of civilised delight.

William Safire

gtk-g-rays2 is an application to configure and manage the Wintec WBT 201 Bluetooth GPS.

The Wintec WBT 201 is an impressive, Bluetooth and USB, logging GPS. It can be used with gpsbabel versions later than 1.33, including 1.34 pre-release CVS versions.

In order to access the WBT 201 configuration settings, the manufacturer provides a closed source application, only available on Microsoft operating systems. gtk-g-rays2 attempts to rectify this situation by providing a portable, open source configuration tool that can work on multiple operating systems. gtk-g-rays2 provides as much of the functionality of the close source application as is possible from the available information on the WBT-201 protocol.

gtk-g-rays2 is licensed under the GNU Public Licence v2 or any later version of your choice. gtk-g-rays2 is (c) Jonathan R Hudson jh+gps@daria.co.uk

Installation

gtk-g-rays2 is provided as a source code archive. It requires the GTK2+ toolkit with the cairo graphics library. If you have a typical open source development environment installed, than installation should be as simple as:

$ ./configure [--prefix=/usr]
    $ make
    $ sudo make install

On first launch, gtk-g-rays2 will create a default configuration file, $HOME/.config/g-rays2/g-rays2rc, which is populated with default values that may be edited from the Preferences menu option.

Usage

How should I know if it works? That's what beta testers are for. I only coded it.

Linus Torvalds

The application is launched as

$ gtk-g-rays2

It may be run from a terminal, or from a menu or other graphical user interface launcher. A suitable icon for a graphical launcher may be found in $prefix/share/gtk-g-rays2/ ($prefix is /usr/local unless changed at build time).

Settings Tab

On start up, the main window is displayed, showing the settings tab:

Settings Tab

At this stage, the useful controls are the Serial Port and Connect items. The Serial Port control lists the serial devices available, by default auto, bluetooth and /dev/ttyUSB0; however this may be changed from the Edit ▸ Preferences menu item.

If the selected device is named auto, then the application will attempt to discover first a USB and then a bluetooth connection.

A device named bluetooth will invoke Bluetooth auto-discovery.

Once a suitable device is selected from the Serial Port combo-box, and the user clicks on the Connect button, gtk-g-rays2 will attempt to connect to the device and read the settings. If the connection is successful, the connection indicator will show the new state, and the settings will be read from the device and displayed.

Settings Tab, connected

Items that are "greyed out" may not be changed; on the right hand side, the valid items will depend on the Log Type selected. The different log types and the parameters pertinent to each one are described in the documentation of the proprietary Wintec application. Please see this document for an explanation of the fields.

The buttons on this tab perform the following functions:

Apply

Clicking Apply will apply the settings to the device;

Clear Log

Clear Log will clear any logged (stored) track and way-point data from the device;

Reset Defaults

Reset Defaults will restore the factory defaults (or at least the initial settings obtained from the author's device);

Quit

Quit closes the application, and saves the current preferences.

Data Tab

The data tab switches the device from settings into normal usage mode and displays GPS data and satellite information. Although the fields cannot be edited, they are "activated", so data may be copied with the mouse.

Data Tab

As with the Setting tab, Quit closes the application, and saves the current preferences.

Automatic Bluetooth instantiation

The central enemy of reliability is complexity.

Geer et al.

From version 2.00, Bluetooth devices are auto-discovered. Let's see how reliable that is.

For version 2.04 and later, we eschew the Bluez API (shall we change the API with every release?, shall we fail to provide any sort of usable documentation?

Instead, from 2.04, gtk-g-rays2 uses the low level libbluetooth API. This should work across all distributions, regardless of Bluez version.

The main reason for migrating to a BT auto-discovery model are:

  • Remove the need for a SUID / sudo script to instigate the Bluetooth serial connection;

  • Allow for auto-detection and configuration of the first available interface (USB or Bluetooth, in that order).

There are a number of things you need to be aware using the 2.0x Bluetooth auto-detection implementation:

  • The bluetooth service must be running;

  • The G-Rays2 device must be paired. Changing the BT adaptor probably means it needs re-pairing.

  • It is also possible that some application (perhaps modem-manager) has grabbed the BT (or USB) device, and is unhelpfully probing it in case it happens to be a 3G modem. There are a couple of sample udev rules (install in /etc/udev/rules.d) in the documentation directory that might help with this problem (you will need to adjust for your own devices IDs), or you can disable modem-manager in the network manager configuration.

When you select auto or bluetooth as a connection, gtk-g-rays2 will attempt to auto-discover the BT GPS. If a GRays-2 GPS is discovered, gtk-g-rays2 saves the BT address under the key btaddr= in the configuration file. The next time you use auto or bluetooth as the connection type, this BT address will be used, greatly speeding up the connection. If you were to use different GRays-2 GPS, then it would be necessary to manually delete this key in order to permit auto-discovery again.

Bluetooth manual instantiation

It is possible to use Bluetooth without auto-detection, in the same manner as was implemented for gtk-g-rays2 version 1.x, but with manual creation and tear down of the Bluetooth serial device.

  • Create a /dev/rfcomm0 device, for example using the g-rays2-rfcomm.sh script shipped with earlier versions of gtk-g-rays2;

  • Start gtk-g-rays2 and set the device manually to /dev/rfcomm0 and connect to it;

  • When you exit gtk-g-rays2, remove the Bluetooth device.

	g-rays2-rfcomm.sh start
	gtk-g-grays2
	g-rays2-rfcomm.sh stop