Skip to content

platform-setup.md

Latest commit

 

History

History
180 lines (115 loc) · 6.17 KB

platform-setup.md

File metadata and controls

180 lines (115 loc) · 6.17 KB

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.0.0 and Zephyr SDK v0.17.0.

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 a Zephyr module. Add the following to your West manifest file (west.yml):

manifest:
  projects:
    - name: esp-flasher
      url: https://github.com/espressif/esp-serial-flasher
      revision: master
      path: modules/lib/esp_flasher

After updating the manifest, fetch the module:

west update

Project Configuration

Add these configuration options to your prj.conf:

CONFIG_ESP_SERIAL_FLASHER=y
CONFIG_CONSOLE_GETCHAR=y

Example Code

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

Raspberry Pi Pico Setup

Testing Status: Regularly tested with Raspberry Pi Pico SDK v1.5.1 and arm-gnu-toolchain-13.2.

Prerequisites

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

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