Skip to content

Self Propelling In Tunnel

Self propelling in tunnel or underpass

This tutorial shows how to make a vehicle move smoothly in a tunnel or underpass when the GPS signal is lost. It's recommended to turn on this feature for a mobile device or an embedded device without dead reckoning.

Get started

Turn on self propelling at the creation of navigation service to enable it for the whole life cycle of the session.

1
2
3
4
5
6
7
// turn on self propelling
const auto settings = tn::foundation::Settings::Builder()
    .setString(tn::drive::api::SettingConstants::SETTING_POSITION_SELF_PROPELLING_UPON_WEAK_GPS, "true")
    .build();

const auto navigationService = tn::drive::api::NavigationServiceFactory::createNavigationService(
    options, system, settings, mapContent, directionService);

Update a location to indicate GPS signal lost

When entering a tunnel or underpass, GPS signal may be lost at some point. The phenomena could be connected satellite number is zero or GPS location is not changed for a while. In either case, self propelling will be working in navigation service and a deducted location will be provided in this case.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
tn::drive::models::v1::VehicleLocation inputLocation;
// satellite number is zero for the case of GPS signal is lost
inputLocation.satellite_num = 0;

// bearing is strongly recommended to be set to increase map matching quality
inputLocation.bearing = getVehicleBearing();

// speed is strongly recommended to be set to increase map matching quality
// NOTICE: speed MUST be greater than zero to trigger self propelling mode, otherwise it is considered that vehicle stops at the entry of the tunnel or underpass
inputLocation.speed = getVehicleSpeed();

// GPS location is must to have for an input location, could the same as the last location before signal is lost
inputLocation.coordinate = getVehicleGpsLocation();

navigationService->updateLocation(inputLocation);

Predict moving distance in self propelling mode

Once navigation service enters self propelling mode, it will pick up a speed as mock speed to predict moving distance in tunnel or underpass. The mock speed will be selected according to the following priorities:

  1. Live vehicle speed from updated vehicle location
  2. Live traffic speed
  3. Historical speed
  4. Max limited speed
  5. Vehicle speed updated last time

Handle self propelled location

Once navigation service enters self propelling mode, location updates will be caused by tn::drive::models::v1::Indicator::Cause::SelfPropelling. In free mode, self propelled location will be following the most possible path. In navigation mode, it will be following the route.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
void LocationObserver::onPositionIndicatorUpdated(const tn::drive::models::v1::Indicator& indicator)
{
    // cause is self propelling if GPS signal lost in tunnel or underpass
    const auto cause = indicator.cause;
    if (cause == tn::drive::models::v1::Indicator::Cause::SelfPropelling)
    {
        // location information is always available
        const auto location = indicator.location.matched_location;
        showVehicleLocationOnMap(location);
    }
}

Update a location to indicate GPS signal recovered

When leaving a tunnel or underpass, the GPS signal may recover at some point. Update a location that is outside a tunnel or underpass to exit self propelling mode.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
tn::drive::models::v1::VehicleLocation inputLocation;
// satellite number is usually greater than zero after GPS signal recovered
inputLocation.satellite_num = 4;

// bearing is strongly recommended to be set to increase map matching quality
inputLocation.bearing = getVehicleBearing();

// speed is strongly recommended to be set to increase map matching quality, it does not matter what speed is to exit self propelling mode
inputLocation.speed = getVehicleSpeed();

// GPS location is must to have for an input location, MUST be a location out of tunnel or underpass to exit self propelling mode
inputLocation.coordinate = getVehicleGpsLocation();

navigationService->updateLocation(inputLocation);