Control App

Use the Control App desktop application to control your device via serial connection

On this page

The Control App is a Python desktop GUI built with PyQt6 that controls your GhostESP device over a USB serial connection. It offers Wi-Fi/BLE scanning, packet capture, custom commands, firmware flashing, and more through organized tabs with real-time feedback - a friendlier alternative to the command line.

Prerequisites

  • Python 3.8 or newer: Required to run the application
  • USB cable: To connect your GhostESP device to your computer
  • GhostESP firmware: Your device must be running compatible GhostESP firmware
  • System dependencies (Linux only, if needed): Some Linux distributions may require libxcb-cursor0 for PyQt6 to function properly. Install it if you encounter cursor-related errors:
    sudo apt update
sudo apt install libxcb-cursor0
  • ESP-IDF (optional, for custom builds): Required only if you plan to build custom firmware. See ESP-IDF installation instructions

Installation

The Control App is located in the scripts/control app/ directory of the GhostESP repository. To run it:

  1. Navigate to the control app directory:

    cd scripts/control\ app/

  2. Run the application:

    python main.py

The application will automatically:

  • Create a Python virtual environment (ghost-control-venv)
  • Install all required dependencies from requirements.txt
  • Launch the GUI

Note: On first run, the setup process may take a few minutes as dependencies are downloaded and installed.

Connecting to Your Device

  1. Connect your GhostESP device via USB to your computer
  2. Select the serial port from the dropdown in the Serial Connection section
  3. Click Refresh Ports if your device doesn’t appear in the list
  4. Click Connect to establish the serial connection

When connected, the UI overlay disappears and controls are enabled, and the log area shows connection status. When disconnected, an overlay reads “No serial connection. Connect to enable controls.” Enable Auto-reconnect in settings to reconnect automatically if the connection drops.

Main Features

The command panel is organized into five top-level tabs: WiFi Operations, Network Operations, BLE Operations, Evil Portal, and Settings.

Wi-Fi Operations

The Wi-Fi Operations tab groups its controls into Scanning, Attacks, Beacons, and Capture sub-tabs:

  • Scan Access Points: Discover nearby Wi-Fi networks
  • List APs/Stations: View currently stored access points and stations
  • Deauth Attacks: Start or stop deauthentication attacks on selected networks
  • Beacon Spam: Send beacon frames with options for:
    • Random SSIDs
    • Rickroll SSIDs
    • AP list (uses stored access points)

Network Operations

The Network Operations tab provides:

  • WiFi Connection: Join a network by SSID and password
  • Network Tools: Cast a random YouTube video or print to a network printer
  • Port Scanner: Scan a target IP (or local) with common-port, all-port, or range arguments

BLE Operations

The BLE tab handles Bluetooth Low Energy scanning:

  • Find Flippers: Scan specifically for Flipper Zero devices
  • AirTag Scanner: Detect Apple AirTags
  • Raw BLE Scan: Perform a general BLE device scan
  • Stop Scan: Cancel any active BLE scan

Packet Capture

The Capture sub-tab under Wi-Fi Operations enables Wi-Fi packet monitoring. The Capture Type combo offers:

  • Probes: Monitor Wi-Fi probe requests
  • Beacons: Log beacon frames
  • Deauth: Track deauthentication packets
  • Raw: Capture raw Wi-Fi frames
  • WPS: Log WPS (Wi-Fi Protected Setup) packets
  • Pwnagotchi: Capture for Pwnagotchi-style handshake collection

Portal Management

The Evil Portal tab handles evil portal operations:

  • Upload Custom HTML: Send a local HTML file to use as a custom portal
  • Progress Indicator: Visual feedback during file upload
  • Portal Selection: Choose from built-in portals or your uploaded HTML

Custom Commands

The Custom Command field allows you to send any command directly to the device:

  1. Type your command in the text field
  2. Press Enter or click Send
  3. View the response in the log and display areas

This is useful for commands not covered by the GUI tabs or for advanced operations.

Firmware Flashing

The Control App includes three methods for flashing firmware to your device.

Flash Firmware Panel

Flash firmware using individual binary files:

  1. Select chip type: Choose the correct ESP32 variant (ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C5, ESP32-C6)
  2. Select files: Browse and select:
    • bootloader.bin
    • partition-table.bin
    • firmware.bin
  3. Select serial port: Choose the port your device is connected to
  4. Click Flash Board: The flashing process will begin
  5. Exit Flash Mode: Return to the main UI when done

Release Bundle Flashing

Download and flash official release bundles directly from GitHub:

  1. Select release version: Choose from available releases or select Custom local .zip for your own bundle
  2. Select asset: If multiple assets are available, choose the appropriate one for your hardware
  3. Download or browse: Either download the asset automatically or browse for a local .zip file
  4. Select chip type and port: Choose your device’s chip type and serial port
  5. Click Flash Bundle: The application will extract and flash the bundle
  6. Exit Flash Mode: Return to the main UI when complete

