Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.location

Class NmeaLocationDataSource

java.lang.Object
com.esri.arcgisruntime.location.LocationDataSource
com.esri.arcgisruntime.location.NmeaLocationDataSource
public final class NmeaLocationDataSource extends LocationDataSource
This object will parse specific NMEA messages pushed into it. Valid GGA, GSA, GST, GSV, RMC, VTG messages are parsed and, depending upon the message type and contents, and a LocationDataSource.LocationChangedEvent or NmeaLocationDataSource.SatellitesChangedEvent may be raised. The LocationDataSource.LocationChangedEvent will return a NmeaLocationDataSource.NmeaLocation object. The NmeaLocationDataSource.LocationChangedEvent will return an array of NmeaSatelliteInfo objects. This data source is based on NMEA version 4.11 (November 2018).
Since:
100.10.0

  • Constructor Details

    • NmeaLocationDataSource

      public NmeaLocationDataSource()
      Creates an NMEA location data source object. Locations created from this data source will have a SpatialReference of WGS84.
      Since:
      100.10.0

    • NmeaLocationDataSource

      public NmeaLocationDataSource(SpatialReference receiverSpatialReference, SpatialReference outputSpatialReference, DatumTransformation outputDatumTransformation)
      Creates an NMEA location data source object. Locations from this data source will be projected from the SpatialReference defined by the receiverSpatialReference parameter to the spatial reference defined by the outputSpatialReference parameter using the datum transformation defined by outputDatumTransformation. If the outputSpatialReference is null, the locations will not be projected and the locations will be in the receiverSpatialReference, ignoring the outputDatumTransformation.

      This constructor can be be used when a receiver is outputting locations in a SpatialReference other than WGS84, such as when using a reference base station, and/or the application requires the output locations to be projected to a different SpatialReference using a DatumTransformation.

      Parameters:
      receiverSpatialReference - the spatial reference of incoming NMEA receiver data
      outputSpatialReference - the spatial reference to project the NmeaLocationDataSource.NmeaLocation to
      outputDatumTransformation - the DatumTransformation to use when projecting the NmeaLocationDataSource.NmeaLocation
      Throws:
      IllegalArgumentException - if receiverSpatialReference is null
      Since:
      100.10.0

    • NmeaLocationDataSource

      public NmeaLocationDataSource(SpatialReference receiverSpatialReference, SpatialReference outputSpatialReference)
      Creates an NMEA location data source object. Locations from this data source will be projected from the SpatialReference defined by the receiverSpatialReference parameter to the spatial reference defined by the outputSpatialReference parameter. If the outputSpatialReference parameter is null, the locations will not be projected and the locations will be in the receiverSpatialReference.

      This constructor can be be used when a receiver is outputting locations in a SpatialReference other than WGS84, such as when using a reference base station, and/or the application requires the output locations to be projected to a different SpatialReference.

      Parameters:
      receiverSpatialReference - the spatial reference of incoming NMEA receiver data
      outputSpatialReference - the spatial reference to project the NmeaLocationDataSource.NmeaLocation to
      Throws:
      IllegalArgumentException - if receiverSpatialReference is null
      Since:
      100.10.0

    • NmeaLocationDataSource

      public NmeaLocationDataSource(SpatialReference receiverSpatialReference)
      Creates an NMEA location data source object. Locations from this data source will have a SpatialReference defined by the receiverSpatialReference parameter.

      This constructor can be used when a receiver is outputting locations in a SpatialReference other than WGS84, such as when using a reference base station.

      Parameters:
      receiverSpatialReference - the spatial reference of incoming NMEA receiver data
      Throws:
      IllegalArgumentException - if receiverSpatialReference is null
      Since:
      100.10.0

  • Method Details

    • getOutputDatumTransformation

      public DatumTransformation getOutputDatumTransformation()
      Gets the DatumTransformation to be used in the project operation. If set, this property will be used as the DatumTransformation in the call to GeometryEngine.project(Geometry, SpatialReference, DatumTransformation). For this property to be used, the outputSpatialReference property also has to be set.
      Returns:
      the datum transformation to be used in the project operation
      Since:
      100.10.0

    • getOutputSpatialReference

      public SpatialReference getOutputSpatialReference()
      Gets the output spatial reference. The projected point will be stored in LocationDataSource.Location.getPosition(). If this property is null, the position will contain the original incoming x, y, and z values from the NMEA data sentence and the getReceiverSpatialReference().
      Returns:
      the output spatial reference
      Since:
      100.10.0

    • getReceiverSpatialReference

      public SpatialReference getReceiverSpatialReference()
      Gets the SpatialReference to be assigned to the output NmeaLocationDataSource.NmeaLocation; the default is WGS84. By default, this will be WGS84 for its horizontal (WKID=4326) and vertical reference systems (WKID=115700). This can be set to a different spatial reference if a receiver returns locations in a different reference system.
      Returns:
      the spatial reference to be assigned to the output location, the default is WGS84
      Since:
      100.10.0

    • addSatellitesChangedListener

      public void addSatellitesChangedListener(NmeaLocationDataSource.SatellitesChangedListener listener)
      Registers the given listener to be called when satellites have changed.

      This listener will be invoked on the UI thread if it is added from the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

      Parameters:
      listener - a listener to be called when the satellites have changed
      Throws:
      IllegalArgumentException - if listener is null
      Since:
      100.10.0
      See Also:

    • removeSatellitesChangedListener

      public boolean removeSatellitesChangedListener(NmeaLocationDataSource.SatellitesChangedListener listener)
      Unregisters the given listener that was previously added using addSatellitesChangedListener(SatellitesChangedListener).
      Parameters:
      listener - the listener to unregister
      Returns:
      true if the listener was removed successfully; false otherwise
      Since:
      100.10.0
      See Also:

    • pushData

      public void pushData(byte[] data)
      Reads the input NMEA data creating an NmeaLocationDataSource.NmeaLocation. The NMEA location data source needs to be started before calling this method.

      When pushing data:

      • Each sentence needs to begins with a '$'.
      • Each sentence needs to end with carriage return/line feed sequence.
      • Single or multiple sentences can be pushed at one time, all strings in the buffer will be parsed.
      • There is no explicit limit on the amount of data that can pushed at one time.
      • If a partial sentences are pushed the data source accumulates (and concatenates) the pushed data until a carriage return/line feed sequence is reached.
      • The data source parses these messages types: GGA, GSA, GST, GSV, RMC, VTG.
      • Each sentence's checksum is validated.
      • Unknown/bad/incorrect sentences are ignored (They do not produce any location, satellite updates etc.).
      • Sentences support up to 256 characters (This is beyond the NMEA spec's 82 character limit to support receiver's that output longer sentences).
      • Messages should be of the form: "$XXYYY,[data]*[checksum]\r\n"
      Example: 
      
 <String>$GPGGA,092750.000,5321.6802,N,00630.3372,W,1,8,1.03,61.7,M,55.2,M,,*76
 $GPGSA,A,3,10,07,05,02,29,04,08,13,,,,,1.72,1.03,1.38*0A
 $GPGSV,3,1,11,10,63,137,17,07,61,098,15,05,59,290,20,08,54,157,30*70
      See https://www.nmea.org/ for more information on the NMEA standard.
      Parameters:
      data - the data buffer that contains NMEA data
      Since:
      100.10.0

    • onStart

      protected void onStart()
      Description copied from class: LocationDataSource
      Called from LocationDataSource.startAsync(). Subclasses should implement this method to prepare for starting the data source. The LocationDataSource.onStartCompleted(Throwable) method must be called by the subclass once the location data source has finished its starting process.
      Specified by:
      onStart in class LocationDataSource

    • onStop

      protected void onStop()
      Description copied from class: LocationDataSource
      Called from the LocationDataSource.stopAsync() method, subclasses should perform any necessary clean-up in this method; for example, stop streaming the location data, release resources, and so on.
      Specified by:
      onStop in class LocationDataSource