VMGate User Manual

Complete guide for installing, configuring, and operating VMGate

VMGate User Manual

Version: 1.5.1.68A
Startel International LLC
Last Updated: December 2025

What This Manual Covers

This manual explains how to install, configure, and operate VMGate - an Android application that terminates VoIP calls on GSM SIM cards.

Prerequisites:

  • Rooted Android device (A15/A16/A53/A54, Android 13+)
  • Valid VMGate license from Startel
  • VoIP softswitch with SIP credentials
  • Basic understanding of VoIP termination

Not covered here:

  • Device rooting (see separate Rooting Guide)
  • VoIP switch configuration (your responsibility)

Table of Contents

  1. Installation
  2. First-Time Setup
  3. Settings Reference
  4. Daily Operation
  5. Automatic Features
  6. Troubleshooting
  7. Support

1. Installation

1.1 Fresh Installation (New Device)

Before you start:

  • Device must be rooted with Magisk installed
  • Magisk must have Systemizer module installed
  • Install Termux app from Play Store (or use adb shell from computer)

Steps:

  1. Receive APK via email from Startel
  2. Install APK on device
  3. Click DONE (do NOT click "Open"!)
  4. Open Termux app
  5. Type: su + ENTER (grant superuser when prompted)
  6. Type: setenforce 0 + ENTER
  7. Type: systemize + ENTER
  8. Type: 1 + ENTER (option: systemize an app)
  9. Find VMGate in the list that appears (note its number)
  10. Type VMGate's number + ENTER
  11. Type: 2 + ENTER (install as system/priv-app)
  12. Wait for completion (Systemizer will confirm)
  13. Type: 0 + ENTER (exit Systemizer)
  14. Reboot device
  15. Now open VMGate (from app drawer)

⚠️ CRITICAL: Do not skip the systemization step. VMGate requires system-privileged status to function.

1.2 Updating VMGate (Compatible Versions)

When Startel releases an update (e.g., v1.5.0 → v1.5.1):

  1. Download new APK (email from Startel → Download folder)
  2. Open File Manager on device
  3. Navigate to Download folder
  4. Tap the APK file
  5. Select "APP INSTALLER"
  6. Tap "UPDATE"
  7. Wait for completion
  8. Open VMGate

System-privileged status is preserved. Settings are preserved.

1.3 Major Version Migrations

If Startel instructs you to perform a major version migration (incompatible versions):

Contact Startel support: info@startelinternational.com

We will provide specific migration instructions.

2. First-Time Setup

After opening VMGate for the first time (fresh install), follow this sequence:

2.1 Enable Accessibility Service

VMGate automatically enables Accessibility Service when properly systemized (installed as system/priv-app). However, on some phones, manual activation may still be required.

Automatic Enablement (Most Phones):

  • VMGate automatically enables Accessibility Service on launch
  • No user interaction required
  • Works immediately after systemization

Manual Activation (Some Phones):

If Accessibility Service is not automatically enabled:

  1. VMGate opens → Shows "Accessibility Permission Required" dialog (if not auto-enabled)
  2. Tap OK
  3. Android Settings opens → Accessibility section
  4. Find VMGate in the app list
  5. Toggle ON
  6. If "Allow restricted settings" dialog appears:
    • Go to: Settings → Apps → VMGate
    • Open the top right menu (three dots or menu icon)
    • Select: "Allow restricted settings"
    • Return to: Settings → Accessibility → VMGate
    • Toggle ON (Accessibility Service)
  7. Return to VMGate (back button or app switcher)

Note: The "Allow restricted settings" dialog is normal on some Android 13+ devices. You must enable it in the app's settings menu before you can enable Accessibility Service.

[SCREENSHOT: Accessibility settings with VMGate toggle]

2.2 Grant Permissions

VMGate will request the following permissions (grant all):

  • Location (Position)
  • Contacts
  • Phone (Manage calls)
  • SMS (Manage SMS)

LAST and MOST CRITICAL:

  • Set VMGate as DEFAULT PHONE APP

⚠️ WARNING: If VMGate is not set as default phone app, it will NOT function. You must accept this.

[SCREENSHOT: Default phone app selection dialog]

2.3 Activate License

  1. Tap menu icon (⋮) → Settings
  2. Scroll to "License:" section (top of settings)
  3. Enter your Customer ID (provided by Startel)
  4. Tap "Activate License"
  5. Wait for confirmation: "License synced successfully!"
  6. VMGate automatically returns to Main Activity (prevents accidental multiple clicks)

Your License ID will appear automatically after activation.

Check your license pool: https://customer-vmgate.startelinternational.com/login

[SCREENSHOT: License activation section with Customer ID field]

2.4 Configure Language, Country, and Currency

  1. Return to Settings (menu ⋮ → Settings)
  2. Language: Select your language (currently English only)
  3. Country: Select your country from the dropdown list
  4. Currency: Select your currency from the dropdown list

Note: These settings are currently informative. They will be used for auto-configuration and billing features in future versions.

[SCREENSHOT: Language, Country, Currency spinners]

2.5 Configure SIP Server

  1. Continue in Settings (scroll down from Language/Country/Currency)
  2. IP: Enter your SIP server address (e.g., sip.yourprovider.com or IP address)
  3. Port: Fixed at 5060 (not editable)
  4. User: Enter your SIP username (normal text field)
  5. Password: Enter your SIP password (masked field - click eye icon to reveal/hide)

[SCREENSHOT: SIP configuration section]

2.6 Configure Essential Settings

Before using VMGate, you must configure:

Call Configuration:

  • Country Code (your country code, e.g., 39 for Italy)
  • Number manipulation flags (see Section 3.4)

