Skip to content

DriveMotionClient

DriveMotion supports starting and stopping driving through method calls instead of automatic detection in MANUAL mode. To use this feature, developers must obtain DriveMotionClient after initializing DriveMotion.

Get DriveMotionClient

1
2
3
4
5
    try {
        DriveMotionClient driveMotionClient = DriveMotionService.getDriveMotionClient();
    } catch (DriveMotionException e) {
        // The SDK is not initialized
    }

1
2
3
4
5
    try {
        val driveMotionClient: DriveMotionClient = DriveMotionService.getDriveMotionClient()
    } catch (e: DriveMotionException) {
        // The SDK is not initialized
    }

Use DriveMotionClient

DriveMotionClient provides the entrance to start driving and stop driving manually, but DriveDetectionMode must be set to MANUAL, otherwise DriveMotionException will be generated.

Start Drive

The startDrive method will notify DriveMotion to start new trip. This is an asynchronous operation. When DriveMotion completes all necessary trip initialization, and then it will send a DriveStartEvent to the application via broadcast(by trigger onDriveStart callback). Then the application can get the session id, trip id, start time and start location information with the SDK.

The necessary initialization includes obtaining current device status and location info. If initialization meets any error, and DriveMotionException is thrown. Please check the exception message and perform subsequent operations.

Start Drive in synchronous [Deprecated, using asynchronous instead]

1
2
3
4
5
    try {
        driveMotionClient.startDrive();
    } catch (DriveMotionException e) {
        // The DriveDetectionMode is set to AUTO or trip start fail
    }

1
2
3
4
5
    try {
        driveMotionClient.startDrive()
    } catch (e: DriveMotionException) {
        // The DriveDetectionMode is set to AUTO or trip start fail
    }

Start Drive in asynchronous

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    driveMotionClient.startDriveRequest().build()
            .execute(new Callback<StartDriveResponse> {
                @Override
                public void onSuccess(StartDriveResponse response) {
                    // StartDriveRequest() execute finished and trip already started. 
                }

                @Override
                public void onFailure(Throwable t) {
                    // StartDriveRequest() execute failed due to ${t.message}
                }
            });

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    driveMotionClient.startDriveRequest().build()
            .execute(object : Callback<StartDriveResponse> {
                override fun onSuccess(response: StartDriveResponse) {
                    // StartDriveRequest() execute finished and trip already started. 
                }

                override fun onFailure(t: Throwable) {
                    // StartDriveRequest() execute failed due to ${t.message}
                }
            })

Note

If multiple consecutive startDrive()/startDriveRequest() calls are made, all subsequent calls to startDrive requests will be ignored as the presence of currentTrip, and the entire trip will be treated as one consecutive trip.

Note

If the SDK could not obtain the valid location when startDrive()/startDriveRequest(), the thrown exception is described as invalid location. Some common status are:

  • The device location service is not enabled.
  • The device has not been able to obtain location since restarted.
  • The current location has no GPS signal coverage.

There are several possible recovery methods for this situation:

  • Check whether the device location service is started normally from Settings.
  • Retry to startDrive with a delay.
  • If could not back to normal, try to re-initialize the SDK with a default GPS info. See SDKOptions section for details.

Stop Drive

The stopDrive method will notify DriveMotion to end current trip. This is an asynchronous operation. When DriveMotion completes end, it will send two event to application via broadcast:

DriveEndEvent(by trigger onDriveEnd callback). Then the application can get the session id, trip id, end time, end location and trip valid status information from the driveEndEvent.

Note

If the trip distance is too short or been detected as invalid trip, it will be hidden from any API calls when trip finished. The value driveEndEvent.isValidTrip will indicate the specific status of the finished trip.

DriveAnalyzedEvent(by trigger onDriveAnalyzed callback). Application can get the final trip information and score information from the driveAnalyzedEvent.

Stop Drive in synchronous [Deprecated, using asynchronous instead]

1
2
3
4
5
    try {
        driveMotionClient.stopDrive();
    } catch (DriveMotionException e) {
        // The DriveDetectionMode is set to AUTO or stop trip fail
    }

1
2
3
4
5
    try {
        driveMotionClient.stopDrive()
    } catch (e: DriveMotionException) {
        // The DriveDetectionMode is set to AUTO or stop trip fail
    }

Stop Drive in asynchronous

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    driveMotionClient.stopDriveRequest().build()
            .execute(new Callback<StopDriveResponse> {
                @Override
                public void onSuccess(StopDriveResponse response) {
                    // StopDriveRequest() execute finished and current live trip has been stopped.
                }

                @Override
                public void onFailure(Throwable t) {
                    // StopDriveRequest() execute failed due to ${t.message}
                }
            });

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    driveMotionClient.stopDriveRequest().build()
            .execute(object : Callback<StopDriveResponse> {
                override fun onSuccess(response: StopDriveResponse) {
                    // StopDriveRequest() execute finished and current live trip has been stopped.
                }

                override fun onFailure(t: Throwable) {
                    // StopDriveRequest() execute failed due to ${t.message}
                }
            })