ArcGIS Runtime SDK for iOS: AGSNMEALocationDataSource Class Reference
ArcGIS Runtime SDK for iOS  100.15
AGSNMEALocationDataSource Class Reference

Description

An NMEA location data source object.

An instance of this class 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, an locationDataSource:locationDidChange: (AGSLocationChangeHandlerDelegate-p) or NMEALocationDataSource:satellitesDidChange: (AGSNMEALocationDataSourceDelegate-p) may be raised. The locationDataSource:locationDidChange: (AGSLocationChangeHandlerDelegate-p) will return an AGSNMEALocation. The NMEALocationDataSource:satellitesDidChange: (AGSNMEALocationDataSourceDelegate-p) will return an array of AGSNMEASatelliteInfo. This data source is based on NMEA version 4.11 (November 2018).

This object can parse NMEA messages pushed into it creating an AGSNMEALocation object that is obtained via the locationDataSource:locationDidChange: (AGSLocationChangeHandlerDelegate-p)

The Apple AppStore has guidelines and restrictions for apps that communicate with MFi accessories (for example: an external GPS receiver). Apps that use NMEA data need to satisfy the Apple requirements to be accepted in the store. Apps need to declare support via PPID in their submission and the MFi provider needs to list the bundle ID so Apple can cross reference it. For more information, see the site MFi Program.

Since
100.10
Inheritance diagram for AGSNMEALocationDataSource:
AGSLocationDataSource AGSObject

Instance Methods

(void) - didStartOrFailWithError:
 
(void) - didStop
 
(void) - didUpdateHeading:
 
(void) - didUpdateLocation:
 
(void) - doStart
 
(void) - doStop
 
(instancetype) - init
 
(nullable instancetype) - initWithEAAccessory:protocol:
 
(instancetype) - initWithReceiverSpatialReference:
 
(instancetype) - initWithReceiverSpatialReference:outputSpatialReference:
 
(instancetype) - initWithReceiverSpatialReference:outputSpatialReference:outputDatumTransformation:
 
(void) - pushData:
 
(void) - startWithCompletion:
 
(void) - stop
 
(void) - stopWithCompletion:
 

Class Methods

(instancetype) + NMEALocationDataSource
 
(nullable instancetype) + NMEALocationDataSourceWithEAAccessory:protocol:
 
(instancetype) + NMEALocationDataSourceWithReceiverSpatialReference:
 
(instancetype) + NMEALocationDataSourceWithReceiverSpatialReference:outputSpatialReference:
 
(instancetype) + NMEALocationDataSourceWithReceiverSpatialReference:outputSpatialReference:outputDatumTransformation:
 

Properties

NSError * error
 
id< AGSNMEALocationDataSourceDelegatelocationChangeHandlerDelegate
 
AGSDatumTransformationoutputDatumTransformation
 
AGSSpatialReferenceoutputSpatialReference
 
AGSSpatialReferencereceiverSpatialReference
 
BOOL started
 
AGSLocationDataSourceStatus status
 

Method Documentation

◆ didStartOrFailWithError:

- (void) didStartOrFailWithError: (nullable NSError *)  error

Subclasses must call this in doStart (AGSLocationDataSource(ForSubclassEyesOnly)) once the datasource has started.

Since
100

Provided by category AGSLocationDataSource(ForSubclassEyesOnly).

◆ didStop

- (void) didStop

Subclasses must call this in doStop (AGSLocationDataSource(ForSubclassEyesOnly)) once the datasource has stopped.

Since
100

Provided by category AGSLocationDataSource(ForSubclassEyesOnly).

◆ didUpdateHeading:

- (void) didUpdateHeading: (double)  heading

Subclasses must call this once they have a new heading.

Since
100

Provided by category AGSLocationDataSource(ForSubclassEyesOnly).

◆ didUpdateLocation:

- (void) didUpdateLocation: (AGSLocation *)  location

Subclasses must call this once they have a new location.

Since
100

Provided by category AGSLocationDataSource(ForSubclassEyesOnly).

◆ doStart

- (void) doStart

