Java Marine API

• Java Marine API
  • About
    • Features
    • Licensing
    • Disclaimer
    • Requirements
    • Usage
  • Supported Protocols
    • NMEA 0183
    • AIS
    • Raymarine SeaTalk¹
    • u-blox
  • Distribution
    • Pre-built JARs
    • Maven
      • Snapshots
  • Contributing
  • References
    • National Marine Electronics Association
    • Navigation Center of U.S. Department of Homeland Security
    • Product Manuals and User Guides
    • Wikipedia
    • Miscellaneus
    • No longer available

About

Java Marine API is an NMEA 0183 parser library for decoding and encoding the data provided by various electronic marine devices such as GPS, echo sounder and weather instruments.

Features

• Generic and extentable API
• Detects NMEA 0183 sentences from most input streams
  • E.g. from file, serial port, TCP/IP or UDP socket
  • The provided data readers can be overridden with custom implementation
• Converts the ASCII data stream to event/listener model with interfaces and parsers for selected sentences
• Additional parsers may be added by extending the provided base classes
  • This can be done at runtime and does not require compiling the library
• Sentence encoding with common validation and unified formatting
• Several sentences can be aggregated to single event by using providers
  • For example, to record current position and depth of water
• Decoding of selected AIS messages
• The NMEA 0183 layer of Raymarine SeaTalk¹
• Utilities and enumerations for handling the extracted data

Licensing

Java Marine API is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Java Marine API is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with Java Marine API. If not, see http://www.gnu.org/licenses/.

• See also: LGPL and Java

Disclaimer

Java Marine API is not official NMEA 0183 software. Further, it is not related to National Marine Electronics Association.

The interpretation of NMEA 0183 and related protocols is based entirely on varying set of publicly available documents in the Internet. Thus, it is not guaranteed that the library follows and implements these standards correctly.

Electronic devices and software do not replace safe navigation practices and should never be your only reference.

Requirements

• Java 2 SE JRE/JDK 11 or newer
• For serial port communication (choose one):
  • Neuron Robotics Java Serial Library
  • PureJavaComm
  • RXTX library
  • Java Communications API

Usage

Write a listener:

class GGAListener extends AbstractSentenceListener<GGASentence> {
    public void sentenceRead(GGASentence gga) {
        Position pos = gga.getPosition();
        // .. your code
    }
}

Set up the reader:

File file = new File("/var/log/nmea.log");
SentenceReader reader = new SentenceReader(new FileInputStream(file));
reader.addSentenceListener(new GGAListener());
reader.start();

Manual parsing:

String nmea = "$GPGSA,A,3,03,05,07,08,10,15,18,19,21,28,,,1.4,0.9,1.1*3A";
SentenceFactory sf = SentenceFactory.getInstance();
GSASentence gsa = (GSASentence) sf.createParser(nmea);

Recommended Android Proguard settings when minifyEnabled is set true:

-keep class net.sf.marineapi.** { *; }
-keep interface net.sf.marineapi.** { *; }
-keepattributes MethodParameters
-dontwarn gnu.io.CommPortIdentifier
-dontwarn gnu.io.RXTXPort
-dontwarn gnu.io.SerialPort

See also:

• Examples
• Javadocs
• Graphical User Interface using marine-api by @aitov

Supported Protocols

NMEA 0183

The following sentences are decoded and encoded. The provided parsers may be overridden and additional parsers may be added at runtime, without compiling the library. See wiki for instructions.

AIS

The following AIS messages are decoded.

Raymarine SeaTalk¹

Not to be confused with SeaTalk^ng derived from NMEA 2000.

Only the NMEA layer is currently supported, see STALKSentence and Issue #67.

u-blox

The following u-blox vendor extension messages are supported:

Distribution

Releases and snapshots are published every now and then, but there is no clear plan or schedule for this as most of the development happens per user requests or contribution.

Pre-built JARs

Release JARs may be downloaded from releases and Sourceforge.net. The ZIP package should contain all to get you going.

The project was first published in Sourceforge, hence the net.sf.marineapi package naming.

Maven

Both releases and snapshots are deployed to Maven Central Repository and may be imported by adding the following dependency in your pom.xml.

<dependency>
  <groupId>net.sf.marineapi</groupId>
  <artifactId>marineapi</artifactId>
  <version>0.10.0</version>
  <type>bundle</type>
</dependency>

Snapshots

The snapshots should be mostly stable, but they are still Work In Progress and should be considered as a preview of the next release.

See changelog.txt for the current SNAPSHOT version. Notice that you may need to tweak your Maven settings to enable snapshot dependencies.

<dependency>
  <groupId>net.sf.marineapi</groupId>
  <artifactId>marineapi</artifactId>
  <version>0.11.0-SNAPSHOT</version>
  <type>bundle</type>
</dependency>

Snapshots may also be downloaded manually from the repository.

Contributing

Any feedback or contribution is welcome. You have several options:

• Contact me
• Report a bug
• Fork and open a pull request to share improvements.

References

All information and specifications for this library has been gathered from the following documents, availability last checked on 2020-03-15.

Notice: any warnings regarding the accuracy of the information in below documents apply equally to Java Marine API.

National Marine Electronics Association

• Amendment to NMEA 0183 v4.10 # 20130814
• Amendment to NMEA0183 v4.10 # 20130815
• Amendment to NMEA0183 v4.10 # 20131216
• Approved 0183 Manufacturer's Mnemonic Codes
• Manufacturer Mnemonic Codes and Sentence Formatters List
• NMEA 0183 Sentences Not Recommended for New Designs
• Standards Update October 2014 by Steve Spitzer

Navigation Center of U.S. Department of Homeland Security

• Automatic Identification System Overview

Product Manuals and User Guides

• BD9xx GNSS Receivers Help by Trimble Navigation Limited
• Guide for AgGPS Receivers by Trimble Navigation Limited
• Hydromagic NMEA 0183 documentation by Eye4Software
• NM-2C User's Guide by Nuova Marea Ltd
• PB100 WeatherStation Manual by Airmar
• RT Intertial+ NMEA Description (rev. 100720) by Oxford Technical Solutions Ltd
• SeaTalk/NMEA/RS232 Converter Manual by gadgetPool
• SiRF NMEA Reference Manual by SiRF Technology, Inc.
• The NMEA Information Sheet by Actisense
• ZED-F9P F9 high precision GNSS receiver Interface Description by u-blox

Wikipedia

• NMEA 0183
• Automatic Identification System

Miscellaneus

• AIVDM/AIVDO protocol decoding by Eric S. Raymond
• NMEA Revealed by Eric S. Raymond
• SeaTalk Technical Reference by Thomas Knauf

No longer available

• NMEA Data by Dale DePriest
• NMEA Sentence Information by Glenn Baddeley (not found)
• RS232/SeaTalk/NMEA Converter manual by gadgetPool (not found)
• The NMEA FAQ by Peter Bennett (see older copy)