ESP-WHO: Espressif's example platform for face detection and recognition on an ESP32 chip

What ESP-WHO is: a directory of examples rather than a library

ESP-WHO describes itself as an image processing development platform based on Espressif chips, and the repository layout backs up the narrower reading. `examples/` holds five directories: `human_face_recognition/`, `object_detect/`, `object_tracking/`, `pp_ocr_v6/` and `qrcode_recognition/`. There is no `src/` directory, no versioned package manifest, and nothing that reads like a published library API. The README's instruction is to enter the corresponding folder under `examples/` and build from there.

That distinction decides how you should treat the project. If you are looking for something to add to a dependency list, this is the wrong shape. If you are looking for a complete, working program that talks to a camera on an ESP32-S3 or ESP32-P4 and runs a neural network over the frames, the examples are exactly that, with `components/`, `default_bin/`, `tools/` and `docs/` supplying the shared pieces. Each example also carries its own `sdkconfig.bsp.*` default configuration file, which is why the build command takes a board name as an argument.

Exporting IDF_EXTRA_ACTIONS_PATH is the first build step

The quick start begins with an environment variable rather than a clone command, which is unusual and worth understanding. ESP-WHO registers custom idf.py actions through a `tools/` directory in the repository, and `IDF_EXTRA_ACTIONS_PATH` is the variable ESP-IDF reads to find them. On Linux or macOS:

export IDF_EXTRA_ACTIONS_PATH=/path_to_esp-who/tools/
echo $IDF_EXTRA_ACTIONS_PATH

The same variable has three different spellings depending on your shell. PowerShell uses `$Env:IDF_EXTRA_ACTIONS_PATH="..."` and cmd.exe uses `set IDF_EXTRA_ACTIONS_PATH=...`, then `echo %IDF_EXTRA_ACTIONS_PATH%` to confirm. The README marks the verification step as important, and it is right to: a wrong path here fails later, at the point where idf.py cannot resolve the board configuration, and the error message will not point back at the environment variable.

Worth noting for anyone new to Espressif tooling, the repository also carries `.gitlab-ci.yml` and `.gitlab/` alongside `.github/`, plus a `.pre-commit-config.yaml` and a `.clang-format`. This is an internally mirrored codebase rather than a community project, and the mixed CI configuration is a small hint at how changes are reviewed.

Pointing set-target at a board-specific sdkconfig and flashing

Once the variable is set, the actual build is three commands. The first selects the chip and the default configuration file, where `bsp_name` is the board support package name you found in the example's `sdkconfig.bsp.*` files:

idf.py -DSDKCONFIG_DEFAULTS=sdkconfig.bsp.bsp_name set-target esp32xx

Under PowerShell the same command needs the defaults value quoted, which the README calls out explicitly: `idf.py -DSDKCONFIG_DEFAULTS="sdkconfig.bsp.bsp_name" set-target "esp32xx"`. Getting that wrong produces a confusing failure on Windows rather than an obvious one, so it is worth copying the shell-specific form.

Then `idf.py menuconfig` opens the interactive configuration screen if you need to change options, and the flash step builds, writes and attaches a monitor in one go:

idf.py [-p port] flash monitor

The port argument is optional, and the README explains that without it idf.py scans every port it can find. For a board with an onboard USB serial converter that is usually fine. For a bare module on an external adapter, pass `-p` explicitly, because the scan will happily pick the wrong device.

The refactor onto ESP-DL dropped the ESP32 examples you may remember

The `What's new` section is short and it matters. The repository has been fully refactored to adapt to a new version of ESP-DL, ESP32-P4 support was added, and camera capture and the deep learning model now run asynchronously, which the README credits with higher frame rates. LVGL was added so you can build a graphical application on top, and a new pedestrian detection model came with it.

The catch sits one paragraph later. Some chips such as esp32 and esp32-s2 are not available on this branch, and neither are examples such as cat face detection and color detection. The README points those to an older branch at `release/v1.1.0`. So the same repository name describes two substantially different codebases depending on which branch you check out, and searching for a cat face detection example will land you in code that does not build against current ESP-IDF.

The supported ESP-IDF range is a table with four columns: release/v5.4, release/v5.5, release/v6.0 and release/v6.1, all checked. That is a wide span and it is unusual to see it. In practice it means the code targets more than one major IDF generation, so expect some friction around newer driver APIs even where the checkbox says supported.

Hardware requirements are the real constraint, not the code

Only three boards are listed in the support table, and each is a fairly complete device rather than a bare module. The ESP32-P4 Function EV Board is listed with an es8311 audio codec for both microphone and speaker, an ek79007, ili9881c and lt8912b display path, a uSD card and a gt911 touch panel. The ESP32-S3-EYE has an st7789 display, an IMU, a camera and a uSD card. The ESP32-S3-Korvo-2 has es7210 and es8311 audio, an ili9341 display and an LED array.

That list is the honest answer to whether your board works. There is no generic ESP32 board row, so an inexpensive ESP32-S3 dev kit with a DVP camera will not simply work by pointing sdkconfig at it. You would need to supply the camera driver, the display driver and the board configuration yourself, which means leaving ESP-WHO and assembling the parts from the four repositories it names: ESP-DL for models, ESP-BSP for board peripherals, ESP32_CAMERA for the camera driver, and ESP_VIDEO_COMPONENTS for video.

This is a real limitation for anyone hoping to use ESP-WHO as a component. The dependency sprawl is the price of the example being end to end. If you already run ESP-BSP for your board and you have a working camera pipeline, you may only need the ESP-DL model wrapper and can skip most of this.

Where the README stops and the docs directory starts

The README is a build guide and a board list. Everything about what the code actually does lives in `docs/`, and the repository ships an English and a Chinese README as separate files linked from the top. Peripherals get one link each to external documentation rather than an explanation here, which is the right call technically and the wrong one if you are trying to decide whether an example fits your product.

Release history is thin and the version line is confusing. The two releases on the repository are v0.9.0 from 2019-01-03, named Face recognition and speech wake up for esp-eye, and v0.5.0 from 2018-12-03. Both predate the ESP-DL refactor described in the README, and both document an ESP-EYE board workflow that no longer matches the current branch. The last push was on 2026-08-21 and the repository is not archived, so the code moves, but the tags do not describe it.

So the practical reading order is: the README for the build, `docs/en/get-started/` for a specific board, and the ESP-DL repository for models. If you are evaluating this for production, the questions the README leaves open are model memory footprint on your chip, licensing of the shipped weights, and whether the asynchronous pipeline behaves under sustained load. None of those are answered here.

Editorial conclusion

ESP-WHO is worth reading when you are standing in front of a camera and an ESP32 and need a working answer within an afternoon. The `idf.py` path is real, the examples are complete enough to flash, and the board support table tells you which parts of the repository you can actually run today. It is not a pip or npm install, and the framework is deliberately thin: models come from ESP-DL, board bring up comes from ESP-BSP, and the camera driver comes from a separate repository. The current `master` branch is the one to use, and the older `release/v1.1.0` branch is what you want only if you need the ESP32 and ESP32-S2 examples, including cat face and color detection, that were dropped during the refactor.

Frequently asked questions

Official sources

1. espressif/esp-who on GitHub
2. Issues
3. README
4. Releases