Chapter 3: Scan and Clear Process

After successful authentication, all the public classes and functions are available to you for implementation. This chapter explains how to run an advanced full scan and full clear codes process. Please make sure that Chapter 2: Authentication is implemented and the SDK is authenticated successfully before you proceed with this chapter.

This chapter is divided into two modules - Scan Process and Clear Codes Process

Module 1: Scan Process

Step 1: Instantiate 'GProScanProcess' class

Context context = <YourActivity>.this;
GProScanProcess gProScanProcess = new GProScanProcess(context);

There is only one parameter required to instatiate 'GProScanProcess' class -

1. Context -> Pass the activity context in which this class is instantiated and used.

Step 2: Initialize Activity Launchers

private ActivityResultLauncher<Intent> mBtResultLauncher;
private ActivityResultLauncher<Intent> mSettingsResultLauncher;
private String mKeyType;
.
.
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    ....
    ..
    mKeyType = <GlobalStaticKeys.KEY_SCAN> or <GlobalStaticKeys.KEY_CLEAR>;
    initializeActivityLaunchers();
}

private void initializeActivityLaunchers() {
    mBtResultLauncher = registerForActivityResult(
            new ActivityResultContracts.StartActivityForResult(),
            result -> {
                if (result.getResultCode() == Activity.RESULT_OK) {
                    Log.i(TAG, "Bluetooth Enabled!");
                    if (mGProScanProcess != null)
                        mGProScanProcess.checkPermissions();
                } else {
                    Log.i(TAG, "Bluetooth NOT Enabled!");
                    onPermissionFailure(mKeyType, "Your bluetooth is not ENABLED!");
                }
            }
    );

    mSettingsResultLauncher = registerForActivityResult(
            new ActivityResultContracts.StartActivityForResult(),
            result -> {
                if (result.getResultCode() == Activity.RESULT_OK) {
                    Log.i(TAG, "Permission given!");
                    if (mGProScanProcess != null)
                        mGProScanProcess.checkPermissions();
                } else {
                    Log.i(TAG, "Permission denied!");
                    onPermissionFailure(mKeyType, "Near by devices, bluetooth and location permissions needed for searching and connecting with OBDII scanner.");
                }
            }
    );
}

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    mGProScanProcess.onRequestPermissionsResult(requestCode, permissions, grantResults);
}

First create two global ActivityResultLauncher objects -

1. mBtResultLauncher -> This result launcher is to get activity result callback when the SDK checks if the bluetooth is enabled on the device or not.
2. mSettingsResultLauncher -> This result launcher is to get activity result callback when the SDK opens device settings page to let the user enable the location and near by devices permissions, so that the SDK is able to connect to the scanner.

Then create one global String variable -

1. mKeyType -> This variable contains the key as to which process is initiated
   Scan Process = GlobalStaticKeys.KEY_SCAN
   Clear Codes Process = GlobalStaticKeys.KEY_CLEAR

In the onCreate() function of your activity, please initialize mKeyType variable and call initializeActivityLaunchers() function before you start with the scan process or clear codes process.
NOTE - Please copy the above initializeActivityLaunchers() function and onRequestPermissionsResult() as it is in your activity.

Step 3: Call 'initScan(String makeName, String registrationNumber, String jobCardId)' function

String makeName = <Make/Manufacturer Name>;
String registrationNumber = <Registration Number/License Plate Number>;
String jobCardId = <Unique Job Card ID>;
gProScanProcess.initScan(makeName, registrationNumber, jobCardId);

Parameters required for calling 'initScan(...)' function are -

1. Make Name -> This is the make or manufacturer name of the vehicle being scanned, for example Maruti Suzuki, Hyundai, Honda etc.
2. Registration Number -> This is the registration number or the license plate number of the vehicle being scanned.
3. Job Card ID -> This is a unique ID used to identify which job card this scan will belong to, or to create a connection between a job card, vehicle and it's scan report/data.

