小智AIチャットボット文書センター | 小智AI.Dev
使用ガイド - XiaoZhi AI音声ロボット使用チュートリアル
初回起動：Wi-Fi 設定、アクティベーション、バインド

初回起動：Wi-Fi 設定、アクティベーション、バインド

小智デバイスを初めて起動すると、次の 3 つのステップが順に進みます。Wi-Fi に接続する、サーバーに接続してファームウェアのバージョンを確認する、アクティベーションコードでアカウントにバインドするです。このページは v2.5.2 のファームウェアの実際のコードに基づき、各ステップでデバイスが何をしているか、画面に何が表示されるか、うまくいかないときにどうするかを説明します。

このページが扱うのはファームウェアの動作だけです。コンソールの画面はバージョンによって変わるため、コンソール上の案内に従ってください。自前サーバーの場合、アクティベーションの流れはそのサーバーが実装しています。自前サーバーと、お使いのプロジェクトのドキュメントを参照してください。

全体の流れ

  1. 電源を入れると、デバイスは保存済みの Wi-Fi があるかを確認します。なければ設定モードに入ります。保存済みのネットワークがあれば接続を試み、60 秒以内に接続できなければ設定モードに戻ります。
  2. オンラインになると、デバイスは「アクティベーション」状態に入り、OTA URL にバージョン情報を問い合わせます。
  3. サーバーが新しいファームウェアを返した場合、デバイスは先にアップグレードします。アクティベーションコードを返した場合、デバイスはそのコードを画面に表示して読み上げます。
  4. コンソールにコードを入力するとバインドが完了します。デバイスは通信設定を読み込んで待機状態になり、成功音を再生します。

ステップ 1：Wi-Fi 設定

デバイスが設定モードに入る条件

  • Wi-Fi が 1 つも保存されていない（初回起動）。
  • 保存済みのネットワークに 60 秒以内に接続できなかった。
  • 起動中にボードの設定ボタンを押した。ボタンはボードによって異なります。例えば bread-compact-wifi は、起動中に BOOT ボタンをクリックすると設定に入ります。他のボードは main/boards/ 配下の該当ディレクトリの README を参照してください。

ホットスポット設定（既定）

ファームウェアは既定でホットスポット設定を使います（menuconfig の WiFi Configuration Method → Hotspot。既定で有効）。

  1. 画面と音声で設定モードを案内します。案内にはホットスポット名と設定用 URL（Xiaozhi-XXXX や 192.168.4.1 など）が含まれます。ホットスポット名は Xiaozhi- で始まり、デバイスの MAC アドレスの下位 2 バイトが続きます。画面に表示された内容に従ってください。
  2. スマートフォンをこのホットスポットに接続し、ブラウザで 192.168.4.1 を開きます。このホットスポットはパスワードのないオープンなネットワークで、同時に 4 台まで接続できます。信頼できる場所で、すばやく設定を済ませてください。
  3. ルーターを選び、パスワードを入力します。多くのチップは 2.4 GHz のみ対応で、ESP32-C5 は 5 GHz にも対応します。
  4. 保存すると、デバイスは設定モードを終了し、新しい認証情報で再接続します。

設定ページの詳細設定タブでは、OTA URL、Wi-Fi の送信電力、Wi-Fi のスリープモードを設定できます（OTA URL とスリープの欄を表示するかはファームウェアが決めます。v2.5.2 は両方を表示します）。ここで入力した OTA URL は既定値を置き換え、デバイスはそのアドレスにバージョンとアクティベーションの情報を問い合わせるようになります。信頼できるサーバーだけを入力してください。

BluFi 設定

BluFi はファームウェアのビルド時に選択するもので、ホットスポット設定と同時には有効にできません。有効にすると、デバイスは Bluetooth 名 Xiaozhi-Blufi をアドバタイズし、EspBlufi などのクライアントから Wi-Fi 情報を送ります。設定方法は BluFi 設定ガイドを参照してください。

ステップ 2：バージョン確認

オンラインになると、ファームウェアは OTA URL にリクエストを送ります。URL は、設定ページで指定していればその値、そうでなければ 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。ある場合、デバイスは先にアップグレードします
activationmessage（表示文）、code（アクティベーションコード）、challenge、timeout_ms
mqtt / websocket以後の対話に使う通信設定。WebSocketと MQTT + UDPを参照

activation フィールドがない場合、デバイスはアクティベーション不要と判断し、起動を続けます。

ステップ 3：アクティベーションとバインド

  1. レスポンスにアクティベーションコードが含まれていると、デバイスはサーバーの案内文を画面に表示し、通知音を鳴らしてから、コードの数字を 1 桁ずつ読み上げます。
  2. 公式コンソールにサインインし、案内に従ってコードを入力して、デバイスをアカウントにバインドします。
  3. その間、デバイスは <OTA URL>/activate への応答の送信を繰り返します。eFuse シリアル番号を持つデバイスは hmac-sha256 の結果（challenge を eFuse の HMAC キーで署名したもの）を送り、それ以外のデバイスは空のオブジェクトを送ります。サーバーは、成功なら 200、「まだバインドされていない」なら 202（デバイスは 3 秒待って再試行）を返します。それ以外のステータスなら、デバイスは 10 秒待って再試行します。
  4. 1 ラウンドの試行は最大 10 回です。それでもアクティベーションが完了しなければ、デバイスはバージョン確認に戻り、次のラウンドを始めます。必ず画面に最後に表示されたコードを使ってください。
  5. アクティベーションが済むと、デバイスはサーバーの設定から通信プロトコルを初期化し（レスポンスに指定がなければ既定は MQTT）、バージョン番号を表示して成功音を再生します。これで対話を始められます。

トラブルシューティング

症状考えられる原因対処
画面に設定の案内が出ないすでに Wi-Fi が保存されているため、デバイスがそのネットワークを先に試し、60 秒後にようやく設定モードに入る。または BluFi 用のファームウェアでビルドされている60 秒待つか、起動中に設定ボタンを押す。BluFi ファームウェアなら、スマートフォンで Xiaozhi-Blufi を探す
ホットスポットには接続できるが設定ページが開かないスマートフォンがデバイスのホットスポットに留まっていないXiaozhi- のホットスポットに接続したままであることを確認して、192.168.4.1 を開く
保存したのに設定モードに戻る60 秒以内にルーターに接続できなかった名前とパスワードを確認し、ルーターの 2.4 GHz が有効であることを確認する
「Check for new version failed, will retry in N seconds」OTA URL に到達できないか、サーバーが 200 以外のステータスを返したネットワークを確認する。OTA URL を変更した場合はその値も確認する。再試行の間隔は 10 秒から始まり、毎回 2 倍になり、最大 10 回まで
アクティベーションコードの画面から進まないデバイスがコンソールでのバインドの完了を待っている（サーバーが 202 を返している）画面に表示された最新のコードをコンソールに入力する
Wi-Fi を変更したい保存済みのネットワークがあるため、デバイスは自分では設定モードに入らないボードの設定ボタンで設定モードに入り直す。ボタンはボードによって異なる

関連ドキュメント

出典：78/xiaozhi-esp32 v2.5.2 の wifi_board.cc、ota.cc、application.cc、Kconfig.projbuild、および設定コンポーネント 78/esp-wifi-connect の README。

対応ボード一覧ネットワーク設定説明