XiaoZhi AI Chatbot Documentation Center | XiaoZhi.Dev
Usage Guide
Network Configuration Guide

Network Configuration Guide

This page explains how a XiaoZhi device can get online, how Wi-Fi is configured, and what to do when you need to change networks. For the complete first-boot flow, including the activation code and binding, see First Boot: Wi-Fi Setup, Activation and Binding.

Connectivity Options

What is available depends on the board hardware:

  • Wi-Fi: the most common option.
  • Wired Ethernet and USB RNDIS.
  • Cat.1 4G modules: ML307, EC801E, or NT26. Some hardware can switch between Wi-Fi and 4G, and the way to switch depends on the board. For example, yunliao-s3 switches when you double-click the button within 1 second during startup or on the setup screen.

Wi-Fi Provisioning Methods

MethodDescriptionHow to enable
Hotspot (default)The device opens a hotspot named Xiaozhi-XXXX; connect your phone and pick your router on a web pagemenuconfig WiFi Configuration Method → Hotspot, on by default
BluFi (BLE)The device advertises the Bluetooth name Xiaozhi-Blufi; a client such as EspBlufi sends the Wi-Fi detailsEnable ESP-BluFi and turn off Hotspot; see the BluFi setup guide

The two methods cannot be enabled together in one firmware. The hotspot steps are described in First Boot.

Network Requirements

  • Band: most chips use 2.4 GHz only. Chips with 5 GHz support (such as ESP32-C5) pick the band automatically.
  • Saved networks: the device keeps up to 10 Wi-Fi networks. When several routers share a name (for example in a mesh network), it connects to the one with the strongest signal.
  • Connection timeout: if a saved network cannot be reached within 60 seconds, the device returns to configuration mode.
  • Hotspot security: the setup hotspot is an open network with no password and accepts up to 4 devices. Set up Wi-Fi in a trusted place.

Re-provisioning

When a Wi-Fi network is already saved, the device does not enter setup on its own. To change networks:

  • Press the board’s setup button during startup. The button depends on the board: bread-compact-wifi uses a single click on BOOT; for other boards, see the README in the matching directory under main/boards/.
  • Some boards provide an MCP tool named self.disp.network (“reconfigure network”).
  • If the old network disappears or its password changes, the device enters configuration mode on its own after 60 seconds of failed connection attempts.

Advanced Settings

The Advanced tab of the setup page lets you set the 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). The OTA URL decides which server the device asks for version and activation information, so enter only servers you trust.

Troubleshooting

Start with First Boot: Troubleshooting. If the device still cannot get online:

  • Make sure the router uses 2.4 GHz and that the name and password are correct.
  • Move the device closer to the router to rule out signal and obstruction issues.
  • Read the device’s serial log to see why the connection failed.
  • See the FAQ for more.

Sources: 78/xiaozhi-esp32 v2.5.2 files README.md, wifi_board.cc, and docs/blufi.md, plus the provisioning component 78/esp-wifi-connect.

First Boot: Wi-Fi Setup, Activation and BindingSelf-Hosted Server: Connect XiaoZhi Devices to Your Own Server