🚀 Quick Start

Connect Your Device

Mode	Setup
USB	Plug in your phone · Enable USB Debugging
Wi-Fi	Same network · Enable Wireless Debugging

Launch Options

🪟 Windows

Auto-detect (Recommended)

android_dex_win.exe

Force USB Connection

android_dex_win.exe --usb

Connect via IP Address

android_dex_win.exe 192.168.1.100

Connect via IP & Port

android_dex_win.exe 192.168.1.100:5555

🐧 Linux

1. Prepare: Extract android_dex_linux.tar.gz and open terminal in the folder.
2. Setup: Make the script executable:

   chmod +x run_android_dex.sh

3. Launch:

   ./run_android_dex.sh

Note: The run_android_dex.sh script automatically checks if your Linux environment is compatible (drivers, graphics, and dependencies) and ready to launch the session.

---

📖 Deep-Dive Documentation

Check out these detailed guides to understand exactly how Android DEX works under the hood:

1. Architectural Design — Three-layer system design, responsibilities, and data flow.
2. Boot & Initialization — Step-by-step connection flow with progress stages.
3. Reconnection System — Smart auto-healing, recovery phases, and UI overlay.
4. Real-Time Data Model — State store, JSON telemetry protocols, and message handling.
5. Error Handling — User-facing messaging pipelines and full fallback reference.
6. System Modules — Internal component roles, public APIs, and singletons.
7. Device Manager — ADB device selection, UI dialogs, and IP connections.

---

🛠️ How It Works — The Handshake Protocol

The system uses a three-layer architecture with a cryptographic-style handshake before the desktop UI unlocks. Every component must confirm readiness before the session begins.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#0078D4', 'primaryTextColor': '#fff', 'primaryBorderColor': '#0078D4', 'lineColor': '#888', 'secondaryColor': '#0061af', 'tertiaryColor': '#222', 'noteBkgColor': '#333', 'noteTextColor': '#fff', 'noteBorderColor': '#555' }}}%%
sequenceDiagram
    participant PC as Windows Side (Flutter/ADB)
    participant JAR as Android Logic Engine (Java JAR)
    participant APK as Android App Hub (Kotlin APK)

    Note over PC: 1. ADB Initialization (startAdbBlocking)
    PC->>PC: 2. Local Server Setup (JarServer & ApkServer .start)
    
    Note over PC,JAR: Phase 1: Engine Deployment (Bridge)
    PC->>JAR: Push JAR to Device (via ADB Pipe)
    PC->>JAR: Launch JAR Runtime (adb.startJarRuntime)
    JAR-->>PC: Handshake Response: "jar.hello" (Logic Engine Ready)

    Note over PC,APK: Phase 2: Feature Manager Startup (Hub)
    PC->>APK: Check Install & Install if Missing
    PC->>APK: Trigger Service startup (ServerStartService)
    APK-->>PC: WebSocket Handshake: "apk.hello" (App Hub Ready)

    PC->>APK: 3. Start Extended Notification & Media Services
    Note over PC,APK: System Synchronized: Desktop UI Unlocked

---

📱 App Preview

---

🏗️ Three-Layer Architecture

Android DEX distributes responsibilities across three specialized layers:

Layer	Role	Technology
Windows Side	Orchestration, UI, Streaming	Flutter · ADB · Native C++ · scrcpy
Logic Engine	Low-level device commands	Java · ADB Shell
Feature Hub	Telemetry, Notifications, Media	Kotlin · Android SDK

→ Deep-dive: Architecture »

---

📋 Getting Started

Prerequisites

• OS: Windows 10+ or Modern Linux (Ubuntu, Fedora, etc.)
• Device: Android device running Android 8.0+
• Drivers: ADB is bundled — no separate installation needed

Step-by-Step

1. Enable Developer Options on your phone

   • Settings → About Phone → tap Build Number 7 times

2. Enable USB Debugging

   • Settings → Developer Options → USB Debugging → ON

3. Plug in your phone (for USB) or enable Wireless Debugging (for Wi-Fi)

4. Launch Android DEX — watch the boot progress bars fill to 100%

5. The desktop unlocks — your Android is now a full Windows desktop experience

If connection fails, a "Select Device" button appears in the boot screen — click it to open the ADB Manager and pick your device without restarting.

---