The NMEA Reader is a library for processing and parsing raw NMEA data in to java objects. The model is developed to allow multiple data sources as well as multiple clients receiving the processed data.
The library is composed of three primary component types, DataProviders which are the sources of raw NMEA data, NMEAListeners or clients of the parsed NMEA data and the NMEASentenceProvider which connects the two. All NMEA data provided to the listeners is in the form of sub-classes of the class NMEASentence.
All raw data providers must extend the class DataProvider. This base class provides the core logic used by the NMEASentenceProvider for connecting the raw data provided by the DataProvider to the parsing logic and subsequently to the listeners. The concrete implementation of the DataProvider class submits raw data for processing by calling the method provideData(byte[] data, int offset, int numBytes) on the super class DataProvider. The concrete data provider is expected to implement the method start() which starts the processing of data and the method stop() in which the data provider should halt processing and clean up all resources in use. How the raw NMEA data is read and provided to the underlying system is entirely up to the data provider implementation.
Two data providers are included in the library, the PortListenerDataProvider which reads the raw data from a serial port and the InputFileDataProvider which reads raw NMEA sentences from an input. The primary usage for the second date provider is for development and debugging purposes when a live NMEA data source is not available. The provided SentenceLogger listener saves NMEA in a format consistent with the InputFileDataProvider.
All clients for the NMEA data must implement the interface NMEAListener. _NMEASentence_s are provided to the client by call backs to the method processEvent(NMEASentence sentence). Any processing in this method should be kept to minimal levels of complexity to minimize the work done on the parsing thread. Slowing this thread will potentially impact the rate at which sentences are provided to the system since all clients are served by the same thread.
During the shutdown process, the NMEASentenceProvider will call the method stop() on the listener to allow it to close any open resources.
The NMEASentenceProvider is the core driver for the processing. All data providers from which raw data will should be processed are provided when the NMEA sentence provider is constructed and listeners are registered through the method addListener(NMEAListener listener). For each data provider processed by the NMEASentenceProvider a thread is constructed to parse the data from this data provider and provide the NMEASentence to the listeners. This parsing thread and the data provider are connected through a pair of piped output and input streams. Processing of data is started and stopped by calling the methods start() and stop().
An example Java application is provided in the class com.bb.nmea.main.Main. This client is configurable using a properties file and supports reading NMEA data from files and serial ports.
The basic pattern for using the NMEASentenceProvider is as follows;
// Create and add all desired data providers to the list
List<DataProvider> dataProviders = ArrayList<DataProvider>();
// Create the NMEA sentence provider
NMEASentenceProvider nmeaProvider = new NMEASentenceProvider(dataProviders);
// Create and add any listeners
SentenceLogger logger = new SentenceLogger();
nmeaProvider.addListener(logger);
// Start processing
nmeaProvider.start();
//
// Wait while data is processed...
//
// When ready to exit, stop processing
nmeaProvider.stop();All NMEA sentence implementations included library are in the package com.bb.nmea.sentences. Each class in this package except for the classes InvalidSentence and UnsupportedSentence are concrete implementations for a specific three-digit NMEA sentence type. The general class naming scheme is for the class name to be all capital letters and the same as the NMEA type the class supports.
The two classes InvalidSentence and UnsupportedSentence are used in the parsing logic for specific purposes. All raw NMEA sentences which do not pass basic validation are parsed in to instances of the class InvalidSentence and all valid sentences of an NMEA type which do not have a concrete class implementing support are parsed in to instances of the type UnsupportedSentence. This allows the system to provide parsing for all sentence types for basic listeners such as the SentenceLogger which really only need the raw data.
All NMEA sentences classes must extend the base class, NMEASentence, and must implement a constructor taking a single String parameter, where the string is the raw NMEA sentence. All parsing of the raw sentence into discrete fields is handled by the superclass. The subclasses can utilize methods, ie. getField(int) or getFieldAsFloat(int), on the superclass to obtain the value of the fields from the raw NMEA sentence as specific field types. Some special classes for parsing particular field types, such as latitude and longitude values as well as heading types, are included in the package com.bb.nmea.sentences.common. These field types are encoded in particular ways in the raw NMEA sentence, so the common logic is provided for parsing and representing these.
In addition, each class supporting an NMEA sentence type are registered in the properties file, sentences.properties. The format for an entry in this file is "type=fully.qualified.path.for.Class" where the property name is the three digit NMEA sentence type and the value is the fully qualified class.
Basic steps for implementing a support for a new NMEA sentence type are;
- Implement the class for the sentence in the package
com.bb.nmea.sentences - Implement a basic unit test for the new sentence type class
- Add an entry for this class in the properties file,
sentences.properties - Add a test case in unit test SentenceFactoryTest.java for the new class to insure that the factory properly handles the new class.
- If desired, add this sentence to a test case in the unit test NMEASentenceProviderTest.java. At some point, not all sentences need be included here.