Navigation

Engine that instantiates the update of the data store used for navigation.

The DefaultTomTomNavigation object defines the functionality of the navigation.

Defines the error cases that can occur while generating guidance steps.

Declares an observer that can receive announcements and instruction update events.

The method TomTomSDKNavigationEngines.GuidanceEngine.generateGuidance(navigationSnapshot:) generates the guidance with instructions and distance. Based on the guidance result, appropriate observer methods are called.

The protocol provides the interface for handling several events like changes in instructions, generation of announcements, and changes in distance to the next instruction.

To observe the guidance changes, first implement this interface to create an observer, for example:

class CustomGuidanceUpdateObserver: GuidanceUpdateObserver {

    func didChangeInstructions(instructions: [GuidanceInstruction]) {
        // Add code here that handles the changes of instructions.
    }

    func didGenerateAnnouncement(announcement: GuidanceAnnouncement, shouldPlay: Bool) {
        // Add code here that handles a new generate announcement.
    }

    func didChangeDistanceToNextInstruction(
        distance: Measurement<UnitLength>,
        instructions: [GuidanceInstruction],
        currentPhase: InstructionPhase
    ) {
        // Add code here that handles a change of distance to new instruction.
    }
}

Then add the observer using addGuidanceUpdateObserver(_:). To stop observation of the guidance changes, remove the observer using removeGuidanceUpdateObserver(_:).

Declares an observer that can receive changes when lane guidance starts and ends.

The LaneGuidanceUpdateObserver interface provides the methods that are called when lane guidance shall appear and disappear, respectively. These methods facilitate efficient and dynamic update of lane guidance information during a journey.

To observe the lane guidance changes, first implement this interface to create an observer, for example:

class CustomLaneGuidanceObserver: LaneGuidanceUpdateObserver {
    func didStartLaneGuidance(laneGuidance: LaneGuidance) {
        // Add code here that handles the lane guidance starting
    }

    func didEndLaneGuidance(laneGuidance: LaneGuidance) {
        // Add code here that handles the lane guidance ending
    }
}

Then add the observer using addLaneGuidanceUpdateObserver(_:). To stop observation of the lane guidance changes, remove the observer using removeLaneGuidanceUpdateObserver(_:).

Declares an observer that can receive navigation map matching events. Check the MapMatchingEngine documentation for more information on map-matching.

Declares an observer that can receive events indicating that the active route has been changed. The active route is the only followed route for which the navigation provides guidance.

The active route is changed when:

• The navigation is started with a new route using the start(navigationOptions:) method.
• The navigation is updated using the setActiveRoutePlan(_:) method. Note, if setActiveRoutePlan(_:) is called with the currently active RoutePlan, this observer will not receive an active route changed notification.
• Replanning is completed by the navigation and a new route is set as the active route. Replanning can be triggered by:
  • Deviating from the active route.
  • Running out of battery, in the case of Electric Vehicle navigation.
  • Requesting a navigation language change, by using the preferredLanguage property.
  • Continuous replanning:
  • A better route proposal is found and accepted automatically.
  • A better route proposal is accepted using the selectActiveRoute(routeId:) method.
  • A better route proposal is accepted by steering into the proposed route.

In order to receive notifications for active route changes, implement an instance of NavigationActiveRouteChangeObserver and register the observer by calling addActiveRouteChangeObserver(_:). For example:

class CustomRouteObserver: NavigationActiveRouteChangeObserver {
    func didChangeActiveRoute(route:) {
        // Implement the necessary functionality for handling the active route being changed
    }
}

The NavigationActiveRouteChangeObserver is notified after adding the route to the navigation and prior to the removal of the old active route. Hence, it is notified after the NavigationRouteAddObserver and before the NavigationRouteRemoveObserver.

To stop receiving these events, remove the observer using removeActiveRouteChangeObserver(_:).

Declares an observer that can receive navigation events of arrival at destination.

Destination arrival is detected by the TomTomSDKNavigationEngines/ArrivalDetectionEngine. On arrival detection, navigation continues in turn-by-turn mode until it’s stopped or switched into free-driving mode.

To be notified about the destination arrival event while navigating, first implement the NavigationDestinationArrivalObserver protocol:

class CustomNavigationDestinationArrivalObserver: NavigationDestinationArrivalObserver {
    func didArriveAtDestination(route: TomTomSDKRoute.Route) {
        // Add code here that handles arrival at a destination.
    }
}

