QMICLI Modem Handler

• QMICLI Modem Handler
  • Introduction
  • Features
  • Dependencies
  • Configuration Constants
  • Command Result Response
  • Usage
    • Initialize modem
      • Initialize standalone
      • Initialize with config file
    • Disconnect (Teardown) modem
    • Device and SIM info
    • Signal and network Info
• Notes

Introduction

The modem_control Bash script is designed to interact with a modem device.

Features

• Modem Initialization: Configure the modem with tailored settings
• Device Information Retrieval: Easily obtain details about the device.
• Network Connection Handling: Take control of network connection.
• Signal Packet Statistics: Monitor the signal strength and gather packet statistics.
• SIM Card Information: Access SIM card details.

Dependencies

The script requires the following utilities to function properly:

• usbreset
• qmicli
• awk
• jq

Configuration Constants

Adjust the following constants according to the specific needs of your setup.

• DEVICE_PATH: Specifies the path to the cdc device of the modem. By default, this is typically set to /dev/cdc-wdm0.
• VENDOR_ID_MODEM: Defines the vendor ID of the modem, which is utilized in certain reset functions within the script. To ascertain the vendor ID of your modem, you can use the lsusb command. For example, the output Bus 001 Device 004: ID 1508:1001 Fibocom Fibocom Modem indicates that the vendor ID is 1508.
• DELAY_TIME_ITF_CHANGE: Time delay (in seconds) after an interface change.
• MAX_WAIT_TIME: Maximum wait time (in seconds) for loop operations.
• DEBUG: When set to 0, all non-JSON outputs are redirected to the LOG_FILE. Conversely, if set to any other value, errors will also be displayed on the console. For production environments, especially when the called application or script relies on JSON parsing, it is important to ensure that this is set to 0.
• DEBUG_LOG_AS_JSON: Currently, this feature is not implemented, as it has not found a use case in production environments.

Command Result Response

Every command executed by the script provides a JSON-formatted response containing the following objects:

• state: An object that indicates the status of the command execution.
  • If the command is executed successfully, state is set to "success".
  • In case of an error, state is set to "error", and a error message is provided.
• value: An object that holds the result of the command. In case of an error, this is set to an empty object.

Example of a successful command execution:

{
  "state": {
    "state": "success",
    "message": "success"
  },
  "value": {}
}

Usage

This section outlines various commands for modem operations such as initialization, disconnection, and information retrieval.

Initialize modem

The modem can be initialized in two different ways: using standalone mode or by using a configuration file in JSON format. The standalone mode allows for direct argument passing to the script, while the configuration file enables persistent settings.

Initialize standalone

To initialize the modem in standalone mode, you can execute the script with the required arguments as shown in the example below:

./modem_control -init-modem --mode=standalone --apn=wsim --no-roaming=no --auth=NONE

Show example output of -init-modem

{
  "state": {
    "state": "success",
    "message": "success"
  },
  "value": {
    "sim_info": {
      "sim_card_state": "present",
      "slot_app_state": "available",
      "application_state": "ready",
      "pin1_state": "disabled",
      "imsi": "<imsi>",
      "iccid": "<iccid>"
    },
    "profile_settings": {
      "profile_pdp_type": "ipv4",
      "profile_no_roaming": "",
      "profile_apn": "wsim",
      "profile_username": "",
      "profile_password": "",
      "profile_auth": "none"
    },
    "interface": {
      "used_interface": "cellular",
      "interface_available": "true",
      "sys_path": "/sys/class/net/cellular",
      "interface_up": "true"
    },
    "network_settings": {
      "ip_family": "IPv4",
      "ip": "10.2.18.210",
      "mtu": "1500",
      "subnet": "255.255.255.252",
      "gateway": "10.2.18.209",
      "dns_primary": "130.244.127.161",
      "domains": "none",
      "dns_secondary": "130.244.127.169"
    },
    "device_info": {
      "imei": "869816054543839",
      "manufacturer": "Fibocom Wireless Inc.",
      "model": "NL668_EAU_05_M.2_10_51",
      "revision": "19305.1000.00.02.73.03",
      "hw_revision": "V1.0.0",
      "operating_mode": "online-connected"
    },
    "serving_provider": {
      "plmn": "262-01",
      "mcc": 262,
      "mnc": 1,
      "description": "TDG",
      "roaming": true,
      "selected_network": "3gpp",
      "current_serving": true
    },
    "signal_strength": {
      "simple_signal": {
        "signal_human_readable": "good",
        "signal_bar": 3
      },
      "extended_signal": {
        "rssi": {
          "value": -78,
          "unit": "dBm"
        },
        "rsrq": {
          "value": -15,
          "unit": "dB"
        },
        "rsrp": {
          "value": -108,
          "unit": "dBm"
        },
        "snr": {
          "value": -1,
          "unit": "dB"
        }
      }
    },
    "operating_mode": {
      "operating_mode": "online-connected"
    }
  }
}

Initialize with config file

You can also connect by using a configuration file. There is a example config file attached.

./modem_control -init-modem --mode="config.json" # path to config file

