Skip to content

Self Propelling In Tunnel

Self propelling in tunnel

This tutorial shows how to make a vehicle move smoothly in a tunnel 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 drive session 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 driveSession = tn::drive::api::DriveSessionFactory::createDriveSession(
    options, system, settings, mapContent, directionService);

Update a location to indicate GPS signal lost

When entering a tunnel, 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 drive session 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
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();

driveSession->updateLocation(inputLocation);

Handle self propelled location

Once drive session 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
    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, the GPS signal may recover at some point. Update a location that is outside a tunnel 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 to exit self propelling mode
inputLocation.coordinate = getVehicleGpsLocation();

driveSession->updateLocation(inputLocation);