Первый запуск: настройка Wi-Fi, активация и привязка

Центр документации XiaoZhi AI чат-бота | 小智AI.Dev

При первом включении устройство XiaoZhi последовательно проходит три шага: подключается к Wi-Fi, обращается к серверу и проверяет версию прошивки, привязывается к вашей учётной записи по коду активации. Страница написана по реальному коду прошивки v2.5.2: что устройство делает на каждом шаге, что вы увидите и что делать, если процесс застрял.

Страница описывает только поведение прошивки. Интерфейс консоли меняется от версии к версии, поэтому следуйте подсказкам самой консоли. При использовании собственного сервера процесс активации реализует этот сервер; см. Собственный сервер и документацию выбранного проекта.

Общий порядок

После включения устройство проверяет, сохранена ли хотя бы одна сеть Wi-Fi. Если нет, оно переходит в режим настройки. Если сеть сохранена, устройство пробует подключиться и возвращается в режим настройки, если за 60 секунд не подключилось.
Оказавшись в сети, устройство переходит в состояние «Активация» и запрашивает сведения о версии по адресу OTA.
Если сервер возвращает новую прошивку, устройство сначала обновляется. Если сервер возвращает код активации, устройство показывает и зачитывает этот код.
Вы вводите код в консоли, и привязка завершается. Устройство загружает настройки связи, переходит в режим ожидания и проигрывает звук успеха.

Шаг 1. Настройка Wi-Fi

Когда устройство переходит в режим настройки

Не сохранено ни одной сети Wi-Fi (первый запуск).
К сохранённой сети не удалось подключиться за 60 секунд.
Вы нажали кнопку настройки платы во время запуска. Кнопка зависит от платы. Например, bread-compact-wifi входит в режим настройки при щелчке по кнопке BOOT во время запуска; для остальных плат см. README в соответствующем каталоге main/boards/.

Настройка через точку доступа (по умолчанию)

По умолчанию прошивка использует настройку через точку доступа (menuconfig WiFi Configuration Method → Hotspot, включено по умолчанию).

Экран и голос сообщают о режиме настройки. В тексте указаны имя точки доступа и адрес страницы настройки, например Xiaozhi-XXXX и 192.168.4.1. Имя точки доступа начинается с Xiaozhi-, дальше идут два последних байта MAC-адреса устройства; ориентируйтесь на то, что показывает экран.
Подключите телефон к этой точке доступа и откройте в браузере 192.168.4.1. Точка доступа — открытая сеть без пароля, к ней можно подключить до 4 устройств, поэтому завершите настройку быстро и в надёжном месте.
Выберите свой роутер и введите его пароль. Большинство чипов поддерживает только 2,4 ГГц; ESP32-C5 поддерживает также 5 ГГц.
После сохранения устройство выходит из режима настройки и переподключается с новыми данными.

На вкладке Дополнительно страницы настройки можно задать адрес OTA, мощность передатчика Wi-Fi и режим энергосбережения Wi-Fi (показывать ли поля адреса OTA и энергосбережения, решает прошивка; в v2.5.2 показываются оба). Указанный там адрес OTA заменяет адрес по умолчанию, и устройство запрашивает сведения о версии и активации уже по нему. Вводите только серверы, которым доверяете.

Настройка через BluFi

BluFi выбирается при сборке прошивки и не может быть включён одновременно с настройкой через точку доступа. Если он включён, устройство объявляет имя Bluetooth Xiaozhi-Blufi, а клиент, например EspBlufi, отправляет данные Wi-Fi. О конфигурации см. Руководство по настройке BluFi.

Шаг 2. Проверка версии

Выйдя в сеть, прошивка отправляет запрос по адресу OTA. Адрес берётся со страницы настройки, если вы его там задали; иначе это значение параметра menuconfig Default OTA URL (CONFIG_OTA_URL). В запросе есть заголовки с идентификацией устройства: Device-Id (MAC-адрес), Client-Id (UUID устройства), Activation-Version, User-Agent и Accept-Language. Устройства, которые читают действительный серийный номер из eFuse, отправляют также Serial-Number.

В JSON-ответе могут быть такие поля:

Поле	Назначение
`firmware`	Версия и URL загрузки новой прошивки; если она есть, устройство сначала обновляется
`activation`	`message` (текст подсказки), `code` (код активации), `challenge` и `timeout_ms`
`mqtt` / `websocket`	Настройки связи для последующих диалогов; см. WebSocket и MQTT + UDP

Если поля activation нет, устройство считает, что активация не нужна, и продолжает запуск.

Шаг 3. Активация и привязка

Если в ответе есть код активации, устройство показывает на экране текст подсказки сервера, проигрывает звук-приглашение и затем зачитывает цифры кода по одной.
Войдите в официальную консоль и следуйте её указаниям: введите код и привяжите устройство к своей учётной записи.
Пока вы это делаете, устройство продолжает отправлять ответ на <OTA URL>/activate. Устройство с серийным номером в eFuse отправляет результат hmac-sha256 (значение challenge, подписанное HMAC-ключом из eFuse); остальные устройства отправляют пустой объект. Сервер отвечает 200 при успехе или 202, если привязки ещё нет (устройство ждёт 3 секунды и повторяет); при любом другом статусе устройство ждёт 10 секунд и повторяет.
За один раунд делается не больше 10 попыток. Если активация всё ещё не завершена, устройство возвращается к проверке версии и начинает новый раунд; всегда используйте код, показанный на экране последним.
После активации устройство инициализирует протокол связи по настройкам сервера (если в ответе их нет, по умолчанию используется MQTT), показывает номер версии и проигрывает звук успеха. После этого можно начинать диалог.

Устранение неполадок

Симптом	Вероятная причина	Что делать
На экране нет подсказки по настройке	Сеть Wi-Fi уже сохранена, поэтому устройство сначала пробует её и переходит к настройке только через 60 секунд; либо прошивка собрана с BluFi	Подождите 60 секунд или нажмите кнопку настройки во время запуска; для прошивки с BluFi найдите на телефоне `Xiaozhi-Blufi`
Телефон подключился к точке доступа, но страница настройки не открывается	Телефон не остался в сети точки доступа устройства	Убедитесь, что вы по-прежнему подключены к точке доступа `Xiaozhi-`, затем откройте `192.168.4.1`
После сохранения снова режим настройки	К роутеру не удалось подключиться за 60 секунд	Проверьте имя и пароль и убедитесь, что на роутере включён диапазон 2,4 ГГц
«Check for new version failed, will retry in N seconds»	Адрес OTA недоступен либо сервер вернул статус не 200	Проверьте сеть, а если меняли адрес OTA — и его. Интервал повтора начинается с 10 секунд и каждый раз удваивается, всего до 10 повторов
Застряли на экране с кодом активации	Устройство ждёт, пока в консоли завершится привязка (сервер возвращает 202)	Введите в консоли последний код, показанный на экране
Нужно сменить сеть Wi-Fi	Сохранённая сеть есть, поэтому устройство само в режим настройки не переходит	Снова войдите в режим настройки кнопкой платы; кнопка зависит от платы

Что читать дальше

Источники: файлы 78/xiaozhi-esp32 v2.5.2 — wifi_board.cc, ota.cc, application.cc и Kconfig.projbuild, а также README компонента настройки 78/esp-wifi-connect.

Поддерживаемые платы Инструкции по настройке сети