2.2.3 Knowledge Pack Firmware Integration

The library and source code versions of a Knowledge Pack allow you to integrate Knowledge Pack APIs into your application at the firmware level. After downloading a Knowledge Pack, the contents need to be added to your MPLAB X project. Follow the steps below to integrate the knowledge pack into an MPLAB X project.

Extract the contents of the downloaded .zip file.
Create a new folder named knowledgepack in the firmware folder of your MPLAB X project, then copy the application and mplabml folders from the downloaded .zip into that new folder.
In MPLAB X, open your project.
In the Projects pane, right click the Header Files folder under the template project, then select Add Existing Items from Folders from the options.
In the resulting window that opens, click the Add Folder button.
In the new dialog, select Header Files from the Files of Type drop-down, then navigate to the template project's firmware directory, then select the knowledgepack directory.
Click the Select button to add the directory.
Back in the Add Files window, click the Add button to finish adding the necessary header files, then close the dialog.
Right click the Source Files folder in the Projects pane, then select Add Existing Items from Folders from the menu.
Repeat steps 6-8 to add all source files (.c files) from the knowledgepack folder.

Source Format

If you deployed a knowledge pack in the Source format, the Knowledge Pack is now integrated into your MPLAB X project.

Library Format

If you deployed a knowledge pack in the Library format, follow the remaining steps below to link the library into your project.

In the Projects pane, right click on the Libraries folder under the template project, then select Add Library/Object File.
In the resulting window that opens, select the libmplabml.a file from the firmware/knowledgepack/mplabml/lib directory. Your project is now ready to compile.

Calling Knowledge Pack APIs from Your Code

For this, we’ll use snippets from the filesml_recognition_run.c. The same changes largely apply to your project, regardless of platform.

Adding the header include

The Knowledge Pack will have the file kb.h in the mplabml/inc directory.

#include "kb.h"

Initialize the model(s)

You only need to initialize the library once. This is done with kb_model_init():

/* Initialize Knowledge Pack */
kb_model_init();

Running the Model for Classification

For this example, a function like this is generated automatically for you. In sml_recognition_run.c, the task gets a message for a batch of sensor data to process. It, then, handles the sensor data in this way:

ret = kb_run_model((SENSOR_DATA_T *)data, num_sensors, KB_MODEL_rank_0_INDEX);

if (ret >= 0){
    //Output model results
    sml_output_results(KB_MODEL_rank_0_INDEX, ret);

    //Reset running model to initial state.
    kb_reset_model(KB_MODEL_rank_0_INDEX);
}

The key items to take away are:

ret = kb_run_model((SENSOR_DATA_T *)data, num_sensors, KB_MODEL_rank_0_INDEX);

This is the call to pass a single sample of data to your model. The model will take care of any segmentation and feature extraction/classification from there.
if (ret >= 0)

If you get a value from kb_run_model greater than or equal to zero, you have received a classification. "0" means Unknown. Classes above zero are mapped to the classes that are in your project class map from the MPLAB® Machine Learning Development Suite:
sml_output_results(KB_MODEL_rank_0_INDEX, ret);

For the example in sml_recognition_run.c, only the results are reported out. Here is where your development comes in. You get to decide how to handle the output from the classifier.
kb_reset_model(KB_MODEL_rank_0_INDEX);

After a classification completes, you need to reset the model. This essentially sets it back to its initialized state and gets the model ready for classifying the next event your device may be experiencing.