PlatformIO Community

Openocd (11.0) is unable to flash a firmware_merged.bin file using ESP-PROG. "Error: Invalid offset!"

It seems openocd is unable to flash a firmware_merged.bin file with an offset of 0x0 to an esp32 target.

I am able to upload a firmware.bin file using openocd in a separate powershell. Therefor, hardware/connection related issues are most likely not the problem.

Any help in uploading a firmware_merged.bin file, so I can start debugging, is highly appreciated.


Visual Studio Code: 
	Version: 1.70.1 (system setup)
	Commit: 6d9b74a70ca9c7733b29f0456fd8195364076dda
	Date: 2022-08-10T06:08:33.642Z
	Electron: 18.3.5
	Chromium: 100.0.4896.160
	Node.js: 16.13.2
	OS: Windows_NT x64 10.0.19043
	Core 6.1.4 Home 3.4.3

Very simple test program:

#include <Arduino.h>

void setup() {
  // put your setup code here, to run once:

void loop() {
  // put your main code here, to run repeatedly:

The hardware components are working because I am able to upload the firmware.bin based on the following platformio.ini settings

platform = espressif32
board = esp32doit-devkit-v1
framework = arduino
monitor_speed = 115200
;debug_tool = esp-prog
;upload_protocol = esp-prog

and using openocd with the esp-prog in a powershell:

openocd -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg -c "program_esp ./firmware.bin 0x10000 verify exit"

However, using upload_protocol = esp-prog in platformio.ini will create a new firmware.bin file.
Before uploading this file it is changed by into a firmware_merged.bin file. Openocd is attempting to upload this file with an offset of 0x0. This upload fails with “Error: Invalid offset”. See log for the details.

Processing esp32doit-devkit-v1 (platform: espressif32; board: esp32doit-devkit-v1; framework: arduino)
----------------------------------------------------------------------------------------------------------------------------Verbose mode can be enabled via `-v, --verbose` option
PLATFORM: Espressif 32 (5.1.0) > DOIT ESP32 DEVKIT V1
HARDWARE: ESP32 240MHz, 320KB RAM, 4MB Flash
DEBUG: Current (cmsis-dap) External (cmsis-dap, esp-bridge, esp-prog, iot-bus-jtag, jlink, minimodule, olimex-arm-usb-ocd, olimex-arm-usb-ocd-h, olimex-arm-usb-tiny-h, olimex-jtag-tiny, tumpa)
 - framework-arduinoespressif32 @ 3.20004.220818 (2.0.4)
 - tool-esptoolpy @ 1.30300.0 (3.3.0)
 - tool-mkfatfs @ 2.0.1
 - tool-mklittlefs @ 1.203.210628 (2.3)
 - tool-mkspiffs @ 2.230.0 (2.30)
 - tool-openocd-esp32 @ 2.1100.20220706 (11.0)
 - toolchain-xtensa-esp32 @ 8.4.0+2021r2-patch3
LDF: Library Dependency Finder ->
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 32 compatible libraries
Scanning dependencies...
No dependencies
Building in release mode
Retrieving maximum program size .pio\build\esp32doit-devkit-v1\firmware.elf
Checking size .pio\build\esp32doit-devkit-v1\firmware.elf
Advanced Memory Usage is available via "PlatformIO Home > Project Inspect"
RAM:   [=         ]   5.0% (used 16440 bytes from 327680 bytes)
Flash: [==        ]  18.6% (used 243837 bytes from 1310720 bytes)
"C:\Users\jelle\.platformio\penv\Scripts\python.exe" C:\Users\jelle\.platformio\packages\tool-esptoolpy\ --chip esp32 merge_bin -o .pio\build\esp32doit-devkit-v1\firmware_merged.bin --flash_mode dio --flash_size 4MB 0x10000 .pio\build\esp32doit-devkit-v1\firmware.bin "0x1000" "C:\Users\jelle\.platformio\packages\framework-arduinoespressif32\tools\sdk\esp32\bin\bootloader_dio_40m.bin" "0x8000" "D:\Jelle\Documents\Prive\Programmeren\PlatformIO\Projects\test debugginh jtag probe\.pio\build\esp32doit-devkit-v1\partitions.bin" "0xe000" "C:\Users\jelle\.platformio\packages\framework-arduinoespressif32\tools\partitions\boot_app0.bin" v3.3
Flash params set to 0x0220
Wrote 0x4ba00 bytes to file .pio\build\esp32doit-devkit-v1\firmware_merged.bin, ready to flash to offset 0x0
Configuring upload protocol...
AVAILABLE: cmsis-dap, esp-bridge, esp-prog, espota, esptool, iot-bus-jtag, jlink, minimodule, olimex-arm-usb-ocd, olimex-arm-usb-ocd-h, olimex-arm-usb-tiny-h, olimex-jtag-tiny, tumpa
CURRENT: upload_protocol = esp-prog
Uploading .pio\build\esp32doit-devkit-v1\firmware_merged.bin
Open On-Chip Debugger  v0.11.0-esp32-20220706 (2022-07-06-15:48)
Licensed under GNU GPL v2
For bug reports, read
debug_level: 1

adapter speed: 20000 kHz

WARNING: boards/esp-wroom-32.cfg is deprecated, and may be removed in a future release.
DEPRECATED! use 'adapter speed' not 'adapter_khz'
adapter speed: 5000 kHz

** Programming Started **
Error: Invalid offset!
Error: failed erasing sectors 0 to 75
embedded:startup.tcl:1184: Error: ** Programming Failed **
in procedure 'program_esp' 
in procedure 'program_error' called at file "C:/Users/jelle/.platformio/packages/tool-openocd-esp32/share/openocd/scripts/target/esp_common.cfg", line 171
at file "embedded:startup.tcl", line 1184
*** [upload] Error 1

Reason for creating the merged file is described in

# Arduino core v2.0.4 contains updated bootloader images that have innacurate default
# headers. This results in bootloops if firmware is flashed via OpenOCD (e.g. debugging
# or uploading via debug tools). For this reason, before uploading or debugging we need
# to merge binaries via esptoolpy so that the image headers will be adjusted according to
# --flash-size and --flash-mode arguments.

I tested the uploading of the original firmware.bin file using the powershell openocd command. Uploading works but the esp32 system is stuck in the bootloop as described above.

The most recent commit in explicitly talks about fixing that – when you use

platform =

in your platformio.ini and build the project again and retry debugging, does it work?


This is really great!! Upload works, I will try to debug later.

Thanks again for the fast reply, I have been spending a full day on this :smiley:

Debugging also works!!


It took me 7 hours today to get esp-prog work in CLion PlatformIO with esp32…and this was the key…#lifesaver

The critical commit was already released in a stable version more than 2 weeks ago in platform version 5.1.1, so my comment is not valid anymore. Use the regular platform = espressif32 and make sure your platform is up-to-date – e.g. by using the PIO Home → Platforms GUI, or pio pkg update -g -p espressif32 on the CLI.

Interesting you say that as my pio and packages are up to date and it did not work (in CLion) until I used your link…
PIO Status

Thanks anyway for your work and sharing