SIM Configuration (for each SIM present):

Other Configuration:

  • MinIDLE / MaxIDLE (see Section 3.9)
  • Ring Timeout (suggested: 10 seconds)

Detailed explanation of each setting: See Section 3: Settings Reference

2.7 Save and Register

  1. Scroll to bottom of Settings
  2. Tap "Save"
  3. Return to Main Activity (back button)
  4. VMGate automatically attempts to register with your SIP server

⚠️ IMPORTANT: Initial Registration Delay (Normal Behavior)

When VMGate starts fresh (after app launch or reboot), you may observe the following sequence:

  1. App starts → VMGate automatically attempts to register
  2. Brief registration → May register and then immediately unregister
  3. Manual register button → May not respond immediately (this is normal)
  4. Wait 30-90 seconds → VMGate completes initial app operations:
    • Accessibility Service initialization
    • SIP client initialization
    • Network connectivity verification
    • Background services startup
  5. Automatic registration → VMGate registers successfully on its own
  6. From this point forward → Manual register/unregister buttons work normally

This is expected behavior. The initial delay allows VMGate to complete all necessary initialization steps before establishing a stable SIP connection.

What to do:

  • Wait 30-90 seconds after app start before expecting stable registration
  • Do not repeatedly tap "Register" during the initial period
  • Once registered (Connection Status LED turns green), VMGate is ready to use
  • After initial registration succeeds, manual register/unregister works immediately

Check Connection Status:

  • Green LED + "Registered" → Ready to use!
  • Red/Gray LED + "Disconnected" → Wait for auto-registration, or check SIP credentials if it doesn't register after 90 seconds

If registration fails after 90 seconds: Verify IP address in Settings.

[SCREENSHOT: Main Activity showing "Registered" status]

3. Settings Reference

This section explains every setting in VMGate. Settings are organized by section as they appear in the app.

3.1 License

Customer ID

  • Your unique customer identifier (provided by Startel)
  • Required for license activation

Buttons:

  • Activate License: Initial license activation
  • Re-sync License: Re-synchronize with Startel server (see below)

Important Notes:

License and Device Binding:

  • Each license is bound to your device's unique fingerprint
  • License activation is one-time only per device

OS/Firmware Reinstallation:

  • If you reinstall Android OS or firmware → Device fingerprint changes
  • You must activate a NEW license (old license becomes invalid)
  • To deactivate old license: Contact Startel at info@startelinternational.com with Customer ID and request license revocation
  • Startel will release the old license back to your license pool

License Recovery (Re-sync):

  • If license was issued but lost due to technical issue (app data cleared, etc.)
  • Tap "Re-sync License" to attempt automatic recovery
  • If recovery fails → "Activate License" button becomes available again
  • Tapping "Activate License" will issue a new license from your pool

Summary:

  • Re-sync: Recovers existing license or enables reactivation
  • New OS/firmware: Requires new license (contact Startel to release old one)
  • Lost license (same device): Re-sync first, then reactivate if needed

3.2 Language, Country, Currency

Language

  • Currently: English only
  • Future: Multi-language support

Country

  • Select your country
  • Currently informative
  • Future: Used for auto-configuration (v1.6/2.0)

Currency

  • Select your currency
  • Currently informative
  • Future: Used for billing features (v1.6/2.0)

3.3 SIP Configuration

IP

  • Your SIP server address (domain or IP)
  • Example: sip.yourprovider.com or 203.0.113.45

Port

  • SIP port: Fixed at 5060 (not editable)

User

  • Your SIP username
  • Entered as a normal text field

Password

  • Your SIP password
  • Entered as a masked field (hidden by default)
  • Click the eye icon on the right to reveal/hide the password

3.3.1 RTP Port Configuration (NEW)

Purpose: Configure custom RTP (Real-time Transport Protocol) ports for audio transmission. Useful when your network or operator blocks default RTP ports.

Enable RTP Port Configuration

  • Toggle: Enable/disable custom RTP port configuration
  • Default: OFF (uses system default ports)
  • When enabled: All RTP port fields become editable

RTP Port Base

  • Range: 10002 - 60000
  • Requirement: Must be an even number (RTCP uses the next odd port)
  • Default: 20000
  • What it does: Sets the base RTP port used for audio transmission
  • Example: If set to 20000, RTP uses port 20000, RTCP uses port 20001

RTP Port Min / RTP Port Max

  • Range: 10000 - 60000 (each field)
  • Requirement: Min must be less than Max, both must be even numbers
  • Default: Min = 20000, Max = 30000
  • What it does: Defines the port range for automatic port discovery

Find Working Port (Discovery Feature)

  • Button: "Find" (changes to "Cancel" during discovery)
  • What it does:
    1. Tests UDP connectivity to your SIP server
    2. Scans even ports in the Min-Max range
    3. Finds the first port that can successfully send UDP packets
    4. Automatically fills the "RTP Port Base" field with the working port
  • Progress: Shows progress bar during discovery
  • Duration: Typically 10-60 seconds depending on range size
  • Requirements:
    • SIP IP address must be configured and valid
    • Port range must be valid (Min < Max, both even, within 10000-60000)
    • Device must have network connectivity

How to Use:

  1. Enable "Change RTP Port" toggle
  2. Set Min/Max port range (e.g., 20000-30000)
  3. Tap "Find" button
  4. Wait for discovery to complete
  5. Verify the discovered port is filled in "RTP Port Base"
  6. Save settings
  7. Restart VMGate or re-register for changes to take effect

When to Use:

  • Operator blocks default RTP ports
  • Network firewall requires specific port ranges
  • Troubleshooting audio issues
  • VoIP provider requires custom RTP ports

