XiaoZhi ESP32 Firmware v2.5 Explained: ESP-IDF 6, Full-Matrix Releases and Hardening

October 23, 2026

Between July and October 2026 the upstream firmware repository 78/xiaozhi-esp32 shipped v2.4.x and v2.5.x. Only three things in that run change what you actually do: building from source now requires ESP-IDF 6, prebuilt firmware is published differently, and the protocol implementations gained a batch of validation. This article walks through the releases; every item names the commit or document it comes from so you can verify it yourself.

Versions are assigned by the first tag that contains a commit. Numbers come from the v2.5.2 tag and that release’s manifest. Upstream keeps moving, so treat the official releases page as the source of truth.

1. The short version

Who you are	What to do
You only want to flash ready-made firmware	Pick your board’s variant on the Firmware Download page; no development environment needed
You build the firmware yourself	Install ESP-IDF v6.0.1 or later (the `release/v6.1` branch is recommended). ESP-IDF 5.x is no longer supported; see ESP-IDF Setup
You maintain a custom board	Board code must follow ESP-IDF 6; see Migrating a Custom Board to ESP-IDF 6
You run your own server or write a client	The protocol docs were updated; see WebSocket and MQTT + UDP

2. Release timeline

Version	Main changes	Source
v2.4.0	Migration to ESP-IDF 6.0, followed by hardening	`3e78cd7` (#2120), `0f6c435` (#2123)
v2.4.2	ESP32-S31 board support	`3e86f0a` (#2151)
v2.5.0	ESP-IDF 5.x support removed; streamed notify playback; string length validation and JSON-RPC error codes in MCP; Brazilian Portuguese UI language	`4a5d446`, `bb9122a` (#2191), `acb2fc7` (#1847), `d68505f` (#2243)
v2.5.2	Manually triggered full-matrix firmware release workflow; WebSocket and OTA security fixes; IP101 Ethernet driver migrated to ESP-IDF 6	`49b4380` (#2302), `d436097`, `f05adce`, `d395220`

PROJECT_VER in v2.5.2 is 2.5.2.

3. Build: the move to ESP-IDF 6

One large migration: commit 3e78cd7 touches 119 files, including board driver headers, dependency versions and audio codecs. Board-level changes are covered in the migration article.
Version requirement: main/idf_component.yml declares idf: '>=6.0.1'; the upstream README recommends the release/v6.1 branch and says ESP-IDF 5.x is no longer supported.
One known issue: the README warns against the v6.1 release tag, which has reports of Wi-Fi initialization failures on ESP32-C3 (issue #2344).
Switching SDKs: run git submodule update --init --recursive, reload export.sh, then run idf.py fullclean. Details are in ESP-IDF Setup.
ESP32-S31: variants for this chip need ESP-IDF 6.1 or later.

4. Release: the full-matrix firmware workflow

Commit 49b4380 added a manually triggered Release Firmware workflow, documented in upstream docs/releasing.md:

it builds every release variant supported by ESP-IDF 6.1 with scripts/build.py <board> --name <variant> --zip;
each variant produces v<version>_<variant>.zip containing a single merged-binary.bin;
the release also carries release-manifest.json (the full variant list) and SHA256SUMS for all archives.

The v2.5.2 manifest records 154 board directories and 188 firmware variants, built with ESP-IDF 6.1.0. See Supported Boards for the full list.

The upstream README still says “138 board directories and 171 release variants”, which is older than the manifest. This site follows the manifest. After downloading, verify archives against SHA256SUMS.

5. Features and protocol

Streamed notify: bb9122a adds streamed playback so the device can asynchronously play voice notifications pushed by the server outside a conversation. See Asynchronous Voice Notifications.
Glyph Push: the server can push glyphs that are missing from the local font. See Glyph Push.
MCP validation: the device-side MCP server validates the max_length of string arguments and returns JSON-RPC error codes. See the MCP protocol.
ESP32-P4: each P4 build is split into a rev < 3 variant and a -p4x variant (b7dc88f).
UI languages: the pt-BR locale was added (d68505f).

6. Security hardening

These are the hardening points stated in the upstream commit messages:

Area	Change	Source
MQTT	Validates the session id of the goodbye message	`e182471` (#2023)
WebSocket	If the server hello carries a non-string `transport`, the old code called `strcmp` on a null pointer and the device panicked; the type is now checked first	`d436097` (#2247)
OTA	Rejects unsafe eFuse serial numbers	`f05adce`
Encryption	MQTT and BluFi encryption moved to PSA Crypto	upstream README, “Recent updates”

All of these are included in v2.5.2.

7. Documentation changes

Upstream docs/ is now English-first, with Chinese versions named *_zh.md. New or heavily revised documents include custom-board, websocket, mqtt-udp, mcp-protocol, mcp-usage, blufi, glyph-push, notify and releasing. The matching pages on this site were rewritten for v2.5.2:

Sources

Upstream tags v2.5.2 and v2.5.0: commit history, README.md, docs/releasing.md and main/idf_component.yml.
Checked on 2026-10-23. Send corrections to [email protected].

Migrating a Custom Board to ESP-IDF 6: Lessons from the Upstream Migration Commit [Open Source DIY] Building Your Personal AI Assistant with Xiaozhi-ESP32