Version 2.0.0

v2.0.0 (2026-06-04)

🚨 Breaking changes

• The port logging API replaces debug_print with levelled
  log and log_hex callbacks. SERIAL_FLASHER_DEBUG_TRACE is removed;
  configure SERIAL_FLASHER_LOG_LEVEL or the
  CONFIG_SERIAL_FLASHER_LOG_LEVEL_* Kconfig choice instead. (Jaroslav Burian - 6cec7b1)
• esp_loader_change_transmission_rate_stub is removed.
  connect_to_target_with_stub() takes only the target rate (0 to skip). (Jaroslav Burian - ee35ca4)
• The pre-built STM32H743 example project no longer
  exists. Users must generate a CubeMX project for their own MCU and
  follow the guide in examples/stm32_example/README.md. (Jaroslav Burian - 37a9940)
• Port configuration structs have renamed fields:
  reset_trigger_pin → reset_pin, gpio0_trigger_pin → boot_pin. (Jaroslav Burian - dbfe6a7)
• Port configuration structs have renamed fields:
  reset_trigger_pin → reset_pin, gpio0_trigger_pin → boot_pin. (Jaroslav Burian - 986b0f3)
• Linux port and example replaces the dedicated Raspberry Pi port. (Jaroslav Burian - af11d24)
• The minimum required CMake version has been raised from
  3.5/3.13/3.16/3.20 to 3.22 across all CMakeLists.txt files and
  documentation. (Jaroslav Burian - c3f2d92)
• loader_port_*_init(), loader_port_*_deinit(), and
  global *_uart_port / *_sdio_port / *_spi_port variables are removed
  from all port headers. Callers must declare a <platform>_port_t struct,
  set .port.ops, fill config fields, and pass &port.port directly to
  esp_loader_init_*(). (Jaroslav Burian - 9677c4b)
• The reboot flag has been removed from esp_loader_flash_finish().
  Previously, the flag had no effect due to bug in ROM bootloader.
  See docs/migration-v1-to-v2.md for migration guidance. (Jaroslav Burian - 3193ffe)
• esp_loader_flash_finish() now verifies MD5,
  esp_loader_flash_verify() is removed. MD5 library is bundled with the
  library always which adds around 2kB flash usage.
  esp_loader_flash_finish() must always be called after flashing to
  finalize the flash operation and trigger the MD5 verification. (Jaroslav Burian - 64f25ca)
• all public API function signatures changed; port
  implementations must be rewritten as a vtable. See
  docs/migration-v1-to-v2.md for the full upgrade guide. (Jaroslav Burian - 272c1ff)
• ESP-IDF v5.4 and older are no longer supported. (Jaroslav Burian - 25f15fb)

✨ New Features

• log: replace debug_print with levelled log/log_hex callbacks (Jaroslav Burian - 6cec7b1)
• examples: Add support for RP2350 (Vojtech Piroch - 75756b2)
• sdio: support full esp-flasher-stub command protocol (Jaroslav Burian - 59f066f)
• serial: increase flash read throughput with stub (Jaroslav Burian - d9ad3bc)
• port: Update Zephyr integration and sample (Marek Matej - 174f3ea)
• examples: Improve error message when firmware binaries are not provided (Vojtech Piroch - 5d13d3a)
• stubs: Migrate to the new espressif/esp-flasher-stub (Jaroslav Burian - c6189bd)
• uart: Reconnect to ROM if stub running on mem_begin (Jaroslav Burian - 9854c21)
• port: Add generic Linux example working with USB and GPIOs (Jaroslav Burian - af11d24)
• port: Allow multiple simultaneous loader instances over different peripherals (Jaroslav Burian - 9677c4b)
• protocol: add flash deflate write (kerms - f3cd5f9)
• Add support for ESP32-C61 as target device (Jeija - 4e33990)
• Add esp_loader_deinit() to release hardware resources (Jaroslav Burian - 05c2240)
• Remove necessity to specify target chip in secure download mode (Jaroslav Burian - 4327c64)
• Attach flash only when needed (Jaroslav Burian - 6ee3983)
• Allow runtime MD5 check selection (Jaroslav Burian - 64f25ca)
• context-based API with runtime protocol selection (Jaroslav Burian - 272c1ff)