Note: RTP port changes only take effect after saving settings and re-registering with the SIP server.

3.4 Call Configuration

These settings control how VMGate manipulates phone numbers when routing VoIP calls to GSM.

Direction: VoIP → GSM only (outgoing termination)

Country Code

  • Your country dialing code (without +)
  • Examples: 1 (USA), 39 (Italy), 44 (UK), 7 (Russia)

Number Manipulation Flags (choose one combination):

Flags Active VoIP sends 393123456789 → GSM dials
Add Plus (+) +393123456789 (international format)
Remove CC 3123456789 (national format)
Remove CC + Add Zero 03123456789 (local format with trunk prefix)

Common combinations:

  1. ✅ Add Plus - International format (most common, works everywhere)
  2. ✅ Remove CC - National format (no country code)
  3. ✅ Remove CC + Add Zero - Local format (Italian/European style)

⚠️ Invalid: Add Plus + (Add Zero OR Remove CC) - System prevents this combination

Recommendations:

  1. Add Plus - Most compatible, works internationally (primary recommendation)
  2. Remove CC + Add Zero (or Remove CC only) - Complete simulation of local calls, better anti-detection

3.5 SIM Details

Purpose: These fields define the "called number" (B-number) when incoming GSM calls are forwarded to VoIP.

Direction: GSM → VoIP only (incoming calls)

SIM1 Phone Number

  • Shown only if SIM1 is present in device
  • Format: +CountryCodeAreaCodeNumber (e.g., +393123456789)
  • Used as B-number when SIM1 receives incoming GSM call
  • If empty: Placeholder 999999999999 is used

SIM2 Phone Number

  • Shown only if SIM2 is present in device
  • Same format and logic as SIM1

Why manual entry?

  • Allows custom routing on your VoIP switch based on B-number
  • Track which SIM received the call
  • Different DIDs per SIM

3.6 SIM1 Configuration

These settings control termination limits and behavior for SIM1.

⚠️ IMPORTANT: All limits are checked at call start only. VMGate never interrupts ongoing calls. Plan limits accordingly (set lower than actual quota to account for in-progress calls).

MIN Daily Attempts / MAX Daily Attempts

  • Purpose: Simulate human behavior (anti-detection)
  • Range: 0-9999 per field
  • How it works:
    • Every day at midnight, VMGate picks a random number between MIN and MAX
    • Example: MIN=50, MAX=150 → Today's limit might be 87 attempts
    • Tomorrow it might be 134 attempts
    • Randomness prevents machine-like patterns
  • Attempts = Total calls (answered + unanswered)
  • Suggestion: Set wide range (e.g., 100-300) for realistic variation

MIN DLIMIT / MAX DLIMIT

  • Purpose: Daily minute limits (anti-detection)
  • Range: 0-500 per field
  • How it works:
    • Same random logic as Daily Attempts
    • Every day, VMGate picks random minutes limit between MIN and MAX
    • DLIMIT = Daily Limit (minutes per calendar day)
  • Suggestion: Set based on your carrier's typical usage patterns
    • Low volume: 50-150 minutes
    • Medium volume: 100-300 minutes
    • High volume: 200-500 minutes

MLIMIT

  • Purpose: Hard safety cap (monthly maximum minutes)
  • Range: 0-15000
  • How it works:
    • Maximum minutes this SIM can terminate in calendar month (1st to end of month)
    • Example: MLIMIT=5000 → SIM stops accepting calls after 5000 minutes this month
    • Resets automatically on 1st of each month
  • Prevents: Over-usage that triggers carrier anti-fraud systems
  • Suggestion: Set to ~80% of your actual monthly carrier quota

Package Minutes

  • Purpose: Track prepaid carrier bundle quota
  • Range: 0-999999
  • How it works:
    • If your carrier plan includes a bundle (e.g., "500 minutes/month"), enter it here
    • VMGate tracks usage against this quota
    • Works alongside MLIMIT (separate counter)
  • Leave at 0 if: No package tracking needed

Package Reset

  • Purpose: When does the package quota reset?
  • Options:
    • None - No package tracking
    • Sunday - Reset every Sunday
    • Monday - Reset every Monday
    • 1st - Reset on 1st of month
    • 1st and 16th - Reset twice per month
    • End of Month - Reset on last day of month
    • Specific - Enter custom day (e.g., 15 for 15th of each month)

Package Used Minutes

  • Read-only display
  • Shows current usage against package quota
  • Reset button: Manually reset counter if needed

Block Flash Messages (SIM 1)

  • Purpose: Prevent carrier post-call SMS from interfering with termination
  • What are flash messages?
    • Legitimate SMS from carrier after each call
    • Shows cost and duration (e.g., "Your call cost 0.50€, duration 5:23")
    • Problem: These messages interfere with VMGate's call handling → termination stops working
  • How it works:
    • Blocks flash messages only during call timeout period (not all the time)
    • Prevents interference without compromising normal SMS
  • When to enable:
    • ON: If your carrier sends post-call cost/duration SMS
    • OFF: If your carrier doesn't send these messages
  • Common in: Mostly Africa, Latin America, and Asia
  • Test: Make a test call, check if you receive SMS immediately after. If yes, enable this flag.

Next Available Date

  • Read-only display
  • Shows when SIM1 becomes available again after IDLE timeout
  • Format: DD/MM/YYYY HH:MM:SS
  • Reset button: Force immediate availability (overrides IDLE countdown)

Used Daily Minutes / Used Monthly Minutes

  • Read-only displays
  • Show current usage counters
  • Reset buttons: Manually reset if needed

