ESP-Drone: a Crazyflie port for Wi-Fi chips, and what the repository still says about it

A port, with the upstream commit pinned in the readme

ESP-Drone is described as an open source solution built on the Espressif ESP32, ESP32-S2 and ESP32-S3, controllable from a mobile app or a gamepad over Wi-Fi. The important sentence is the one that follows: the main code is ported from the Crazyflie open source project under the GPL3.0 protocol. That framing decides how to read the rest of the repository. You are not looking at an original flight stack written for Espressif silicon, you are looking at Bitcraze's stack with the radio link replaced.

A repository that keeps its provenance this plainly is worth crediting, and it makes the third-party table in the README the most load-bearing part of the documentation. Two rows matter. The flight controller under `core/crazyflie` comes from Crazyflie at tag `2021_01`, commit `b448553`, under GPL3.0. The DSP library under `lib/dsp_lib` comes from the esp32-lin project at commit `6fa39f4c`. Both are GPL3.0, which lines up with this repository's own GPL-3.0 license field, so the licensing story is at least internally consistent.

Those two commit identifiers are more useful than they look. If a flight behaviour looks wrong, the fastest path is usually to compare against Crazyflie at the same tag, because the port target is frozen at a 2021 release rather than tracking upstream. Anyone assuming the code tracks current Crazyflie main will waste time.

The repository itself carries 2,204 stars, 510 forks and 34 open issues, is written in C, is not archived, and had a push on 2026-08-10. The modest open-issue count for a repository of that size fits a project whose bug surface is bounded by the upstream it ports.

Six control modes, two of which need extra hardware

The README lists six features, and the ordering is a reasonable priority order for a new user. Stabilize mode is first, which is the sensible default attitude hold where the controller resists roll and pitch but does not try to hold altitude or position. Height-hold mode is second and position-hold mode third, and both carry the same caveat: extension boards are required, with the README directing readers to the hardware reference.

That caveat is the thing to internalise before buying anything. Height hold needs a reliable altitude estimate, position hold needs a position estimate, and on this hardware that usually means adding a barometer, a ranging sensor or a vision module on an expansion board. A bare ESP32 flight mainboard can stabilize, and that is where a first build should stop.

The last three features are about control paths rather than flight behaviour. App control is the mobile path, and the README links both the iOS and the Android source, in separate EspressifApps repositories, so the phone apps are readable and not a black box. The fifth feature is compatibility with cfclient, the Python client from the Crazyflie clients project, which means the port can be driven from a laptop with the same tooling used for real Bitcraze hardware. The sixth is ESP-BOX3 joystick control through esp-now, which is the odd one out: it uses the ESP-NOW peer-to-peer radio rather than Wi-Fi.

The esp-now path deserves attention because it is the one feature that does not fit the Wi-Fi framing in the intro paragraph. On hardware with an ESP32-S3 and enough peripherals on board, it is also the cheapest way to get a physical controller working without any network setup.

The toolchain constraint is a pinned ESP-IDF v5.0

The README is direct about this: use the ESP-IDF `release/v5.0` branch as the development environment. That is a specific pin, not a minimum version, and it is worth respecting exactly rather than trying v5.3 or a later IDF on the grounds that it should be compatible.

The repository layout supports the idea that this pin is load-bearing. There is a `.idf_build_apps.toml` at the root, which is the mechanism Espressif's CI uses to describe how a repository builds its apps, plus separate `sdkconfig.defaults.esp32s2` and `sdkconfig.defaults.esp32s3` files. Per-target default configurations only make sense when the two chips need different driver or peripheral settings, and they are the first place to look when a build behaves differently on an S2 than on an S3.

The remaining top-level entries are ordinary but informative: `CMakeLists.txt`, `components/`, `main/`, `hardware/`, `docs/`, `.gitlab-ci.yml` and `.pre-commit-config.yaml`. The `hardware/` directory is the one most newcomers underrate. There is a published schematic for the ESP32_S2 Drone V1.2 mainboard, linked from the README, so the board this firmware targets is a documented design rather than an assembly of loose parts. Matching your own hardware to that schematic is the shortest route to a stable hover.

The documentation situation is mixed, and honestly so. The README points readers to a docs site whose URLs are under a `zh_CN` path, which means the published getting-started material is Chinese first. The repository's own `docs/` directory exists, but the prose documentation is thin next to the code, so plan on reading component source rather than expecting architecture write-ups.

Limited support since December 2022, stated in the readme

