USB Relay Manager

A desktop application for USB reverse tethering on Android and Windows Mobile/CE devices. Enables network connectivity for devices connected via USB by routing traffic through the host computer's internet connection.

Built on gnirehtet by Genymobile (Apache 2.0).

Overview

USB reverse tethering allows a mobile device to use a computer's internet connection through a USB cable. Supports two device modes:

Android Mode — For Honeywell CN80G devices using ADB + gnirehtet VPN relay:

┌─────────────────┐         USB          ┌─────────────────┐
│   CN80G Device  │◄────────────────────►│    Computer     │
│                 │                       │                 │
│  VPN Service    │      ADB Tunnel      │  Relay Server   │
│  (USB Relay)    │◄────────────────────►│  (USB Relay)    │
│                 │                       │                 │
└─────────────────┘                       └────────┬────────┘
                                                   │
                                                   ▼
                                              Internet

Windows Mobile Mode — For Windows Mobile/CE scanners (Honeywell CK65, Zebra MC3300, etc.) using RNDIS + WinNAT (Windows only):

┌─────────────────┐    USB RNDIS (local link)    ┌─────────────────┐
│  WinMobile/CE   │◄───────────────────────────►│  Host PC        │
│  Scanner        │                              │                 │
│                 │   DHCP IP: 192.168.137.2     │  192.168.137.1  │
│                 │   Gateway: 192.168.137.1     │  (NAT gateway)  │
│                 │   DNS:     auto-detected     │  DHCP server    │
└─────────────────┘                              └────────┬────────┘
                                                          │
                                                     NAT translates
                                                          │
                                                          ▼
                                                   Internet / LAN

Supported Platforms

Platform	Output	Status
Windows	`USBRelay.exe` (~25 MB)	Available
macOS	`USBRelay.app` (.zip ~30 MB)	Available

Quick Start

Android Mode (Windows / macOS)

Download USBRelay.exe (Windows) or USBRelay.app.zip (macOS)
Run the application — relay starts automatically in Android mode
Connect CN80G device via USB dock
Approve USB debugging on device when prompted
Approve VPN permission on device (first time only)
Device is now online

macOS note: Right-click and select "Open" (first time, to bypass Gatekeeper). You may need to allow the app in System Settings > Privacy & Security.

Windows Mobile Mode (Windows only)

One-time admin setup (run once by an administrator):

powershell -ExecutionPolicy Bypass -File setup_admin.ps1

Or follow the step-by-step instructions in ADMIN_SETUP_GUIDE.md.

Daily use (no admin required):

Run USBRelay.exe
Select the "Windows Mobile" radio button in the GUI
Click START
Connect the Windows Mobile/CE device via USB
The device receives its IP configuration automatically via DHCP
Device is now online

Note: If your device doesn't support DHCP on the RNDIS adapter, you can configure a static IP as a fallback — see ADMIN_SETUP_GUIDE.md Step 5 for details.

Features

Dual mode: Android (ADB/gnirehtet) and Windows Mobile (RNDIS/WinNAT)
Single-file portable application (no installation required)
Start/Stop buttons with visual status indicator
Auto-start relay on launch (Android mode)
Automatic device detection and tunnel setup
Automatic reconnection when device is unplugged/replugged
Pre-configured WinNAT with zero-admin runtime (Windows Mobile mode)
Built-in DHCP server for automatic device IP configuration (Windows Mobile mode)
Automatic DNS server detection from host system
Scrolling log panel with timestamps and log export
Cross-platform (Windows and macOS; Windows Mobile mode is Windows-only)

Project Structure

