XiaoZhi AI Chatbot Documentation Center | XiaoZhi.Dev
ESP32 Development Guide
Advanced Extension Points: Network Types, Wake Words, MCP and Asset Customization

Advanced Extension Points: Network Types, Wake Words, MCP and Asset Customization

Once basic board adaptation and chat work, the firmware offers several kinds of extension entry points. This page is navigation only: it says where each capability lives in the source and points to the detailed document, and it does not invent implementation plans without an upstream basis.

1. Network Types

main/boards/common/ provides base classes for different networks, and a concrete board inherits one of them:

Base classPurpose
WifiBoardWi-Fi networking; for provisioning see First Boot and Network Configuration
Ml307Board4G Cat.1 network through an ML307 module
DualNetworkBoardSwitches between Wi-Fi and ML307; the network type is stored in Settings, and the default comes from the board constructor parameter
EthernetBoard, RndisBoard, Nt26BoardBase classes for other network types; for usage, read the directories of the boards that use them

Boards such as bread-compact-ml307 are the reference implementation of ML307 4G. For wiring, see the 4G module part of the Hardware Build Guide.

2. Wake Words and Audio Processing

  • The wake word type is chosen by the Kconfig option WAKE_WORD_TYPE: AFE wake word, WakeNet without AFE, MultiNet custom wake word, or disabled. For the options of each chip, see Chip Support and Storage Specs.
  • Custom wake words have two paths: compile options (CUSTOM_WAKE_WORD and so on) or packing into assets.bin, see the Custom Assets Guide.
  • With SEND_WAKE_WORD_DATA enabled, the most recent two seconds or so of audio are sent to the server as the first message of the conversation after a wake-up (a PSRAM ring buffer, see main/audio/README.md).

3. MCP Tools

The device registers tools in main/mcp_server.* so a large language model can control it; some tools are user-only (such as self.assets.set_download_url). For how to register tools and the list of built-in tools, see MCP IoT Control Usage, and for the protocol flow see the MCP Protocol. A board can add tools in its own initialization code, for example bread-compact-esp32 uses LampController as a lamp control demo.

4. Notifications, Font Supplements and Emoji

5. Provisioning and Upgrade

  • BluFi Provisioning Guide: configure Wi-Fi over Bluetooth.
  • OTA version check, activation code and firmware upgrade are handled by main/ota.* and Application; see First Boot for the flow.
  • The assets partition can be upgraded independently of the firmware, see the Custom Assets Guide.

6. Power Management

Board defines three power-save levels, LOW_POWER, BALANCED and PERFORMANCE, implemented by the board-level SetPowerSaveLevel(); boards/common/ also provides helpers such as power_save_timer, sleep_timer and battery monitoring. Whether the device enters sleep is decided by Application::CanEnterSleepMode(). Concrete behavior differs from board to board, so read the source of your target board.

Related Documents

Sources: main/boards/common/, main/Kconfig.projbuild, main/mcp_server.cc and main/audio/README.md of 78/xiaozhi-esp32 v2.5.2.

Firmware Code Tour: Directory Layout, State Machine and Development RulesESP32 Development Troubleshooting