esp-tflite-micro: TensorFlow Lite Micro packaged for the ESP-IDF

A vendor package around the upstream TFLite Micro tree

esp-tflite-micro exists because TensorFlow Lite Micro, the upstream inference library, is not packaged for the Espressif environment. Following the vendor support guidelines for TFLite Micro, this repository holds an esp-tflite-micro component plus the examples needed to run TensorFlow Lite Micro on Espressif chipsets, for example the ESP32-P4, using the ESP-IDF platform. The upstream project is a separate repository, and this one is the Espressif wrapper around it.

The component is a normal ESP-IDF component. The repository carries idf_component.yml and a Kconfig file, a CMakeLists.txt at the root, a signal directory, a scripts directory, and a tensorflow directory holding the copied library alongside a third_party directory. The examples live in examples/ and there are three of them: hello_world, micro_speech and person_detection.

Two facts about the repository shape matter for anyone planning an upgrade. There are no GitHub releases at all, so there is no versioned artefact to pin, and the tensorflow directory is a copy rather than a submodule reference. The component does have a Component Registry badge, so it is distributed through the Espressif component registry rather than only as a git clone.

The supported ESP-IDF branch list is explicit

The component tracks the ESP-IDF support period policy, and the project publishes the resulting table. release/v6.0, release/v5.5, release/v5.4, release/v5.3 and release/v5.1 are all marked supported, release/v5.2 is supported but explicitly not covered by CI, and release/v5.0 and below are end of life and unsupported.

That table is the single most useful fact for an adopter, because it defines the upgrade window. A project on release/v5.0 has to move before it can use this component at all, while a project on release/v5.2 gets a working component without CI coverage for that branch, which means regressions in that combination surface locally rather than in the project's own pipeline. The examples build is tracked by a GitHub Actions workflow, and the repository also carries a .gitlab-ci.yml and a .pre-commit-config.yaml, so the project runs more than one CI system and expects commits to be checked before they land.

Because the support window moves with Espressif's own policy rather than with this repository, an adopter who wants a long-lived product has to watch the upstream IDF schedule as well as the component.

Adding the component and pulling an example project

The prerequisite is a working ESP-IDF installation. The project points at the ESP-IDF get started guide for the toolchain, and states two assumptions for the steps that follow: that the IDF environment variables are set, specifically that IDF_PATH is set, and that the idf.py and Xtensa-esp32 tools such as xtensa-esp32-elf-gcc are in $PATH.

Inside an existing ESP-IDF project, the component is added with a single command:

idf.py add-dependency "esp-tflite-micro"

A standalone example project is created the same way, with the component name and the example name:

idf.py create-project-from-example "esp-tflite-micro:<example_name>"

If the repository has already been cloned, the examples come with it, and the instruction is to go into the example directory, examples/<example_name>, and build there. The three available examples are hello_world, micro_speech and person_detection, which cover the range from a minimal inference to a keyword spotting model and a camera based detector.

One convenience is worth knowing about before you wire up hardware. A board specific quick flash entry is listed for the ESP32-S3-EYE with the person detection example, pointing at an ESP Launchpad configuration for that board.

Setting the target, building, flashing and watching the serial output

The build sequence is the standard idf.py flow. The target chip is selected first, for example:

idf.py set-target esp32p4

and the project is then compiled:

idf.py build

Writing the image to hardware needs the device serial port, and the documented example uses the Linux device node, noting that it should be replaced with the port of your own board:

idf.py --port /dev/ttyUSB0 flash

The same port is used to watch the serial output, and the monitor is exited with Ctrl+]:

idf.py --port /dev/ttyUSB0 monitor

Flash and monitor can be issued together, which is what you want when the first run of an example decides whether the model loaded:

idf.py --port /dev/ttyUSB0 flash monitor

The project defers the details of what each example does to the per example documents, which is reasonable for the general instructions and means the model, the input source and the expected output of any single example are documented next to its code rather than in the top level file.

ESP-NN is compiled in by default, and the speedup is large

The performance story in this repository comes from ESP-NN, a separate Espressif library of optimized kernel implementations for the kernels TFLite Micro uses. It is integrated with this repository and is compiled as part of every example, so it is not something a user has to opt into.