Then add this observer using addDestinationArrivalObserver(_:).

To stop receiving the destination arrival event, remove the observer using removeDestinationArrivalObserver(_:).

Provides access to current registered engines and allows updating them.

Represents the NavigationEvent published by TomTomNavigation\eventPublisher.

Errors which may be thrown during navigation creation.

Declares an observer that can receive navigation guidance events.

Declares an observer that can receive navigation horizon events.

Declares an observer that can receive the language update events.

The navigation language is changed when TomTomNavigation.preferredLanguage is set and the route is successfully updated.

To add a NavigationLanguageChangeObserver, use addLanguageChangeObserver(_:). To stop receiving these events, remove the observer using removeLanguageChangeObserver(_:).

Declares an observer that can receive navigation guidance events.

Navigation options define parameters required to start or update a navigation session.

To specify navigation options, first plan a TomTomSDKRoute/Route using TomTomSDKRoutePlanner/RoutePlanner and TomTomSDKRoutePlanner/RoutePlanningOptions, then create a RoutePlan.

For more information on navigation session see: start(), start(navigationOptions:) and stop().

Declares an observer that can receive navigation progress events.

Declares an observer that can receive a route has been added to the navigation session.

A new route can be added to the session under the following circumstances:

• When navigation has started with a route using the start() method with NavigationOptions as an argument.
• When navigation is updated using the setActiveRoutePlan(_:) method. Note, if the new route is identical, which means it has the same Route/id as the current active route, it will not notify the observer.
• When navigation finds a better route and the TomTomSDKNavigationEngines/BetterProposalAcceptanceMode is set to either TomTomSDKNavigationEngines/BetterProposalAcceptanceMode/manual or TomTomSDKNavigationEngines/BetterProposalAcceptanceMode/unreachableOnly.
• When navigation finds a reachable route and TomTomSDKNavigationEngines/BetterProposalAcceptanceMode is set to TomTomSDKNavigationEngines/BetterProposalAcceptanceMode/manual.
• When navigation finds a reachable route, due to the navigated route being unreachable, and TomTomSDKNavigationEngines/BetterProposalAcceptanceMode is set to TomTomSDKNavigationEngines/BetterProposalAcceptanceMode/unreachableOnly so that the reachable route is automatically applied.
• When the TomTomSDKNavigationEngines/BetterProposalAcceptanceMode is set to TomTomSDKNavigationEngines/BetterProposalAcceptanceMode/automatic and the proposed route is automatically applied.
• When navigation automatically replans and adds the newly planned route to the session.
• When the preferredLanguage is set and the replanning with the new language has completed.

To receive notifications of a route being added to the session, first implement an observer object that conforms to NavigationRouteAddObserver, for example:

class CustomRouteObserver: NavigationRouteAddObserver { ... }

In order to complete conformance, the observer object must implement the following callback:

func didAddRoute(route: options: reason:) {
    // add code here that handles the route being added to the session
}

This callback function could render the newly added route on the map, for example.

Next, add this observer with navigation using addRouteAddObserver(_:). To stop notifications of a route being added to the session, remove the observer using removeRouteAddObserver(_:).

Please note that NavigationRouteAddObserver is notified only when the replanned route differs from the current active route in terms of geometry. Events like route refresh and increment update of guidance instructions will not notify this observer. For these scenarios the NavigationRouteUpdateObserver is notified.

The complementary observer that notifies on the removal of routes from the session is NavigationRouteRemoveObserver.

Declares an observer that can receive the active or proposed route has been removed from the navigation session.

The active route is removed from the session when:

• The navigation has completed replanning and set the new replanned route as the active one.
• The navigation is updated using the setActiveRoutePlan(_:).
• A better route proposal has been accepted using the selectActiveRoute(routeId:) method. Note, if the setActiveRoutePlan(_:) is called with the same route as the current active one, this observer will not be notified.
• The user is not following the active route as reported by NavigationRouteTrackingStateUpdateObserver.

The proposed route is removed from the session when:

• The user is not following the route, as reported by NavigationRouteTrackingStateUpdateObserver resulting in the proposed route being placed in the TomTomSDKNavigationEngines/RouteTrackingState/unfollowedRoutes list.
• The navigation has finished planning a new route due to replanning initiated by the navigation.
• The navigation is updated using the setActiveRoutePlan(_:) method. Note, if the setActiveRoutePlan(_:) is called with the same route as the proposed one, this observer will not be notified.

To receive notifications of a route being removed from the session, first implement an observer object that conforms to NavigationRouteRemoveObserver, for example:

class CustomRouteObserver: NavigationRouteRemoveObserver { ... }

/// In order to complete conformance, the observer object must implement the following callback:

func didRemoveRoute(route: reason:) {
    // add code here that handles the route being removed from the session
}

This callback function could remove a rendered route from the map, for example.

Next, add this observer with navigation using addRouteRemoveObserver(_:). To stop notifications of a route being removed from the session, remove the observer using removeRouteRemoveObserver(_:).

The complementary observer that provides updates on the addition of routes to the session is NavigationRouteAddObserver. Note, during navigation in turn by turn mode there will always be one active route. Therefore, any removal of the current active route will always be preceded by an NavigationActiveRouteChangeObserver call, with details of the new active route.

Declares an observer that can receive route tracking state updates.

The information about the route state is represented by TomTomSDKNavigationEngines/RouteTrackingState. When the driver deviates or returns to the active route, the navigation engine sends route-tracking state updates to the observer.

To be notified about the route state update while navigating, first implement the NavigationRouteTrackingStateUpdateObserver protocol:

class CustomNavigationRouteTrackingStateUpdateObserver: NavigationRouteTrackingStateUpdateObserver {
    func didUpdateRouteTrackingState(routeTrackingState: RouteTrackingState) {
        // Add code here that handles the route state update.
    }
}

To start receiving route tracking state updates, become an observer using TomTomSDKNavigation/TomTomNavigation/addRouteTrackingStateUpdateObserver(_:): To stop receiving route tracking state updates, remove the previously added observer using TomTomSDKNavigation/TomTomNavigation/removeRouteTrackingStateUpdateObserver(_:):

Declares an observer that can receive the current route has been updated.

The current route is updated under the following circumstances:

• When the route data is refreshed with data from the replanned route.
• When instructions and lane guidance are incrementally updated for the current route.

To receive notifications of a route being updated, first implement an observer object that conforms to NavigationRouteUpdateObserver, for example:

class CustomRouteObserver: NavigationRouteUpdateObserver { ... }

In order to complete conformance, the observer object must implement the following callback:

func didUpdateRoute(route: reason:) {
    // add code here that handles the route being updated
}