3.7 SIM2 Configuration

Identical to SIM1 Configuration (Section 3.6).

All fields, ranges, and logic are the same.

3.8 Modem Health Monitor (A15/A16 Only)

Shown only on: Samsung A15 and A16 devices

Purpose: Detect and recover from GSM modem freezes

The Problem:

  • A15/A16 patched modem firmware has known bug
  • After ~24 hours of usage → Complete GSM signal loss on BOTH SIMs

The Solution:

  • Monitor checks signal every 1 minute (separate thread)
  • Detects loss (0 ASU, OUT_OF_SERVICE) → Automatic recovery
  • Recovery behavior depends on Android version:
    • Android 13/14: Multi-stage recovery (airplane mode toggle → RIL restart) - Recovery time: ~10 minutes
    • Android 15: Direct reboot after 90 seconds (due to different policies enforced by Android 15)

Setup Requirements:

1. Enable Magisk Superuser Permission:

  1. Open Magisk Manager app
  2. Tap Superuser (shield icon)
  3. Find VMGate in app list
  4. Tap VMGate entry
  5. Enable:
    • ✅ Grant superuser permission
    • ✅ Allow background execution ← CRITICAL!
  6. Save settings

2. Enable in VMGate Settings:

  • Toggle "Modem Health Monitor (A15/A16)" to ON

When to use:

  • ALWAYS enable on A15/A16 devices
  • Not shown on A53/A54 (not needed)

Performance impact: Minimal (1-minute intervals, separate thread)

Manual alternatives if monitor is OFF:

  • Enable monitor → wait for auto-recovery (Android 13/14: ~10 minutes, Android 15: 90 seconds)
  • Reboot device

3.9 Other Configuration

These settings control call timing, billing, and behavior.

MinIDLE / MaxIDLE

  • Purpose: Post-call cooldown period (simulate human behavior)
  • Range: 0-6000 seconds (0-100 minutes)
  • Units: Seconds
  • How it works:
    1. Call ends on SIM1
    2. VMGate picks random seconds between MinIDLE and MaxIDLE
    3. Example: MIN=120, MAX=600 → might pick 347 seconds
    4. Countdown starts (visible in Main Activity)
    5. SIM1 is unavailable until countdown reaches zero
    6. "Next Available Date" is set (current time + countdown duration)
  • Purpose: Humans don't make calls back-to-back instantly. This simulates realistic call spacing.
  • Suggestion:
    • Low volume: 60-300 seconds (1-5 minutes between calls)
    • Medium volume: 120-600 seconds (2-10 minutes)
    • High volume: 30-180 seconds (0.5-3 minutes)
    • Trade-off: Higher/wider range = fewer calls terminated, but SIM lives longer

Ring Timeout

  • Purpose: Detect GSM failures early
  • Range: 0-60 seconds
  • How it works:
    • SIP call accepted → VMGate places GSM call
    • If GSM doesn't start ringing within Ring Timeout seconds:
    • Abort immediately with SIP 503 (allows VoIP switch to reroute)
  • Suggestion: 10 seconds (works in 90% of cases)
  • Acceptable range: 5-15 seconds

Cost Minute

  • Purpose: Future feature (v1.6/2.0) for billing/reporting
  • Currently: Informative only (enter for future use)
  • Must be entered (required field)

Billing

  • Purpose: Define billing increments
  • Format: Initial period / Subsequent increment (in seconds)
Option Meaning
1/1 Bill per second from start
30/1 First 30 sec billed as block, then per second
30/30 Bill in 30-second blocks throughout
60/1 First 60 sec billed as block, then per second
60/60 Bill per minute throughout

Most common: 1/1 or 60/1

3.10 Presentation Configuration

Purpose: Control Caller ID presentation on outgoing GSM calls (VoIP → GSM)

Flags (mutually exclusive - only one ON at a time):

  • Normal: Send Caller ID as-is (show A-number)
  • Restricted: Hide/block Caller ID (private number)
  • Unknown: Send as "Unknown" caller

⚠️ WARNING: Most GSM operators do not honor these settings. They may ignore the request or override it with their own policy.

Suggestion: Leave Normal enabled (default).

3.11 SIP Specific

Purpose: Control how SIP stack responds when GSM call starts ringing.

Options:

  1. Nothing - No special handling
  2. Change status to ring - Update SIP status only
  3. Start local ring and ready to accept media ← DEFAULT (recommended)
  4. Start media receive/playback - Start audio immediately
  5. Change status to ring and start receive/playback - Combined approach

What happens:

  1. SIP INVITE arrives
  2. VMGate checks limits/availability
  3. ✅ Checks OK → Place GSM call
  4. GSM starts ringing → VMGate notifies SIP stack
  5. SIP response behavior depends on this setting

Recommendation: Option 3 (default) works with 90% of VoIP switches. Do not change unless your VoIP provider requires specific behavior.

3.12 Call Logging

Log Enabled

  • Purpose: Enable detailed logging for debugging
  • ON: VMGate writes logs to Android/data/com.startel.vmgate/files/CallLog.txt
  • OFF: No logging (saves storage, slightly better performance)
  • Recommendation: Enable during initial setup and troubleshooting. Disable in production if not needed.

3.13 Forward Incoming Call

Purpose: Control what happens when VMGate receives incoming GSM calls (GSM → VoIP)

Flag: Forward Call

Flag = ON (Forward to VoIP)

  • Behavior:
    • Auto-answer GSM call
    • Send SIP INVITE to configured IP
    • Caller (A-number): GSM caller's number (unchanged)
    • Called (B-number): SIM1/SIM2 Phone Number (or 999999999999 if empty)
    • Bridge GSM ↔ VoIP audio
  • Use case: Route all incoming GSM calls to your VoIP switch

