Driver Behaviour

_|

The Driver Behaviour feature enables the analysis and scoring of a driver's behavior during a trip, identifying risky driving patterns and summarizing them with safety scores. This feature tracks both real-time and session-level driving events, such as harsh braking, cornering, or ignoring traffic signs, and evaluates overall risk using multiple criteria.

This data can be used to offer user feedback, identify unsafe habits, and assess safety levels over time. All information is processed using on-device sensor data (via the configured DataSource) and optionally matched to the road network if useMapMatch is enabled.

Starting and Stopping Analysis

To use the Driver Behaviour module, a session must be started using the startAnalysis method of the DriverBehaviour object. The session is closed using stopAnalysis, which returns a DriverBehaviourAnalysis instance representing the complete analysis.

auto driverBehaviour = bh::DriverBehaviour::produce(
    myDataSource,
    true
    );

bool started = driverBehaviour->startAnalysis();

// ... after some driving

auto result = driverBehaviour->stopAnalysis();

if (!result.isValid())
{
    GEM_INFO_LOG("The analysis is invalid and cannot be used");
}

warning

All DriverBehaviourAnalysis instances expose an isValid getter to determine whether the analysis is valid. Always verify this property before accessing or relying on the data it contains.

Inspecting a Driving Session

The result returned by stopAnalysis (or via getLastAnalysis) contains aggregate and detailed information on the trip:

if (!result.isValid()) {
    GEM_INFO_LOG("The analysis is invalid and cannot be used");
    return;
}

Time startTime = result.getStartTime();
Time finishTime = result.getFinishTime();
double distance = result.getKilometersDriven();
double drivingDuration = result.getMinutesDriven();
double speedingTime = result.getMinutesSpeeding();

The session also includes risk scores:

bh::DrivingScores scores = result.getDrivingScores();
if (scores.isDefault()) {
    GEM_INFO_LOG("No driving scores available");
    return;
}

double speedRisk = scores.getSpeedAverageRiskScore();
double brakingRisk = scores.getHarshBrakingScore();
double fatigue = scores.getFatigueScore();
double overallScore = scores.getAggregateScore();

note

Each score ranges from 0 (unsafe) to 100 (safe). A score of -1 means invalid or unavailable.

Inspecting a Driving Session

Use the drivingEvents property of the session result to access discrete driving incidents that were detected:

auto events = result.getDrivingEvents();
for (auto& event : events)
    GEM_INFO_LOG("Event at location (%f, %f) at time %llu with type %d", event.getLatitudeDeg(), event.getLongitudeDeg(), event.getTime().asInt(), (int)event.getEventType() );

Event types are defined by the bh::EDrivingEvent enum:

Driving Event Types

Enum Value	Description
NoEvent	No event
StartingTrip	Starting a trip
FinishingTrip	Finishing a trip
Resting	Resting
HarshAcceleration	Harsh acceleration
HarshBraking	Harsh braking
Cornering	Cornering
Swerving	Swerving
Tailgating	Tailgating
IgnoringSigns	Ignoring traffic signs

Real-time Feedback

If the analysis is ongoing, you can fetch real-time scores using:

auto instantScores = driverBehaviour->getInstantaneousScores();

These reflect the user's current behavior and are useful for immediate in-app feedback.

Stop Analysis and Get Last Analysis

To stop an ongoing analysis you can use:

auto analysis = driverBehaviour->stopAnalysis();
if (!analysis.isValid()) 
{
    GEM_INFO_LOG("No valid analysis available");
    return;
}

You can also retrieve the last completed analysis:

auto lastAnalysis = driverBehaviour->getLastAnalysis();
if (!lastAnalysis.isValid()) 
{
    GEM_INFO_LOG("No valid analysis available");
    return;
}

Retrieve Past Analyses

All completed sessions are stored locally and accessible via:

auto pastSessions = driverBehaviour->getAllDriverBehaviourAnalyses();

You can also obtain a combined analysis over a time interval:

Time start = Time::getUniversalTime() - LargeInteger(7 * 24 * 3600 * 1000); // 7 days ago
Time end = Time::getUniversalTime();

auto combinedAnalysis = driverBehaviour->getCombinedAnalysis(start, end);

Analyses Storage Location

Driver behaviour analyses are stored locally on the device. Inside the app’s directory, a folder named DriverBehaviour is created (at the same level as Data).

Data Cleanup

To save space or comply with privacy policies, older sessions can be erased:

Time time = Time::getUniversalTime() - LargeInteger(30 * 24 * 3600 * 1000); // 30 days ago
driverBehaviour->eraseAnalysesOlderThan(time);

note

Driver behaviour analysis requires a properly configured DataSource. See the Positioning guide to set up your data pipeline. To ensure reliable results, make sure to start and stop the analysis appropriately and avoid frequent interruptions or overlapping sessions.