Platform Setup Guide

This document provides setup instructions for using ESP Serial Flasher on different host platforms to program and interact with ESP devices.

Platform SDK Compatibility

Each port is a reference implementation tied to a specific platform SDK. The tested SDK versions are noted in each platform section below. Ports are not part of the library's semantic versioning guarantee. Ports are maintained on a best-effort basis — breaking changes to them are minimized, but are sometimes necessary to stay up to date with upstream platform SDKs. When such an update is needed, it is released as a minor or patch version of this library.

General Prerequisites

Before setting up any platform, ensure you have the following:

• CMake 3.22 or later - Build system generator
• Platform-specific toolchain - See individual platform sections below

ESP-IDF Support

Testing Status: Regularly tested with all major and minor versions of ESP-IDF from v5.5 onwards

Prerequisites

• ESP-IDF v5.5+ - ESP-IDF development framework

Setup

ESP Serial Flasher is available as a managed component through the Espressif Component Registry. This is the recommended installation method for ESP-IDF projects.

Installation:

1. Navigate to your ESP-IDF project directory
2. Add the component dependency:

   idf.py add-dependency "espressif/esp-serial-flasher"
   

3. Build your project:

   idf.py build
   

The component will be automatically downloaded and integrated into your project's build system.

Component Registry: espressif/esp-serial-flasher

Example Code

See examples/esp32_example for a complete implementation with build instructions.

STM32 Setup

No pre-built example project is provided for STM32, as STM32 projects are chip-specific and generated by STM32CubeMX. The examples/stm32_example directory contains a guide that walks through generating a project for your MCU, integrating esp-serial-flasher, and writing the application code.

Zephyr Setup

Testing Status: Regularly tested with Zephyr RTOS v4.4.0 and Zephyr SDK v1.0.1.

Prerequisites

• Zephyr RTOS - Real-time operating system
• Zephyr SDK - Development toolkit
• West - Zephyr's meta-tool for managing repositories

Setup

ESP Serial Flasher can be integrated as an external Zephyr module. Add the zephyr/submanifest/esf.yaml file with the following content:

manifest:
  projects:
    - name: esp-serial-flasher
      url: https://github.com/espressif/esp-serial-flasher
      revision: master
      path: modules/lib/esp_serial_flasher # adjust the path as needed

After updating the submanifest, update all modules:

west update

Or fetch only the esp-serial-flasher module:

west update esp-serial-flasher

Project Configuration

All necessary configuration options are set in the example prj.conf. However, you can pass additional configuration options on the command line or add them to the prj.conf.

Please refer to the Zephyr example README.md for more details on usage.

Example Code

See examples/zephyr_example for a complete implementation with build instructions.

Raspberry Pi Pico and Pico 2 Setup

Testing Status: Regularly tested with Raspberry Pi Pico SDK v2.2.0 and arm-gnu-toolchain-15.2.

The original Pico (RP2040) only needs the ARM embedded toolchain. Pico 2 (RP2350) can run your app on either the ARM core or the RISC-V core; the Pico SDK selects that with PICO_PLATFORM, and each option needs the matching cross-compiler (they are not interchangeable in a single build).

Prerequisites

• Git - For cloning repositories
• Raspberry Pi Pico SDK - Development framework
• ARM GCC toolchain - Cross-compilation toolchain for ARM core
• RISC-V GCC toolchain - Cross-compilation toolchain for RISC-V core

Setup

1. Clone the repository:

   git clone https://github.com/espressif/esp-serial-flasher.git
   cd esp-serial-flasher
   

2. Ensure Pico SDK is available:

   • Either set PICO_SDK_PATH environment variable
   • Or place the Pico SDK in a standard location

3. Pick board and platform

   • Set PICO_BOARD and PICO_PLATFORM to match your hardware and whether you want ARM or RISC-V on RP2350; use the matching GCC toolchain.

4. Set toolchain path

   • Either set PICO_TOOLCHAIN_PATH to ARM GCC toolchain folder
   • Or to RISC-V toolchain folder

Example Code

See examples/pi_pico_example for a complete implementation with build instructions.

Linux Setup

Testing Status: Regularly tested on Debian/Ubuntu. Also runs on SBCs such as Raspberry Pi 4/5 running Raspberry Pi OS or any other Linux distribution.

Prerequisites

• CMake ≥ 3.22 and a C compiler (gcc / clang)
• libgpiod ≥ 2.0 — only required when using GPIO character-device mode for reset/boot control on SBCs (not needed for USB connections)

Install libgpiod on Debian/Ubuntu:

# Debian 13 (Trixie) / Ubuntu 24.04 or later — libgpiod 2.x is in the main repos:
sudo apt-get install libgpiod-dev
# Older distros: build from source (https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git)

Ensure your user is in the dialout (and optionally gpio) groups:

sudo usermod -aG dialout $USER   # for serial port access
sudo usermod -aG gpio $USER      # for GPIO character-device access (SBCs)
# logout and back in for group changes to take effect

Build

cd examples/linux_example
mkdir -p build && cd build

# USB connection (DTR/RTS auto-reset — no GPIO library needed):
cmake ..

# GPIO connection (SBC with libgpiod reset/boot control):
cmake -DLINUX_PORT_GPIO=ON ..

make

CMake Variables

Variable	Default	Description
PORT	—	Must be LINUX
LINUX_PORT_GPIO	OFF	Enable GPIO character-device support (requires libgpiod ≥ 2.0)

Example Code

See examples/linux_example for a complete implementation including run-time options, wiring diagrams, and Raspberry Pi-specific setup steps.

Next Steps

After successful platform setup:

1. Review the Configuration Guide for library configuration options
2. Check platform-specific examples in the examples/ directory
3. Read the API documentation for usage details
4. Upgrading from v1? See the Migration Guide