Flag = OFF (Auto-Answer with Audio)

  • Behavior:
    • Auto-answer GSM call
    • Play random .wav file from: Android/data/com.startel.vmgate/files/AudioMessages/
    • After playback ends → Auto-hangup

Audio file requirements:

  • Format: .wav (WAV files only)
  • Sample Rate: 8000 Hz (8 kHz)
  • Encoding: PCM 16-bit
  • Channels: Mono (single channel)

User must provide audio files. Suggested content:

  • Waiting music
  • "All operators are busy, please call back later"
  • Country-specific appropriate messages

Use case: Don't want to route GSM calls to VoIP, but also don't want to reject them (rejection = suspicious to carrier)

⚠️ IMPORTANT: Save Your Settings

After configuring any settings in Sections 3.1-3.13 above:

  1. Scroll to bottom of Settings screen
  2. Tap "Save" button
  3. Wait for confirmation (toast message)
  4. Return to Main Activity (back button)

If you don't save: All changes will be lost when you exit Settings.

If registration fails after saving: Tap "Register" button on Main Activity to reconnect (works immediately after initial registration succeeds).

4. Daily Operation

4.1 Main Activity Screen

When VMGate is running, keep the Main Activity screen open.

[SCREENSHOT: Main Activity with all status fields labeled]

The Main Activity screen is organized into three main sections:

Top Section: Connection Status & Controls

Connection Status LED

  • Green circle: Registered and connected to SIP server
  • Red/Gray circle: Disconnected or not registered

SIP Server IP:Port

  • Shows SIP server address and port when registered
  • Example: 157.90.34.59:5060
  • Updates automatically when registration status changes

Register / Unregister Buttons

  • Register: Click to connect to SIP server (shown when disconnected)
  • Unregister: Click to disconnect from SIP server (shown when connected)
  • Compact design for space efficiency

Middle Section: Active/Last Call Information (NEW)

Two side-by-side cards display call information:

Outbound Call Card (LEFT)

  • Header:
    • Shows "Active Outbound Call" during an active outgoing call
    • Changes to "Last Outbound Call" after call ends
  • Phone Number: Displays the dialed number
  • Duration Timer:
    • Updates every second during active calls (MM:SS format)
    • Stops automatically when call ends
    • Final duration is saved and displayed for last call
  • SIM Indicator: Shows which SIM (SIM1 or SIM2) handled the call

Inbound Call Card (RIGHT)

  • Header:
    • Shows "Active Inbound Call" during an active incoming call
    • Changes to "Last Inbound Call" after call ends
  • Phone Number: Displays the caller's number
  • Duration Timer:
    • Updates every second during active calls (MM:SS format)
    • Stops automatically when call ends
    • Final duration is saved and displayed for last call
  • SIM Indicator: Shows which SIM (SIM1 or SIM2) received the call

Note: Both cards remain visible at all times. Information persists after calls end, allowing you to review the last call details.

Bottom Section: SIM Cards Status (NEW)

Two side-by-side compact cards, one for each SIM:

SIM 1 Card (LEFT) / SIM 2 Card (RIGHT)

Each card displays:

  1. SIM Status
    • "SIM 1: Online" or "SIM 2: Online" (green) when active
    • "SIM 1: Offline" or "SIM 2: Offline" (gray) when inactive
  2. Countdown Timer
    • Shows remaining seconds until SIM becomes available (IDLE timeout)
    • Format: MM:SS (e.g., 05:23)
    • Placeholder: Shows 00:00 in white when no countdown is active
    • Always visible to prevent card resizing
  3. Call Status
    • Label: "Call Status:" (on first line)
    • Status Value: (on second line)
      • IDLE → No active call, waiting for next call
      • Dialing --> +393123456789 → Outgoing call being placed
      • Ringing → GSM call is ringing (incoming or outgoing)
      • OnCall → Active call in progress
  4. Next Available
    • Label: "Next available:" (on first line)
    • Date/Time: (on second line)
      • Format: DD/MM/YYYY HH:MM:SS
      • Shows when SIM becomes available after IDLE timeout
      • Updates automatically when countdown completes
  5. Daily Attempts
    • Label: "Daily Attempts:" (on first line)
    • Value: current / limit (on second line)
      • Example: 87 / 150
      • Shows current attempts vs. today's random limit
    • Progress Bar:
      • Color-coded: Green (<50%), Yellow (50-79%), Red (≥80%)
      • Height: 22dp for easy visibility
      • Updates in real-time
  6. Daily Minutes
    • Label: "Daily Minutes:" (on first line)
    • Value: MM:SS / MM:SS (on second line)
      • Example: 45:23 / 120:00
      • Shows current minutes vs. today's random limit
    • Progress Bar:
      • Color-coded: Green (<50%), Yellow (50-79%), Red (≥80%)
      • Height: 22dp for easy visibility
      • Updates in real-time
  7. Reset Daily Counters Button
    • Label: "Reset daily counters"
    • Function: Resets daily attempts and daily minutes counters to 0
    • Behavior:
      • Enabled: When no call is active (allows reset)
      • Disabled: During active calls or when placing calls (prevents accidental reset)
    • What it resets:
      • Daily attempts counter → 0
      • Daily minutes counter → 0
    • Important: This resets the actual data, not just the display. Values persist after app restart.
    • Use case: If random daily limits are blocking calls, you can manually reset to allow more calls immediately.

