Getting Started

MobileInsight has two versions: mobile version and desktop version. They share the same set of APIs, with slightly different installation and execution procedures. This guide covers how to install each version, and configure the monitoring/analysis environment.

Running MobileInsight on the Phone

Installation

MobileInsight supports in-phone cellular network monitoring and analysis. The version 2.0 currently supports Android phones with Qualcomm chipsets. To run it,

  1. Please root your phone. MobileInsight needs root access to the cellular interface.

  2. Please install MobileInsight apk to your phone. You can either directly copy it to the external storage of your phone and install it, or download it to a desktop machine (with Android adb installed) and use the following command:

    adb install MobileInsight-2.1.0.apk
    
  1. For some phone models, you may need to run MobileInsight in special boot mode. For example, for Nexus 6/6P, please boot your phone as baseband processing mode (e.g., see this link on how to do it). Note that most phone models do not need this step. Please try it only when MobileInsight reports warnings.

Running a MobileInsight Plugin

The mobile version encapsulates the cellular mointoring/analysis code as a plugin. At runtime, it loads the selected plugin, and performs the corresonding tasks. Currently MobileInsight provides three built-in apps: NetLogger, RrcAnalysis and NasAnalysis. Besides, you can also write your own in-phone plugins with MobileInsight APIs. To run a plugin, simply select it and click “Run!”, as shown below:

_images/mobileinsight-in-phone.png

If you run NetLogger, it will save the cellular logs (in *.mi2log format) to /sdcard/mobile_insight/log/. For RrcAnalysis and NasAnalysis, they will save the analysis results (in *.db format) to /sdcard/mobile_insight/db/.

Running MobileInsight on Desktops

Besides the mobile version, you can also connect your phone to the desktop machines and run the same functions. MobileInsight currently supports Windows/Linux/OSX.

Installation

To installation on the desktop machines, there are three steps:

Prerequisites

  1. Please install Python 2.7. Currently MobileInsight does not support Python 3.

  2. MobileInsight builds on top of pyserial, crcmod and xmltodict, so please install both libraries:

    pip install pyserial
    pip install crcmod
    pip install xmltodict
    

On Windows, you can also download both modules here and here.

  1. To run MobileInsight GUI, please install the following Python libraries:

    pip install wxPython
    pip install matplotlib
    

MobileInsight Installation

Please download the desktop version of MobileInsight here, extract the code and install it:

tar -zxvf MobileInsight-2.1.0.tar.gz
cd MobileInsight-2.1.0
sudo python setup.py install

In this process, MobileInsight will detect your operating system, download the platform-dependent libraries, and install the modules/libraries.

NOTE: for OS X 10.11 (EI Captian) users, please disable the System Integratity Protection (SIP) for successful installation (see tutorials here).

Configure the Phone

For the desktop version, the phone may be connected to the desktop machine for monitoring and (online) analysis. There are three steps:

  1. Enable the diagnostic mode on the phone. Note that this procedure is phone-specific. Here are a collection of instructions on differnet phone models.

  2. Connect the phone to the desktop machine with the USB cable. For some phones, the USB drivers should be installed on the desktop machine.

  3. Figure out the COM port for the phone’s diagnostic mode, which would be used for monitoring the network (see examples here).

    • On Windows: the corresponding port can be found in “Device manager -> serial port (COM and LPT)”. Some phone models require installing the usb drivers first;

      _images/windows-com-port.png
    • On Linux: the usbserial module should be loaded first. After connecting the device to the laptop, first run lsusb to get phone’s vendor and product hex code (Samsung in the following example):

      lsusb
      Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
      Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
      Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
      Bus 001 Device 003: ID 04e8:681c Samsung Electronics Co., Ltd
      Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
      

      Then load usbserial as follows:

      modprobe usbserial vendor=0x04e8 product=0x681c
      

      Typically the serial port would be listed, typically as /dev/ttyUSBX (X=0,1,2,...).

    • On OS X: the new devices can be found in /dev/tty.X. For example, for SAMSUNG series, the corresponding port is typically /dev/tty.SAMSUNG_VSP. Some phone models require installing the corresponding usb drivers first.

For some phones, there may be more than one port listed. You may try each port to test if it generates diagnostic logs.

Running a Command-line MobileInsight Script

In MobileInsight, running cellular network monitoring/analysis codes are written in Python. Running the code is as simple as running a Python script. Some example scripts can be found in mobile_insight/examples. For instance, if you want to collect runtime cellular logs, you can connect the phone to the desktop machine, and run the example code mobile_insight/examples/monitor-example.py as follows (assuming the phone’s port is /dev/tty.serial_port, and the baudrate is 9600):

python monitor-example.py /dev/tty.serial_port 9600 (OS X/Linux)
python monitor-example.py COM6 9600 (Windows)

If successful, it will save cellular logs to monitor-example.mi2log in the same directory, and dump the messages on screen in the following format (press ctrl-C to stop the monitoring):

1435219131.01 [INFO] WCDMA_RRC_Serv_Cell_Info
<dm_log_packet>
        <pair key="type_id">WCDMA_RRC_Serv_Cell_Info</pair>
        <pair key="timestamp">2015-06-28 23:37:59.130003</pair>
        <pair key="Uplink RF channel number">9763</pair>
        <pair key="Download RF channel number">10713</pair>
        <pair key="Cell ID">42602391</pair>
        <pair key="UTRA registration area (overlapping URAs)">11</pair>
        <pair key="Allowed Call Access">0</pair>
        <pair key="PSC">3504</pair>
        <pair key="PLMN">460-0115</pair>
        <pair key="LAC">46345</pair>
        <pair key="RAC">1</pair>
</dm_log_packet>
1435219131.76 [INFO] WCDMA_RRC_OTA_Packet
...
1435219135.51 [INFO] LTE_RRC_OTA_Packet
...

Using MobileInsight GUI

Besides running analysis scripts, MobileInsight also provides a user-friendly, platform-independent GUI to analyze your log files. It currently supports MobileInsight *.mi2log and Qualcomm *.qmdl logs. The MobileInsight GUI is located in mobile_insight/GUI/mobile_insight_gui.py. To run it:

cd mobile_insight/GUI/
./mobile_insight_gui.py

You will see the GUI below. Then you can load the logs and perform analysis.

_images/mobileinsight-gui.png

Next Step

Now you are ready to write your own MobileInsight code! Please read the tutorials and learn how to do it.