Subclasses must implement this method to start the datasource. Once the datasource has started or failed to start it should call didStartOrFailWithError: (AGSLocationDataSource(ForSubclassEyesOnly)). As updates are received, the datasource should call didUpdateLocation: (AGSLocationDataSource(ForSubclassEyesOnly)) or didUpdateHeading: (AGSLocationDataSource(ForSubclassEyesOnly)).

Since
100

Provided by category AGSLocationDataSource(ForSubclassEyesOnly).

◆ doStop

- (void) doStop

Subclasses must implement this method to stop the datasource. Once the datasource has stopped it should call didStop (AGSLocationDataSource(ForSubclassEyesOnly))

Since
100

Provided by category AGSLocationDataSource(ForSubclassEyesOnly).

◆ init

- (instancetype) init

Creates an NMEA data source object.

Locations created from an NMEA data source object instantiated with this initializer will have an AGSSpatialReference of WGS84.

Since
100.10

◆ initWithEAAccessory:protocol:

- (nullable instancetype) initWithEAAccessory: (EAAccessory *)  accessory
protocol: (NSString *)  protocolString 

Creates an NMEA data source object with the provided EAAccessory and the protocolString and reads input data from the connected NMEA hardware.

Use this initializer when you have a bluetooth connected NMEA hardware connected to your iOS device. When the data source is started, incoming data is automatically read, so you don't have to call pushData:.

Note that you are still responsible for NMEA hardware device discoverabilty. Once connected via bluetooth, the connected accessories can be obtained by using the connectedAccessories property on the shared EAAccessoryManager.

Locations created from an NMEA data source object instantiated with this initializer will have an AGSSpatialReference of WGS84.

Parameters
accessoryThe EAAccessory object NMEA hardware device that the iOS device is connected via bluetooth.
protocolStringThe protocol string for the NMEA device connected. Protocol string names are formatted as reverse-DNS strings. For example, the string “com.apple.myProtocol” might represent a custom protocol defined by Apple. Manufacturers can define custom protocols for their accessories or work with other manufacturers and organizations to define standard protocols for different accessory types. The protocol strings of an accessory can be discovered using protocolStrings property on the EAAccessory object. You are required to provide this protocol string in Information Property List Key UISupportedExternalAccessoryProtocols. For more information, see here
Since
100.11

◆ initWithReceiverSpatialReference:

- (instancetype) initWithReceiverSpatialReference: (AGSSpatialReference *)  receiverSpatialReference

Creates an NMEA data source object.

Locations created from an NMEA data source object instantiated with this constructor will have an AGSSpatialReference defined by the receiverSpatialReference parameter. This initializer can be used when a receiver is outputting locations in an AGSSpatialReference object other than WGS84, such as when using a reference base station.

Parameters
receiverSpatialReferenceThe AGSSpatialReference object of incoming NMEA receiver data.
Since
100.10

◆ initWithReceiverSpatialReference:outputSpatialReference:

- (instancetype) initWithReceiverSpatialReference: (AGSSpatialReference *)  receiverSpatialReference
outputSpatialReference: (nullable AGSSpatialReference *)  outputSpatialReference 

Creates an NMEA data source object.

Locations created from an NMEA data source object instantiated with this initializer will be projected from the AGSSpatialReference defined by the receiverSpatialReference parameter to the AGSSpatialReference defined by the outputSpatialReference parameter. If the outputSpatialReference parameter is nil, the locations will not be projected and the locations will be in the receiverSpatialReference. This initializer can be used when a receiver is outputting locations in an AGSSpatialReference 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 AGSSpatialReference.

Parameters
receiverSpatialReferenceThe AGSSpatialReference object of incoming NMEA receiver data.
outputSpatialReferenceThe AGSSpatialReference object to project the AGSNMEALocation object to.
Since
100.10

◆ initWithReceiverSpatialReference:outputSpatialReference:outputDatumTransformation:

- (instancetype) initWithReceiverSpatialReference: (AGSSpatialReference *)  receiverSpatialReference
outputSpatialReference: (nullable AGSSpatialReference *)  outputSpatialReference
outputDatumTransformation: (nullable AGSDatumTransformation *)  outputDatumTransformation 

Creates an NMEA data source object.

