Skip to content

Work with DriveSession

Drive session is the most important component of our SDK. It serves map-matching, navigation, alerts and other important services.

As with our other service components, the user creates the drive session instances via a factory.

1
DriveSession driveSession = DriveSession.Factory.createInstance();

1
val driveSession: DriveSession? = DriveSession.Factory.createInstance()

By default, some of its services like the position service will automatically run once the drive session instance been created. Some of its services disabled by default, user need to call related drive session API to enable it. For example, with enableAlert member function call during lifecycle of drive session instance to enable or disable alert service, or calling enableADAS to enable or disable ADAS service.

There is another important concept named event hub which using for communicating between each service and the SDK user during runtime, SDK user can get the event hub instance with getEventHub function call:

1
2
3
EventHub eventHub = driveSession.getEventHub();
// TODO, add or remove spesific service listener
//  ...

1
2
3
val eventHub: EventHub? = driveSession?.getEventHub()
// TODO, add or remove spesific service listener
//  ...

Position Service

As the name states, position service provides the core positional service. It continually informs the user of detailed information like: the road name, speed limit, driving side of the street, etc... It also provides the accurately map-matched GPS position with high frequency (4Hz by default). Internally in our SDK, it is directly retrieving GPS location via the Android system API. SDK user does not need to perform any further action except grant/ensure user permission ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION.

The position service automatically runs once the drive session instance been created. To monitor events broadcasting from position service, one needs to create a PositionEventListener instance and add it to the event hub of the drive session:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
driveSession.getEventHub().addPositionEventListener(new PositionEventListener() {
    @Override
    public void onLocationUpdated(@NonNull final Location vehicleLocation) {
        // TODO: the input parameter is map-matched location
    }

    @Override
    public void onStreetUpdated(@NonNull final StreetInfo curStreetInfo, boolean drivingOffRoad) {
        // TODO: present street information current driving along with
    }

    @Override
    public void onCandidateRoadDetected(@NonNull RoadCalibrator roadCalibrator) {
        // TODO: present candicate road list and make correction on where the current vehicle is located
    }
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
driveSession.eventHub.addPositionEventListener(object : PositionEventListener {
    override fun onLocationUpdated(vehicleLocation: Location) {
        // TODO: the input parameter is map-matched location
    }

    override fun onStreetUpdated(curStreetInfo: StreetInfo, drivingOffRoad: Boolean) {
        // TODO: present street information current driving along with
    }

    override fun onCandidateRoadDetected(roadCalibrator: RoadCalibrator) {
        // TODO: present candicate road list and make correction on where the current vehicle is located
    }
})

The SDK provides turn-by-turn audio-ready instructions once the user gets a route and starts a navigation session. Meanwhile, the SDK will automatically re-calculate the navigation route for you when one or more of the following situation happens:

  • The user deviates from current route
  • There exists some critical traffic incidents or heavy traffic situations ahead
  • Illegal turn encountered ahead

To start a new navigation session with startNavigation function call (assuming client already owns an instance of drive session):

1
2
NavigationSession navigationSession = driveSession.startNavigation(route, false, 0.0);
//  ....

1
2
var navigationSession = driveSession?.startNavigation(route!!, false, 0.0)
//  ....

During an active navigation session, the SDK will broadcast navigation signals (at 1Hz frequenct) informing each other on the status of current navigation session, following information included:

  • distance to turn
  • turn type(icon) of current step
  • next street name
  • next-next street name(if available)
  • highway EXIT label and other signpost strings(if availible)
  • lane patterns(if available)
  • junction view image(if available)
  • ETA of upcoming stop or destination

To monitor these kinds of navigation events, the user needs to create a navigation event listener and register it to the drive session event hub. The following sample code illustrates registering a navigation event listener (assuming client already owns instance of drive session):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
driveSession.getEventHub().addNavigationEventListener(new NavigationEventListener() {
    @Override
    public void onNavigationEventUpdated(@NonNull final NavigationEvent navEvent) {
        //  TODO: present navEvent on HMI
        //  ...
    }

    @Override
    public void onNavigationRouteUpdated(@NonNull Route route, RouteUpdateReason reason) {
        //  TODO: refresh route showing on map and turn-list
        //  ...
    }

    //  TODO: override other callback apis from NavigationEventListener
    //  ...
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
driveSession.eventHub.addNavigationEventListener(object : NavigationEventListener {
    override fun onNavigationEventUpdated(navEvent: NavigationEvent) {
        //  TODO: present navEvent on HMI
        //  ...
    }

    override fun onNavigationRouteUpdated(route: Route, reason: RouteUpdateReason?) {
        //  TODO: refresh route showing on map and turn-list
        //  ...
    }

    //  TODO: override other callback apis from NavigationEventListener
    //  ...
})

Anytime navigation has been automatically re-routed, the client will be informed via the navigation event listener(see NavigationEventListener.onNavigationRouteUpdated).

During a navigation session, the user can change the current route. For example, adding, deleting or modifying stops and changing route styles. Here is the sample API call (assuming client already owns navigation session instance):

1
navigationSession.updateRoute(route);

1
navigationSession?.updateRoute(route)

To stop the current navigation session, just call SDK api NavigationSession.stopNavigation. Once the navigation session been stopped, all resource binding together with the navigation session instance will be cleaned. The client won't recieve navigation related events anymore.

1
navigationSession.stopNavigation();

1
navigationSession?.stopNavigation()

ADAS(Advanced Driving Assistance System) service

The SDK provides map-matching with high accuracy ADAS information such as the speed limit, road type, slope and curvature, traffic speed etc... while driving (regardless of whether in active navigation or free-driving). By default, ADAS service will not be activated until user enables ADAS service explicitly. One can call enableADAS to enable or disable the ADAS service. Once ADAS service been activated, drive session will broadcast ADAS massages with high frequency (4Hz by default). The following code segment illustrates how to enable ADAS service and receive ADAS messages:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
driveSession.enableADAS(true);  //  activate ADAS service
driveSession.getEventHub().addADASEventListener(new ADASEventListener() {
    @Override
    public void onADASEventUpdated(@NonNull final List<AdasMessage> adasMessageList) {
        for (AdasMessage msg : adasMessageList) {
            //  TODO: handle ADAS message
            //  ...
        }
    }
});

1
2
3
4
5
6
7
driveSession.enableADAS(true) //  activate ADAS service
driveSession.eventHub.addADASEventListener { adasMessageList ->
    for (message in adasMessageList) {
        // TODO: handle ADAS message
        //  ...
    }
}