First Boot: Wi-Fi Setup, Activation and Binding

The first time a XiaoZhi device is powered on, it goes through three steps in order: connect to Wi-Fi, check in with the server and check the firmware version, and bind to your account with an activation code. This page follows the actual firmware v2.5.2 code and explains what the device is doing at each step, what you will see, and what to do when it gets stuck.

Overview

1. After power-on, the device checks whether any Wi-Fi network is saved. If none is, it enters configuration mode. If one is saved, it tries to connect, and returns to configuration mode if it has not connected within 60 seconds.
2. Once online, the device enters the “Activation” state and asks the OTA URL for version information.
3. If the server returns a new firmware, the device upgrades first. If it returns an activation code, the device shows and reads out the code.
4. You enter the code in the console to complete binding. The device then loads the communication settings, goes to standby, and plays a success sound.

Step 1: Wi-Fi Setup

When the Device Enters Configuration Mode

• No Wi-Fi network has been saved (first boot).
• The saved network could not be reached within 60 seconds.
• You press the board’s setup button during startup. The button depends on the board. For example, bread-compact-wifi enters setup when you click the BOOT button during startup; for other boards, see the README in the matching directory under main/boards/.

Hotspot Setup (Default)

The firmware uses hotspot setup by default (menuconfig WiFi Configuration Method → Hotspot, enabled by default).

1. The screen and voice announce the configuration mode. The text includes the hotspot name and the configuration URL, such as Xiaozhi-XXXX and 192.168.4.1. The hotspot name starts with Xiaozhi-, followed by the last two bytes of the device MAC address; use what the screen shows.
2. Connect your phone to that hotspot and open 192.168.4.1 in a browser. The hotspot is an open network with no password and accepts up to 4 devices, so finish setup promptly in a trusted place.
3. Choose your router and enter its password. Most chips support 2.4 GHz only; ESP32-C5 also supports 5 GHz.
4. After you save, the device leaves configuration mode and reconnects with the new credentials.

The Advanced tab of the setup page offers an OTA URL, the Wi-Fi transmit power, and the Wi-Fi sleep mode (the firmware decides whether the OTA URL and sleep fields are shown; v2.5.2 shows both). An OTA URL entered there replaces the default, and the device then requests version and activation information from that address. Enter only servers you trust.

BluFi Setup

BluFi is selected when the firmware is built and cannot be enabled together with hotspot setup. When enabled, the device advertises the Bluetooth name Xiaozhi-Blufi, and a client such as EspBlufi sends the Wi-Fi credentials. See the BluFi setup guide for configuration.

Step 2: Version Check

After going online, the firmware sends a request to the OTA URL. The URL comes from the setup page if you set one there; otherwise it is the value of the menuconfig option Default OTA URL (CONFIG_OTA_URL). The request carries device identity headers: Device-Id (MAC address), Client-Id (device UUID), Activation-Version, User-Agent, and Accept-Language. Devices that read a valid eFuse serial number also send Serial-Number.

The JSON response may contain:

If there is no activation field, the device treats itself as not needing activation and continues starting up.

Step 3: Activation and Binding

1. When the response contains an activation code, the device shows the server’s prompt text on screen, plays a prompt sound, and then reads the digits of the code one by one.
2. Sign in to the official console and follow its instructions to enter the code and bind the device to your account.
3. While you do this, the device keeps posting a reply to <OTA URL>/activate. A device with an eFuse serial number sends an hmac-sha256 result (the challenge signed with the eFuse HMAC key); other devices send an empty object. The server answers 200 for success or 202 for “not bound yet” (the device waits 3 seconds and retries); any other status makes the device wait 10 seconds and retry.
4. One round makes at most 10 attempts. If activation is still incomplete, the device goes back to the version check and starts another round; always use the code most recently shown on screen.
5. After activation, the device initializes the communication protocol from the server’s settings (it defaults to MQTT when the response has none), shows the version number, and plays a success sound. You can then start a conversation.

Troubleshooting

Related Reading

• Firmware download and flashing
• Network setup
• FAQ
• BluFi setup guide

Sources: 78/xiaozhi-esp32 v2.5.2 files wifi_board.cc, ota.cc, application.cc, and Kconfig.projbuild, plus the README of the provisioning component 78/esp-wifi-connect.