ESP32 Programmer

This guide explains how to use vPlayer as a standalone flasher for any ESP32-based board. Since different ESP32 variants (ESP32, ESP32-S2, ESP32-S3, ESP32-C3, etc.) may have unique partition layouts, you can specify memory offsets for the bootloader, partition table, firmware, and SPIFFS (or other file systems) in a simple config.txt file. vPlayer reads these offsets at startup, ensuring compatibility across multiple boards without recompilation.

To maintain different firmware sets, create unique folders on the SD card—one folder per firmware variant—placing the associated .bin files and a matching config.txt into each folder.

Source Code and bin file

GitHub

Configuration File

  1. Create a file named config.txt in your firmware folder.

  2. Define offsets for each component (bootloader, partitions, firmware, etc.):

    bootloaderNameOffset=0x0
partitionsNameOffset=0x8000
bootNameOffset=0xe000
firmwareNameOffset=0x10000
spiffsNameOffset=0x10000

    • These values are example offsets commonly used for an ESP32-C3.

    Example for a Standard ESP32

    bootNameOffset=0xe000
bootloaderNameOffset=0x1000
partitionsNameOffset=0x8000
firmwareNameOffset=0x10000
spiffsNameOffset=0x3D0000

Locating the Offsets

If you’re compiling and uploading with the Arduino IDE, you can retrieve the exact offsets by enabling verbose output (in File -> Preferences, check “Verbose Output” for both compile and upload). During the upload process, look for a line similar to:

"/Users/YourName/Library/Arduino15/packages/esp32/tools/esptool_py/4.9.dev3/esptool"
  --chip esp32s3 --port "/dev/cu.usbmodem1412201" --baud 921600
  --before default_reset --after hard_reset write_flash -z --flash_mode keep --flash_freq keep --flash_size keep
  0x0 "/Users/YourName/Library/Caches/arduino/sketches/.../myProject.ino.bootloader.bin"
  0x8000 "/Users/YourName/Library/Caches/arduino/sketches/.../myProject.ino.partitions.bin"
  0xe000 "/Users/YourName/Library/Arduino15/packages/esp32/hardware/esp32/.../boot_app0.bin"
  0x10000 "/Users/YourName/Library/Caches/arduino/sketches/.../myProject.ino.bin"

Here, each offset is followed by the corresponding .bin file:

  • 0x0 – Bootloader (.bootloader.bin)

  • 0x8000 – Partition table (.partitions.bin)

  • 0xe000 – Boot App (boot_app0.bin)

  • 0x10000 – Main application firmware (myProject.ino.bin)

You can also copy these .bin files from their listed paths to your SD card folder, making sure they follow the naming rules below.

File Naming Requirements

When you select a folder on the SD card, the code checks for specific keywords in the filenames to identify each file type. This is how it knows which files to flash and their intended purpose.

Required Files

  1. Bootloader - Must contain the substring bootloader in its filename. - Examples: bootloader_s3.bin, mybootloader.bin.

  2. Partition Table - Must contain the substring partitions in its filename. - Examples: partitions.bin, partitions_custom.bin.

  3. Main Firmware - Must contain either .ino.bin (e.g., mySketch.ino.bin) or esp32.bin (e.g., myFirmware_esp32.bin) in its name. - If either substring is detected, it’s assumed to be the main application.

  4. Boot App - Must contain the substring boot_app in its filename. - Example: boot_app0.bin.

  5. SPIFFS (Optional) - Must contain the substring spiffs.bin (e.g., myData_spiffs.bin). - If present, SPIFFS will be flashed using the offset in config.txt. - If missing, SPIFFS flashing is skipped.

  6. Configuration File - Must be named exactly config.txt. - Includes key-value pairs for each file’s flash offset (e.g., bootloaderNameOffset=0x0). - If this is missing, the flasher will not proceed.

Example Folder Layout

A typical folder might look like this:

/MyFirmwareFolder
├─ config.txt
├─ boot_app0.bin
├─ bootloader_s3.bin
├─ partitions_custom.bin
├─ mySketch.ino.bin
├─ myData_spiffs.bin

Where:

  • boot_app0.bin has boot_app

  • bootloader_s3.bin has bootloader

  • partitions_custom.bin has partitions

  • mySketch.ino.bin has .ino.bin

  • myData_spiffs.bin has spiffs.bin

  • config.txt defines the offsets.

_images/programmerFolders.png

Connection Basics

For minimal hookup, simply connect the vPlayer device to your target ESP32’s TX and RX pins. If you want automated programming (i.e., toggling the ESP32 into bootloader mode without manual intervention), you can add code to drive the BOOT and RESET lines directly—vPlayer has extra I/O pins available for this purpose. However, for a basic setup, you only need:

  1. TX (vPlayer) -> RX (ESP32)

  2. RX (vPlayer) -> TX (ESP32)

  3. GND (shared between vPlayer and ESP32)

To enter the bootloader manually:

  • Hold the BOOT pin low,

  • Then toggle RESET or power cycle the ESP32 while BOOT is held low.

_images/ProgrammerWiring.png