Locations created from an NMEA data source object instantiated with this initializer will be projected from the AGSSpatialReference object defined by the receiverSpatialReference parameter to the AGSSpatialReference object defined by the outputSpatialReference parameter using the outputDatumTransformation. If the outputSpatialReference parameter is nil, the locations will not be projected and the locations will be in the receiverSpatialReference, if the outputDatumTransformation parameter is set it will be ignored. This initializer can be used when a receiver is outputting locations in an AGSSpatialReference 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 AGSSpatialReference using an AGSDatumTransformation.

Parameters
receiverSpatialReferenceThe AGSSpatialReference object of incoming NMEA receiver data.
outputSpatialReferenceThe AGSSpatialReference object to project the AGSNMEALocation object to.
outputDatumTransformationThe AGSDatumTransformation object to use to project the AGSNMEALocation object.
Since
100.10

◆ NMEALocationDataSource

+ (instancetype) NMEALocationDataSource

Creates an NMEA data source object.

Locations created from an NMEA data source object instantiated with this constructor will have an AGSSpatialReference of WGS84.

Returns
A new NMEA data source object.
Since
100.10

◆ NMEALocationDataSourceWithEAAccessory:protocol:

+ (nullable instancetype) NMEALocationDataSourceWithEAAccessory: (EAAccessory *)  accessory
protocol: (NSString *)  protocolString 

Creates an NMEA data source object with the provided EAAccessory object and the protocolString parameter and reads input data from the connected NMEA hardware.

Use this initializer when you have a bluetooth connected NMEA hardware connected to your iOS device. When the data source is started, incoming data is automatically read, so you don't have to call pushData:.

Note that you are still responsible for NMEA hardware device discoverabilty. Once connected via bluetooth, the connected accessories can be obtained by using the connectedAccessories property on the shared EAAccessoryManager object.

Locations created from an NMEA data source object instantiated with this initializer will have an AGSSpatialReference of WGS84.

Parameters
accessoryThe EAAccessory object NMEA hardware device that the iOS device is connected via bluetooth.
protocolStringThe protocol string for the NMEA device connected. Protocol string names are formatted as reverse-DNS strings. For example, the string “com.apple.myProtocol” might represent a custom protocol defined by Apple. Manufacturers can define custom protocols for their accessories or work with other manufacturers and organizations to define standard protocols for different accessory types. The protocol strings of an accessory can be discovered using protocolStrings property on the EAAccessory object. You are required to provide this protocol string in Information Property List Key UISupportedExternalAccessoryProtocols. For more information, see here
Since
100.11

◆ NMEALocationDataSourceWithReceiverSpatialReference:

+ (instancetype) NMEALocationDataSourceWithReceiverSpatialReference: (AGSSpatialReference *)  receiverSpatialReference

Creates an NMEA data source object.

Locations created from an NMEA data source object instantiated with this constructor will have an AGSSpatialReference defined by the receiverSpatialReference parameter. This initializer can be used when a receiver is outputting locations in an AGSSpatialReference other than WGS84, such as when using a reference base station.

Parameters
receiverSpatialReferenceThe AGSSpatialReference object of incoming NMEA receiver data.
Returns
A new NMEA data source object.
Since
100.10

◆ NMEALocationDataSourceWithReceiverSpatialReference:outputSpatialReference:

+ (instancetype) NMEALocationDataSourceWithReceiverSpatialReference: (AGSSpatialReference *)  receiverSpatialReference
outputSpatialReference: (nullable AGSSpatialReference *)  outputSpatialReference 

Creates an NMEA data source object.

Locations created from an NMEA data source object instantiated with this initializer will be projected from the AGSSpatialReference defined by the receiverSpatialReference parameter to the AGSSpatialReference defined by the outputSpatialReference parameter. If the outputSpatialReference parameter is nil, the locations will not be projected and the locations will be in the receiverSpatialReference. This initializer can be used when a receiver is outputting locations in an AGSSpatialReference object 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 AGSSpatialReference object.

Parameters
receiverSpatialReferenceThe AGSSpatialReference object of incoming NMEA receiver data.
outputSpatialReferenceThe AGSSpatialReference object to project the AGSNMEALocation object to.
Returns
A new NMEA data source object.
Since
100.10

◆ NMEALocationDataSourceWithReceiverSpatialReference:outputSpatialReference:outputDatumTransformation:

