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
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: |
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
-
accessory The EAAccessoryobject NMEA hardware device that the iOS device is connected via bluetooth.protocolString The 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 protocolStringsproperty on theEAAccessoryobject. You are required to provide this protocol string in Information Property List KeyUISupportedExternalAccessoryProtocols. 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
-
receiverSpatialReference The AGSSpatialReferenceobject 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
-
receiverSpatialReference The AGSSpatialReferenceobject of incoming NMEA receiver data.outputSpatialReference The AGSSpatialReferenceobject to project theAGSNMEALocationobject 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
-
receiverSpatialReference The AGSSpatialReferenceobject of incoming NMEA receiver data.outputSpatialReference The AGSSpatialReferenceobject to project theAGSNMEALocationobject to.outputDatumTransformation The AGSDatumTransformationobject to use to project theAGSNMEALocationobject.
- 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
-
accessory The EAAccessoryobject NMEA hardware device that the iOS device is connected via bluetooth.protocolString The 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 protocolStringsproperty on theEAAccessoryobject. You are required to provide this protocol string in Information Property List KeyUISupportedExternalAccessoryProtocols. 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
-
receiverSpatialReference The AGSSpatialReferenceobject 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
-
receiverSpatialReference The AGSSpatialReferenceobject of incoming NMEA receiver data.outputSpatialReference The AGSSpatialReferenceobject to project theAGSNMEALocationobject 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
-
receiverSpatialReference The AGSSpatialReferenceobject of incoming NMEA receiver data.outputSpatialReference The AGSSpatialReferenceobject to project theAGSNMEALocationobject to.outputDatumTransformation The AGSDatumTransformationobject to use to project theAGSNMEALocationobject.
- 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
-
data The 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
-
completion block 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
|
readnonatomicstronginherited |
The error that prevented the datasource from starting or was encountered while retrieving a location udpate
- Since
- 100
◆ locationChangeHandlerDelegate
|
readwritenonatomicweak |
The delegate which will receive satellite info updates from the data source.
- Since
- 100.10
◆ outputDatumTransformation
|
readnonatomicstrong |
The AGSDatumTransformation object to be used in the project operation.
- Since
- 100.10
◆ 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
|
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
|
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
|
readnonatomicassigninherited |
The status of the data source.
- Since
- 100.14
