Java Marine API

Java Marine API

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):

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

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 SeaTalk¹ (`$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 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:

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.