verachen/xiaozhi-esp32
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
87f6faee795c19ca8cd29ba1d9cb628915ff1305
xiaozhi-esp32/docs/blufi.md
Terrence 87f6faee79 Update Chinese and English documentation for custom board setup and MCP protocol 
- Added a comprehensive guide for creating custom boards in the XiaoZhi AI project, detailing directory structure, configuration files, and initialization code.
- Introduced a new document explaining the MCP protocol for IoT control, including message formats and interaction flows.
- Updated existing documentation to reflect changes in tool registration and usage examples for the MCP protocol.
- Enhanced README files for better clarity and consistency across languages.
2026-04-17 03:36:37 +08:00

2.8 KiB
Raw Blame History

BluFi Provisioning (with esp-wifi-connect)

This document explains how to enable and use BluFi (BLE-based WiFi provisioning) in the XiaoZhi firmware, together with the in-tree esp-wifi-connect component that handles WiFi connection and credential storage. See the official Espressif BluFi documentation for the protocol details.

Prerequisites

  • A chip and firmware configuration that support BLE.
  • In idf.py menuconfig, enable WiFi Configuration Method -> Esp Blufi (CONFIG_USE_ESP_BLUFI_WIFI_PROVISIONING=y). If you want to use BluFi, disable the Hotspot option in the same menu; otherwise hotspot provisioning wins by default.
  • Keep the default NVS and event-loop initialization provided by the project's app_main.
  • Exactly one of CONFIG_BT_BLUEDROID_ENABLED / CONFIG_BT_NIMBLE_ENABLED must be selected; they are mutually exclusive.

Workflow

  1. A phone (using the official EspBlufi app or another BluFi client) connects to the device over BLE and sends the target WiFi SSID / password. The phone can also request the list of WiFi networks scanned by the device through the BluFi protocol.
  2. In ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP, the device stores the credentials into SsidManager (persisted in NVS by the esp-wifi-connect component).
  3. The device then launches WifiStation to scan and connect; progress is reported back over BluFi.
  4. If provisioning succeeds, the device connects to the new WiFi automatically. If it fails, an error status is sent back.

Steps

  1. Configure: turn on Esp Blufi in menuconfig, then build and flash the firmware.
  2. Trigger provisioning: at first boot with no stored WiFi credentials the device enters provisioning automatically.
  3. Phone side: open the EspBlufi app (or another BluFi client), scan and connect to the device, optionally enable encryption, then enter the WiFi SSID / password and send them.
  4. Observe the result:
    • Success: BluFi reports success and the device connects to WiFi.
    • Failure: BluFi reports failure; retry or check the router.

Notes

  • BluFi cannot be used at the same time as hotspot provisioning. If hotspot provisioning is already enabled, the device will use it. Keep only one provisioning method in menuconfig.
  • When running repeated tests, clear or overwrite the stored SSID (wifi NVS namespace) to avoid stale credentials interfering with the next run.
  • If you write your own BluFi client, follow the official protocol frame format linked above.
  • The EspBlufi app download links are listed in the official documentation.
  • Because the BluFi API changed in IDF 5.5.2, firmware built with 5.5.2 advertises the Bluetooth name as "Xiaozhi-Blufi", while 5.5.1 uses "BLUFI_DEVICE".