カスタム Assets ガイド：ウェイクワード、フォント、絵文字、チャット背景

小智ファームウェアは、ウェイクワードモデル、テキストフォント、絵文字の画像、チャット背景を 1 つの assets.bin にまとめます。このファイルは Flash の assets パーティションに置かれます。このファイルを差し替えれば、アプリケーションのコードに触れずに、デバイスの見た目とウェイクワードを変えられます。このガイドでは、assets.bin の中身、作り方、デバイスへの書き込み方を説明します。

I. カスタマイズできるもの

これらはすべて assets.bin 内の index.json で記述されます。「V. index.json の構造」を参照してください。

II. assets パーティション

パーティションテーブル v2 は、Flash のサイズごとに assets パーティション（type は data、subtype は spiffs）を確保しています。上流の partitions/v2/README.md にあるサイズは次のとおりです。

assets.bin はパーティションを超えてはいけません。起動時にデバイスがヘッダーとチェックサムを検証し、検証に失敗するとそのパーティションは有効になりません。

III. assets.bin を作成する

方法 1：Assets Generator（推奨）

xiaozhi-assets-generator はシングルページアプリです。ブラウザ上でローカルに assets.bin を作成し、バックエンドは不要です。手順は 3 つです。

1. チップ（esp32s3、esp32c3、esp32p4、esp32c6）、画面の種類、解像度を選びます。色は 16 ビットの RGB565 に限られます。
2. ウェイクワード、フォント、絵文字、チャット背景の 4 つのタブでテーマを設計します。
3. パッケージ化する項目の一覧を確認して、生成をクリックします。カスタムフォントは時間がかかります。変換した結果はキャッシュされるので、再生成は速くなります。

各タブのルール：

ウェイクワード

• プリセットのウェイクワード（WakeNet）：ESP32-C3 / C6 は WakeNet9s モデルのみ、ESP32-S3 / P4 は WakeNet9 モデルのみに対応します。

  ウェイクワード	C3 / C6 (WakeNet9s)	S3 / P4 (WakeNet9)
  Hi, Lexin	wn9s_hilexin	wn9_hilexin
  Hi, ESP	wn9s_hiesp	wn9_hiesp
  Ni hao Xiaozhi	wn9s_nihaoxiaozhi	wn9_nihaoxiaozhi_tts
  Hi, Jason	wn9s_hijason_tts2	wn9_hijason_tts2
  Xiaoai Tongxue	-	wn9_xiaoaitongxue
  Hai Xiaoou	-	wn9_hai1xiao3ou1_tts3
  Ni hao Xiaorui	-	wn9_ni3hao3xiao3rui4_tts3

• カスタムウェイクワード（MultiNet）：ジェネレーターが現在対象とするのは ESP32-S3 のみです。中国語には mn6_cn か mn7_cn を使い、ni hao xiao zhi のようなピンインで入力します。英語には mn6_en か mn7_en を使います。しきい値（0〜100）とタイムアウトを設定できます。

フォント

• プリセットのフォントは Alibaba PuHuiTi で、約 7000 の常用漢字をカバーします：font_puhui_14_1、font_puhui_16_4、font_puhui_20_4、font_puhui_30_4（命名規則：name_size_bpp）。
• カスタムフォントは TTF と WOFF を受け付けます。サイズは 8〜80、bpp は 1、2、4 です。文字セットは GB2312（7445 文字）か DeepSeek R1（7405 文字、既定）です。変換には lv_font_conv を使い、出力ファイルの名前は font_[name]_[size]_[BPP].bin になります。

絵文字セット

1 セットは 21 枚の画像です。neutral が既定で、ほかは happy、laughing、funny、sad、angry、crying、loving、embarrassed、surprised、shocked、thinking、winking、cool、relaxed、delicious、kissy、confident、sleepy、silly、confused です。

• プリセット：Twemoji の 32x32 または 64x64 の PNG。
• カスタム：共通の幅と高さ（画面より大きくないこと）、GIF アニメーションまたは透過 PNG。neutral は必須で、足りない感情は neutral で代替されます。

チャット背景

ライトモードとダークモードは別々に設定します。既定値は #ffffff（ライト）と #121212（ダーク）です。色を変えることも、静止画像を使うこともできます。画像は画面の解像度に合わせて調整されます。形式は通常、lv_image_dsc_t を収めた 64 バイトのヘッダー付きの RGB565 ビットマップです。

方法 2：コマンドラインの scripts/spiffs_assets

ファームウェアのリポジトリには scripts/spiffs_assets/build.py があり、ウェイクワードモデル、フォント、絵文字フォルダーを assets.bin にまとめます（Python 3.6 以上が必要）。

cd scripts/spiffs_assets