Next, add this observer with navigation using TomTomNavigation/addRouteUpdateObserver(_:)`. To stop notifications of a route being updated, remove the observer usingTomTomNavigation/removeRouteUpdateObserver(_:)“.

Please note that the NavigationRouteUpdateObserver is notified only when the route is updated. It means that the route geometry is preserved. When a route update happens the active route does not change, therefore the NavigationActiveRouteChangeObserver is not notified. To receive notifications of route changes that result in the geometry change, refer to the NavigationRouteAddObserver, NavigationRouteRemoveObserver and the NavigationActiveRouteChangeObserver.

Specifies the current navigation state of the TomTomNavigation object.

The current state changes under the following circumstances:

• When navigation is started by calling start(), the navigation state changes to freeDriving.
• When navigation is started by calling start(navigationOptions:), the navigation state changes to activeGuidance.
• When navigation is updated by calling setActiveRoutePlan(_:), being in the freeDriving state, the navigation state changes to activeGuidance.
• When navigation is stopped by calling stop() , the navigation state changes to idle.

Declares an observer that can receive navigationState change events.

The navigation state changes when the navigation session is started, resumed, stopped, or updated from from free driving to active guidance.

For more information on navigation states, see the NavigationState and navigationState documentation.

To be informed of navigation state updates implement NavigationStateChangeObserver:

class CustomStateChangeObserver: NavigationStateChangeObserver {
    func didChangeNavigationState(navigationState: NavigationState) {
        // add code that handles navigation state changes
    }
}

Then add the observer using addNavigationStateChangeObserver(_:).

To stop receiving these events, remove the observer using removeNavigationStateChangeObserver(_:).

Declares an observer that can receive navigation events related with visiting waypoints.

The waypoint arrival state changes are detected by the TomTomSDKNavigationEngines/ArrivalDetectionEngine. Different observer methods are called depending on what state has been detected by the TomTomSDKNavigationEngines/ArrivalDetectionEngine:

• didArriveAtWaypoint(waypoint:on:) is received when the TomTomSDKNavigationEngines/ArrivalDetectionEngine detects an arrival at a waypoint.
• didDepartFromWaypoint(waypoint:on:) is received when the TomTomSDKNavigationEngines/ArrivalDetectionEngine detects a departure from a waypoint.

To be notified about the waypoint arrival events while navigating, first implement the NavigationWaypointArrivalObserver protocol:

class CustomNavigationWaypointArrivalObserver: NavigationWaypointArrivalObserver {
    func didArriveAtWaypoint(waypoint: RouteStop, on route: Route) {
        // Add code here that handles an arrival at a waypoint.
    }

    func didDepartFromWaypoint(waypoint: RouteStop, on route: Route) {
        // Add code here that handles a departure from a waypoint.
    }
}

Then add this observer using addWaypointArrivalObserver(_:).

To stop receiving these events, remove the observer using removeWaypointArrivalObserver(_:).

SegmentsFilterError defines the errors that can occur while fetching the route progress.

Specifies how to handle requests which failed during replanning of a Route.

Responsible for creating default implementation of a ReplanningRetryPolicy.

Defines the reasons why a route was added to the navigation session.

Defines the reasons why a route was removed from the navigation session.

The options used for TomTomRouteReplanningEngine configuration

Defines the reasons why a route was updated during the navigation session.

A class responsible for calculating route progress in a standalone manner.

TomTomArrivalDetectionEngine checks if the driver has reached the destination or waypoint.

Creates a DynamicGuidanceEngine.

DynamicGuidanceEngine generates dynamic Guidance for the TomTomSDKRoute.Instructions supplied within NavigationSnapshot.activeRoute.

To generate dynamic Guidance, DynamicGuidanceEngine takes various parameters into account. These parameters include, but are not limited to:

• Distance to the next maneuver.
• Current speed of the vehicle.
• Free-flow speed of the road between the current position and the next maneuver.
• Traffic situation ahead.

So, unlike TomTomGuidanceEngine, DynamicGuidanceEngine does not depend on TomTomSDKRoute.Announcement information that may or may not be included in the TomTomSDKRoute.Instruction. It continuously checks the active route progress to provide up-to-date Guidance information. Once the vehicle reaches an announcement point, the generated Guidance includes the (GuidanceAnnouncement) to be announced.

Another difference between DynamicGuidanceEngine and TomTomGuidanceEngine is that DynamicGuidanceEngine uses TomTom’s advanced verbal instruction messages to synthesize GuidanceAnnouncements dynamically on the fly. Note that the set of supported languages may differ between different GuidanceEngines.

DynamicGuidanceEngine can be used to provide turn-by-turn navigation with any routing client (offline, online with TomTomSDKRoutePlanner.GuidanceOptions.guidanceVersion v1 or v2).

TomTomGuidanceEngine generates Guidance using the list of TomTomSDKRoute.Instructions supplied within NavigationSnapshot.activeRoute.

TomTomGuidanceEngine depends on the TomTomSDKRoute.Announcements included in the supplied TomTomSDKRoute.Instructions. The engine continuously checks the active route progress to provide up-to-date Guidance information. When the vehicle reaches an announcement point, the generated Guidance includes the GuidanceAnnouncement to be announced. Note that the set of supported languages may differ between different GuidanceEngines.

TomTomGuidanceEngine should only be used with the online routing client that uses TomTomSDKRoutePlanner.GuidanceOnlineAPIVersion.v1 as the TomTomSDKRoutePlanner.GuidanceOptions.guidanceVersion. This is because the instructions from offline and the online routing client configured with TomTomSDKRoutePlanner.GuidanceOnlineAPIVersion.v1 are designed to be used by the DynamicGuidanceEngine and do not contain static announcement information.

The TomTomNavigation protocol serves as the primary interface for controlling the navigation process. It provides a comprehensive set of functionalities for managing and customizing a navigation session.

To manage the lifecycle of a navigation session, the protocol offers methods to start() and stop() navigation. It also provides functionality to set and select active routes.

The protocol also includes a range of observers that allow developers to receive updates on various aspects of the navigation.

In addition to the observers, the interface enables customization of the navigation experience. Note that by changing these properties in runtime, the navigation initialization configuration is overridden. Users can configure the betterProposalAcceptanceMode, which determines how to handle better route proposals. Users can also choose the deviationReplanningMode, which defines whether the navigation automatically replans the route. The unitSystem and preferredLanguage can be customized to provide guidance instructions and announcements in the desired format and language.

RouteReplanningEngine implementation.

Defines types of unit system handling.