TETHERING_TOOL/
├── src/                  # Python source code
│   ├── main.py           # Entry point - resource extraction and app launch
│   ├── gui.py            # Tkinter GUI (Android + Windows Mobile modes)
│   ├── build_config.py   # Build-time config (ENABLED_MODES, generated by build.py)
│   ├── relay_manager.py  # Gnirehtet relay subprocess manager
│   ├── device_monitor.py # Base class for device monitors (shared logic)
│   ├── adb_monitor.py    # ADB device detection and tunnel setup
│   ├── wmdc_monitor.py   # Windows Mobile RNDIS detection + NAT verification
│   └── dhcp_server.py    # Lightweight DHCP server for device auto-configuration
├── tests/                # Test scripts
│   ├── simulate_wmdc_device.py  # DHCP loopback, integration & simulate tests
│   ├── dhcp_client.py           # DHCP client simulator for testing
│   └── virtual_adapter.py      # Virtual loopback adapter for simulate mode
├── resources/            # Bundled binaries and assets
│   ├── adb.exe           # Android Debug Bridge (Windows)
│   ├── AdbWinApi.dll     # ADB Windows API DLL
│   ├── AdbWinUsbApi.dll  # ADB Windows USB API DLL
│   ├── gnirehtet.apk     # Gnirehtet APK for device-side VPN
│   ├── app_icon.png      # Application icon (512x512)
│   ├── scan_logo.png     # SCAN brand logo
│   └── scan_icon.ico     # Windows icon
├── setup_admin.ps1       # One-time admin setup for Windows Mobile mode
├── ADMIN_SETUP_GUIDE.md  # Step-by-step admin setup instructions
├── build.py              # PyInstaller build script (supports --mode flag)
├── USBRelay.spec         # PyInstaller spec (Windows, reference only)
├── USBRelay.macos.spec   # PyInstaller spec (macOS, reference only)
├── requirements.txt      # Python dependencies
├── LICENSE               # GPL v3
└── README.md

Building from Source

Prerequisites

Python 3.8+
PyInstaller (pip install pyinstaller)

Windows

# Install build dependencies
pip install -r requirements.txt

# Build the executable (both modes — default)
python build.py --windows

# Android-only build (smaller binary, no WMDC code)
python build.py --windows --mode android

# Windows Mobile-only build (smallest binary, no ADB/gnirehtet)
python build.py --windows --mode winmobile

Required resources in resources/ (for --mode both / --mode android):

gnirehtet.exe - Relay server binary (pre-built, or built from source as fallback)
adb.exe - Android Debug Bridge (auto-downloaded if missing)
AdbWinApi.dll - ADB Windows DLL (auto-downloaded if missing)
AdbWinUsbApi.dll - ADB USB DLL (auto-downloaded if missing)
gnirehtet.apk - Gnirehtet APK
scan_logo.png - SCAN brand logo
scan_icon.ico - Windows icon

For --mode winmobile, only scan_logo.png and scan_icon.ico are required.

Output: dist/USBRelay.exe

macOS

# Install build dependencies
pip install -r requirements.txt

# Build the .app bundle (Android mode — default on macOS)
python build.py --macos

# Explicitly Android-only
python build.py --macos --mode android

Note: --mode winmobile is not available on macOS (Windows Mobile tethering requires Windows).

Required resources in resources/:

gnirehtet - Relay server binary (pre-built, or built from source as fallback)
adb - Android Debug Bridge (no extension, from Android SDK Platform Tools)
gnirehtet.apk - Gnirehtet APK
scan_logo.png - SCAN brand logo

Obtaining macOS binaries:

adb: Download Android SDK Platform Tools for macOS
gnirehtet: Pre-built binary is included. If missing, install Rust (rustup.rs) and the build will compile it from vendored source automatically.

Output: dist/USBRelay.app and dist/USBRelay.app.zip

Build Modes

The --mode flag controls which device modes are included in the build:

Mode	Includes	Use case
`both` (default)	Android + Windows Mobile	Full-featured build
`android`	Android only	Smaller binary, no WMDC dependencies
`winmobile`	Windows Mobile only	Smallest binary, Windows-only, no ADB/gnirehtet

Single-mode builds produce a cleaner UI — the mode radio buttons are hidden and the enabled mode is auto-selected.

Troubleshooting

Device not detected after docking

Check USB cable/dock is properly connected
Enable USB debugging on device (Settings > Developer Options > USB Debugging)
Run adb devices to verify connection
If device shows "unauthorized", check device screen for authorization prompt
Try a different USB port

macOS: "USBRelay.app is damaged" or cannot be opened

macOS Gatekeeper may block unsigned applications:

Right-click the app and select "Open"
Click "Open" in the dialog that appears
Or: System Settings > Privacy & Security > "Open Anyway"

VPN permission denied

The first time USB tethering is enabled, Android will prompt for VPN permission. This must be approved for tethering to work.

Relay disconnected notification on device

Ensure USB Relay Manager is running on computer
Check ADB tunnel: adb reverse --list
Stop and restart the relay using the GUI buttons

