/marine-api

Java Marine API - NMEA 0183 library for Java

Primary LanguageJavaGNU Lesser General Public License v3.0LGPL-3.0

Java Marine API

License Build Maven Central Download Java Marine API Javadocs Sponsored by Spice

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 SeaTalk1
  • 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/.

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

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:

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.

ID Description
ALK The NMEA 0183 layer of Raymarine SeaTalk1 ($STALK)
APB Autopilot cross-track error, destination bearings and heading
BOD Bearing from origin to destination
CUR Water currents information
DBT Water depth below transducer in meters, feet and fathoms
DPT Water depth in meters with offset to transducer
DTA Boreal GasFinder2 and GasFinderMC
DTB Boreal GasFinder2 and GasFinderMC
DTM Datum reference
GBS Glonass satellite fault detection (RAIM support)
GGA GPS fix data
GLL Current geographic position and time
GNS Glonass fix data
GSA Precision of GPS fix
GST GPS pseudorange noise statistics
GSV Detailed GPS satellite data
HDG Heading with magnetic deviation and variation
HDM Magnetic heading in degrees
HDT True heading in degrees
HTC Heading/Track control systems input data and commands.
HTD Heading/Track control systems output data and commands.
MDA Meteorological composite
MHU Relative and absolute humidity with dew point
MMB Barometric pressure
MTA Air temperature in degrees Celcius
MTW Water temperature in degrees Celcius
MWD Wind speed and direction.
MWV Wind speed and angle
OSD Own ship data
RMB Recommended minimum navigation information "type B"
RMC Recommended minimum navigation information "type C"
ROT Vessel's rate of turn
RPM Engine or shaft revolutions
RSA Rudder angle in degrees
RSD Radar system data
RTE GPS route data with list of waypoints
TLB Target label
TTM Tracked target message
TXT Text message
VBW Dual ground/water speed.
VDM The NMEA 0183 layer of AIS: other vessels' data
VDO The NMEA 0183 layer of AIS: vessel's own data
VDR Set and drift
VHW Water speed and heading
VLW Distance traveled through water
VTG Course and speed over ground
VWR Relative wind speed and angle
VWT True wind speed and angle
WPL Destination waypoint location and ID
XDR Transducer measurements
XTE Measured cross-track error
ZDA UTC time and date with local time offset

AIS

The following AIS messages are decoded.

ID Description
01 Position Report Class A
02 Position Report Class A (Assigned schedule)
03 Position Report Class A (Response to interrogation)
04 Base Station Report
05 Static and Voyage Related Data
09 Standard SAR Aircraft Position Report
18 Standard Class B CS Position Report
19 Extended Class B Equipment Position Report
21 Aid-to-Navigation Report
24 Static Data Report
27 Position Report for long range applications

Raymarine SeaTalk1

Not to be confused with SeaTalkng 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:

ID Description
PUBX,01 Lat/Long Position Data
PUBX,03 Satellite Status

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:

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

Navigation Center of U.S. Department of Homeland Security

Product Manuals and User Guides

Wikipedia

Miscellaneus

No longer available