Skip to content

Navigation Service

Overview

Navigation service is a key component in the TA SDK, which provides various information and functionalities for you to build a navigation product that helps people enjoy the experience on the road.

Free drive

When the user is not navigating on a selected route, which we call free mode, navigation service will provide information to help the user learn about road situations around them in free mode.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// create a navigation service options with all components enabled
tn::drive::api::NavigationServiceOptions options;
options.enable_alert = true;
options.enable_audio_guidance = true;
options.enable_navigation = true;

// system instance is created for sharing in the whole SDK
// if any of the default settings do not match the requirements, an instance of the setting should be created, which can be nullptr if the default value is good enough.
// mapContent instance is created for sharing in the whole SDK
// directionService instance is created for sharing in the whole SDK 
const auto navigationService = tn::drive::api::NavigationServiceFactory::createNavigationService(options, system, settings, mapContent, directionService);

Get a navigable route

Navigation service provides extensions to the direction service functionality with hybrid route calculation support. The calculation tasks are always performed in hybrid mode, navigation service will decide if both onboard and offboard calculations will be performed in parallel. In the case of parallel calculation, navigation service will choose a result which suits the SDK status the best. If calculation tasks are performed in either onboard or offboard mode, navigation service will behave the same way as direction service does.

Use direction service to build a routing request and use it in navigation service to make a hybrid routing calculation. 

1
2
3
// routing request is built with direction service
// use default hybrid routing configuration to create a task
const auto routingTask = navigationService->createNavigableRouteTask(routingRequest);

Hybrid routing configuration can be adjusted for each request. 

1
2
3
4
5
6
7
8
9
// adjust hybrid routing configuration
tn::drive::api::HybridRoutingConfiguration routingConfig;
routingConfig.timeout_for_short_route = 2000;
routingConfig.timeout_for_medium_route = 3000;
routingConfig.timeout_for_long_route = 5000;
routingConfig.timeout_for_old_data_version = 15000;

// use customized hybrid routing configuration to create a task
const auto routingTask = navigationService->createNavigableRouteTask(routingRequest, routingConfig);

Check the data version used for the route to see if the result is chosen from onboard or offboard calculation. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
// get streaming data version from map content
tn::mapcontent::ContentVersionInfo streamingVersion;
mapContent->getVersion(streamingVersion, tn::mapcontent::ContentMode::STREAMING);

// get map version from version information
std::string mapDataVersion;
for (const auto& info : streamingVersion.layers_info)
{
    if (info.layer == tn::mapcontent::DataLayerType::MAP)
    {
        mapDataVersion = info.version;
        break;
    }
}

// run hybrid routing task and handle the result
routingTask->runAsync([mapDataVersion](
    tn::foundation::ErrorCode errorCode, tn::shared_ptr<tn::drive::api::NavigableRouteResponse> response)
{
    if (errorCode == tn::foundation::SDKError::OK && response)
    {
        const auto& routes = response->routes();

        for (const auto& route : routes)
        {
            if (route)
            {
                const auto routeDataVersion = route->dataVersion();
                if (routeDataVersion == mapDataVersion)
                {
                    // offboard route
                }
                else
                {
                    // onboard route
                }
            }
        }
    }
});

When the user selects a route to navigate, navigation service will provide turn-by-turn instructions and information along the way.

1
2
3
4
5
6
7
8
// create a navigation session from navigation service
// notice: the navigation component must be enabled when creating a navigation service
// notice: navigation session is created and maintained by navigation service
// you MUST NOT delete it or access it after the navigation session is stopped
const auto* navigationSession = navigationService->startNavigation(route);

// stop the navigation session when it is no longer needed
navigationService->stopNavigation();

Next steps