Custom Build Panel

Build and flash your own firmware using ESP-IDF:

  1. SDKConfig management (optional):

    • Copy an SDKConfig template using the Copy SDKConfig button
    • Edit your existing SDKConfig with the Edit SDKConfig button
    • Delete SDKConfig templates as needed

  2. Set target chip: Select your device’s chip type and click Set Target

  3. Build firmware:

    • Click Run Build to compile your firmware (requires ESP-IDF in PATH)
    • Use Run idf.py fullclean to clean the build folder if needed

  4. Flash custom build: Click Flash Custom Build to flash the compiled firmware

  5. Status indicators: Visual indicators show the presence of:

    • ESP-IDF installation
    • SDKConfig file
    • Build folder
    • Bootloader
    • Partition table
    • Firmware binary

  6. Exit Flash Mode: Return to the main UI when done

Note: Custom builds are unsupported. Use at your own risk.

Panel Instructions: The Flasher Output window displays step-by-step instructions for each flashing panel when you switch between them.

Settings

The Settings tab allows you to configure application behavior:

  • Auto-reconnect: Automatically attempt to reconnect if the serial connection is lost
  • Theme: Switch between light and dark themes
  • Baud rate: Adjust serial communication speed (default: 115200)
  • Other preferences: Various application-specific settings

Logging and Display

The application provides two main output areas:

Log Area

Shows real-time command feedback with timestamps:

  • Connection status messages
  • Command execution results
  • Error messages and warnings
  • Serial communication details

Display Area

Displays structured output for:

  • Wi-Fi scan results
  • BLE scan results
  • Device status information
  • Formatted command responses

Both areas support ANSI color codes for better readability of terminal output.

UI Features

Drag the splitter between the command and display areas to resize them.

  • Connection overlay: When disconnected, a semi-transparent overlay covers the main UI with a message
  • Status indicators: Color-coded indicators show connection status and flashing panel status
  • Progress indicators: Visual feedback for file uploads and long-running operations
  • Keyboard: Press Enter to send a custom command; standard text editing shortcuts work in all text fields

Troubleshooting

Cannot Connect to ESP32

  • Check the serial port: Ensure the correct port is selected
  • Verify firmware: Make sure your device is running compatible GhostESP firmware
  • Check power: Ensure the device is properly powered
  • Try different USB cable: Some cables are charge-only and don’t support data
  • Check permissions (Linux): You may need to add your user to the dialout group:
    sudo usermod -a -G dialout $USER
    Then log out and back in.

Unexpected Disconnections

  • Check USB cable: Try a different cable or port
  • Lower baud rate: Try reducing the baud rate in settings
  • Enable auto-reconnect: This will automatically attempt to reconnect
  • Check for interference: Move away from sources of electrical interference

Command Errors

  • Verify firmware version: Ensure your device firmware supports the commands you’re trying to use
  • Check command syntax: Refer to the CLI Reference for correct syntax
  • View error messages: Check the log area for detailed error information

UI Overlay Covers Controls

  • This is normal: The overlay only appears when disconnected
  • Serial controls remain accessible: The connection controls are always available, even when the overlay is shown
  • Connect to remove overlay: Once connected, the overlay automatically disappears

Portal Upload Hangs

  • Verify connection: Ensure you’re connected to the device
  • Check device status: Make sure the ESP32 is ready and not performing other operations
  • Try again: Cancel and retry the upload
  • Check file size: Very large HTML files may take longer to upload

ESP-IDF Not Found (Custom Build)

  • Install ESP-IDF: Follow the official installation guide
  • Add to PATH: Ensure idf.py is accessible from your system PATH
  • Verify installation: Run idf.py --version in a terminal to confirm it’s working

Missing SDKConfig or Build Files

  • Use status indicators: The Custom Build panel shows which files are missing
  • Copy SDKConfig template: Use the Copy SDKConfig button to create a template
  • Run Set Target: Ensure you’ve set the target chip type
  • Check build folder: Verify that the build completed successfully

Application Won’t Start

  • Check Python version: Ensure you have Python 3.8 or newer (python --version)
  • Install system dependencies (Linux): Install libxcb-cursor0 if missing
  • Check virtual environment: The app should create it automatically, but you can delete ghost-control-venv and restart to recreate it
  • View error messages: Check the terminal output for specific error messages

Notes

  • Responsible use: This is a development and diagnostics tool - always comply with local regulations when using network diagnostic tools.
  • Cross-platform: Works on Windows, macOS, and Linux.