When you call the 'initScan(...)' function, the SDK will perform a series of checks and steps before the scan starts -

1. Authentication Check -> The scan process begins with an authentication check to ensure that the user is authorized to access the GaragePro SDK functionalities.
2. Permissions Check -> The SDK initiates checks for location and nearby devices permissions. These permissions are crucial for identifying and connecting to nearby Bluetooth scanners. If the required permissions are not granted by the user, the process halts and returns a failure callback. Permission dialogs and their callbacks are handled by the SDK itself.
3. Bluetooth Status Check -> After obtaining necessary permissions, the SDK checks the Bluetooth status on the device. If Bluetooth is disabled, the SDK prompts the user to enable Bluetooth before proceeding further.
4. Connect to Bluetooth Scanner -> Once Bluetooth is enabled, the SDK opens a Bluetooth OBDII scanners dialog, displaying a list of available OBDII scanners. The user selects a scanner from the list and initiates the connection process by pressing 'Connect'.
5. Start Scanning Process -> Upon successful connection to the selected scanner, the SDK begins the scanning process. It retrieves real-time data, trouble codes, and vehicle information from various systems like Engine, ABS, SRS, and more.

Step 4: Implement 'GProScanListener' Listener

After the scan process stops, the SDK utilizes callback functions to provide feedback and handle various scenarios:

public class YourActivity extends AppCompatActivity implements GProScanListener {
....
...

@Override
public void onScanAuthenticationFailure(String scanOrClear, String message) {
    Log.e(TAG, "Scan Authentication failure: " + scanOrClear + ": " + message);
    // Triggered if authentication fails during the scan/clear codes process
}

@Override
public void onPermissionRequest(String scanOrClear, int requestCode) {
    Log.d(TAG, "Permission request: " + scanOrClear + ": " + requestCode);
    // Copy the below code as it is
    runOnUiThread(() -> {
        if (requestCode == GlobalStaticKeys.RC_ENABLE_BT) {
            Intent enableBtIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE);
            mBtResultLauncher.launch(enableBtIntent);
        } else if (requestCode == GlobalStaticKeys.RC_ENABLE_LOCATION) {
            Intent intent = new Intent();
            intent.setAction(Settings.ACTION_APPLICATION_DETAILS_SETTINGS);
            Uri uri = Uri.fromParts("package", MainActivity.this.getPackageName(), null);
            intent.setData(uri);
            mSettingsResultLauncher.launch(intent);
        }
    });
}

@Override
public void onPermissionFailure(String scanOrClear, String message) {
    Log.e(TAG, "Permission failure: " + scanOrClear + ": " + message);
    // Indicates failure when user denies the permissions during the scan/clear codes process
}

@Override
public void onScannerConnectionCompleted(String scanOrClear, String message) {
    Log.d(TAG, "Scanner connection completed: " + scanOrClear + ": " + message);
    // Notifies successful connection to the Bluetooth scanner.
}

@Override
public void onScannerConnectionFailed(String scanOrClear, String message) {
    Log.e(TAG, "Scanner connection failed: " + scanOrClear + ": " + message);
    // Indicates failure to connect to the Bluetooth scanner. You have to check that the scanner is connected to the vehicle's OBDII port 
    // and the battery light is working, and that the scanner selected in the SDK is the same. 
    // Try starting the scan/clear codes process again.
}

@Override
public void onScanCompleted(String makeName, String registrationNumber, String jobCardId, String message, int scanId) {
    Log.d(TAG, "Scan completed: " + message);
    // Notifies successful completion of the scan process. Scan id can be used to retrieve the report details from CaRPM APIs.
}

@Override
public void onScanAbrupted(String makeName, String registrationNumber, String jobCardId, String message) {
    Log.e(TAG, "Scan abrupted: " + message);
    // Indicates an abrupt end to the scan process due to user action or other reasons.
}