+ (instancetype) NMEALocationDataSourceWithReceiverSpatialReference: (AGSSpatialReference *)  receiverSpatialReference
outputSpatialReference: (nullable AGSSpatialReference *)  outputSpatialReference
outputDatumTransformation: (nullable AGSDatumTransformation *)  outputDatumTransformation 

Creates an NMEA data source object.

Locations created from an NMEA data source object instantiated with this initializer will be projected from the AGSSpatialReference object defined by the receiverSpatialReference parameter to the AGSSpatialReference defined by the outputSpatialReference parameter using the outputDatumTransformation. If the outputSpatialReference parameter is nil, the locations will not be projected and the locations will be in the receiverSpatialReference, if the outputDatumTransformation parameter is set it will be ignored. This initializer can be used when a receiver is outputting locations in an AGSSpatialReference object 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 AGSSpatialReference using an AGSDatumTransformation.

Parameters
receiverSpatialReferenceThe AGSSpatialReference object of incoming NMEA receiver data.
outputSpatialReferenceThe AGSSpatialReference object to project the AGSNMEALocation object to.
outputDatumTransformationThe AGSDatumTransformation object to use to project the AGSNMEALocation object.
Since
100.10

◆ pushData:

- (void) pushData: (NSData *)  data

Reads the input NMEA data creating an AGSNMEALocation object. 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: $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
    dataThe data buffer that contains NMEA data.
    Since
    100.10

◆ startWithCompletion:

- (void) startWithCompletion: (nullable void(^)(NSError *__nullable error))  completion

This is invoked by the location display on the datasource to initiate requesting location updates. Internally this method calls doStart (AGSLocationDataSource(ForSubclassEyesOnly)) which subclasses must implement.

Parameters
completionblock which will be invoked when the operation completes. If the dataSource failed to start, the error property will be populated.
Since
100

◆ stop

- (void) stop

This is invoked by the location display on the datasource to stop requesting location updates. Internally this method calls doStop (AGSLocationDataSource(ForSubclassEyesOnly)) which subclasses must implement.

Since
100
Deprecated:
100.14. Replaced by stopWithCompletion:.

Provided by category AGSLocationDataSource(AGSDeprecated).

◆ stopWithCompletion:

- (void) stopWithCompletion: (nullable void(^)(void))  completion

This is invoked by the location display on the datasource to stop requesting location updates. Internally this method calls doStop (AGSLocationDataSource(ForSubclassEyesOnly)) which subclasses must implement.

Since
100.14

Property Documentation

◆ error

- (NSError*) error
readnonatomicstronginherited

The error that prevented the datasource from starting or was encountered while retrieving a location udpate

Since
100

◆ locationChangeHandlerDelegate

- (id<AGSNMEALocationDataSourceDelegate>) locationChangeHandlerDelegate
readwritenonatomicweak

The delegate which will receive satellite info updates from the data source.

Since
100.10

◆ outputDatumTransformation

- (AGSDatumTransformation*) outputDatumTransformation
readnonatomicstrong

The AGSDatumTransformation object to be used in the project operation.

Since
100.10

◆ outputSpatialReference

- (AGSSpatialReference*) outputSpatialReference
readnonatomicstrong

The spatial reference to which the AGSNMEALocation object is projected.

If this property is nil, the AGSNMEALocation::position proprety will contain the original incoming x, y, z values from the NMEA data sentence and the AGSNMEALocationDataSource::receiverSpatialReference property.

Since
100.10

◆ receiverSpatialReference

- (AGSSpatialReference*) receiverSpatialReference
readnonatomicstrong

The AGSSpatialReference object applied when an NMEALocation object is created.

By default this will be WGS84 for its horizontal (WKID=4326) and vertical reference systems (WKID=115700), though a different value can be passed during initialization if a receiver returns locations in a different reference system.

Since
100.10

◆ started

- (BOOL) started
readnonatomicassigninherited

YES if the data source has been started, NO otherwise.

Since
100.0
Deprecated:
100.14. Replaced by AGSLocationDataSource::status.

Provided by category AGSLocationDataSource(AGSDeprecated).

◆ status

- (AGSLocationDataSourceStatus) status
readnonatomicassigninherited

The status of the data source.

Since
100.14