Disconnect (Teardown) modem

Use the -teardown-modem command to disconnect.

./modem_control -teardown-modem

Show example output of -teardown-modem

{
  "state": {
    "state": "success",
    "message": "Network stopped successfully"
  },
  "value": {
    "operating_mode": "online-disconnected"
  }
}

Device and SIM info

Verify modem availability on the system

./modem_control -is-modem-available

Show example output of -is-modem-available

{
  "state": {
    "state": "success",
    "message": "success"
  },
  "value": {
    "usb_vendor_product": "1508:1001",
    "device_path": "/dev/cdc-wdm0"
  }
}

Get some general modem device information

./modem_control -get-device-info

Show example output of -get-device-info

{
  "state": {
    "state": "success",
    "message": "success"
  },
  "value": {
    "imei": "<imei>",
    "manufacturer": "Fibocom Wireless Inc.",
    "model": "NL668_EAU_05_M.2_10_51",
    "revision": "19305.1000.00.02.73.03",
    "hw_revision": "V1.0.0",
    "operating_mode": "online-disconnected"
  }
}

Get some general SIM information

./modem_control -get-sim-info

Show example output of -get-device-info

{
  "state": {
    "state": "ready",
    "message": "SIM is ready and can be used"
  },
  "value": {
    "sim_card_state": "present",
    "slot_app_state": "available",
    "application_state": "ready",
    "pin1_state": "disabled",
    "imsi": "<imsi>",
    "iccid": "<iccid>"
  }
}

Get the operating mode information

./modem_control -get-operating-mode

Show example output of -get-operating-mode

{
  "state": {
    "state": "success",
    "message": "success"
  },
  "value": {
    "operating_mode": "online-disconnected"
  }
}

Signal and network Info

Get provider information

./modem_control -get-serving-provider

Show example output of -get-serving-provider

{
  "state": {
    "state": "success",
    "message": "success"
  },
  "value": {
    "plmn": "262-01",
    "mcc": 262,
    "mnc": 1,
    "description": "TDG",
    "roaming": true,
    "selected_network": "3gpp",
    "current_serving": true
  }
}

Check autoreconnect based on provider and system data

./modem_control -check-autoreconnect

Note: This command checks if the provided network settings are still the same as the system settings

Show example output of -check-autoreconnect

{
  "state": {
    "state": "success",
    "message": "success"
  },
  "value": {
    "report_action": "assigned_ip_eq_provided"
  }
}

Fetch signal strength information

./modem_control -get-signal-strength

Show example output of -get-signal-strength

{
  "state": {
    "state": "success",
    "message": "success"
  },
  "value": {
    "simple_signal": {
      "signal_human_readable": "good",
      "signal_bar": 3
    },
    "extended_signal": {
      "rssi": {
        "value": -78,
        "unit": "dBm"
      },
      "rsrq": {
        "value": -15,
        "unit": "dB"
      },
      "rsrp": {
        "value": -108,
        "unit": "dBm"
      },
      "snr": {
        "value": 2,
        "unit": "dB"
      }
    }
  }
}

Get packet statistic

./modem_control -get-packet-statistics

Show example output of -get-packet-statistics

{
  "state": {
    "state": "success",
    "message": "success"
  },
  "value": {
    "tx_packets": 14,
    "tx_bytes": 1052,
    "tx_dropped_packets": 0,
    "rx_packets": 14,
    "rx_bytes": 1324,
    "rx_dropped_packets": 0
  }
}

Get interface information

./modem_control -get-itf-information

Show example output of -get-itf-information

{
  "state": {
    "state": "success",
    "message": "success"
  },
  "value": {
    "used_interface": "cellular",
    "interface_available": "true",
    "sys_path": "/sys/class/net/cellular",
    "interface_up": "true"
  }
}

Get the network settings from provider

./modem_control -get-network-settings

Show example output of -get-network-settings

{
  "state": {
    "state": "success",
    "message": "success"
  },
  "value": {
    "ip_family": "IPv4",
    "ip": "10.2.18.210",
    "mtu": "1500",
    "subnet": "255.255.255.252",
    "gateway": "10.2.18.209",
    "dns_primary": "130.244.127.161",
    "domains": "none",
    "dns_secondary": "130.244.127.169"
  }
}

Notes

The code of the modem_control is inspired by some other projects.

Source: https://github.com/mikeloveapple2/qmi_dial_script
Description: A simple bash script to setup a mobile connection
Main parts: https://github.com/mikeloveapple2/qmi_dial_script/blob/master/redial.sh
Inspiration: Used to understand the basic logic for connecting and disconnecting

Source: https://github.com/lf-edge/eve - EVE is Edge Virtualization Engine
Description: Open edge device logics for virtualization
Main parts: https://github.com/lf-edge/eve/blob/10.11/pkg/wwan/usr/bin/wwan-init.sh
Notes: The WWAN Modem handling in bash is only available for versions < 11.0
Inspiration: Used to understand complex handling of the modem.
This project inspired us to use the json parsing logic to call the modem_control from other programs and handle the output in JSON format.