Turn-by-turn navigation

VERSION 0.3.1056
PUBLIC PREVIEW

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

Turn-by-turn navigation is navigation along a calculated route. It provides information about the next maneuvers and the progress along the current route. To begin, add the navigation module to your project and set up a TomTomNavigation object. You can learn how to do this in the Quickstart guide.

Starting navigation

Once the TomTomNavigation object is initialized, you can start navigation. Turn-by-turn navigation requires NavigationOptions for navigation to follow. NavigationOptions encapsulate an active RoutePlan.

A RoutePlan consists of a Route and the RoutePlanningOptions objects used for planning it. You can learn more about how to plan a Route in the Planning a route guide.

val routePlan = RoutePlan(route = route, routePlanningOptions = routePlanningOptions)

Now you can use the prepared RoutePlan to create NavigationOptions and start navigation. To do this, call the start(NavigationOptions) method on your TomTomNavigation object.

tomTomNavigation.start(NavigationOptions(routePlan))

center

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

tomTomNavigation.stop()

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

Updating the route

Once TomTomNavigation is started, you can change the RoutePlan you’re following at any time.

tomTomNavigation.update(routePlan)

Navigation RoutePlan updates are observed using the OnRouteUpdatedListener callback.

If it is registered on the TomTomNavigation object, it reports when there is a successful RoutePlan update.

The provided Route parameter is then the new Route that navigation follows. The RouteUpdateReason parameter indicates why the route was updated.

A manual RoutePlan update results in an updated reason of RouteUpdateReason.Manual.

Other reasons can occur after route replanning.

1val onRouteUpdatedListener =
2 OnRouteUpdatedListener { route: Route, updateReason: RouteUpdateReason ->
3 when (updateReason) {
4 RouteUpdateReason.Manual -> { /* YOUR CODE GOES HERE */ }
5 RouteUpdateReason.Refresh -> { /* YOUR CODE GOES HERE */ }
6 RouteUpdateReason.Unreachable -> { /* YOUR CODE GOES HERE */ }
7 RouteUpdateReason.BetterFound -> { /* YOUR CODE GOES HERE */ }
8 RouteUpdateReason.Deviation -> { /* YOUR CODE GOES HERE */ }
9 RouteUpdateReason.Increment -> { /* YOUR CODE GOES HERE */ }
10 }
11 }
12tomTomNavigation.addOnRouteUpdatedListener(onRouteUpdatedListener)

To remove a previously-added listener, call TomTomNavigation.removeOnRouteUpdatedListener(onRouteUpdatedListener).

tomTomNavigation.removeOnRouteUpdatedListener(onRouteUpdatedListener)

Route progress

The position-dependent data fields are collectively known as the "Route Progress" data. Examples of these data are position on route (offset from the beginning) and remaining travel time. These fields are updated on every position update roughly once per second for every followed route in the system. You can listen for changes to route progress. To listen for changes, set OnProgressUpdateListener to the TomTomNavigation object. OnProgressUpdateListener is triggered whenever the user’s progress along the Route is changed. It provides the current RouteProgress, which contains, among other things, the arrival time and the remaining distance along the route.

1val onProgressUpdateListener = OnProgressUpdateListener { progress: RouteProgress ->
2 /* YOUR CODE GOES HERE */
3}
4tomTomNavigation.addOnProgressUpdateListener(onProgressUpdateListener)

To remove a previously-added listener, call TomTomNavigation.removeOnProgressUpdateListener(OnProgressUpdateListener).

tomTomNavigation.removeOnProgressUpdateListener(onProgressUpdateListener)

Route deviations

The Navigation module detects when the user has diverged from the navigated route. Whenever a deviation is detected, the OnRouteDeviationListener is invoked with a location and a route. The GeoLocation provided by the callback is the localization of that route deviation. The Route parameter is the Route from which the user deviated. You can listen for route deviations. To listen to route deviations, set OnRouteDeviationListener to the TomTomNavigation object.

1val onRouteDeviationListener =
2 OnRouteDeviationListener { location: GeoLocation, route: Route ->
3 /* YOUR CODE GOES HERE */
4 }
5tomTomNavigation.addOnRouteDeviationListener(onRouteDeviationListener)

To remove OnRouteDeviationListener use the TomTomNavigation.removeOnRouteDeviationListener(OnRouteDeviationListener) method.