The project publishes a comparison of the person detection example across four chips, measuring the time taken for the invoke() call, along with the CPU frequency used:

| Target | Without ESP-NN | With ESP-NN | CPU Freq | | ESP32-P4 | 1395ms | 73ms | 360MHz | | ESP32-S3 | 2300ms | 54ms | 240MHz | | ESP32 | 4084ms | 380ms | 240MHz | | ESP32-C3 | 3355ms | 426ms | 160MHz |

These are the project's own measurements, and the notes attached to them matter as much as the numbers. The P4 optimisation is described as work in progress, and the without ESP-NN column is produced by completely disabling the library by removing a flag from CMakeLists.txt:

      # enable ESP-NN optimizations by Espressif
      target_compile_options(${COMPONENT_LIB} PRIVATE -DESP_NN)

The scaling is uneven across chips, from roughly a 19x improvement on the P4 to about 42x on the S3 and close to 10x on the plain ESP32, so a chip-specific expectation is worth forming rather than assuming a single multiplier.

The upstream library is copied in, and there is a script to refresh it

Under the upstream repository policy, the tflite-lib is copied into the components directory of this repository, and the maintainers update that copy to the latest upstream version from time to time. The consequence for a user is that the TensorFlow code in the tree is a copy, not a live reference, so the version in use has to be read from the copied tree rather than assumed to match the upstream head.

For anyone who needs to move ahead of the vendored copy, the project names a script for it, scripts/sync_from_tflite_micro.sh, which is run from the repository root.

This is the mechanism behind the component's main maintenance risk. A copy that is refreshed from time to time means a change in upstream can land in your build without appearing in this repository's own change list, and if the copied code interacts badly with the ESP-NN kernels, the diagnosis happens inside a diff you did not write. The pre-commit configuration and the CI workflows are what stand between that and a broken build.

The licensing reflects the same split. The component and its examples are under Apache 2.0 with details in the LICENSE file, while the TensorFlow library code and the third_party code keep their own licences under their respective repositories. A product that ships this has to account for both.

Where this component is the wrong choice

The first limitation is version pinning. There are no GitHub releases, so there is no artefact to lock onto, and the component's lifetime is tied to the ESP-IDF branches in the support table rather than to a version of its own. A team that needs a reproducible, auditable dependency for a shipping product has to vendor the component itself and manage the update, which is exactly the work the component registry entry is supposed to save you from.

The second is the scope of what is provided. The three examples are a starting point, not a library of models, and each example's details live in its own document. There is no model zoo here, no accuracy figures for the speech or detection models, and no documented way to convert your own model into something these examples accept, so the conversion path has to come from the upstream TFLite Micro project.

The third is the alternative that is often better. ESP-NN is published as its own library with its own performance documentation, and using its kernels directly means writing your own inference loop and buffer management instead of adopting an interpreter and a model format. That is more work up front and less machinery in the shipped firmware, and for a fixed model on a fixed chip it is often the smaller total. The other alternative is the upstream tflite-micro repository built with its own CMake system, which keeps you on the newest upstream code but leaves the ESP-NN integration and the ESP-IDF packaging to you. Neither route is a free win, and the difference is whether you want an interpreter plus a model format, kernels plus your own loop, or a vendored component pinned to a branch you control.

Editorial conclusion

Adopt esp-tflite-micro if you are already inside the ESP-IDF toolchain, targeting a supported ESP32 variant, and want an inference runtime with the vendor kernels on rather than a general embedded machine learning stack you have to assemble yourself. Do not adopt it if your product needs a release you can pin, if you need an ESP-IDF version outside the supported list, or if you need control over upstream TFLite Micro changes, since the library is vendored into the tree. Before you start, confirm that your ESP-IDF branch is one of the supported ones, that the person_detection example reproduces the timing you need on your own chip and clock, and that the Apache 2.0 terms of this component sit alongside the separate TensorFlow and third_party licences it carries.

Frequently asked questions

Official sources

1. espressif/esp-tflite-micro on GitHub
2. Issues
3. License: Apache-2.0
4. README