Chapter 5: Live Data Scan Process

This chapter explains how to run live data scan process. Please make sure that Chapter 2: Authentication is implemented and the SDK is authenticated successfully before you proceed with this chapter.
Also this feature is implemented in SDK version 10 (0.1.0) and later.

Step 1: Instantiate 'GProLiveScanProcess' class

Context context = <YourActivity>.this;
GProLiveScanProcess gProLiveScanProcess = new GProLiveScanProcess(context);

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

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

Step 2: Initialize Activity Launchers

(You can skip this step if already done for Scan or Clear process, but just keep in mind that these result launchers should be available in the activity where you are using this Live Data Scan feature.)

private ActivityResultLauncher<Intent> mBtResultLauncher;
private ActivityResultLauncher<Intent> mSettingsResultLauncher;
.
.
.
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    ....
    ..
    .
    initializeActivityLaunchers();
}

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

    mSettingsResultLauncher = registerForActivityResult(
            new ActivityResultContracts.StartActivityForResult(),
            result -> {
                if (result.getResultCode() == Activity.RESULT_OK) {
                    Log.i(TAG, "Permission given!");
                    if (mGProLiveScanProcess != null)
                        mGProLiveScanProcess.checkPermissions();
                } else {
                    Log.i(TAG, "Permission denied!");
                    onLiveScanPermissionFailure("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);
    mGProLiveScanProcess.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.

In the onCreate() function of your activity, please call initializeActivityLaunchers() function before you start with the live data scan process.
NOTE - Please copy the above initializeActivityLaunchers() function and onRequestPermissionsResult() as it is in your activity.

Step 3: Call 'initLiveScan(String makeName, String modelName, String variantName, String registrationNumber, String jobCardId)' function

String makeName = <Make/Manufacturer Name>;
String modelName = <Model Name>;
String variantName = <Variant Name>;
String registrationNumber = <Registration Number/License Plate Number>;
String jobCardId = <Unique Job Card ID>;
gProLiveScanProcess.initLiveScan(makeName, modelName, variantName, registrationNumber, jobCardId);

Parameters required for calling 'initLiveScan(...)' 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. Model Name -> This is the model name of the vehicle scanned, for example Baleno, Scorpio, Elite i20 etc.
3. Variant Name -> This is the variant name of the vehicle scanned, for example Delta AMT, S10, Asta etc.
4. Registration Number -> This is the registration number or the license plate number of the vehicle being scanned.
5. 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 'initLiveScan(...)' function, the SDK will perform a series of checks and steps before the live data 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 fetches all the modules available for live data scan and returns a list of module names to the calling activity.
6. Display Live Scan Modules -> The callback function is onLiveScanModulesList(List moduleNames) which will return a list of module names to select from.

Step 4: Select a Live Data Scan Module

After receiving the list of module names for the particular vehicle, you have to select a module to proceed further and get a list of commands available for a particular module.
Call 'selectLiveScanModule(String moduleName)' function

gProLiveScanProcess.selectLiveScanModule(moduleName);

where moduleName is the selected module for which you want to see the available live data commands.
This function will fetch all the available live data commands for this selected module, and returns a hash map of the commands. The callback function is onLiveScanModuleCommandList(HashMap<Integer, String> commandList) where Key of the hashmap is an unique ID of the command, and Value is the name of the command.

Step 5: Select Live Data Scan commands

After receiving the list of commands for the particular module, you have to select the commands which you want to run in this live data scan.
Call 'selectLiveScanModuleCommands(HashMap<Integer, String> commandList)' function

gProLiveScanProcess.selectLiveScanModuleCommands(commandList);

where commandList is the hashmap of the selected commands.
This function will start running the commands and return the values in a callback function.

Step 6: Implement 'GProLiveScanListener' Listener

During the live data scan process, the SDK utilizes callback functions to provide feedback, results and handle various scenarios:

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

@Override
public void onLiveScanAuthenticationFailure(String message) {
    Log.e(TAG, "Live Scan Authentication failure: " + message);
    // Triggered if authentication fails during the live data scan process
}

@Override
public void onLiveScanPermissionRequest(int requestCode) {
    Log.d(TAG, "Live Scan Permission request: " + 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 onLiveScanPermissionFailure(String message) {
    Log.e(TAG, "Live Scan Permission failure: " + message);
    // Indicates failure when user denies the permissions during the live data scan process
}

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

@Override
public void onLiveScanScannerConnectionFailed(String message) {
    Log.e(TAG, "Live Scan scanner connection failed: " + 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 live data scan process again.
}

@Override
public void onLiveScanModulesList(List<String> moduleList) {
    Log.d(TAG, "List of Modules: " + moduleList.size());
    for (String moduleName : moduleList) {
        Log.d(TAG, "Module Name: " + moduleName);
    }
    // Returns a list of module names for which live data commands are available for the selected vehicle
}

@Override
public void onLiveScanModuleCommandList(HashMap<Integer, String> commandList) {
    Log.d(TAG, "List of commands: " + commandList.size());
    for (Map.Entry<Integer, String> entry : commandList.entrySet()) {
        Log.d(TAG, "Command: " + entry.getKey() + "/" + entry.getValue());
    }
    // Returns a hash map of live data commands available for the selected module and vehicle
}

@Override
public void onLiveScanResultUpdate(ConcurrentHashMap<String, LiveDataContract> resultHashMap) {
    Log.d(TAG, "Result Map: " + resultHashMap.size());
    for (Map.Entry<Integer, LiveDataContract> entry : resultHashMap.entrySet()) {
        Log.d(TAG, "Command Name: " + entry.getKey());
        Log.d(TAG, "Command Result: " + entry.getValue());
    }
    // Returns a hash map of the selected live data command results
}

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

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

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

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

Step 7: Understanding the Commands Result Map - ConcurrentHashMap<String, LiveDataContract> resultHashMap

In this result hash map, Key is the command name, and Value is a custom class which contains different fields for different result values. Here is the

1. Key (String) -> Command Name, for example Speed, RPM, Engine Load etc.

2. Value (LiveDataContract) -> Custom class called LiveDataContract which contains fields for different result values. Here is the detailed explaination of the fields -

   1. id -> Unique ID of the live data command
   2. name -> Name of the live data command
   3. metricUnit -> Unit of the live data command, in metric or SI unit system. For example Km/hr or degree celsius etc.
   4. imperialUnit -> Unit of the live data command, in imperial unit system. For example miles/hr or degree fahrenheit etc.
   5. metricResult -> Final decoded value of the live data command, in metric or SI unit system
   6. imperialResult -> Final decoded value of the live data command, in imperial system
   7. createdAt -> Timestamp when the entry is created
   8. rawException -> Any exception which may have occurred during the calculation of the live data command
   9. module -> Module name selected

Step 8: End Live Data Scan Process

gProLiveScanProcess.endLiveScan();

Call endLiveScan() to stop the scan instantly, and save the data whatever is gathered till now. Live Data Scan will not end on its own, so this function should be called whenever you want to end the live data scan.