tomTomNavigation.removeOnRouteDeviationListener(onRouteDeviationListener)

If the driver does deviate from the route, navigation enters free driving mode. This means that navigation runs without a RoutePlan. The RoutePlan 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 and provide a new RoutePlan manually using the update method.

Route guidance

The combination of maneuver instructions and maneuver announcements is called Route Guidance.

During navigation, 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 within a suitable range. The generated guidance is then sent to OnGuidanceUpdateListener.

OnGuidanceUpdateListener has three methods:

The GuidanceAnnouncement is an announcement point with its own message, location, and distance to the instruction point.

1val onGuidanceUpdateListener = object : OnGuidanceUpdateListener {
2 override fun onInstructionsChanged(instructions: List<GuidanceInstruction>) {
3 /* YOUR CODE GOES HERE */
4 }
5
6 override fun onAnnouncementGenerated(announcement: GuidanceAnnouncement) {
7 /* YOUR CODE GOES HERE */
8 }
9
10 override fun onDistanceToNextInstructionChanged(
11 distance: Distance,
12 instructions: List<GuidanceInstruction>,
13 currentPhase: InstructionPhase
14 ) {
15 /* YOUR CODE GOES HERE */
16 }
17}
18tomTomNavigation.addOnGuidanceUpdateListener(onGuidanceUpdateListener)

To remove a previously-added OnGuidanceUpdateListener use the TomTomNavigation.removeOnGuidanceUpdateListener(OnGuidanceUpdateListener) method.

tomTomNavigation.removeOnGuidanceUpdateListener(onGuidanceUpdateListener)

Lane level guidance

TomTomNavigation has built-in support for generating lane guidance. Lane guidance is generated for each LaneSection object in a Route.

You can learn more about how to request a route with a LaneSection by reading the Route sections guide.

The LaneGuidance object includes:

  • lanes - This is an object that consists of a list with directions and an optional lane direction that the driver should follow.
  • laneSeparators - This is a list of lane separators.
  • routeOffset - This is the distance in meters from the start of the route to the start of the lanes.
  • length - This is the length in meters of the lane section.

The generated LaneGuidance is sent to OnLaneGuidanceUpdateListener. OnLaneGuidanceUpdateListener has two methods:

1val onLaneGuidanceUpdateListener = object : OnLaneGuidanceUpdateListener {
2 override fun onLaneGuidanceStarted(laneGuidance: LaneGuidance) {
3 /* YOUR CODE GOES HERE */
4 }
5
6 override fun onLaneGuidanceEnded(laneGuidance: LaneGuidance) {
7 /* YOUR CODE GOES HERE */
8 }
9}
10tomTomNavigation.addOnLaneGuidanceUpdatedListener(onLaneGuidanceUpdateListener)

To remove a previously-added OnLaneGuidanceUpdateListener, use the TomTomNavigation.removeOnLaneGuidanceUpdatedListener(OnLaneGuidanceUpdateListener) method.

tomTomNavigation.removeOnLaneGuidanceUpdatedListener(onLaneGuidanceUpdateListener)

Arrival experience

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

At that point navigation continues to be in turn-by-turn mode until it’s stopped or switched into free driving mode.

1val onDestinationReachedListener = OnDestinationReachedListener {
2 /* YOUR CODE GOES HERE */
3}
4tomTomNavigation.addOnDestinationReachedListener(onDestinationReachedListener)

OnDestinationReachedListener can be removed as below.

tomTomNavigation.removeOnDestinationReachedListener(onDestinationReachedListener)

Waypoint arrival

The Route being followed can contain route stops that the driver wants to visit before arriving at the destination. These stops, called waypoints, are included in routeStops as instances of the type Waypoint. 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 OnWaypointVisitedListener. This means that the ArrivalDetectionEngine has successfully detected an arrival at the waypoint.

1val onWaypointVisitedListener = OnWaypointVisitedListener {
2 /* YOUR CODE GOES HERE */
3}
4tomTomNavigation.addOnWaypointVisitedListener(onWaypointVisitedListener)

OnWaypointVisitedListener can be removed as shown in the following figure.

tomTomNavigation.removeOnWaypointVisitedListener(onWaypointVisitedListener)

Next steps

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