Developer

Turn-by-turn navigation

VERSION 0.63.0
PUBLIC PREVIEW

The Navigation SDK for iOS is only available upon request. Contact us to get started.

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.

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.

1do {
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.

navigation.stop()

If navigation has not been started, the stop method will have no effect.

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.

1do {
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:

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

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

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

A manual RoutePlan update results in a RouteAddedReason.manuallyUpdated reason provided in the NavigationRouteAddObserver.

Other reasons can occur as described in the Continuous replanning and route deviation guide.

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.

1func 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.

navigation.addRouteTrackingStateUpdateObserver(self)

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

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.

You can disable automatic replanning on deviation and provide a new RoutePlan manually using the TomTomNavigation.setActiveRoutePlan(_:) method.

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:

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

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

13func 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:

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

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

5func 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.

1func 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: