Add example for Espressif ESP32 executorch runner with no optimizations by jpiat · Pull Request #18224 · pytorch/executorch

jpiat · 2026-03-17T07:59:22Z

Summary

This PR introduce a new example for the ESP32 Espressif SoC. The example implement an executorch runner for the ESP32 platform and a project that executes a simple network. The example does not use ops optimized for ESP32 platform but demonstrate feasibility.

Test plan

This example was tested on a ESP32-S3 development platform. The project compiles and when loaded on the platform show the expected log trace.

cc @psiddh @AdrianLundell @digantdesai

…e it included in runner

…play correct error messages

pytorch-bot · 2026-03-17T07:59:27Z

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/18224

📄 Preview Python docs built from this PR

Note: Links to docs will display an error until the docs builds have been completed.

❌ 10 Awaiting Approval, 1 New Failure

As of commit 34a42c7 with merge base c81126e ():

AWAITING APPROVAL - The following workflows need approval before CI can run:

NEW FAILURE - The following job has failed:

Copilot code review / Cleanup artifacts (gh)
Process completed with exit code 1.

This comment was automatically generated by Dr. CI and updates every 15 minutes.

meta-cla · 2026-03-17T07:59:28Z

Hi @jpiat!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

Copilot

Pull request overview

Adds an Espressif (ESP32 / ESP32-S3) ExecuTorch “executor runner” example project plus a new CMake preset to help cross-compile ExecuTorch for ESP targets.

Changes:

Introduces a new esp-baremetal CMake preset and preset file for ESP-oriented ExecuTorch builds.
Adds a full ESP-IDF example project (runner component + template project + build script + docs).
Adds ESP-IDF configuration defaults (sdkconfig defaults + partition table) for ESP32-S3-oriented setups.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
tools/cmake/preset/esp_baremetal.cmake	New ESP-oriented ExecuTorch build preset settings.
CMakePresets.json	Registers the `esp-baremetal` configure preset.
examples/espressif/README.md	End-to-end instructions for exporting, building, flashing, and troubleshooting on ESP32/ESP32-S3.
examples/espressif/build.sh	Helper script to build the ESP-IDF project and optionally generate `model_pte.h`.
examples/espressif/executor_runner/CMakeLists.txt	ESP-IDF component + standalone build definition for the runner.
examples/espressif/executor_runner/esp_executor_runner.cpp	Main ESP runner implementation (PAL hooks, loading, execution, optional FS load/ETDump/BundleIO).
examples/espressif/executor_runner/esp_memory_allocator.{h,cpp}	ESP-specific allocator wrapper with usage tracking.
examples/espressif/executor_runner/esp_perf_monitor.{h,cpp}	Simple perf measurements using cycle counter + `esp_timer`.
examples/espressif/executor_runner/pte_to_header.py	Converts `.pte` into a C header for compiled-in model embedding.
examples/espressif/project/CMakeLists.txt	Template ESP-IDF project that pulls in the runner component.
examples/espressif/project/main/{CMakeLists.txt,main.cpp}	Minimal “main” component that calls into the runner.
examples/espressif/project/sdkconfig.defaults	Default ESP-IDF configuration for the example (generic).
examples/espressif/project/sdkconfig.defaults.esp32s3	Target-specific ESP32-S3 config defaults.
examples/espressif/project/partitions.csv	Custom partition table for the example firmware.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

examples/espressif/executor_runner/esp_executor_runner.cpp

examples/espressif/executor_runner/esp_perf_monitor.cpp

examples/espressif/executor_runner/esp_executor_runner.cpp

examples/espressif/README.md

examples/espressif/project/partitions.csv

examples/espressif/project/sdkconfig.defaults

tools/cmake/preset/esp_baremetal.cmake

jpiat · 2026-03-17T08:17:48Z

@pytorchbot label "release notes: examples"

meta-cla · 2026-03-17T08:17:57Z

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Adds a new Espressif ESP32/ESP32-S3 example integration for running ExecuTorch models under ESP-IDF, along with build tooling and documentation to cross-compile ExecuTorch for Xtensa and build/flash an example project.

Changes:

Introduces an ESP-IDF executor_runner component and example project scaffolding (CMake, app_main, sdkconfig defaults, partitions).
Adds an ESP-focused CMake preset (esp-baremetal) to configure ExecuTorch builds for the target.
Adds a model conversion helper (pte_to_header.py), a build helper script, and a comprehensive README.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
tools/cmake/preset/esp_baremetal.cmake	New preset to configure ExecuTorch build options for ESP targets.
CMakePresets.json	Registers the `esp-baremetal` CMake preset.
examples/espressif/README.md	End-to-end documentation for exporting, building, flashing, and troubleshooting.
examples/espressif/build.sh	Helper script to generate `model_pte.h` and build via `idf.py`.
examples/espressif/executor_runner/CMakeLists.txt	ESP-IDF component definition + standalone CMake build option; integrates prebuilt ExecuTorch libs.
examples/espressif/executor_runner/esp_executor_runner.cpp	Core runner implementation: loading PTE, setting up allocators, executing, logging, optional SPIFFS load.
examples/espressif/executor_runner/esp_memory_allocator.{h,cpp}	Custom allocator wrapper with tracking helpers.
examples/espressif/executor_runner/esp_perf_monitor.{h,cpp}	Perf measurement helpers using cycle counter and `esp_timer`.
examples/espressif/executor_runner/pte_to_header.py	Converts a `.pte` into a C header byte array for firmware embedding.
examples/espressif/project/CMakeLists.txt	Example ESP-IDF project top-level CMake.
examples/espressif/project/main/CMakeLists.txt	Minimal `main` component that depends on `executor_runner`.
examples/espressif/project/main/main.cpp	Provides `app_main()` that invokes `executor_runner_main()`.
examples/espressif/project/sdkconfig.defaults	Baseline ESP-IDF defaults for the example project.
examples/espressif/project/sdkconfig.defaults.esp32s3	ESP32-S3-specific defaults (PSRAM, etc.).
examples/espressif/project/partitions.csv	Custom partition table template for the example project.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

examples/espressif/executor_runner/esp_executor_runner.cpp

examples/espressif/executor_runner/esp_memory_allocator.cpp

examples/espressif/project/main/main.cpp

examples/espressif/project/sdkconfig.defaults

examples/espressif/README.md

tools/cmake/preset/esp_baremetal.cmake

… on xtensa.

…argument.

…atching result type

Copilot

Pull request overview

This pull request adds an Espressif ESP32/ESP32-S3 ExecuTorch “executor runner” example plus a CMake preset to support cross-compiling ExecuTorch for ESP targets.

Changes:

Introduces a new esp-baremetal CMake preset and preset file to configure an ESP-oriented ExecuTorch build.
Adds a full ESP-IDF example project + build script + documentation for running .pte models on ESP32/ESP32-S3.
Adds ESP-specific runtime utilities (performance monitor, memory allocator) and an ESP executor runner implementation.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
tools/cmake/preset/esp_baremetal.cmake	New preset file defining default ExecuTorch build toggles for ESP builds.
CMakePresets.json	Adds `esp-baremetal` configure preset entry.
extension/threadpool/threadpool.cpp	Adjusts TSAN thread limit constant type in `get_threadpool()`.
examples/espressif/README.md	New end-to-end documentation for ESP32/ESP32-S3 runner and workflow.
examples/espressif/build.sh	New helper script to generate `model_pte.h` and build the ESP-IDF project.
examples/espressif/executor_runner/CMakeLists.txt	Defines ESP-IDF component + standalone build wiring for the runner.
examples/espressif/executor_runner/esp_executor_runner.cpp	Main ESP runner implementation (PAL hooks, allocators, optional FS load, execution loop).
examples/espressif/executor_runner/esp_memory_allocator.h	Declares a tracking allocator wrapper for embedded diagnostics.
examples/espressif/executor_runner/esp_memory_allocator.cpp	Implements tracking allocator accounting.
examples/espressif/executor_runner/esp_perf_monitor.h	Declares ESP timing/profiling helpers.
examples/espressif/executor_runner/esp_perf_monitor.cpp	Implements cycle/time measurement + logging for ESP builds (stubbed for non-ESP).
examples/espressif/executor_runner/pte_to_header.py	Utility to convert `.pte` into a compiled-in C header.
examples/espressif/project/CMakeLists.txt	Template ESP-IDF project using the runner component via `EXTRA_COMPONENT_DIRS`.
examples/espressif/project/main/CMakeLists.txt	Minimal `main` component definition for the ESP-IDF app.
examples/espressif/project/main/main.cpp	ESP-IDF `app_main()` that calls `executor_runner_main()`.
examples/espressif/project/sdkconfig.defaults	Baseline ESP-IDF config defaults for the example.
examples/espressif/project/sdkconfig.defaults.esp32s3	ESP32-S3 specific ESP-IDF config defaults (PSRAM/oct mode, etc.).
examples/espressif/project/partitions.csv	Custom partition table for the example project.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

extension/threadpool/threadpool.cpp

examples/espressif/executor_runner/esp_executor_runner.cpp

examples/espressif/executor_runner/esp_memory_allocator.cpp

examples/espressif/executor_runner/CMakeLists.txt

examples/espressif/project/main/main.cpp

examples/espressif/executor_runner/CMakeLists.txt

Copilot

Pull request overview

Adds an Espressif ESP32/ESP32-S3 executor runner example and build scaffolding to cross-compile and run ExecuTorch on ESP-IDF targets, plus a small threadpool type tweak and a new CMake preset for ESP baremetal builds.

Changes:

Add a full ESP-IDF example project/component for running ExecuTorch models on ESP32/ESP32-S3 (runner, perf monitor, allocator, build script, docs, sdkconfigs, partition table).
Add an esp-baremetal CMake preset and corresponding preset file for cross-compiling ExecuTorch for ESP targets.
Adjust threadpool TSAN thread-limit constant type to match the detected thread-count type.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
tools/cmake/preset/esp_baremetal.cmake	New build preset configuration for ESP baremetal/cross builds.
CMakePresets.json	Registers `esp-baremetal` configure preset.
extension/threadpool/threadpool.cpp	Uses `decltype(result)` for TSAN thread-limit constant type alignment.
examples/espressif/README.md	ESP32/ESP32-S3 usage and build instructions.
examples/espressif/build.sh	Helper script to generate model header and build via `idf.py`.
examples/espressif/project/CMakeLists.txt	ESP-IDF example project wiring and component path setup.
examples/espressif/project/main/CMakeLists.txt	ESP-IDF main component registering `main.cpp`.
examples/espressif/project/main/main.cpp	Example `app_main()` that calls `executor_runner_main()`.
examples/espressif/project/sdkconfig.defaults	Default ESP-IDF config for the example.
examples/espressif/project/sdkconfig.defaults.esp32s3	ESP32-S3-specific defaults (Octal PSRAM, etc.).
examples/espressif/project/partitions.csv	Example partition table for the ESP-IDF project.
examples/espressif/executor_runner/CMakeLists.txt	ESP-IDF component definition + linkage to prebuilt ExecuTorch libs; optional ETDump/BundleIO.
examples/espressif/executor_runner/esp_executor_runner.cpp	Core ESP runner implementation (PAL hooks, memory pools, model loading, execution loop).
examples/espressif/executor_runner/esp_perf_monitor.h	Perf monitor API for cycle/time measurement.
examples/espressif/executor_runner/esp_perf_monitor.cpp	Perf monitor implementation using ESP-IDF timers/cycle counter.
examples/espressif/executor_runner/esp_memory_allocator.h	Instrumented allocator wrapper for tracking used/free bytes.
examples/espressif/executor_runner/esp_memory_allocator.cpp	Implementation of tracked allocator.
examples/espressif/executor_runner/pte_to_header.py	Utility to convert `.pte` into a compiled-in C header array.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

examples/espressif/project/main/main.cpp

+#include <stdio.h>
+#include "sdkconfig.h"
+#include "freertos/FreeRTOS.h"
+#include "esp_system.h"
+
+extern void executor_runner_main(void);
+
+extern "C" void app_main(void) {
+    printf("Starting executorch runner !\n");
+    fflush(stdout);
+    // Custom initialization here
+    executor_runner_main();
+    for (int i = 5; i >= 0; i--) {
+        vTaskDelay(1000 / portTICK_PERIOD_MS);
+    }


examples/espressif/executor_runner/esp_perf_monitor.cpp

+uint64_t start_cycle_count = 0;
+int64_t start_time_us = 0;
+
+} // namespace
+
+void StartMeasurements() {
+  start_cycle_count = esp_cpu_get_cycle_count();
+  start_time_us = esp_timer_get_time();
+}
+
+void StopMeasurements(int num_inferences) {
+  uint64_t end_cycle_count = esp_cpu_get_cycle_count();
+  int64_t end_time_us = esp_timer_get_time();
+
+  uint64_t total_cycles = end_cycle_count - start_cycle_count;
+  int64_t total_time_us = end_time_us - start_time_us;


examples/espressif/executor_runner/esp_executor_runner.cpp

+  // Load model from filesystem
+  // Use a temporary allocator for the file loading
+  EspMemoryAllocator file_allocator(
+      method_allocation_pool_size, method_allocation_pool);
+  auto [buffer, buffer_size] =
+      load_file_from_fs("/spiffs/model.pte", file_allocator);
+  if (buffer == nullptr) {
+    ET_LOG(Fatal, "Failed to load model from filesystem.");
+    return;
+  }
+  model_pte = buffer;
+  model_pte_size = buffer_size;
+  pte_size = buffer_size;


examples/espressif/executor_runner/esp_executor_runner.cpp

+  auto read_size = fread(buffer, 1, size, fp);
+  if (read_size != size) {
+    ET_LOG(
+        Info,
+        "Partial read of %s: got %lu of %lu bytes",
+        filepath,
+        static_cast<unsigned long>(read_size),
+        static_cast<unsigned long>(size));
+  }
+  fclose(fp);
+  return std::make_pair(buffer, read_size);
+}


examples/espressif/executor_runner/esp_executor_runner.cpp

+
+#if defined(ET_LOG_DUMP_INPUT)
+  {
+    std::vector<EValue> inputs((*ctx.method.value())->inputs_size());


examples/espressif/executor_runner/esp_executor_runner.cpp

+    const char* etdump_filename = "/spiffs/etdump.bin";
+    ET_LOG(Info, "Writing etdump to file: %s", etdump_filename);
+    FILE* f = fopen(etdump_filename, "w+");
+    if (f) {
+      fwrite((uint8_t*)result.buf, 1, result.size, f);
+      fclose(f);
+    } else {
+      ET_LOG(Error, "Could not open %s for writing", etdump_filename);
+    }


examples/espressif/executor_runner/pte_to_header.py

+    if args.section == "none":
+        # No section attribute - let the linker/compiler decide placement.
+        # On ESP32 with PSRAM, the compiler/linker or EXT_RAM_BSS_ATTR
+        # in the code handles placement.
+        attr = "__attribute__((aligned(16))) const unsigned char "
+    else:
+        attr = f'__attribute__((section("{args.section}"), aligned(16))) const unsigned char '
+    if not os.path.exists(args.outdir):
+        os.makedirs(args.outdir)
+    with open(args.pte, "rb") as fr, open(outfile, "w") as fw:
+        data = fr.read()
+        hexstream = binascii.hexlify(data).decode("utf-8")
+
+        fw.write(
+            "/* Auto-generated model header for ESP32 ExecuTorch runner. */\n"
+        )
+        fw.write(f"/* Source: {os.path.basename(args.pte)} ({len(data)} bytes) */\n\n")
+        fw.write("#pragma once\n\n")
+        fw.write(attr + "model_pte[] = {")
+


examples/espressif/README.md

+| Chip     | CPU           | Internal SRAM | PSRAM (optional) |
+|----------|---------------|---------------|------------------|
+| ESP32    | Xtensa LX6 (dual-core, 240MHz) | ~520KB | 4-8MB |
+| ESP32-S3 | Xtensa LX7 (dual-core, 240MHz) | ~512KB | 2-32MB (Octal) |


jpiat added 9 commits March 17, 2026 08:53

Added an example executor runner for espressif

b21a1fd

Changed build to generate the model header in the project dir and hav…

52f13f3

…e it included in runner

Fixed some compile error. Should probably be fixed differently to dis…

dee4c8d

…play correct error messages

Added default configuration for esp-baremetal

1978162

Fixed README for lib compilation

7d6a0de

Updated CMake to cope with executorch find package issue in esp idf

fcffd84

First inference ran ! Need a ESP32 with at least 8MB of RAM.

1d89f39

Adjusted example for selective build to save on flash

0ec941d

Modified README to inform user about which platform is really supported

0f29967

jpiat requested a review from larryliu0820 as a code owner March 17, 2026 07:59

Copilot AI review requested due to automatic review settings March 17, 2026 07:59

jpiat requested a review from kirklandsign as a code owner March 17, 2026 07:59

Copilot started reviewing on behalf of jpiat March 17, 2026 08:00 View session

Copilot AI reviewed Mar 17, 2026

View reviewed changes

pytorch-bot bot added the release notes: examples Changes to any of our example LLMs integrations, such as Llama3 and Llava label Mar 17, 2026

meta-cla bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Mar 17, 2026

Fix README.md for clearer instructions

c363a73

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings March 17, 2026 08:24

Copilot started reviewing on behalf of jpiat March 17, 2026 08:24 View session

Copilot AI reviewed Mar 17, 2026

View reviewed changes

jpiat added 2 commits March 17, 2026 09:38

Applied some of the suggested copilot modifications

1a7b28b

Fixing issue with min function not taking different type on its input…

3a3c888

… on xtensa.

Copilot AI review requested due to automatic review settings March 17, 2026 10:32

jpiat requested a review from kimishpatel as a code owner March 17, 2026 10:32

Copilot started reviewing on behalf of jpiat March 17, 2026 10:32 View session

Casting result of processors_count instead of forcing type on second …

ba1c8d4

…argument.

Replaced static_cast with decltype to have tsan_thread_limit always m…

e5dc87c

…atching result type

Copilot AI reviewed Mar 17, 2026

View reviewed changes

jpiat added 2 commits March 17, 2026 12:32

Fixed some issue reported by copilot

43f6c37

Added typo fix in CMake and improved README

34a42c7

Copilot AI review requested due to automatic review settings March 17, 2026 11:47

Copilot started reviewing on behalf of jpiat March 17, 2026 11:48 View session

Copilot AI reviewed Mar 17, 2026

View reviewed changes

nil-is-all added the module: microcontrollers For embedded MCUs like Cortex-M, or RTOS like Zephyr, does not track NPU backend like Arm Ethos. label Mar 17, 2026

rascani self-requested a review March 17, 2026 17:42

Conversation

jpiat commented Mar 17, 2026 • edited by pytorch-bot bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

pytorch-bot bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/18224

❌ 10 Awaiting Approval, 1 New Failure

Uh oh!

meta-cla bot commented Mar 17, 2026

Action Required

Process

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jpiat commented Mar 17, 2026

Uh oh!

meta-cla bot commented Mar 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jpiat commented Mar 17, 2026 •

edited by pytorch-bot bot

Loading

pytorch-bot bot commented Mar 17, 2026 •

edited

Loading