.. _xiaozhi_ai: ====================== 4.Xiaozhi AI Setup ====================== Use this page to configure the Xiaozhi backend, customize the assistant role, and use the local flashing workflow when the online flasher is not available. This project is based on `xiaozhi-esp32 `_. If you want to add your own features, continue with secondary development after the standard setup path is working. .. _xiaozhi_backend_setup: Backend Setup ============================================== Register a Xiaozhi Account ------------------------------------------ .. note:: Xiaozhi account registration may require a phone number and SMS verification. 1. Visit the AI Chatbot Management System: `Xiaozhi.me `_ 2. Click ``Console`` to enter the management backend. 3. Fill in the registration form: * Select your country or region. * Enter the phone number that will receive the verification code. * Complete the captcha. 4. Click ``Send Code`` and enter the SMS verification code to complete registration. 5. After registration, set a password in account management if you want to sign in again later from a different device. .. figure:: img/sign0.png :align: center :alt: Xiaozhi sign-in page .. figure:: img/sign1.png :align: center :alt: Xiaozhi sign-up form .. figure:: img/sign2.png :align: center :alt: Xiaozhi SMS verification page Create an Agent ------------------------------------------ 1. Click ``Create Agent``. 2. Enter an agent name and confirm. 3. Open ``Configure Role`` on the new agent card. .. figure:: img/web1.png :align: center :alt: Create Agent interface .. figure:: img/web2.png :align: center :alt: Configure agent parameters .. figure:: img/web3.png :align: center :alt: Add Device interface Configure the Agent Role ------------------------------------------ 1. Configure the basic role settings: * Assistant Name: Name your AI assistant * Voice Role: Select the preferred voice * Language Preference: Select the conversation language * Role Introduction: Describe the assistant personality * Language Model: Select the backend model 2. Set the role prompt. You can start with the template below and customize it later: :: I am a virtual assistant called {{assistant_name}}. I communicate exclusively in English with a natural, friendly voice. I provide helpful, accurate information and assist users with their queries while maintaining a conversational tone. I adapt my speaking style to match the user's needs and always aim to deliver clear, concise responses in fluent English. .. figure:: img/web4.png :align: center :alt: Configure the assistant role 3. Click ``Save`` to store the role configuration. .. figure:: img/web5.png :align: center :alt: Save the assistant role ------------------------------------------------------------------------------------ Firmware Upload =============== Online Flashing ------------------- You can also use an online flashing tool. The advantage of this method is that you simply open the webpage, select your device and firmware version, and it requires no configuration. Once flashing is complete, you can start using it right away. .. note:: Online flashing is supported only in Chrome or Edge browsers. .. warning:: Use a USB Type-C cable that supports data transfer. A charging-only cable may power the board but will not work for flashing. .. note:: On Windows, connect the USB Type-C data cable to the ESP32-S3 ``UART`` port on the left side of the board before clicking ``Connect``. On macOS, connect the cable to the ESP32-S3 ``USB`` port on the right side, then press and hold ``BOOT``, press ``RESET`` while still holding ``BOOT``, and enter download mode before clicking ``Connect``. The screen will turn black after the device enters download mode; this is normal. For detailed instructions on using the online flasher, see :ref:`Online Flasher `. Follow these steps: A. Open the `LAFVIN Web Flasher `_ B. Select the following options: - Device: ``AIoT Starter Kit`` - Firmware: ``Xiaozhi-Aiot`` - Version: ``Xiaozhi-Aiot`` C. Connect the development board to your computer using the correct USB Type-C port for your operating system, as described in the note above, before clicking ``Connect``. D. Click ``Connect``, then select your device in the browser pop-up window and click ``Connect`` again. E. Click ``Flash`` to start flashing. Wait for the process to complete. F. After flashing is complete, restart the device by pressing the ``RST`` or ``RESET`` button on the ESP32-S3 board. You do not need to unplug the USB cable unless the device does not respond. .. raw:: html
Local Flashing (Alternative) 1. Open the local flashing tool package from the downloaded project files. 2. Double-click ``Flash Download Tools`` and select the same options shown below. .. list-table:: :widths: 50 :header-rows: 0 * - .. figure:: img/flashtool1.png :width: 100% 3. Upload the firmware with the following settings: A. Click the ``Select File`` button and choose your downloaded firmware file in ``.bin`` format. B. In the address field, enter ``0`` or ``0x0``. C. Select the COM port that matches the ESP32-S3 board. Refer to :ref:`install_driver` if you need help finding the port. D. Use the baud rate shown in the flashing tool screenshot. If flashing fails, retry with a lower baud rate. E. Click ``START`` to begin writing the firmware. .. figure:: img/flashtool2.png :align: center :width: 80% .. figure:: img/flash_xiaozhi.png :align: center :width: 80% 4. After flashing is complete, press the ``RST`` button on the development board. 5. The board should restart and enter Wi-Fi provisioning mode. 6. Continue with :ref:`xiaozhi_conf` to connect the board to Wi-Fi and bind it in the backend. If you are using macOS and need a local flashing path, refer to :ref:`macos_upload`. .. raw:: html
------------------------------------------------------------------------------------ .. _xiaozhi_conf: Wi-Fi Configuration ---------------------- * After the firmware is flashed, press the ``RST`` or ``RESET`` button on the development board. The board will restart and enter network configuration mode. * Connect your phone to the hotspot named ``Xiaozhi-XXXX``. The configuration page should open automatically. If not, manually enter ``http://192.168.4.1`` in your browser to access the configuration interface. .. image:: img/wifi_config.png * Select your Wi-Fi network, enter the password, and click ``Save``. The device will save the settings and restart automatically. * After restarting, the board will connect to your Wi-Fi and announce a 6-digit verification code. If it does not restart within about 30 seconds, press the ``RST`` or ``RESET`` button once. Bind the Device ----------------- 1. Keep the board powered on after Wi-Fi configuration. 2. In the agent page, click ``Add Device``. 3. Enter the 6-digit verification code announced by the board. 4. Confirm the binding and wait for the board to restart. .. figure:: img/web6.png :align: center After the restart completes, say ``Hi, ESP`` to start the first conversation. .. figure:: img/main.png :align: center .. _firmware_upload: ------------------------------------------------------------------------------------ .. _alternative_backend: Alternative Backend and Privacy Options ========================================= If you do not want to register with a phone number, want to use a different LLM, or prefer to keep more control over your data flow, you can explore the self-hosted server projects listed in the `xiaozhi-esp32 Related Open Source Projects `_ section. This path usually requires you to: * deploy your own compatible backend service * modify the firmware source code so the device points to your new server * rebuild and flash the firmware again .. warning:: The LAFVIN kit documentation and the workflows in this guide are tested only with the official Xiaozhi server at ``xiaozhi.me``. We do not verify compatibility, deployment steps, privacy behavior, or long-term stability for third-party or self-hosted servers in this tutorial. .. note:: Self-hosting is an advanced workflow intended for users who are comfortable with backend deployment, ESP-IDF builds, firmware changes, and credential management.