QModem

QModem is modular. Depending on your needs, you can install specific packages:

• luci-app-qmodem (Core): Provides the main Web UI for modem management, status monitoring, and dialing.
• luci-app-qmodem-sms: Adds a web interface for sending and receiving SMS messages.
• luci-app-qmodem-mwan: Integrates the modem with OpenWRT's mwan3 for multi-WAN load balancing and failover.
• luci-app-qmodem-ttl: Provides options to modify packet TTL to bypass carrier network sharing restrictions.
• luci-app-qmodem-hc: Supports devices with hardware-controlled SIM slots (e.g., HC-G80) to switch SIM cards via the UI.

The QModem suite is modular. Depending on your needs, you can install specific packages:

• luci-app-qmodem: The core package. Provides the LuCI web interface for modem management, status monitoring, and dialing.
• luci-app-qmodem-sms: Adds an SMS interface for sending/receiving text messages and viewing history (supports PDU mode).
• luci-app-qmodem-mwan: Integrates the modem with OpenWRT's mwan3 for multi-WAN load balancing and failover.
• luci-app-qmodem-ttl: Allows modification of IP packet TTL values to help bypass carrier tethering restrictions.
• luci-app-qmodem-hc: Hardware-specific support (e.g., for HC-G80) to allow SIM switching via the UI using GPIO-controlled slots.

The luci-app-qmodem application follows the standard LuCI MVC pattern. Understanding this structure is essential for extending the WebUI or modifying backend logic:

• controller/qmodem.lua: The core of the application. It defines the menu structure and handles all API calls from the frontend.
• model/cbi/qmodem/: Contains CBI (Configuration Binding Interface) files used to generate modem configuration forms in the LuCI Web interface.
• htdocs/luci-static/resources/qmodem/: Contains JavaScript files (e.g., modem.js) that provide dynamic functionality to the Web interface, such as polling modem status.
• root/etc/config/qmodem: The UCI configuration file where all modem settings are stored.
• vendor/: Contains vendor-specific shell scripts (e.g., quectel.sh) mapped via dynamic_load.json to handle brand-specific AT commands.

The tom_modem tool is an AT command line interface used to communicate with modems via TTY devices. It supports standard AT commands, binary AT commands (using hex encoding), and SMS management (reading, sending, and deleting).

usage: <tool_name> [options]

QFirehose provides two ways to notify external applications about upgrade progress: File-based notification and Message Queue (System V IPC) notification.

Important Compatibility Note: Android devices have limited support for System V IPC mechanisms; therefore, you must use the File-based method on Android. For other platforms, you can choose either.

Progress Values

Progress is communicated as an integer:

• 0: Upgrade has started.
• 1 to 99: Current progress percentage.
• 100: Upgrade completed successfully.
• -1: An error occurred during the upgrade.

Note: If the program crashes unexpectedly, the progress file/queue might be empty. Third-party applications should handle empty content gracefully.

Modem scanning is managed by the script located at luci/luci-app-qmodem/root/usr/share/qmodem/modem_scan.sh. The scanning process is triggered in three scenarios:

1. Service Initialization: When the qmodem_init service starts.
2. Hardware Events: When hotplug events for network cards or USB devices occur.
3. Manual Trigger: When a user initiates a scan via the WebUI.

Understanding these triggers helps in debugging why a modem might or might not be detected during system boot or hardware attachment.

In the pure JS version (luci-app-qmodem-next), SMS functionality is integrated directly into the main interface rather than being a separate plugin.

Key SMS Features & Behaviors:

• Interface: SMS is managed via a dialog box.
• Storage: Messages are automatically exported to the router's file system. The backend uses JSON as a database.
• Forwarding: Supports SMS forwarding, including forwarded read messages.
• Limitations:
  • You cannot set a custom SMS storage location via the UI.
  • You cannot manually delete SMS via the UI (only automatic deletion is supported).
  • Long message concatenation may fail if the operator/module provides unreliable timestamps.

When using the Custom Script forwarding type, the service executes your script and provides SMS data via environment variables.

Available Environment Variables

• $sms_body: The content of the SMS.
• $sms_sender: The sender's phone number.
• $sms_time: The timestamp of the message.
• $raw_pdu: The raw PDU data.

Script Implementation Example

You can access these variables in your shell script. Note that it is good practice to provide defaults for these variables to prevent errors if they are unset.

FROM="${SMS_SENDER:-unknown}"
RECEIVE_TIME="${SMS_TIME:-$(date '+%Y-%m-%d %H:%M:%S')}"
MSG="${SMS_CONTENT:-<empty>}"

A reference implementation can be found at /usr/share/qmodem/sms_forward_example.sh on the system.

The core luci-app-qmodem package provides the following management capabilities through the LuCI interface:

• Modem Information: View manufacturer, model, firmware, IMEI, and signal quality metrics (RSSI, RSRP, RSRQ, SINR).
• Dialing Control: Configure and manage the modem's data connection.
• Advanced Debugging: Perform band locking, cell locking, and send custom AT commands.

The modem scan process automates device detection and configuration. When a user triggers a scan (via the scan_modem API call), the following sequence occurs:

1. Execution: The qmodem.lua controller executes a backend shell script (e.g., /usr/share/qmodem/scan_modem.sh).
2. Detection: The script scans /sys/bus/usb/devices (USB) or /sys/bus/pci/devices (PCIe) for known Vendor/Product IDs, or looks for TTY devices (/dev/ttyUSB*, /dev/ttyACM*) that respond to the ATI AT command.
3. Information Gathering: The script sends AT commands to the detected device to retrieve the Manufacturer, Model, and IMEI.
4. Configuration: The script updates the qmodem UCI configuration file, creating a new configuration section (a "slot") for each detected modem.
5. Refresh: The API returns, and the frontend calls get_modem_list to update the UI with the new modems.