Visual Layout:

  • Both SIM cards are always visible side-by-side
  • Compact design optimizes screen space
  • All information fits without scrolling
  • Color-coded progress bars provide quick visual feedback

4.2 Register / Unregister

Register Button

  • When shown: VMGate is not registered with SIP server
  • Click to: Send SIP REGISTER to server and connect
  • After click: Button changes to "Unregister", status shows "Registered"

Unregister Button

  • When shown: VMGate is registered with SIP server
  • Click to: Disconnect from SIP server
  • After click: Button changes to "Register", status shows "Disconnected"

Automatic Registration:

  • VMGate automatically attempts to register when:
    • App starts (if SIP credentials configured)
    • Settings saved (if credentials correct)
  • Initial Delay: After app start, allow 30-90 seconds for initial registration (see Section 2.7 for details)
  • Exception: After returning from Accessibility settings → may be disconnected
  • Solution: Click "Register" button to reconnect (works immediately after initial registration succeeds)

4.3 Normal Operation Flow

VoIP → GSM (Outgoing Termination):

  1. SIP INVITE arrives at VMGate
  2. VMGate checks:
    • Is a SIM available? (not in IDLE countdown)
    • Are limits OK? (attempts, DLIMIT, MLIMIT, package)
    • Is ring timeout not exceeded?
  3. ✅ All checks pass → Place GSM call
  4. GSM starts ringing → Notify SIP stack (SIP 180 Ringing)
  5. GSM answered → Bridge audio (VoIP ↔ GSM)
  6. Call ends → Record duration, start IDLE countdown
  7. SIM unavailable until countdown finishes

❌ If any check fails: Reject with SIP 503 (Service Unavailable), PDD=0 → VoIP switch can reroute

GSM → VoIP (Incoming Calls):

  • If "Forward Call" = ON:
    • Auto-answer GSM call
    • Send SIP INVITE to switch
    • Bridge audio
  • If "Forward Call" = OFF:
    • Auto-answer GSM call
    • Play random audio file
    • Auto-hangup after playback

4.4 SIM Selection Logic

VMGate uses round-robin + availability logic:

Base rule: Alternate between SIM1 → SIM2 → SIM1 → SIM2...

Availability checks:

  • Is countdown active? → SIM unavailable
  • Is "Next Available Date" not reached? → SIM unavailable
  • Are any limits exceeded? → SIM unavailable

Decision:

  • ✅ Target SIM available → Route to it
  • ❌ Target SIM unavailable, other SIM available → Route to other SIM
  • ❌ BOTH SIMs unavailable → Reject call (SIP 503)

4.5 Best Practices

During operation:

  • Keep Main Activity screen open
  • Monitor countdown timers (ensure SIMs become available)
  • Watch Connection Status LED (ensure green/registered)
  • Check SIM status (ensure "Online")
  • Monitor daily limits progress bars (green/yellow/red indicators)
  • Review active/last call information in call cards

Daily:

  • Review daily attempts and minutes progress bars in SIM cards
  • Check "Next available" date/time for each SIM
  • Verify Connection Status LED = Green (Registered)
  • Use "Reset daily counters" button if limits are blocking calls (only when no calls active)

Weekly:

  • Check package minutes usage (if configured)
  • Review monthly limits (MLIMIT) usage

Monthly:

  • MLIMIT resets automatically on 1st of month
  • Package minutes reset based on configured schedule

4.6 Restarting VMGate

If you need to restart:

Option 1: Soft restart (preferred)

  1. Tap "Unregister" (if registered)
  2. Close app (swipe away from recent apps)
  3. Reopen VMGate
  4. Wait for auto-registration or tap "Register"

Option 2: Hard restart (if accessibility issue)

  1. Force-stop app (Settings → Apps → VMGate → Force Stop)
  2. Reopen VMGate
  3. Re-enable Accessibility if prompted
  4. Wait for auto-registration or tap "Register"

Option 3: Device reboot (if serious issue)

  1. Reboot device
  2. Wait for boot
  3. Open VMGate
  4. Accessibility Service should auto-enable (if systemized). If not, enable manually (see Section 2.1)
  5. Wait for auto-registration or tap "Register"

5. Automatic Features

VMGate includes several automatic features that work in the background to improve reliability and user experience.

5.1 Automatic Accessibility Service Enablement

What it does:

  • VMGate automatically enables Accessibility Service on launch (when properly systemized)
  • No manual intervention required on most phones
  • Works immediately after systemization

When manual activation may be needed:

  • Some Android 13+ devices may still require manual activation
  • If "Allow restricted settings" dialog appears:
    1. Go to Settings → Apps → VMGate
    2. Open the top right menu
    3. Select "Allow restricted settings"
    4. Return to Settings → Accessibility → VMGate and enable
  • If Accessibility Service is disabled, enable manually (Settings → Accessibility → VMGate)

Note: Accessibility Service is critical for VMGate's core functionality (call routing, audio bridging, dialog handling). It must be enabled for VMGate to work.

5.2 Automatic Dialog Handling

What it does:

VMGate automatically detects and handles operator dialogs that can block phone functionality:

  1. STK Restart Dialogs:
    • Operator messages requesting telephony subsystem restart
    • Automatically clicks "Restart" when phone is idle
    • Automatically dismisses during active calls (protects voice operations)
  2. Service Provider Update Dialogs:
    • Operator messages about service updates
    • Automatically detected and handled after reboot
    • Checks all windows/overlays for maximum reliability
  3. Flash SMS Dialogs:
    • Promotional SMS messages displayed as UI dialogs
    • Automatically dismissed (clicks "Cancel" or "Back")
    • Prevents accidental subscription to operator offers
  4. Operator Menu Dialogs:
    • Operator-specific menus (e.g., MTN Menu, CallerTune offers)
    • Automatically dismissed (clicks most dismissive option)
    • Prevents UI blocking