There is no support policy section worth dressing up here, because the README says it in one line: from December 2022 the project offers limited support, while pull requests are still welcomed. That is the whole policy, and it is more useful than a longer document would be, because it tells a reader exactly what to expect from an issue and what to expect from a pull request.

The last recorded push is 2026-08-10. Whatever lands in that commit is best understood as opportunistic rather than scheduled, which is the normal pattern for a maintained-but-unsupported firmware port. The framework under it, ESP-IDF, moves fast and has had several major releases since the pinned v5.0 branch. A project built here is a project with an ageing toolchain pin, and the question of whether to migrate is a decision the framework's own release history forces rather than one the drone firmware has solved.

The 34 open issues are consistent with that reading. A repository where nobody is answering the queue still gets a small number of reports, mostly from people building the board for the first time and hitting the same hardware questions. It also means an issue you file is unlikely to get attention, so the realistic routes are the upstream project, the documentation site, or a pull request that carries its own diagnosis.

For the same reason, the absence of releases matters. There is no tagged v1.0, no changelog, and no version constant to check against. `master` is the only branch, which is convenient until you want to pin a working build for a class or a lab, at which point you should tag it yourself.

Where this fits against Crazyflie itself

The comparison is unavoidable because the code is Crazyflie's. Against the real thing, ESP-Drone trades radio range and determinism for Wi-Fi convenience. A Crazyflie uses its own 2.4GHz link with packet-level reliability guarantees designed for control traffic; this port runs control over Wi-Fi, which is a best-effort network with variable latency and occasional association gaps. For a classroom hover test that difference rarely matters. For anything beyond that, it is the whole ballgame.

What the port adds is integration. Wi-Fi means a browser or phone app is the natural controller, no bootloader radio is needed, and the ESP32-S3 and ESP32-P4 parts carry far more compute than a Crazyflie, which leaves room for on-board detection and streaming video work that the original platform is not shaped for.

What the port does not add is upstream movement. Because the port target is frozen at tag `2021_01`, there is no path where improvements to Bitcraze's estimator, allocator or sensor handling flow in automatically. Anyone who wants current Crazyflie behaviour is better off reading the upstream and porting the pieces they need, which for a C codebase with a clean component split is not as large a job as it sounds.

The honest summary is that ESP-Drone is a strong teaching and prototyping platform with a specific, documented board, and it is a poor basis for a product. Both statements come from the same two facts in the README: a Wi-Fi control link, and a 2021 upstream snapshot under limited support.

A first build, in the order that avoids wasted evenings

A sequence that tends to work starts before any code exists: get the ESP32_S2 Drone V1.2 schematic and confirm your board matches it, because the defaults in `sdkconfig.defaults.esp32s2` assume that layout. Then install ESP-IDF `release/v5.0` and confirm the toolchain builds something trivial for your target, so any later failure is in the drone firmware rather than in the environment.

With the environment proven, build for the simplest achievable goal: stabilize mode with a fixed or gently increasing throttle, no app, no gamepad, no expansion board. Stabilize mode needs no additional sensors, so it isolates the flight controller and the radio link from the estimator's extra inputs. Getting a stable attitude hold before adding altitude sensing saves the debugging effort that would otherwise be spent wondering whether a drifting hover is a bad barometer reading or a bad control loop.

Once attitude hold is boringly reliable, add one input path at a time. The cfclient path is attractive because it is Python and it is the tooling the upstream project already supports, which means the debugging experience transfers. App control is the better demonstration for a classroom, and the source for both mobile clients is public, so any surprise there is a client bug rather than a firmware mystery. The esp-now joystick path on ESP-BOX3 is the one to try last, since it uses a different radio path from everything else in the list.

Only after all of that is it worth asking whether height hold or position hold is worth the extension board cost. Both are listed as features, both need hardware the base board does not carry, and both are where the 2021 upstream snapshot is most likely to show its age.

Editorial conclusion

ESP-Drone is most useful read as a worked example of running a flight stack on a Wi-Fi SoC, since the port target is a Crazyflie 2021.01 tree with Wi-Fi control links in place of radio. A new project should clone it for the hardware bring-up path in `hardware/` and the sensor assumptions in `components/`, then build against ESP-IDF release/v5.0, because the maintainers have limited support to this project since December 2022 while still taking pull requests.

Frequently asked questions

Official sources

1. espressif/esp-drone on GitHub
2. Issues
3. License: GPL-3.0
4. README