🐛 Bug Fixes

• flash: remove in-place buffer mutation and send exact payload size (Jaroslav Burian - 7831ab2)
• esp8266: pass sequence_number by pointer to loader_flash_begin_cmd (Jaroslav Burian - 1d457d7)
• slip: apply escape decoding to first payload byte (Jaroslav Burian - 6929841)
• port: Use correct pin type for Espressif ports (Jaroslav Burian - 36fbd2c)
• port: Fix deadline_ms overflow by comparing elapsed time against timeout (Jaroslav Burian - 77617a6)
• port: Log warning and return false on USB RX stream buffer short write (Jaroslav Burian - 0d4808f)
• targets: Access regs member directly instead of casting esp_target_t pointer (Jaroslav Burian - 54f8c7c)
• sdio: Use common buffer for send and response to save stack space (Jaroslav Burian - 6f4b276)
• port: USB port had wrong variable type causing timeout after 72 minutes (Jaroslav Burian - 08d3c64)
• port: Properly reinit UART after changing baud rate (Jaroslav Burian - 8e8c509)
• sdio: SDIO stub was limiting flash size to 2MB, this was fixed (Jaroslav Burian - 2e77e8b)
• examples: Use cross platform MD5 hash computation (Oliver Norin - 3e78dba)
• default write block retries to 3 when macro is unset (Jaroslav Burian - 2248398)
• Check return value of loader_flash_read_stub_cmd (Jaroslav Burian - d42674e)
• Remove (unsigned) casts in ROUNDUP macro to preserve input type width (Jaroslav Burian - 6f4a422)
• Replace floating-point timeout calculation with integer arithmetic (Jaroslav Burian - 88c6a9a)
• Correct timer overflow and LOAD_RAM_TIMEOUT_PER_MB value (Jaroslav Burian - 7f40ce3)
• Use same sequence number when retrying to write flash (Jaroslav Burian - b6e1917)
• Do not send flash end command to ROM as it has issues (Jaroslav Burian - 3193ffe)

📖 Documentation

• port: Update port versioning policy (Jaroslav Burian - 13d249a)
• Add flash size footprint section to README (Jaroslav Burian - 779714a)
• Remove single target limitation from README.md (Jaroslav Burian - ac85c26)

🔧 Code Refactoring

• sdio: move buffer alignment handling to port (Jaroslav Burian - 33c1524)
• examples: Replace stm32 example with setup guide (Jaroslav Burian - 37a9940)
• port: Rename GPIO pin fields for consistency (Jaroslav Burian - dbfe6a7)
• port: Rename GPIO pin fields for consistency (Jaroslav Burian - 986b0f3)
• unify baud rate change for ROM and stub (Jaroslav Burian - ee35ca4)

Version 1.11.0

v1.11.0 (2025-12-05)

✨ New Features

• Add SDIO support for ESP32-C5 as a target (Jaroslav Burian - 4591799)
• Add support for 1-bit SDIO (Jaroslav Burian - 4d54095)

🐛 Bug Fixes

• Correct flash boundary check for read/verify operations (RevK - bdf7b62)

Version 1.10.0

v1.10.0 (2025-09-25)

✨ New Features

• Add support for communication via CP210x and CH34x serial converters (Jaroslav Burian - 8c67fdc)
• Add support for USB CDC ACM for ESP32-P4 as a host (Jaroslav Burian - e6e5282)

🐛 Bug Fixes

• esp32c2: Fix transmission rate change for ESP32-C2 with 26 MHz crystal (Jaroslav Burian - bb5bc52)
• esp32c2: Add missing magic value of new ECO4 (Jaroslav Burian - 468221a)

📖 Documentation

• Better unify example README files and remove explicit references to ESP32 as a target (Jaroslav Burian - a70404c)
• Create new strucured documentation with separated files for each topic (Jaroslav Burian - 86e49eb)

🔧 Code Refactoring

• Update driver dependency (Chen Chen - 610873b)

Version 1.9.0

v1.9.0 (2025-07-21)

✨ New Features

• add erase function (Jaroslav Burian - 1c36d0a)
• add esp32_sdio_example to demonstrate SDIO flashing (Jaroslav Burian - bb41a06)
• add support for SDIO flashing (Jaroslav Burian - e5ae852)
• add support for ESP32-P4 (Jaroslav Burian - e475fe5)
• Add ESP32-C5 support without stub (Jaroslav Burian - f82b1a4)

🐛 Bug Fixes

• ensure stubs for targets are stored in flash to save RAM space (Jaroslav Burian - e3572f3)
• flash error log indentation (Jaroslav Burian - 8d6504d)
• add missing stub error codes (Jaroslav Burian - f452b3b)
• properly check flash size when verifying flash (Jaroslav Burian - cf1ca67)
• writing above 0x200000 in SDM (Jaroslav Burian - 34d27fe)
• use correct image header size for ESP8266 (Jaroslav Burian - 3f7a78f)
• esp8266 bootloader offset address (Jaroslav Burian - 4858e98)

📖 Documentation

• zephyr: improve description of how to use the Zephyr example (Jaroslav Burian - 08f5f41)
• fix Markdown syntax and improve notes (Jaroslav Burian - 52c064e)
• mention tested SDK and toolchain versions for each port (Jaroslav Burian - 4b556cd)
• add link to devcon talk (Jaroslav Burian - 8869652)

🔧 Code Refactoring

• change chip magic values to variable-length pointer array (Jaroslav Burian - 2b2066c)

Version 1.8.0

v1.8.0 (2025-01-27)

✨ New Features

• examples: Add ESP32 fast reflash example with MD5 check (Jaroslav Burian - e0b9b05)
• Add a function to check flash regions against a known MD5 (Djordje Nedic - dd480bc)
• Add the SDIO inteface and the corresponding esp port (Djordje Nedic - b74194b)

🐛 Bug Fixes

• esp32s3: Ensure electric current capabilities allowing to flash devkits with UART converters (Jaroslav Burian - 05d78a4)
• Print MD5 debug as hex string when using stub (Jaroslav Burian - ab0ce64)
• Unify debug prints of all ports (Jaroslav Burian - ccfd42c)
• Set default flash size when detection fails (Jaroslav Burian - adbe6ab)
• INVALID_ARG error when ESP32P4 used as a host (Jaroslav Burian - b42d1d8)
• Return when SDIO connection not initialized (Jaroslav Burian - 3ee2b25)
• esp32c2 incorrect SPI flash config detection (Jaroslav Burian - ed43e0a)
• Add missing definition for Zephyr debug trace (Jaroslav Burian - 86effb2)
• Update USB reset sequence (Jaroslav Burian - f64cf7c)

📖 Documentation

• Update log output for Zephyr example (Jaroslav Burian - 7abd989)
• Fix swapped RX and TX in Zephyr example (Jaroslav Burian - 7855e5e)

Version 1.7.0

v1.7.0 (2024-11-25)

New Features

• Add support for reading from target flash
• Add support for inverting reset and boot pins
• Update zephyr example to v4.0.0
• examples: Provide more useful error messages

Bug Fixes

• Clarify and validate alignment requirements for flashing
• ROUNDUP calculation fix
• Zephyr example
• Handling of USB buffer overflow
• Callback when USB port is disconnected

Version 1.6.2

v1.6.2 (2024-10-18)

Bug Fixes

• Fix the ESP USB CDC ACM port read return value

Version 1.6.1

v1.6.1 (2024-10-15)

Bug Fixes

• Fix ESP32-H2 flash detection

Version 1.6.0

v1.6.0 (2024-09-26)

New Features

• Add support for Secure Download Mode
• Add support for getting target security info
• Add logging from target to rpi pico port

Bug Fixes

• Add delay to usb example to ensure connection
• Do not enable logging if flashing error - STM
• Add missing esp32c3 chip magic numbers
• Multiple timeout fixes
• Only check if image fits into flash when we know flash size
• Duplicate word in logging message

Code Refactoring

• protocol: Rework command and response handling code
• protocol: Add support for receiving variably sized SLIP packets

Version 1.5.0

v1.5.0 (2024-08-13)

New Features

• Add the Raspberry Pi Pico port