Getting Started

To start using Xedge, you need to upload the firmware onto an ESP32-S3 or an ESP32 with PSRAM (for example, the ESP32 WROVER). Before you begin, ensure your ESP32 device meets the following requirements for the pre-compiled firmware:

  • Standard ESP32: Requires a minimum of 4MB flash memory and 4MB RAM.

  • ESP32-S3 Variant: Requires a minimum of 8MB flash memory and 8MB RAM, but comes with additional features.

First Time Installers

We suggest using the user-friendly web-based installer available on the Xedge32 introduction page for a straightforward installation process. Please consult the advanced installation instructions below if you require more detailed customization.

OTA Upgrade

For users with Xedge32 already installed on an ESP32-S3 device, take advantage of the integrated Xedge32 OTA Upgrade Manager for a seamless update experience. Begin by downloading the latest ESP32-S3 firmware zip file. Once downloaded, extract the contents of the ZIP file. Then, simply drag and drop the xedge.bin or xedge-s0.bin firmware file onto the Upgrade Manager’s user interface to commence the upgrade process.

Advanced Installation/Upgrade

We offer two options for the firmware:

  1. Ready-to-use firmware binary files which you can directly upload onto your board.

  2. C source code files which you can compile using the Espressif ESP-IDF toolchain.

Important: We provide instructions suitable for both the ESP32 and the newer ESP32-S3 chips. Make sure to follow the correct instructions for the chip that you’re using.

Firmware Option 1: Use Pre-Compiled Firmware

The firmware binaries can be uploaded using Windows, Mac, and Linux using the command line tool esptool. Refer to the instructions below for details. We will start by showing how to use a graphical installer, which is only compatible with Windows.

Windows Graphical Installer

How to flash the Xedge32 IDE

To upload the Xcode32 firmware to your ESP32 board, begin by downloading the ESPRESSIF Flash Tool and one of:

Unzip the ESPRESSIF Flash Tool archive and the or archive.

  1. Connect your ESP32 board to your computer and find the com port used by using the Device Manager.

  2. Start the ESPRESSIF Flash Tool flash_download_tool_3.9.4.exe executable.

  3. When the tool starts, select ChipType ESP32 or ESP32-S3 and click OK.

  4. On the SPIDownload page, set the COM port to the one used by the ESP32 and set Speed to 115200.

  5. Click the ERASE button and wait for it to complete.

  6. Click the 3 dots (…) to browse to the bin files you downloaded.

  7. Select the following binary files and set the address accordingly:

    1. Option 1: When using the merged binary firmware file merged-xedge.bin

      Binary File




      Click the checkbox to the left of the binary file to select it.

    2. Option 2: When using the three separate binary files

      Binary File

      ESP32 Address

      ESP32-S3 Address










      Click the three checkboxes to the left of the three bin files to select them.

  8. Do not change any other values.

  9. Click the START button and wait for it to upload the bin files to your ESP32.

  10. When completed, open a terminal emulator such as Putty.

  11. You should see a terminal window with text being printed, as shown in the screenshot below.

  12. When you see LuaShell32 ready being printed, proceed by configuring the ESP32 as explained below.

Firmware Upload Tool

The screenshot above displays the firmware tool on the left with three separate binary files selected, and on the right, it shows a Putty terminal connected to the device. Option one is more user-friendly as it employs a merged binary firmware file, combining the three separate files into one entity.

Potential Issues and Solutions:

  • On certain boards, you must press the boot button before connecting the USB. Once the USB is plugged in, you can release the button.

  • If you’re using an ESP32-S3 board equipped with both USB-OTG and USB-UART, you will need to perform flashing using the USB-UART connection. Meanwhile, connect Putty to USB-OTG.

  • If you do not see the LuaShell32 after connecting Putty, try the following: Configure Putty with the required serial connection parameters so you can quickly click the Open button, then do as follows: Click the ESP32 development board’s reset button, followed by quickly clicking the Open button in Putty.

Linux, Mac, and Windows using the command line tool esptool

The following examples show how to use Linux. The commands are similar for Mac and Windows.

Install the required tool:

sudo apt install python3-pip
pip install esptool

Upload the ESP32 firmware:

cd Xedge32-Firmware

# Use one of:

# python -m esptool --chip esp32 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x0 merged-xedge.bin

# python -m esptool --chip esp32 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 xedge.bin

Upload the ESP32-S3 firmware:

cd Xedge32-Firmware

# Use one of:

# python -m esptool --chip esp32s3 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size detect --flash_freq 80m 0x0 merged-xedge.bin

# python -m esptool --chip esp32s3 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size detect --flash_freq 80m 0x0 bootloader.bin 0x8000 partition-table.bin 0x20000 xedge.bin

For the ESP32-S3, we provide two firmware options

xedge.bin (merged-xedge.bin)
  • Tailored for boards like “xiao esp32-s3” with a single USB port.

  • This firmware activates the Xedge32 console LuaShell32 through the USB port.

xedge-s0.bin (merged-xedge-s0.bin)
  • Ideal for boards that utilize serial UART0 for flashing or console logging. The USB to serial converter chip, such as CP210x or FTDI, can be integrated or external.

  • This firmware version initializes the Xedge32 console using LuaShell32 via the USB-to-UART serial connection.


If you upload the xedge.bin software via USB-to-UART, and your board has two USB ports, you’ll need to switch to the other USB port after uploading. However, with xedge-s0.bin, you can continue using the same USB-to-UART port.

Firmware Option 2: Compile The Code

See the GitHub Repository for details.

Configure the ESP32

Once the firmware upload is complete, reboot the ESP32. The ESP32 will be in Access Point mode after restarting. You can now connect to it using a serial terminal or access the web-based shell by connection to the access point. Select one of these options and program the ESP32 as follows if you want it to connect to your network and not operate as an access point:

In the LuaShell32 prompt, type the following to connect to your network:

  • Using Wi-Fi:

esp32.netconnect("wifi", {ssid="your-Wi-Fi-SSID", pwd="password"})
  • Using Ethernet:

esp32.netconnect("W5500", {spi-settings})

The next time you turn on your ESP32 device, it will automatically connect to your Wi-Fi network, so there’s no need to reconnect the serial console and use the LuaShell32.

Next Step

Once Xedge has successfully connected to your network, continue your journey by exploring our guide on how to use Xedge32 .

Firmware Upgrade Options

The pre-compiled firmware for the ESP32-S3 features convenient drag-and-drop upgrades. To upgrade Xedge32, you have two options:

  1. Follow the detailed firmware installation process described in this tutorial, but only upload xedge.bin or xedge-s0.bin.

  2. Opt for the more straightforward drag-and-drop method as previosly explained.

Support and Discussions

If you encounter any issues, have questions, or simply want to join discussions about the firmware, our main platform for support is the GitHub Discussions page for the project.

Please visit the Xedge32 Discussions on GitHub for assistance and community interactions.