Route Navigation (v2.1.x - Android)

The core component of Navmii SDK responsible for route navigation is RouteNavigator. This class provides the API to control the route navigation process, to get navigation information and guidance updates. The class is also able to handle the rerouting and the rerouting by traffic.

CREATING ROUTE NAVIGATOR

Sdk class contains the getRouteNavigator method providing access to the instance of RouteNavigator. The route navigator instance can be accessed only after the SDK was started.

USING ROUTE NAVIGATOR

Route navigator has different responsibilities all related to each other:

• route navigator performs navigation along the specified route. Route navigator gets GPS position updates internally, updates the route navigation state and notifies if any changes occur.

• route navigator is able to handle rerouting. This option is intended to ease handling the rerouting process for SDK user. If rerouting handling is enabled, navigator, once rerouting is required, notifies that rerouting has started, calculates a new route, starts navigating along the new route and notifies that new route navigation has started.

• route navigator is able to handle rerouting by traffic. This option is intended to ease handing the rerouting by traffic process for SDK user. If rerouting by traffic is enabled, navigator, once traffic has been updated, applies it to the current route, if possible, or builds a new route otherwise, builds alternative routes if possible, and notifies that new route navigation has started, traffic was updated and alternative routes are available.

• route navigator is able to visualize changes in route by emitting route visualizer requests. To achieve such a behaviour you need to connect the route visualizer (getRouteVisualizer method of Sdk) to route navigator using addRouteVisualizerRequestListener method of RouteNavigator:

  Sample: connecting route visualizer to route navigator

  public class RouteVisializerRequestListenerExample { private final RouteNavigator routeNavigator; private final RouteVisualizer routeVisualizer; private final RouteVisualizerRequestListener routeVisualizerRequestListener = new RouteVisualizerRequestListener() { @Override public void onRouteVisualizerRequestAvailable(RouteVisualizerRequest routeVisualizerRequest) { routeVisualizer.performRequest(routeVisualizerRequest); } }; public RouteVisializerRequestListenerExample(Sdk sdk) { routeNavigator = sdk.getRouteNavigator(); routeVisualizer = sdk.getRouteVisualizer(); } private void connectVisualizerToNavigatior() { routeNavigator.addRouteVisualizerRequestListener(routeVisualizerRequestListener); } private void disconnectVisualizerToNavigatior() { routeNavigator.removeRouteVisualizerRequestListener(routeVisualizerRequestListener); } }

  
  
  

ROUTE NAVIGATION

Route navigation starts by calling the startNavigatingTheRoute method. The route parameter is an instance of Route class which represents a route to navigate. The source of routes is Routing Manager. After the route navigation has started, the route navigator gets GPS position updates internally, updates the route navigation state and notifies if any changes occur. Callbacks for the following events are available:

• OnRouteStateChangedListener: the 'on-route state' changes: user has got off the route or got back on the route. The SDK user may need this information to handle rerouting manually;

• PositionOnRouteChangedListener: position on route (distance or time to destination) changes;

• NextDirectionChangedListener: the next direction information changes;

• DistanceToNextDirectionChangedListener: the distance to the next direction changes;

• WaypointsPassedListener: a waypoint has been passed;

• DestinationReachedListener: destination has been reached.

Route navigator has methods to access the latest route navigation information at any time.

Route navigator also provides the route navigation guidance whose callbacks can be gotten by conforming to GuidanceListener interface.

User is able to stop the route navigation by calling the stopNavigation method.

AUTOMATIC REROUTING HANDLING

As mentioned above RouteNavigator is able to handle rerouting automatically. The feature is enabled by default, but RouteNavigator class has the setReroutingEnabled method, which can be used to disable or enable the feature. If automatic rerouting handling is enabled, the route navigator tracks the on-route state and, once the GPS position has got off the route, calculates a new route and applies it. Callbacks about the automatic rerouting process can be gotten by conforming to ReroutingListener interface. The interface has the onReroutingStarted method, which is called once automatic rerouting starts, and the onReroutingFinished method, which is called once the process finishes. The onReroutingFinished method has the newRoute parameter, which is a new instance of Route class representing the new route being navigated. The newRoute can be null if rerouting handling is no longer required (i.e. GPS position has returned back to the previous route).

The rerouting engine has an algorithm, which tries to use a route the most similar to the one passed to the startNavigatingTheRoute method. RouteNavigator has the setReroutingSettings method, which allows to tune the algorithm.

AUTOMATIC REROUTING BY TRAFFIC HANDLING

As mentioned above RouteNavigator is able to handle rerouting by traffic automatically. The feature is enabled by default, but RouteNavigator class has the setRroutingByTrafficEnabled method, which can be used to disable or enable the feature. If automatic rerouting by traffic is enabled, the route navigator internally gets notifications from the traffic service that traffic near the current position has been updated, and, once it happens, handles rerouting by traffic. The SDK user gets callbacks about the rerouting by traffic process by conforming to ReroutingByTrafficListener interface. The protocol has a single method, which is called once the rerouting by traffic occurred.

The rerouting by traffic engine may create a new instance of Route class. The newRoute parameter will have non-null value if that happens. The doesNewRouteResembleOldOne parameter indicates whether the route, being navigated after the rerouting by traffic occurred, is identical (takes the same roads) to the route being navigated before rerouting. So if the newRoute is non-null but the doesNewRouteResembleOldOne is true means that the route being navigated hasn't changed (takes the same roads).

The alternativeRoutes parameter is a list of alternative routes with the latest traffic applied, which can be used for navigation. Use startNavigatingTheRoute method to start navigation along one of the alternative routes.

GUIDANCE

Navmii SDK allows you to setup the way the navigation guidance will be provided. It's possible throughout the NavigationManager.getGuidanceSettings method. You can set the guidance output either to text or switch it off. If you pass GuidanceOutput.TEXT to the GuidanceSettings.setGuidanceOutput method, you'll be able to receive String instances with navigation guidance in NavigationListener.onGuidanceTextReady method.

You can also set guidance language via the GuidanceSettings.setLocale method. To get the list of all languages supported by the SDK use the getSupportedLocales method.

Currently supported languages:

• Czech

• Danish

• English (UK)

• English (US)

• Finnish

• French (France)

• German

• Italian

• Korean

• Norwegian

• Polish

• Portugese (Brazil)

• Portugese (Portugal)

• Russian

• Spanish (Spain)

• Swedish

• Turkish

Voice guidance

It's also possible to receive voice guidance instructions. To do this, first set the path to the directory containing the voice packs by using the Sdk.ConfigurationSettings.Builder.setVoicePacksPath method. After initializing the SDK, you can retrieve the list of available voice packs with the GuidanceSettings.getAvailableVoicePacks method, and select one using GuidanceSettings.setVoicePack. By passing GuidanceOutput.VOICE_PACK to the GuidanceSettings.setGuidanceOutput method, directions will be announced using the chosen voice pack.

Example: