Turn-by-turn navigation

Turn-by-turn navigation is navigation along a provided route. It provides information about the next maneuvers and the progress along the current route. First, add the navigation module to your project and set up an instance of the TomTomNavigation interface. Read how to do this in the Quickstart guide .

Starting navigation

Once the TomTomNavigation instance is initialized, you can start navigation. Turn-by-turn navigation requires a RoutePlan for navigation to follow. RoutePlan consists of a Route and a RoutePlanningOptions object. More details on how to plan a Route can be found in the Planning a route guide .

1
routePlan = RoutePlan(route: route, routePlanningOptions: options)

Now the prepared RoutePlan can be used to start navigation. To do this, call the TomTomNavigation.start(navigationOptions:) method and pass a route plan via the NavigationOptions struct.

1
do {
2
    let navigationOptions = NavigationOptions(activeRoutePlan: routePlan)
3
    try navigation.start(navigationOptions: navigationOptions)
4
} catch {
5
    print("An error occurred: \(error)")
6
}

TomTomNavigation also supports manually stopping navigation. The TomTomNavigation.stop() method stops the current navigation session and clears all data related to it.

1
navigation.stop()

Updating the route

Once TomTomNavigation is started, you can change the RoutePlan that is being followed at any time, either manually (as shown below) or automatically (as described in the Continuous replanning and route deviation guide ) by the navigation session.

1
do {
2
    try navigation.setActiveRoutePlan(routePlan)
3
} catch {
4
    print("An error occurred: \(error)")
5
}

Route change notifications are received by adding the following observers to the navigation session:

1
navigation.addRouteAddObserver(self)
2
navigation.addRouteRemoveObserver(self)
3
navigation.addRouteUpdateObserver(self)
4
navigation.addActiveRouteChangeObserver(self)

To remove previously added observers, call the appropriate methods on the TomTomNavigation .

1
navigation.removeRouteAddObserver(self)
2
navigation.removeRouteRemoveObserver(self)
3
navigation.removeRouteUpdateObserver(self)
4
navigation.removeActiveRouteChangeObserver(self)

• The NavigationRouteUpdateObserver - provides information about route updates that do not change the route geometry. See RouteUpdatedReason for more information.
• The NavigationRouteAddObserver - provides information about the new route being added to the navigation session.
• The NavigationRouteRemoveObserver - provides information about the route being removed from the navigation session.
• The NavigationActiveRouteChangeObserver - provides information about the new active route. Note, the route must have been previously added to the session.

1
do {
2
    try navigation.setActiveRoutePlan(routePlan)
3
} catch {
4
    print("An error occurred: \(error)")
5
}

Route progress

The position-dependent data fields are contained in the RouteProgress . Some examples are position on route (offset from the beginning) and remaining travel time. These fields are updated on every position update roughly once per second. You can listen for changes to route progress. A progress notification is sent via NavigationProgressObserver.didUpdateProgress(progress:) . It provides the current RouteProgress , which contains, among other things, the arrival time and the remaining distance along the route.

1
func didUpdateProgress(progress: RouteProgress) {
2
    let remainingTime: Measurement<UnitDuration> = progress.remainingTime
3
    let distanceAlongRoute: Measurement<UnitLength> = progress.distanceAlongRoute
4
}

Route deviations

During the navigation, TomTomNavigation tracks your position for all navigated routes and provides information on which ones are followed. To listen for such updates, use the NavigationRouteTrackingStateUpdateObserver .

The RouteTrackingState object is provided by the NavigationRouteTrackingStateUpdateObserver and contains a list of the followed and unfollowed routes. Additionally, it informs when the driver has deviated from all followed routes by setting the RouteTrackingState.hasDeviated property to true.

To listen to the route tracking updates, add a NavigationRouteTrackingStateUpdateObserver to the TomTomNavigation object.

1
navigation.addRouteTrackingStateUpdateObserver(self)

To stop observing route tracking updates remove the NavigationRouteTrackingStateUpdateObserver from the TomTomNavigation object.

1
navigation.removeRouteTrackingStateUpdateObserver(self)

