Skip to content

EH Service

Electric Horizon Service

Overview

Electric Horizon service (EH service in short) provides various information and functionalities for you to build a product that helps people enjoy the journey on road with great safety experience.

EH service can work in either standalone or affiliate mode. In standalone mode, it provides information along the predicted most probable path (MPP). In affiliate mode, it provides information along the MPP in free mode, when in navigation mode, it will try to provide information along the selected route if possible.

EH service can be used in two styles, one is in binary message style which follows standard ADASIS v2 specification by default. The other is in object-oriented style which provides the electric horizon constructed already. Both styles can work in either standalone or affiliate mode.

Using EH Service in Standalone Mode

To use EH service in standalone mode with binary message style, you need to create it explicitly. 

1
2
3
4
5
6
7
8
// create settings to specify EH service working mode is standalone
const auto settings = tn::foundation::Settings::Builder()
    .setString(tn::eh::api::SettingConstants::SETTING_EH_SERVICE_MODE, "0") // standalone mode
    .build();

// system instance is created for sharing in the whole SDK
// mapContent instance is created for sharing in the whole SDK
const auto ehMsgService = tn::eh::api::EHServiceFactory::createEHMessageService(system, settings, mapContent);

EH message service provides the paths and information along them in the format of binary messages. You need to register message listener and reconstruct the horizon with messages.

Make a customized message listener to handle EH binary message updates. 

1
2
3
4
5
6
7
8
9
class MessageObserver : public tn::eh::api::EHMessageListener
{
public:
    void onMessageUpdated(const std::vector<tn::eh::api::EHMessage>& messages) override
    {
        // reconstruct the horizon with message updates based on existed horizon if there's any
        // in case of path resetting, discard the old horizon and build a new one from scratch
    }
};

Register the message listener. 

1
2
3
4
5
// make a listener
const auto msgListener = tn::make_shared<MessageObserver>();

// register the listener
ehMsgService->addEHMessageListener(msgListener);

Using EH service in object-oriented style is very much similar as using EH service in binary message style at creation. 

1
2
3
4
5
6
7
8
// create settings to specify EH service working mode is standalone
const auto settings = tn::foundation::Settings::Builder()
    .setString(tn::eh::api::SettingConstants::SETTING_EH_SERVICE_MODE, "0") // standalone mode
    .build();

// system instance is created for sharing in the whole SDK
// mapContent instance is created for sharing in the whole SDK
const auto ehDataService = tn::eh::api::EHServiceFactory::createEHDataService(system, settings, mapContent);

EH data service provides both position and path updates in object-oriented style. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
class DataObserver : public tn::eh::api::EHDataListener
{
public:
    void void onDataUpdated(const std::vector<tn::eh::models::v1::EHData>& data) override
    {
        // ...
    }
};

// make a listener
const auto dataListener = tn::make_shared<DataObserver>();

// register the listener
ehDataService->addEHDataListener(dataListener);

Besides, to leverage the position update for DR calibration, you may need to register a location listener as well. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
class LocationObserver : public tn::eh::api::EHLocationListener
{
public:
    void void onLocationFeedback(const tn::eh::api::EHLocationFeedback& feedback) override
    {
        // align the input and output location with the elapsed timestamp
        // calibrate DR using the output location
    }
};

// make a listener
const auto locationListener = tn::make_shared<LocationObserver>();

// register the listener by message service.
ehMsgService->addEHLocationListener(locationListener);
// or by data service.
ehDataService->addEHLocationListener(locationListener);

If there's no DR integrated in your product, the self propelling feature is recommended to be enabled at creation. 

1
2
3
4
5
// create settings to specify EH service working mode is standalone and self propelling enabled
const auto settings = tn::foundation::Settings::Builder()
    .setString(tn::eh::api::SettingConstants::SETTING_EH_SERVICE_MODE, "0") // standalone mode
    .setString(tn::eh::api::SettingConstants::SETTING_EH_SELF_PROPELLING_UPON_WEAK_GPS, "true")
    .build();

Using EH Service in Affiliate Mode

To use EH service in affiliate mode, you need to create it with service mode set to affiliate and attach the instance to a navigation service. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
// create settings to specify EH service working mode is affiliate
const auto settings = tn::foundation::Settings::Builder()
    .setString(tn::eh::api::SettingConstants::SETTING_EH_SERVICE_MODE, "1") // affiliate mode
    .build();

// system instance is created for sharing in the whole SDK
// mapContent instance is created for sharing in the whole SDK
const auto ehMsgService = tn::eh::api::EHServiceFactory::createEHMessageService(system, settings, mapContent);

// 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);

navigationService->addExtension(ehMsgService);