How it works:

  • Uses Accessibility Service to detect dialogs
  • Scans all accessible windows/overlays
  • Automatically clicks appropriate buttons
  • Logs all actions for debugging

User action required: None. All dialogs are handled automatically.

Note: If a dialog persists, it may be a new type not yet recognized. Contact support with a screenshot.

5.3 Automatic Modem Health Monitoring (A15/A16 Only)

What it does:

  • Automatically detects GSM signal loss on Samsung A15/A16 devices
  • Android 13/14: Performs multi-stage recovery (airplane mode toggle → RIL restart) - Recovery time: ~10 minutes
  • Android 15: Performs direct reboot after 90 seconds (due to different policies enforced by Android 15)
  • Prevents phone from getting stuck in signal loss state

How to enable:

  • Settings → Modem Health Monitor (A15/A16) → Toggle ON
  • Requires Magisk superuser permission

See Section 3.8 for detailed configuration.

6. Troubleshooting

6.1 Cannot Register (Connection Status: Disconnected)

Symptoms:

  • Button shows "Register"
  • Clicking it doesn't connect
  • Status remains "Disconnected"

Causes & Solutions:

  1. Initial app startup delay (NORMAL - NOT A PROBLEM)
    • Symptom: App just started, register button doesn't work, status shows disconnected
    • Cause: VMGate is still initializing (Accessibility Service, SIP client, network checks)
    • Solution: Wait 30-90 seconds after app start. VMGate will register automatically once initialization completes.
    • Do NOT: Repeatedly tap "Register" during this period - it won't help
    • After initial registration succeeds: Manual register/unregister works immediately
    • See Section 2.7 for detailed explanation of initial registration behavior
  2. Wrong SIP credentials
    • Check: IP address in Settings
    • Verify with your VoIP provider
    • Note: Only check this if registration fails after waiting 90 seconds from app start
  3. Network connectivity
    • Check: Device has internet (WiFi or mobile data)
    • Test: Open browser, load a website
    • Note: Only check this if registration fails after waiting 90 seconds from app start
  4. Firewall/NAT issues
    • Check: Port 5060 not blocked
    • Test: Use different network (switch WiFi/mobile data)
  5. SIP server down
    • Check: Contact your VoIP provider
    • Test: Try from another device/softphone

6.2 Calls Not Routing to VMGate

Symptoms:

  • VMGate shows "Registered"
  • VoIP switch shows "subscriber not available" or reroutes calls

Causes & Solutions:

  1. Both SIMs in countdown
    • Check: Main Activity countdown timers
    • Solution: Wait for countdown to finish, or adjust MinIDLE/MaxIDLE to shorter values
  2. Limits exceeded
    • Check: Used Daily Minutes, Used Monthly Minutes in Settings
    • Check: MLIMIT value
    • Solution: Wait for daily/monthly reset, or increase limits
  3. SIMs offline
    • Check: SIM status in Main Activity ("SIM 1: Offline")
    • Solution: Check SIM cards physically inserted, reboot device
  4. Accessibility service disabled
    • Check: Settings → Accessibility → VMGate (must be ON)
    • Solution:
      • If systemized: Close and reopen VMGate (should auto-enable)
      • If still disabled: Enable manually (Settings → Accessibility → VMGate → Toggle ON)
      • If "Allow restricted settings" dialog appears:
        1. Go to Settings → Apps → VMGate
        2. Open the top right menu
        3. Select "Allow restricted settings"
        4. Return to Settings → Accessibility → VMGate and enable

6.3 Audio Issues During Calls

Symptoms:

  • Call connects (status shows "OnCall")
  • No audio, partial audio, or one-way audio

Note: Audio routing problems can have multiple causes and require detailed diagnosis based on specific symptoms.

If you experience audio issues:

  • Contact Startel support: info@startelinternational.com
  • Include:
    • Device model
    • Exact symptom (no audio, one-way, intermittent, etc.)
    • Call logs (if Log Enabled in settings)
    • SIP Specific setting currently configured

Quick checks before contacting support:

  • Verify: Settings → SIP Specific = Option 3 (default)
  • Verify: All permissions granted to VMGate
  • Verify: Device volume not muted
  • Test: Make test calls to isolate the issue

Operator Blocking UDP/RTP Traffic:

Some mobile operators intentionally block UDP ports and/or RTP (Real-time Transport Protocol) traffic, which can cause audio issues in VMGate. This is common in certain regions and carrier networks.

Solution: Use a VPN

If you suspect operator blocking, using a VPN can route SIP and RTP traffic through an encrypted tunnel, bypassing the operator's restrictions.

Tested VPN Solutions:

VMGate has been successfully tested with the following VPN applications:

  1. OpenVPN
  2. WireGuard

Setup Instructions:

  1. Install your chosen VPN app from Google Play Store
  2. Configure VPN connection (requires VPN server/credentials)
  3. Connect to VPN before using VMGate
  4. Test VMGate calls with VPN active
  5. If audio works with VPN → Operator was blocking traffic

Note: VPN usage may add slight latency. Choose a VPN server geographically close to your location for best performance.

6.4 Flash Messages Blocking Calls (SIM stops working after calls)

Symptoms:

  • First few calls work fine
  • After some calls, SIM stops accepting new calls
  • Must reboot to fix

Cause: Carrier sending post-call cost/duration SMS

Solution:

  1. Settings → SIM1/SIM2 Configuration
  2. Enable "Block Flash Messages" for affected SIM
  3. Save settings
  4. Reboot device (to apply)