If the driver does deviate from the route, navigation enters free driving mode . This means that navigation runs without a RoutePlan . Navigation automatically replans using the same cost model as used in the original RoutePlan .

You can find more details about automatic replanning in the Replanning on deviation section .

Route guidance

While navigating, TomTomNavigation generates a guidance update after each location change. Generated guidance consists of the next instructions, the distance to a maneuver, and an announcement if the distance is in a suitable range. The generated guidance notifications are sent via three methods:

• GuidanceUpdateObserver.func didChangeInstructions(instructions: [GuidanceInstruction]) - Reports a change to guidance instructions. GuidanceInstruction contains information describing a maneuver: type, message, travel time, etc.
• GuidanceUpdateObserver.didGenerateAnnouncement(announcement:shouldPlay:) - Triggered when an announcement is generated. The GuidanceAnnouncement is an object containing information about message, verbal message, location and distance to the instruction point.
• GuidanceUpdateObserver.didChangeDistanceToNextInstruction( distance: Measurement<UnitLength>, instructions: [GuidanceInstruction], currentPhase: InstructionPhase ) - Called with each change of distance to the instruction. The first parameter is the distance to the instruction. The second one provides the next instructions.

1
func didChangeInstructions(instructions: [GuidanceInstruction]) {
2
    /* YOUR CODE GOES HERE */
3
}
4

5
func didChangeDistanceToNextInstruction(
6
    distance: Measurement<UnitLength>,
7
    instructions: [GuidanceInstruction],
8
    currentPhase: InstructionPhase
9
) {
10
    /* YOUR CODE GOES HERE */
11
}
12

13
func didGenerateAnnouncement(announcement: GuidanceAnnouncement, shouldPlay: Bool) {
14
    /* YOUR CODE GOES HERE */
15
}

Lane level guidance

The TomTomNavigation has built-in support to generate lane guidance. Lane guidance is generated for each LaneSection object in a Route . More details on how to request a route with a LaneSection are described in the Route sections guide .

The LaneGuidance object consists of:

• LaneGuidance.lanes - An object that consists of a list with directions and an optional lane direction the driver should follow.
• LaneGuidance.laneSeparators - A list of lane separators.
• LaneGuidance.routeOffset - The distance from the start of the route to the start of the lanes.
• LaneGuidance.length - Length of the lane section.

The generated lane level guidance notifications are sent via 2 methods:

• LaneGuidanceUpdateObserver.didStartLaneGuidance(laneGuidance:) - Triggered when lane guidance appears.
• LaneGuidanceUpdateObserver.didEndLaneGuidance(laneGuidance:) - Triggered when lane guidance disappears.

1
func didStartLaneGuidance(laneGuidance: LaneGuidance) {
2
    /* YOUR CODE GOES HERE */
3
}
4

5
func didEndLaneGuidance(laneGuidance: LaneGuidance) {
6
    /* YOUR CODE GOES HERE */
7
}

Arrival experience

The TomTomNavigation detects that the user has arrived at the destination. Whenever an arrival is detected, the notification is sent via NavigationDestinationArrivalObserver.didArriveAtDestination(route:) . At that point the navigation might be stopped or the event might be handled in other way like, for example, only displaying some notification for the user but keep navigating.

1
func didArriveAtDestination(route: Route) {
2
    /* YOUR CODE GOES HERE */
3
}

Waypoint arrival

The Route that is being followed can contain route stops the driver wants to visit before arriving at the destination. These stops, called waypoints, are included in the Route.routeStops as instances of the type RouteStop . You can find more details on waypoints in the Waypoints and custom routes guide .

The Navigation module uses the generated RouteProgress to detect that the user has arrived at a waypoint. Once waypoint arrival is detected it triggers NavigationWaypointArrivalObserver . This means that the ArrivalDetectionEngine has successfully detected an arrival at the waypoint.

Next steps

Since you have learned how to work with turn-by-turn navigation, here are recommendations for the next steps:

• Planning a route
• Voice instructions (Text-To-Speech)
• Turn-by-turn instructions