TomTomSDKNavigation

Responsible for detecting the arrival at destinations or waypoints during navigation.

The TomTomArrivalDetectionEngine evaluates the current navigation state to determine if the driver has arrived at a destination or a waypoint based on specified distance and time thresholds.

An engine that handles the maintenance of the navigation data store.

The DataStoreMaintenanceEngine protocol defines methods for maintaining the data store used in navigation. It ensures that the data store remains current and accurate based on the latest navigation state, which includes the position, route, and other relevant information.

The DefaultTomTomNavigation object defines the functionality of the navigation.

The DefaultTomTomNavigation class offers functionalities to start, stop, and manage navigation sessions. It integrates with TomTom services to provide real-time navigation guidance and updates.

let navigation = DefaultTomTomNavigation()
navigation.startNavigation()

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.

Represents various events that can occur during navigation.

The NavigationEvent enum defines different types of events that can be published by the TomTomNavigation.eventPublisher. These events cover a wide range of scenarios, such as :

• changes in navigation state,
• map matching,
• progress updates,
• route changes,

• guidance updates, and more. Each case in the enum corresponds to a specific event type and includes relevant information about that event.

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

Responsible for generating real-time guidance based on the active route’s instructions.

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

TomTomGuidanceEngine depends on the Announcements included in the supplied 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 GuidanceOnlineAPIVersion.v1 as the GuidanceOptions.guidanceVersion. This is because the instructions from offline and the online routing client configured with GuidanceOnlineAPIVersion.v1 are designed to be used by the DynamicGuidanceEngine and do not contain static announcement information.

Responsible for generating dynamic, real-time guidance based on the active route’s instructions and various dynamic parameters.

TomTomDynamicGuidanceEngine generates dynamic Guidance for the Instructions supplied within NavigationSnapshot.activeRoute.

To generate dynamic Guidance, TomTomDynamicGuidanceEngine 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, TomTomDynamicGuidanceEngine does not depend on Announcement information that may or may not be included in the 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 TomTomDynamicGuidanceEngine and TomTomGuidanceEngine is that TomTomDynamicGuidanceEngine 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.

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

Defines types of unit system handling.

Provides access to current registered engines and allows updating them.

Errors which may be thrown during navigation creation.

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

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

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

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 announcements and instruction update events.

The method 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 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(_:).

Declares an observer that can receive navigation guidance events.

Declares an observer that can receive navigation horizon events.

Horizon information is updated with each location update.

To use this observer, implement the protocol:

class CustomNavigationHorizonObserver: NavigationHorizonObserver {

    func didUpdateSnapshot(options: HorizonOptions, snapshot: HorizonSnapshot) {
        // Handle the updated horizon snapshot.
    }

    func didUpdatePosition(options: HorizonOptions, position: HorizonPosition) {
        // Handle the updated horizon position.
    }

    func didResetHorizon(options: HorizonOptions) {
        // Handle the horizon reset.
    }
}

To add a NavigationHorizonObserver, use addHorizonObserver(_:options:). To stop receiving these events, remove the observer using removeHorizonObserver(_:).

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.

After navigation has started (with or without a route), you will receive LocationContext via the NavigationLocationContextObserver.didDetectLocationContext(locationContext:) method.

To use this observer, implement the protocol:

class CustomNavigationLocationContextObserver : NavigationLocationContextObserver {
    func didDetectLocationContext(locationContext: LocationContext) {
        // Handle the detected location context.
    }
}

To add a NavigationLocationContextObserver, use addLocationContextObserver(_:). To stop receiving these events, remove the observer using removeLocationContextObserver(_:).

Declares an observer that can receive navigation progress events.

The NavigationProgressObserver protocol monitors progress along the active route. It informs the caller when the route progress is updated, which is calculated based on the user’s location and the route geometry. Progress updates occur with each location update.

To observe progress updates, implement this interface to create an observer, for example:

class CustomNavigationProgressObserver: NavigationProgressObserver {

    func didUpdateProgress(progress: RouteProgress) {
        // Handle the updated route progress.
    }
}

Add the observer using addProgressObserver(_:) to start receiving updates. To stop observing progress, remove the observer using removeProgressObserver(_:).

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 id as the current active route, it will not notify the observer.
• When navigation finds a better route and the BetterProposalAcceptanceMode is set to either manual or unreachableOnly.
• When navigation finds a reachable route and BetterProposalAcceptanceMode is set to manual.
• When navigation finds a reachable route, due to the navigated route being unreachable, and BetterProposalAcceptanceMode is set to unreachableOnly so that the reachable route is automatically applied.
• When the BetterProposalAcceptanceMode is set to 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.

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

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

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

Declares an observer that can receive route tracking state updates.

The information about the route state is represented by 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 addRouteTrackingStateUpdateObserver(_:): To stop receiving route tracking state updates, remove the previously added observer using 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.

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

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 ArrivalDetectionEngine. Different observer methods are called depending on what state has been detected by the ArrivalDetectionEngine:

• didArriveAtWaypoint(waypoint:on:) is received when the ArrivalDetectionEngine detects an arrival at a waypoint.
• didDepartFromWaypoint(waypoint:on:) is received when the 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(_:).

Defines the errors that can occur while fetching the route progress.

Responsible for calculating route progress in a standalone manner.

The purpose is to calculate and provide updates on the progress of the navigated route based on NavigationSnapshot.

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

Responsible for creating default implementation of a ReplanningRetryPolicy.

The options used for TomTomRouteReplanningEngine configuration

RouteReplanningEngine implementation.