Receive Data from SDK

NNAltitudeContext contains the calculated altitude data and other related error or status codes. 

public struct NNAltitudeContext {
public let height: Double? // Height above Ellipsoid (HAE) in Meters WGS-84 Datum
public let heightUncertainty: Double? // Height Uncertainty in Meters 90% confidence
public let heightUncertainty68: Double? // Height Uncertainty in Meters 68% confidence
public let heightAboveTerrain: Double? //Height Above Terrain in Meters
public let heightAboveTerrainUncertainty: Double? //Height Above Terrain Uncertainty in Meters 90% confidence
public let heightHatUncertainty68: Double? // Height Above Terrain Uncertainty in Meters 68% confidence
public let floorNumber: Int? //Floor Number if in Known Building
public let floorConfidence: Double? //Floor Confidence
public let address: String? //Address of Current Location
public let addressConfidence: Double? //Address Confidence
public let statusCode: Int? //Altitude Service Status Code
public let errorCode: Int? //Altitude Service Error Code
public let epochTimestamp: Int //epoch timestamp of altitude data
public let manualBaroCal: Bool? //User assisted calibration required
public let userPressure: Double? //Pressure in Pa
}

Note: floorNumber, floorConfidence, address and addressConfidence are not supported currently. 

• Learn more about the Height Above Ellipsoid (HAE) here: https://nextnav.com/hae/ 
• Learn more about the Height Above Terrain (HAT) here: https://nextnav.com/hat/ 

The SDK utilizes the NNAltitudeContext object to report the HAE and HAT uncertainty (sometimes referred to as “accuracy”) values at both the 90% and 68% confidence levels. The uncertainty value indicates that the altitude value generated by the SDK could lie in a range of (altitude-value – altitude uncertainty) and (altitude-value + altitude uncertainty) at a given confidence level. 

For example, if the SDK generates a HAT value of 2m and HAT-Uncertainty value of 3m at 90% confidence. Then there is 90% confidence that the reported HAT value lies between –1m and 5m. 

The uncertainty value is not intended to be an estimate of error relative to the actual vertical location of the mobile device, but instead is provided primarily to convey a quality metric for the altitude estimate. The larger the uncertainty the poorer the quality of the altitude estimate. The SDK reports this quality metric at both 90% and 68% confidence levels. 

These two different levels are reported to enable the developer to choose the uncertainty confidence level best suited for the application. Most applications should use the 68% confidence level to be consistent with the 68% confidence level reported for 2D location uncertainty (68% is the 2D location uncertainty confidence level is typically reported in most commercial devices). 

If the manualBaroCal indicator is returned by the SDK as true, then it is an indicator that the barometer sensor on the device needs to be calibrated. There are 2 options for the host-app to achieve this: 

1. Allow the SDK to run in an initialized state for an additional period of time (even if altitude data is not needed by the Host-App) to allow it to perform background calibration. 

2. Use the manual-calibration (or user-assisted calibration) function as discussed section 5.1 below. 

The Host-App must run the SDK in altitude calculation mode from time-to-time (once every 3 – 4 days) to check the calibration state of the device’ baro-sensor. The “ONE-time mode is sufficient for this calibration check. 

The statusCode field in the NNAltitudeContext object is used to provide the host-app an update on state of assistance data fetch operation performed by the SDK when it is in altitude calculation mode.

SdkStatusNotification supports the following error codes: 

The errorCode field in the NNAltitudeContext object is used to provide the host-app an update on the state of altitude computation in the SDK at the time for altitude generation. 

The following is an example of how to retrieve the calculation results of altitude data from SDK: 

NNSDK.startAltitudeCalculation(mode: NNAltitudeMode.oneTime)) {
[weak self] (code, context) in
if let weakSelf = self {
weakSelf._zasStatusCode = nil
weakSelf._errorCode = nil
if let context = context {
if let height = context.height, let heightUncertainty = context.heightUncertainty {
weakSelf._hae = height
weakSelf._haeu = heightUncertainty
} else {
weakSelf._hae = nil
weakSelf._haeu = nil
}
if let heightAboveTerrain = context.heightAboveTerrain, let heightAboveTerrainUncertainty = context.heightAboveTerrainUncertainty {
weakSelf._hat = heightAboveTerrain
weakSelf._hatu = heightAboveTerrainUncertainty
} else {
weakSelf._hat = nil
weakSelf._hatu = nil
}
if let manualBarocalCalibration = context.manualBaroCal {
//Manual Calibration is requried
}
if let code = context.statusCode {
weakSelf._zasStatusCode = code
}
else if let code = context.errorCode {
weakSelf._errorCode = code}
} else if let code = code {
weakSelf._errorCode = code
}
}
}

Improve the quality and quantity of collected data 

Specific uses cases that require higher quality data from the device in order to calculate the vertical position or altitude can make use of the the setSDKConsistencyFilters method. This method can be used to enable/disable the filters which detect the quality of 2D location and pressure data from the device that goes into the SDK for altitude generation. When this filter is enabled, the SDK provides additional status codes to the app as shown below. Apps, based on its specific use-case could use this information for aspects like user messaging, introducing additional meta-data to qualify the vertical location, etc. 

public static func setSDKConsistencyFilters(_ filters: [NNConsistenyFilter])

Note: currently two filters are supported: LOCATION and PRESSURE 

The warningCode field in the AltitudeContextNotification is used to return the warning code when related filter is enabled. 

The following is an example of how to set up filters for altitude calculation. 

…
private var frequency: NNAltitudeMode!
…
self.filters.append(NNConsistenyFilter.location)
self.filters.append(NNConsistenyFilter.pressure)
…
//After SDK is initialized
NNSDK.setSDKConsistencyFilters(self.filters)
…
NNSDK.startAltitudeCalculation(mode: NNAltitudeMode.oneTime)) {
[weak self] (code, context) in
if let weakSelf = self {
weakSelf._zasStatusCode = nil
weakSelf._errorCode = nil
if let context = context {
if context.warningCode != nil {
print("warning code: \(String(context. warningCode!))")
}
}
}
}