Getting Started

Import Pinnacle SDK Framework

Copy the NextNav.xcframework file to the directory of your project.

Add NextNav.xcframework in your Targets > Framework, Library & Embedded Content with Embed Option as “Embed & Sign”.

Add Application Permissions

Add the Location and Motion Activity permissions to your Info.plist

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your current location will be used to calculate height</string>
<key>NSMotionUsageDescription</key>
<string>Your motion Activity will be used to calculate height</string>

Initialize the SDK

SDK initialization must be done using the SDK KEY and the Pinnacle Service URL information. The SDK KEY can be obtained from NextNav Developer Portal for the developer account.

public static func start( baseURL:String,
  secretKey: String, //This is the SDK KEY obtained from NextNav   location: CLLocation? = nil,
  success: NNSDKHandler?,
  failure: NNSDKHandler?
)

Parameters

The parameter “baseURL” is the Pinnacle service environment URL, therefore developers should use “api.nextnav.io” during the evaluation phase. When the application is ready to be commerically launched, the commercial services agreement for this application will provide the commercial “baseURL” and “secretKey” (SDK KEY). Please email to [email protected] for any additional questions on these two parameters. ©2022 NextNav. All rights reserved. 7 

The parameter “location” is optional and may be used by the host-app/developer to inject a 2D location and associated it’s uncertainty. Value in the “location” field value will signal to the SDK to use this 2D location for altitude generation and to NOT directly fetch 2D location from the device. 

If this “location” field is null, the SDK will directly pick the 2D-Location data from the device. 

Once non-null data is fed into the “location” field, host-app/developer must ensure that the injected location value is updated as needed. An update can be made via the setAltitude function for the SDK which provides the latest/correct location data. Please note, the location data may otherwise become stale with out the update, as the SDK will not collect fresh location data directly from the device. 

The data in the “location” field must follow the iOS “CLLocation” data format. Here is an example: 

var sanFrancisco:CLLocation? = CLLocation(

       coordinate:CLLocationCoordinate2D(
                latitude: 37.36882,
                longitude: -121.98921
       ),
       altitude: 0,
       horizontalAccuracy: 10,

       verticalAccuracy: 0,
       timestamp: Date()
)

The parameter “horizontalAccuracy” is the accuracy (or sometimes referred to as Uncertainty) of the 2D position/location provided to the SDK for Altitude calculation. The unit is in meters. A value of 0 indicates that the 2D location is very accurate. Typically, the accuracy value can range from a few meters to a few hundred meters. Any location accuracy larger than 1000m is not very useful and host App should refrain from injecting such large values for altitude determination. 

Start the Calculation of Altitude

To start the altitude calculation, you need to configure the frequency to receive the results from the Pinnacle Service. There are four different frequencies supported:

Supported FrequencyDescription
oneTimePinnacle SDK outputs altitude data just once.
oneSecondPinnacle SDK outputs altitude data once every second until stopAltitudeCalculation is called.
thirtySecondsPinnacle SDK outputs altitude data once every 30 seconds until stopAltitudeCalculation is called.
oneMinutePinnacle SDK outputs altitude data once every minute until stopAltitudeCalculation is called.

Use the following method to Start altitude calculation: 

public static func startAltitudeCalculation(

         mode: NNAltitudeMode,
         handler: @escaping NNAltitudeHandler

)

The value of NNAltitudeMode must be one of the 4 values listed in the table above. 

The object of NNAltitudeHandler includes the status code and calculated altitude results which are listed in the next section. 

public typealias NNAltitudeHandler = (
         _ code: Int?,_
         
context: NNAltitudeContext?

) -> Void

Use the following method to Stop the altitude calculation: 

public static func stopAltitudeCalculation(

         handler: @escaping NNAltitudeHandler

)

NOTE: If the SDK is used in “ONE_TIME” mode to get altitude data, make sure to call stopAltitudeCalculation() after the calculation is finished. Then initialize the SDK instance before processing the next calculation. 

2D Location Injection

Pinnacle SDK also supports 2D Location Injection at any time when the SDK is started and running. This mode can be used if the automated 2D location fetch for altitude calculation by the SDK is not desired. 

The 2D location injection can be done as follows: 

public static func setAltitude(
  location: CLLocation? = nil, //Optional Field see note below
  pressure:Double? = nil //Optional Field and Pressure needs to be in pascals – NOT currently supported – future feature.

)

NOTE: Once a 2D location is injected via the setAltitude function’s “location” field, the SDK will no longer automatically fetch 2D location from the device for altitude calculation. The host-app/developer must ensure that the injected location value is updated as needed via the setAltitude function for the SDK to use the latest/correct location data otherwise the location data maybe come stale relative to where the altitude is being computed by the SDK.