@Override
public void onScanFailed(String makeName, String registrationNumber, String jobCardId, String message) {
    Log.e(TAG, "Scan failed: " + message);
    // Notifies failure in the scan process due to some unexpected reasons like connection failure etc.
}

@Override
public void onScanInProgress(String makeName, String registrationNumber, String jobCardId, int percentCompletion) {
    Log.d(TAG, "Scan in progress: " + percentCompletion + "%");
    // Provides updates on the scanning progress, such as percentage completion. 
    // percentCompletion value will range from 0 - 100
}

Implementing these callback functions in your application allows you to handle different scenarios gracefully and provide appropriate feedback to the user throughout the scan process.

Note - For changes in version 17 (0.1.7), please visit Version 17 (0.1.7) Release Notes.

There are other callback functions also which are specific to the clear process, we will discuss those in the next module which is Clear Codes Process.

Module 2: Clear Codes Process

Step 1: Same as Scan Process

Step 2: Same as Scan Process

Step 3: Call 'initClearCodes(String makeName, String registrationNumber, String jobCardId)' function

String makeName = <Make/Manufacturer Name>;
String registrationNumber = <Registration Number/License Plate Number>;
String jobCardId = <Unique Job Card ID>;
gProScanProcess.initClearCodes(makeName, registrationNumber, jobCardId);

Parameters required for calling 'initClearCodes(...)' function are -

1. Make Name -> This is the make or manufacturer name of the vehicle being cleared, for example Maruti Suzuki, Hyundai, Honda etc.
2. Registration Number -> This is the registration number or the license plate number of the vehicle being cleared.
3. Job Card ID -> This is a unique ID used to identify which job card this clear codes will belong to, or to create a connection between a job card, vehicle and it's clear report/data.

When you call the 'initClearCodes(...)' function, the SDK will perform a series of checks and steps before the clear process starts which are same as the scan process.

Step 4: Implement 'GProScanListener' Listener

All the callback functions implemented for scan process will remain the same in clear codes process as well. There are few of the callback functions which are specific to the clear codes process which are -

@Override
public void onClearCompleted(String makeName, String registrationNumber, String jobCardId, String message, int clearId) {
    Log.d(TAG, "Clear completed: " + message);
    // Notifies successful completion of the clear codes process.
}

@Override
public void onClearAbrupted(String makeName, String registrationNumber, String jobCardId, String message) {
    Log.e(TAG, "Clear abrupted: " + message);
    // Indicates an abrupt end to the clear codes process due to user action or other reasons.
}

@Override
public void onClearFailed(String makeName, String registrationNumber, String jobCardId, String message) {
    Log.e(TAG, "Clear failed: " + message);
    // Notifies failure in the clear codes process due to some unexpected reasons like connection failure etc.
}

@Override
public void onClearInProgress(String makeName, String registrationNumber, String jobCardId, int percentCompletion) {
    Log.d(TAG, "Clear in progress: " + percentCompletion + "%");
    // Provides updates on the clear codes progress, such as percentage completion. 
    // percentCompletion value will range from 0 - 100
}

Note - For changes in version 17 (0.1.7), please visit Version 17 (0.1.7) Release Notes.

Additional Functions

There are a few additional functions available in scan and clear codes process -

// This function can be used to stop the scan instantly, and save whatever data is gathered till now.
// Can be used if the process gets stuck somehow, or the progress completion is not updating
gProScanProcess.abruptEndScan();

// This function can be used to stop the clear codes instantly, and save whatever data is gathered till now.
// Can be used if the process gets stuck somehow, or the progress completion is not updating
gProScanProcess.abruptEndClearCodes();

// This function can be used to select bluetooth scanner manually. This will reset any existing connection.
// Can be used if user has changed scanner or is having trouble to connect to the scanner, he can manually select the scanner from here
gProScanProcess.selectScanner();

Note - selectScanner() function is only available in version 24 (0.2.4) and above