6.5 A15/A16: Signal Loss After 24 Hours

Symptoms:

  • Device: Samsung A15 or A16
  • After ~24 hours of operation: Complete GSM signal loss
  • Both SIMs show "Offline"

Cause: Known modem firmware bug on A15/A16

Solution:

Option 1: Enable Modem Health Monitor (permanent fix)

  1. Settings → Modem Health Monitor (A15/A16)
  2. Toggle ON
  3. Save settings
  4. Ensure Magisk superuser permission granted (see Section 3.8)
  5. Monitor will automatically detect and recover signal loss:
    • Android 13/14: ~10 minutes (multi-stage recovery)
    • Android 15: 90 seconds (direct reboot)

Option 2: Manual recovery (temporary)

  • Reboot device

6.6 License Activation Fails

Symptoms:

  • Enter Customer ID, tap "Activate License"
  • Error: "Sync failed: [message]"

Causes & Solutions:

  1. Wrong Customer ID
    • Check: Verify Customer ID with Startel
    • Solution: Enter correct Customer ID
  2. No available licenses
  3. Network connectivity
    • Check: Device has internet
    • Solution: Connect to WiFi or mobile data, retry
  4. Device already activated
    • Check: Device fingerprint already used a license
    • Solution: Contact Startel support to revoke/reassign license

6.7 VMGate Not System-Privileged (Fresh Install)

Symptoms:

  • App works partially
  • Some features don't work (airplane mode toggle, call interception)

Cause: Systemization step skipped during installation

Solution:

  • Follow Section 1.1 (Fresh Installation), steps 4-14
  • Systemize the app using Termux/Magisk Systemizer
  • Reboot device

6.9 Settings Not Saved

Symptoms:

  • Change settings, tap "Save"
  • Reopen Settings → changes reverted

Causes & Solutions:

  1. Validation errors
    • Check: Toast messages when tapping "Save" (error notifications)
    • Common errors:
      • MinDLIMIT must be lower than MaxDLIMIT
      • MinIDLE must be lower than MaxIDLE
      • Add Plus and (Add Zero OR Remove CC) cannot be ON together
    • Solution: Fix validation errors, save again
  2. App crashed during save
    • Solution: Force-stop app, reopen, reconfigure, save again

7. Support

7.1 Contact Information

Email: info@startelinternational.com

For support requests, include:

  • Device model (A15/A16/A53/A54)
  • VMGate version (shown in Main Activity)
  • Customer ID
  • Detailed description of issue
  • Screenshots (if applicable)
  • Logs (if Log Enabled in settings)

Log location: Android/data/com.startel.vmgate/files/CallLog.txt

7.2 Customer Portal

License Management: https://customer-vmgate.startelinternational.com/login

Features:

  • View available licenses
  • Check active devices
  • Request license revocation/reassignment

7.3 Documentation

Rooting Guide: VMGate Rooting Guide (also available on website)

Installation Guide: VMGate Installation Guide (also available on website)

Legal Documents:

  • VMGate Master Agreement
  • VMGate Software License Agreement
  • VMGate EULA
  • VMGate Terms of Use
  • VMGate Third-Party Notices

All documents: Provided by Startel during license purchase

Appendix A: Quick Reference

Installation Commands (Fresh Install)

su
setenforce 0
systemize
1
[VMGate number]
2
0
# Reboot device

Essential Settings (Minimum Required)

License:

  • Customer ID

SIP:

  • IP
  • User
  • Password

Call Configuration:

  • Country Code
  • Number manipulation (Add Plus recommended)

SIM Configuration (each SIM):

  • MIN/MAX Daily Attempts (e.g., 100-300)
  • MIN/MAX DLIMIT (e.g., 100-300)
  • MLIMIT (e.g., 5000)

Other:

  • MinIDLE / MaxIDLE (e.g., 120-600)
  • Ring Timeout (e.g., 10)

Common Billing Increments

  • 1/1 - Per-second billing (most common)
  • 30/1 - First 30 sec, then per second
  • 60/1 - First 60 sec, then per second (most common)
  • 60/60 - Per-minute billing

Typical IDLE Values by Use Case

Low volume (preserve SIM):

  • MinIDLE: 300 (5 min)
  • MaxIDLE: 900 (15 min)

Medium volume (balanced):

  • MinIDLE: 120 (2 min)
  • MaxIDLE: 600 (10 min)

High volume (maximize throughput):

  • MinIDLE: 30 (0.5 min)
  • MaxIDLE: 180 (3 min)

Audio File Specs (Forward Call = OFF)

  • Format: WAV
  • Sample Rate: 8000 Hz
  • Encoding: PCM 16-bit
  • Channels: Mono
  • Location: Android/data/com.startel.vmgate/files/AudioMessages/

Document History

Version 1.1 - December 2025

  • Updated for VMGate v1.5.1.68A
  • Added RTP Port Configuration section (Section 3.3.1)
  • Updated Main Activity Screen section (Section 4.1) with new UI layout
  • Added daily limits display with progress bars
  • Added reset daily counters feature documentation
  • Added active/last call information cards documentation
  • Updated SIM card status display documentation
  • Added initial registration delay documentation

Version 1.0 - November 17, 2025

  • Initial release for VMGate v1.5.1
  • Covers all features through Phase 3B (Flash Message Blocker) and Phase 3A (Modem Health Monitor)

End of Manual

Startel International LLC
Komitas Ave 46/33
Yerevan, Armenia
Email: info@startelinternational.com
Phone: +374 (0)94-435-643

© 2025 Startel International LLC. All rights reserved.