Connected but device has no internet (Android)

Verify the computer itself has internet access
Check if a firewall is blocking port 31416
DNS issues: the relay auto-detects DNS from the host. Falls back to Google DNS (8.8.8.8) if detection fails

Windows Mobile: RNDIS adapter not detected

Check USB cable/dock is properly connected
Verify the device driver is installed (should appear as "Remote NDIS" in Device Manager)
Try a different USB port

Windows Mobile: Pre-configuration check failed

Ensure an administrator has run setup_admin.ps1 (see ADMIN_SETUP_GUIDE.md)
Run Get-NetNat -Name USBRelayNAT in PowerShell to verify the NAT rule exists
Run Get-ScheduledTask -TaskName USBRelay-RNDIS-IPConfig to verify the scheduled task exists
Docker Desktop or WSL2 may conflict with WinNAT — see ADMIN_SETUP_GUIDE.md for details

Windows Mobile: Device connected but no internet

Check the USB Relay Manager logs — the device should receive its IP automatically via DHCP
Verify PC has internet access
Try ping 192.168.137.1 from the device to confirm the USB link is up
Check if the scheduled task assigned the gateway IP: Get-NetIPAddress -InterfaceAlias '*RNDIS*'
If DHCP isn't working, configure a static IP on the device as a fallback (see ADMIN_SETUP_GUIDE.md Step 5)

Technical Details

Android Mode

Relay Port: 31416 (TCP)
VPN Address: 172.16.0.2/32
DNS: Auto-detected from host system (falls back to 8.8.8.8)
Default Route: 0.0.0.0/0 (all traffic)
ADB Reverse: localabstract:gnirehtet -> TCP 31416

Windows Mobile Mode

NAT Method: WinNAT (pre-configured by setup_admin.ps1)
Subnet: 192.168.137.0/24
PC Gateway IP: 192.168.137.1
Device IP: 192.168.137.2 (assigned automatically via built-in DHCP server)
DNS: Auto-detected from host system (falls back to 8.8.8.8)
Admin Setup: One-time via setup_admin.ps1 or ADMIN_SETUP_GUIDE.md
Runtime: No admin privileges needed
Platform: Windows only

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

USB Relay Manager uses the following third-party components:

gnirehtet by Genymobile — reverse tethering relay for Android. Licensed under Apache 2.0.
Android Debug Bridge (adb) from the Android SDK Platform Tools by Google — USB communication with Android devices. Licensed under Apache 2.0.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

USB Relay Manager

Overview

Supported Platforms

Quick Start

Android Mode (Windows / macOS)

Windows Mobile Mode (Windows only)

Features

Project Structure

Building from Source

Prerequisites

Windows

macOS

Build Modes

Troubleshooting

Device not detected after docking

macOS: "USBRelay.app is damaged" or cannot be opened

VPN permission denied

Relay disconnected notification on device

Connected but device has no internet (Android)

Windows Mobile: RNDIS adapter not detected

Windows Mobile: Pre-configuration check failed

Windows Mobile: Device connected but no internet

Technical Details

Android Mode

Windows Mobile Mode

License

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
resources		resources
src		src
tests		tests
vendor/gnirehtet-relay-rust		vendor/gnirehtet-relay-rust
.gitattributes		.gitattributes
.gitignore		.gitignore
ADMIN_SETUP_GUIDE.md		ADMIN_SETUP_GUIDE.md
LICENSE		LICENSE
README.md		README.md
USBRelay.macos.spec		USBRelay.macos.spec
USBRelay.spec		USBRelay.spec
build.py		build.py
requirements.txt		requirements.txt
setup_admin.ps1		setup_admin.ps1

Folders and files

Latest commit

History

Repository files navigation

USB Relay Manager

Overview

Supported Platforms

Quick Start

Android Mode (Windows / macOS)

Windows Mobile Mode (Windows only)

Features

Project Structure

Building from Source

Prerequisites

Windows

macOS

Build Modes

Troubleshooting

Device not detected after docking

macOS: "USBRelay.app is damaged" or cannot be opened

VPN permission denied

Relay disconnected notification on device

Connected but device has no internet (Android)

Windows Mobile: RNDIS adapter not detected

Windows Mobile: Pre-configuration check failed

Windows Mobile: Device connected but no internet

Technical Details

Android Mode

Windows Mobile Mode

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages