Notifications

Overview

Alerts will be searched in locally cached data received per the SkyPath.dataQuery configuration. No server request will be made here.

Observed turbulence reports will be used that were fetched within specified route corridor (polygon) and/or viewport in SkyPath.dataQuery. If reports are not available in some area the alerts will be searched in fetched turbulence polygons if it is available.

Tech Algo

Here is the high-level explanation of the algorithm that is used to search turbulence to notify.

H3 Indexes

Generate an array of H3 indexes in corresponding altitudes to search turbulence to notify in.

Turbulence Reports

Get observed turbulence reports in corresponding H3 indexes and altitudes. Each report has an H3 index and altitude block (in 1,000 ft).

Filter Turbulence

Filter found reports by specified criteria:

• history time (ts)
• min severity (sev)

Notify Nearest

Take and notify on the nearest report based on the distance to and altitude difference from the current altitude. Other reports could be grouped into clusters and visualized.

Alert logic

• Distance ahead - 100NM
• Vertical span - 4 altitude blocks (4,000 ft total), example at FL380 would be FL360..<FL400
• Route mode - If there’s a route in place then:
  • 40 NM total width around the route
  • Similar vertical span corridor on the entire route including climb and descent
• Beam mode - If not, go into beam mode
  • 15 degrees horizontal span
  • Similar vertical span

Query

By default, SDK will use a predefined configuration for searching turbulence alerts, see AlertQuery for more details. So it will be a good start to use the default values of AlertQuery().

There are 2 ways to get turbulence alerts:

Manually

Manually when needed. For example, on every location update, or by time intervals or distance passed. This will have all currently found turbulence alerts despite whether they were found in the previous query.

let query = AlertQuery(altRange: altRange, route: route?.coordinates)
let result = SkyPath.shared.alerts(with: query)

It blocks the current thread, so using a separate background thread is recommended.

Automatic

Automatic monitoring. SDK will check for turbulence on every new location update. When found, an alert will be reported via SkyPathDelegate.didReceiveAlert(alert:). This will not report the same turbulence alert multiple times in a row, but it could report the same alert that was reported previously if there were other alerts in between. So it will report only once in cases A1 A1 A1 A1 but will report 3 times in cases A1, A2, and A1.

let query = AlertQuery(altRange: altRange, route: route?.coordinates)
SkyPath.shared.startMonitoringAlerts(with: query)

When the AlertQuery changes you can call only startMonitoringAlerts(with:) with a new query without stopping it first.

Based on the AlertQuery properties, SDK filters server reports. All AlertQuery properties have default values. Configure it per your needs.

There are two modes: route and beam.

• Route mode is used when route line coordinates or a polygon are set in the query. It can use polygon or route line coordinates and width around to make a corridor.

• Beam mode is used when no route is provided. It is configured by angle span, and distance from the current location.

When you get a turbulence alert you can show it in the app with the local iOS notification if the app is in the background. Let SDK know that notification has been presented by:

SkyPath.shared.alertedTurbulenceSeverity(sev)

It is safe to call startMonitoringAlerts and stopMonitoringAlerts multiple times. However, it works as enable disable, so there is no need to call it again after starting monitoring until it stops monitoring and needs to start again. You can also check SkyPath.shared.isMonitoringAlerts if you need to call startMonitoringAlerts or stopMonitoringAlerts.

Background

Background mode is required to keep using location and searching for notifications while the app is running in the background.

Schedule iOS local notification with corresponding information when got a turbuelnce notification while the app is running in the background. SDK provides a helper SPLocalNotificationManager

SPLocalNotificationManager.shared.scheduleNotification(
    title: "Moderate Turbulence Detected", 
    body: "In 10 mins")

Test

To test the notification you need to simulate a flight towards some turbulence area that meets AlertQuery criteria (see the SDK API docs for more details), so the turbulence reports will be in the query corridor altitude, proper severity, etc. The following will describe the simple steps for testing using the default AlertQuery parameters.

1. Find on the map some turbulence hexagons with a Moderate severity level at an altitude of, for example, ~38,000 ft.

2. Simulate a flight to fly at ~38,000 ft (same hexagon turbulence report altitude, so report will be within searching altitude corridor) towards that Moderate turbulence hexagon on a distance of more than 100 NM, for example, 150-200 NM.

3. By default, turbulence alerts are searched in a beam mode within 100 NM ahead, so when you fly at a distance closer than 100 NM the hexagon turbulence will be in range. Make sure that based on the current speed, it will require at least a few minutes to cover this distance.

4. The turbulence notification should arrive.

5. Move the app to the background and test showing a local notification.

These quick steps are valid if the default query parameters are used. Please take into account any customizations you made in AlertQuery for testing. For example, if the severity to alert is set to Moderate-Severity and above, you'll need to find a corresponding Moderate-Severity hexagon and so on.