The following pseudo-UML diagram details the basic structure of the LocationManager framework. The LocationManager framework is composed of the following classes:

• LocationManager - The main class used by the application/activity
• LocationDevice - The abstract class which represents all device descriptors
• LocationProvider - The abstract class which represents all location providers
• LocationException - The root of all exceptions thrown by a location provider
• GPXWriter - Functionality to record streams of locations as a GPX file
• DeviceException - The root of all exceptions thrown by LocationDevice operations

The framework also provides the following devices and providers:

• BuiltInGPSDevice/BuiltInGPSProvider - Interface for the Android built in GPS
• PlaybackDevice/PlaybackProvider - Interface to playback locations from a previously recorded GPX file.

A LocationDevice provides a device Name (human readable) map to the Provider (via getProviderInstance() method). During normal operations, the Application/Activity asks the LocationManager for a list of known providers. The Application/Activity displays those to the user, or makes a choice (somehow). Once the LocationDevice is chosen, the Application then requests updates. The LocationManager will create and manage an instance of the LocationProvider, as needed. The application does not need to be involved in Provider management.

Adding new devices is relatively straight forward. For each new device you must write a new class to be the LocationDevice and write a new class to be the LocationProvider. It is up to the Device to perform detection and verification of the physical device, while the Provider is to provide the normalized location updates when they are made available via the physical device.

If the instrument being added is a Bluetooth device, the you should extend com.agtek.location.bluetooth.AbstractBluetoothDevice instead of the normal LocationDevice and the Provider should extend com.agtek.location.bluetooth.AbstractBluetoothProvider. These classes serve to combine common Bluetooth functionality and data needed across all Bluetooth devices.

Each LocationProvider, once initialized and running is responsible for consuming the data stream from the instrument, normalizing the resulting locations, and providing location updates via the manager. When the LocationProvider is instantiated, it is given a reference to the LocationManager, and the provider should cache that value.

Psuedo Provider Flow In the constructor the Provider most likely performs a series of operations like:

   MyProvider( LocationManager mgr, LocationDevice dev )
   {
      super( mgr, dev );
      m_locationManager = mgr;
   }

If you are implementing a Bluetooth device, you've extended the AbstractBluetoothProvider, which supplies an automatic thread to manage the run state. You need only implement the run() method, consume data, normalize it and report. Note, the following example was extracted from the NMEA Provider, so some details will be different for your Provider.

   public void run()
   {
      long lastTime = 0;
      BluetoothLocationDevice btLocDev = (BluetoothLocationDevice) m_device;
      BluetoothDevice btDev = btLocDev.getBluetoothDevice();
      
      // This UUID is the well known UUID of the SPP
      UUID uuid = UUID.fromString(SPP_UUID_STRING);
      try
      {
         BluetoothSocket socket = btDev.createRfcommSocketToServiceRecord(uuid );
         socket.connect();
         InputStream nmeaStream = socket.getInputStream();
         InputStreamReader nmeaReader = new InputStreamReader( nmeaStream );
         
         // Temporary character storage until the string to read has been assembled. 
         char charBuf[] = new char[256];
         while( m_running )
         {
            // read data
            // Make Location object
            Location l = new Location(); // With magic supplied by you
            
            // now report it.
            m_locationManager.reportPosition( this, l);
         }
   }

Note that this example doesn't show how to handle errors, parse the data, etc. Please note that m_runnning is set by the AbstractBluetoothProvider class in response to stop and starting events from the LocationManager. You must respond to this variable in your inner run loop. This is the signal tell you to continue, or exit the loop.

This diagram illustrates the coarse structure of the Leica ICG60 Provider. Because of how Bluetooth IO works in Android, the Java code must read the socket and pass the information to the native Leica SDK. After processing the native code calls some Agtek call backs (e.g. position updates, etc.) which in turn call back into the Java code to deliver results to the application.

The location manaher provides a basic NMEA provider which allows the system to read and parse location sentences (typically $GPGGA). This provider doesn't do much more than connect to the device, enable position streaming, parse, and deliver the results. The generic NMEA provider is suitable for providing basic location services to applications.

The provider provides extension capabilities allowing subclasses the ability to add additional NMEA sentence parsers for extended capability. The structure of the provider also allows sub classes the send device type specific initialization commands to the instrument as needed.

An example of the extended NMEA capabilities are part of the Track Reader project enabling track download and initialization of specific features for the QStar series of instruments.