./build.py \
    --wakenet_model ../../managed_components/espressif__esp-sr/model/wakenet_model/wn9_nihaoxiaozhi_tts \
    --text_font ../../components/noto-fonts/cbin/font_noto_sans_common_20_4.bin \
    --emoji_collection ../../components/noto-fonts/png/noto-color-emoji_64/

3 つの引数はいずれも省略可能で、必要なものだけをまとめられます。絵文字フォルダーは .png と .gif を受け付けます。スクリプトは build/ フォルダーを作り直し、次を生成します。

• build/assets/：すべてのリソースファイルと index.json
• build/assets.bin：最終的な SPIFFS リソースファイル
• build/config.json、build/output/：ビルド設定と中間ファイル

IV. デバイスに書き込む

次の 3 つの方法から 1 つを選びます。

1. ビルド時に書き込む

idf.py menuconfig で「Xiaozhi Assistant」を開き、Flash Assets を Flash Custom Assets にして、Custom Assets File を入力します。値にはローカルのファイル、または http:// か https:// の URL を指定できます。次の idf.py flash で assets パーティションに書き込まれます。

オプション：

• Flash Default Assets（既定）：現在の sdkconfig の既定のリソースをまとめます。
• Flash Emote Assets：Emote メッセージスタイルが有効なときだけ選べます。emote のリソースをビルドして書き込みます。
• Flash Custom Assets：指定した assets.bin を使います。
• Do not flash assets：assets パーティションには手を触れません。

2. パーティションを直接書き込む

パーティションテーブルの assets 行のオフセットを調べます（例：partitions/v2/16m.csv では 0x800000 と 8 MB）。そして次を実行します。

# Replace the offset with the assets row of your partition table
esptool.py -b 460800 write_flash -z 0x800000 assets.bin

3. MCP 経由でデバイスにダウンロードさせる

デバイスから到達できる HTTP(S) アドレスに assets.bin を置き、ユーザー専用の MCP ツール self.assets.set_download_url を url 引数付きで呼び出します。デバイスはそのアドレスを保存します。次にネットワークに接続して起動したとき（ファームウェアのバージョン確認の前）に、そのアドレスを取り出して消去し、ダウンロードの進行状況を表示し、assets パーティションを消去して書き込み、新しいリソースを適用します。アドレスは 1 回限りの使用なので、ダウンロードに失敗したときは設定し直してください。ファイルはパーティションより大きくてはいけません。ツールの使い方は MCP IoT 制御の使い方を参照してください。

V. index.json の構造

assets.bin 内の index.json は、各リソースを記述します。次はジェネレーターのドキュメントにある例です（絵文字は一部省略）。

{
    "version": 1,
    "chip_model": "esp32s3",
    "display_config": {
        "width": 320,
        "height": 240,
        "monochrome": false,
        "color": "RGB565"
    },
    "srmodels": "srmodels.bin",
    "text_font": "font_puhui_common_30_4.bin",
    "skin": {
        "light": {
            "text_color": "#000000",
            "background_color": "#FFFFFF",
            "background_image": "background_light.raw"
        },
        "dark": {
            "text_color": "#FFFFFF",
            "background_color": "#121212",
            "background_image": "background_dark.raw"
        }
    },
    "emoji_collection": [
        { "name": "sleepy", "file": "sleepy.png" }
    ],
    "multinet": {
        "model": "mn6_cn",
        "command": "ni hao xiao zhi",
        "threshold": 20,
        "duration": 3000
    }
}

ファームウェアは、version が 1 以下のインデックスを受け付けます。それより高いバージョンだと、ファームウェアのアップグレードを促すメッセージが表示されます。

VI. ウェイクワードだけを変える：ビルドオプション

ウェイクワードだけを変えるなら、assets.bin は不要です。menuconfig の「Xiaozhi Assistant」にある Wake Word Implementation Type を設定します。

カスタムウェイクワードを選ぶと、次も設定できます。

• CUSTOM_WAKE_WORD：中国語はピンインで、単語をスペースで区切ります。既定値は xiao tu dou
• CUSTOM_WAKE_WORD_DISPLAY：検出後にサーバーへ送る挨拶。既定値は 小土豆
• CUSTOM_WAKE_WORD_THRESHOLD：1〜99。小さいほど感度が高い。既定値は 20

VII. トラブルシューティング

関連ドキュメント

• カスタムボードガイド：ボードの追加とパーティションテーブルの選び方
• Glyph Push 拡張：フォントにない文字を必要に応じて追加する
• 対応ボード一覧：各ボードのファームウェアバリアント
• ファームウェアのダウンロード：ファームウェア書き込みの基本

出典

• 78/xiaozhi-esp32 v2.5.2：scripts/spiffs_assets/README.md、main/assets.cc、main/Kconfig.projbuild、main/CMakeLists.txt、main/mcp_server.cc、partitions/v2/README.md
• 78/xiaozhi-assets-generator：README