Running Your Customized Plugin on the Phone

In this article, we discuss how to run MobileInsight monitoring/analysis code on the phone. By design, MobileInsight aims to provide a platform-independent environment. If an analysis script is developed with built-in monitors and/or analyzers only, it should run on both desktop servers and phones without modifications. To run it on the phone, the only extra step is to wrap the code as a plugin.

Plugin Structure

In the MobileInsight mobile version, all the user-defined plugins should be placed in /sdcard/mobileinsight/plugins/. Each plugin is placed in a separate folder, and includes at least a plugin entrance (main.mi2app), a description file (readme.txt), and an optional setting pannel configuration (settings.json) Besides, any numbers of files can be included, such as customized analyzers ), metadata, resource files, etc. More specifically, the directory structure of plugins look like this:

/sdcard/mobileinsight/plugins/
    Plugin1/
        main.mi2app
        readme.txt
        settings.json
    Plugin2/
        main.mi2app
        readme.txt
        settings.json
        __init__.py
        files/
        ...
    ...

To wrap MobileInsight codes as a plugin, a minimal step would include: (1) rename the analysis code entrance as main.mi2app, and place all the analysis code into a folder; (2) write a description readme.txt; and (3) copy the folder to /sdcard/mobileinsight/plugins/. At runtime, MobileInsight will automatically recognize your plugin and show it, so that you can select it and run the code.

An Example: Simple In-phone Message Logger

We use a simple example to demonstrate how to wrap the code. Suppose we want to port the previous monitoring example to the phone. To do so, we first create a folder to hold the plugin:

/sdcard/mobileinsight/plugins/
    MyLogger/
        main.mi2app
        readme.txt
        settings.json

The main.mi2app will hold the monitoring code, and looks like this:

# main.mi2app
import os
import sys

from mobile_insight.monitor import OnlineMonitor

# A helper utilities for mobileinsight
import mi2app_utils


# options of enabling logs

lte_control = [
        'LTE_RRC_OTA_Packet',
        'LTE_NAS_ESM_OTA_Incoming_Packet',
        'LTE_NAS_ESM_OTA_Outgoing_Packet',
        'LTE_NAS_EMM_OTA_Incoming_Packet',
        'LTE_NAS_EMM_OTA_Outgoing_Packet',
        ]
lte_data = [
        'LTE_MAC_UL_Transport_Block',
        'LTE_MAC_DL_Transport_Block',
            ]

# Initialize a 3G/4G monitor
src = OnlineMonitor()

# Configure the path of saving logs
cache_directory  = mi2app_utils.get_cache_dir()
log_directory    = os.path.join(cache_directory, "mi2log")
src.set_log_directory(log_directory)


# Enable logs based on settings
if plugin_config["log_type"] == "LTE Control Plane":
    src.enable_log(lte_control)
elif plugin_config["log_type"] == "LTE Control/Data Plane":
    src.enable_log(lte_control + lte_data)


#Start the monitoring
src.run()

Note that, we use plugin_config to access the configurations in setting panel, which is a built-in list of avaialble parameters based on settings.json. Compared with the monitoring example, we removed parameters of serial port and baudrate. But even if you keep them, it would still work correctly.

Next, we write a configuration of setting panel (settings.json), which follows the convention of kivy setting profile:

[
    {
        "type"   : "title",
        "title"  : ""
    },
    {
        "type"   : "options",
        "title"  : "Log Type",
        "desc"   : "Set the log type to collect",
        "key"    : "log_type",
        "default": "LTE Control Plane",
        "options": ["LTE Control Plane", "LTE Control/Data Plane"]
    },
    {
        "type"   : "numeric",
        "title"  : "Log Size (KB)",
        "desc"   : "The size of each log",
        "key"    : "mi_log_size",
        "default": "500"
    },
]

Last, we write a simple description file (readme.txt):

# readme.txt
An example in-phone message logger

Then copy the entire MyLogger/ to /sdcard/mobileinsight/plugins/. It can be done through either Android adb or directly downloading the folder to the sdcard.

Now launch MobileInsight app on the phone, and you will see MyLogger as folows:

_images/plugin.png

You can also change MyLogger’s configurations in the setting panel:

_images/plugin-settings.png

It is ready to run your code now!