Skip to content

Installation

Jump to bottom
Spooks edited this page Nov 9, 2024 · 3 revisions

Installation Guide

This guide provides detailed instructions for installing GhostESP firmware on your ESP32 device.

Prerequisites

Before starting, ensure you have:

  • A compatible ESP32 board (see Supported Hardware)
  • A modern web browser (Google Chrome recommended, as Firefox doesn’t support WebSerial)
  • Appropriate USB cable (Micro USB or USB-C, ensure it's a data cable, not a charge-only cable)
  • File Extraction Tool: Install 7-Zip or a similar program for extracting firmware files.
  • Internet connection for downloading firmware
  • If using a Flipper Zero, ensure it has the latest firmware for compatibility

Note: For best results, disable any VPN or firewall that might block the flashing process, as some network configurations may interfere with the web flasher.

Flashing Methods

Choose your preferred method:

Web Flasher Method

  1. Prepare for Flashing

    • Visit Spooky Tools Web Flasher
    • If the site doesn’t load correctly, clear your browser cache and try again.
    • Use Google Chrome as Firefox does not support WebSerial.
    • Ensure your ESP32 is disconnected from other software or tools to avoid port conflicts.

  2. Enter Bootloader Mode

    • Method 1: Boot Button and USB Connection (most boards):

      • Step 1: Hold down the BOOT button on your ESP32 board.
      • Step 2: While holding the BOOT button, plug in the USB cable to connect the ESP32 to your computer.
      • Step 3: Keep holding the BOOT button for a few seconds, then release it. Your board should now be in bootloader mode.

    • Method 2: Boot and Reset Button Sequence:

      • Step 1: Press and hold the BOOT button on your ESP32.
      • Step 2: While holding the BOOT button, press and release the RESET button.
      • Step 3: Continue holding the BOOT button for an additional second or two, then release it. This sequence will also put the ESP32 into bootloader mode.

  3. Flash Process

    • Select your board type from the dropdown menu on the flasher site. If you're unsure of your specific ESP model, check the engraving on the chip.
    • Follow the on-screen instructions to initiate flashing.
    • Wait until the process is complete.

  4. Verify the Flash

    • After flashing, disconnect and reconnect your board to ensure the firmware update was successful.
    • Verify that the firmware boots correctly by accessing the control options described in the Post-Installation section.

Tips: After flashing, you may need to restart the device to initialize the new firmware. To ensure a clean start, disconnect and reconnect your ESP32.

USB Connection Method

This method is suitable for boards equipped with either a Micro USB or USB-C port and involves using the ESP flashing tool.

  1. Download and Extract the Firmware

    • Visit the GhostESP Releases page to download the latest firmware version for your board.
    • Extract the downloaded .tar.gz or .zip file using 7-Zip or another extraction tool.

  2. Connect Your Board

    • Identify the boot button on your board. For Flipper Dev Boards, it's the button closest to the USB port. On other boards, this button should be labeled "Boot" or "Select," but it can vary, especially if your board has a case.
    • Enter the board's bootloader mode by holding the identified boot button while connecting the board to your PC via a Micro USB or USB-C cable.

  3. Flash the Firmware

    • Go to ESP Huhn Flashing Tool and click on "Connect".
    • Select the COM port that your board is connected to. It should be labeled with your board's chipset, like "ESP32-S2".
    • Important Offsets:
      • For ESP32-S2 and similar boards, use the following offsets:
        • bootloader.bin at 0x1000
        • partitions.bin at 0x8000
        • firmware.bin at 0x10000
      • For ESP32-S3, C3 or C6 boards, the bootloader offset changes to:
        • bootloader.bin at 0x0
        • Continue using 0x8000 for partitions.bin and 0x10000 for firmware.bin.
    • Click "Flash" and wait until the process completes.

  4. Verify the Flash

    • After flashing, disconnect and reconnect your board to ensure the firmware update was successful.

Flipper Zero Method

  1. Download Required Files

    • Obtain the latest GhostESP .fap file from this link.
    • Download the latest firmware files from the GhostESP Releases page for the GhostESP project.

  2. Prepare the Firmware Files

    • Extract the downloaded firmware files using 7-Zip or a similar tool.

  3. Transfer Files to Flipper Zero

    • Ensure you have qFlipper installed on your PC.
    • Connect the Flipper Zero to your PC and use qFlipper to transfer the firmware files.
    • Place the .fap file and firmware files into the following directory on the Flipper Zero: 
      SDCard/apps_data/esp_flasher
      Important: Do not place the files in the assets or other folders to ensure correct functionality.

  4. Connect the Board to Flipper Zero

    • Enter bootloader mode on your ESP32 as described in the Web Flasher Method.
    • Connect your ESP32 to the Flipper Zero using the GPIO header.

  5. Flashing Process

    • Open the ESP flasher app on your Flipper Zero.
    • Select Manual Flash to flash each firmware component:
      • Choose the appropriate bootloader.bin, partitions.bin, and firmware.bin files.
    • Initiate the flash process and wait until it completes.
    • Reset your ESP32 after completion to finalize the installation.

Note: The Flipper Zero app requires the latest version to fully support GhostESP. Check the Flipper Zero GitHub or community forum for any compatibility updates.

Post-Installation

After flashing, you have several control options to configure and interact with GhostESP.

Control Options

  1. Web Interface

    • Open a browser and connect to either ghostesp.local or 192.168.4.1 to access device settings.
    • Use the auto-updating configuration panel to manage settings, Evil Portal controls, and device info.

  2. Qt6 Control App

    • Download and install the Qt6-based desktop application for more advanced control options.
    • Offers access to advanced features, customizable settings, and an improved interface for interacting with GhostESP.

  3. Serial Command Line

    • Connect via a serial interface for direct command-line control.
    • Provides full access to GhostESP’s command suite and is ideal for advanced users or troubleshooting.
    • Refer to the Command Line Interface Documentation for available commands and usage examples.

  4. Flipper Zero App

    • Control GhostESP directly from the Flipper Zero.
    • Ensure you have the latest .fap version on your Flipper Zero for full functionality and access to features like Evil Portal, Wi-Fi control, and more.

Common Installation Issues

Refer to the Troubleshooting page for solutions to common issues:

  • Boot loops: Check your board model and USB cable for compatibility.
  • Flash errors: Ensure you are in bootloader mode, and try a different USB port if flashing fails.
  • Connection issues: Ensure proper drivers are installed, especially on Windows.
  • Power supply problems: Use a stable USB power source to avoid disconnection during flashing.
  • Cache-related issues with the web flasher: Clear your browser cache or try a different browser if problems persist.

Troubleshooting Tip: For the Flipper Zero method, ensure the GPIO connections are secure, and the .fap file is correctly placed in SDCard/apps_data/esp_flasher.

Additional Recommendations

To ensure a smooth installation experience, consider the following:

  • File Extraction: Always verify that firmware files are correctly extracted before flashing.
  • Memory Offsets: Pay attention to the specific memory offsets required for your ESP32 variant to avoid firmware corruption.
  • Firmware Versions: Use the latest firmware versions for both GhostESP and Flipper Zero to ensure compatibility and access to the latest features.
  • Backup: If possible, backup your existing firmware before flashing new firmware to recover in case of any issues.

Additional Resources

Clone this wiki locally