自訂 Assets 指南：喚醒詞、字型、表情與聊天背景

小智韌體把喚醒詞模型、文字字型、表情圖片和聊天背景集中打包成一個 assets.bin，寫入 Flash 的 assets 分區。換掉這個檔案，就能在不改應用程式碼的情況下客製裝置的外觀和喚醒詞。本文說明 assets.bin 包含什麼、如何製作，以及如何寫入裝置。

本文對應上游 v2.5.2 與 xiaozhi-assets-generator。只有分區表含 assets 分區（分區表 v2）的開發板才支援；沒有該分區時，啟動日誌會提示 No assets partition found。

一、可以客製什麼

內容	作用	對應欄位
喚醒詞	預設 WakeNet 模型，或 ESP32-S3 上的 MultiNet 自訂命令詞	`srmodels`、`multinet`
文字字型	螢幕上聊天文字使用的 `.bin` 字型	`text_font`
表情集合	21 種情緒對應的 PNG 或 GIF 圖片	`emoji_collection`
聊天背景	淺色、深色兩套文字顏色、背景顏色或背景圖	`skin`

欄位都寫在 assets.bin 內的 index.json 中，詳見下文「五、index.json 結構」。

二、`assets` 分區

分區表 v2 為不同容量的 Flash 預留 assets 分區（類型 data，子類型 spiffs），上游 partitions/v2/README.md 給出的大小如下：

分區表	`assets` 大小
`8m.csv`	2 MB
`16m.csv`	8 MB
`16m_c3.csv`	4 MB（受可用 mmap 頁限制）
`32m.csv`	16 MB

assets.bin 不能超過分區大小。裝置啟動時會校驗 assets.bin 標頭與校驗和，校驗失敗時該分區不會被啟用。

三、製作 assets.bin

方式一：Assets 產生器（推薦）

xiaozhi-assets-generator 是一個單頁應用。它在瀏覽器本機產生 assets.bin，不依賴後端介面。操作分三步：

選擇晶片（esp32s3、esp32c3、esp32p4、esp32c6）、螢幕類型和解析度；顏色目前只支援 16 位元 RGB565。
在四個分頁中完成主題設計：喚醒詞、字型、表情、聊天背景。
確認待打包清單後點擊產生。自訂字型耗時較長，轉換結果會快取，重新產生更快。

各分頁的規則如下。

喚醒詞

預設喚醒詞（WakeNet）：ESP32-C3 / C6 只支援 WakeNet9s 模型，ESP32-S3 / P4 只支援 WakeNet9 模型。

喚醒詞	C3 / C6（WakeNet9s）	S3 / P4（WakeNet9）
Hi,樂鑫	`wn9s_hilexin`	`wn9_hilexin`
Hi,ESP	`wn9s_hiesp`	`wn9_hiesp`
你好小智	`wn9s_nihaoxiaozhi`	`wn9_nihaoxiaozhi_tts`
Hi,Jason	`wn9s_hijason_tts2`	`wn9_hijason_tts2`
小愛同學	-	`wn9_xiaoaitongxue`
嗨小歐	-	`wn9_hai1xiao3ou1_tts3`
你好小瑞	-	`wn9_ni3hao3xiao3rui4_tts3`

自訂喚醒詞（MultiNet）：產生器目前只面向 ESP32-S3。中文使用 mn6_cn 或 mn7_cn，輸入拼音，例如 ni hao xiao zhi；英文使用 mn6_en 或 mn7_en。可設定閾值（0-100）和逾時時間。

字型

預設字型為阿里巴巴普惠體，涵蓋約 7000 個常用字：font_puhui_14_1、font_puhui_16_4、font_puhui_20_4、font_puhui_30_4（命名規則為 字型名_字號_bpp）。
自訂字型支援 TTF、WOFF，字號範圍 8-80，bpp 可選 1、2、4；字元集可選 GB2312（7445 個字元）或 DeepSeek R1（7405 個字元，預設）。轉換使用 lv_font_conv，輸出命名為 font_[字型名]_[字號]_[BPP].bin。

表情集合

一套表情共 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（深色），也可以改顏色或使用靜態圖片。圖片會自動適配螢幕解析度，格式通常為 RGB565 點陣圖，帶 64 位元組標頭，內容為 lv_image_dsc_t。

方式二：命令列 `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/

三個參數都可以省略，只處理需要的部分。表情目錄支援 .png 和 .gif。腳本會重建 build/ 目錄，並產生：

build/assets/：全部資源檔和 index.json
build/assets.bin：最終的 SPIFFS 資源檔
build/config.json、build/output/：建置設定與中間檔案

四、寫入裝置

三種方式任選其一：

1. 編譯時寫入

在 idf.py menuconfig 的「Xiaozhi Assistant」中，把 Flash Assets 選為 Flash Custom Assets，並設定 Custom Assets File。該值可以是本機檔案，也可以是 http:// 或 https:// 網址。後續 idf.py flash 會把它寫入 assets 分區。

選項說明：

Flash Default Assets（預設）：依目前 sdkconfig 自動打包預設資源。
Flash Emote Assets：僅在啟用 Emote 訊息樣式時可選，產生並寫入表情資源。
Flash Custom Assets：使用你提供的 assets.bin。
Do not flash assets：不寫入 assets 分區。

CUSTOM_ASSETS_FILE 為相對路徑時，main/CMakeLists.txt 按 main/ 目錄解析，與 Kconfig 說明文字中的「專案目錄」不一致。建議使用絕對路徑，避免找不到檔案而編譯失敗。

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 讓裝置自行下載

先把 assets.bin 放到裝置可以存取的 HTTP(S) 網址，再呼叫僅限使用者的 MCP 工具 self.assets.set_download_url，參數為 url。裝置會把網址儲存下來，下次啟動聯網後（先於韌體版本檢查）取出網址並清除，顯示下載進度、擦寫 assets 分區並套用新資源。網址只使用一次，下載失敗需要重新設定；檔案必須不大於分區，否則下載會失敗。工具用法見 MCP 物聯網控制用法。

五、`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 的索引；版本更高時會提示升級韌體。

六、只改喚醒詞：編譯選項

只想換喚醒詞時，也可以不製作 assets.bin，直接在 menuconfig 的「Xiaozhi Assistant」中設定 Wake Word Implementation Type：

選項	說明
`Wakenet model with AFE`	預設（ESP32-S3 / P4 / S31 且有 PSRAM），有條件時支援回音消除（AEC）
`Wakenet model without AFE`	面向 ESP32-C3 / C5 / C6，以及帶 PSRAM 的 ESP32
`Multinet model (Custom Wake Word)`	自訂喚醒詞，要求 ESP32-S3 / P4 / S31 且有 PSRAM
`Disabled`	關閉喚醒詞

選擇自訂喚醒詞後，還可以設定：

CUSTOM_WAKE_WORD：中文使用拼音，詞間用空格分隔，預設 xiao tu dou
CUSTOM_WAKE_WORD_DISPLAY：識別後發給伺服器的問候語，預設 小土豆
CUSTOM_WAKE_WORD_THRESHOLD：1-99，數值越小越靈敏，預設 20

七、常見問題

現象或日誌	可能原因	處理
`No assets partition found` / `Assets partition is disabled`	分區表沒有 `assets` 分區	改用 v2 分區表，或選擇支援的開發板
校驗和不符（`checksum ... does not match`）	`assets.bin` 損壞或寫入偏移不對	重新產生，並核對分區表中的偏移
`The assets version N is not supported, please upgrade the firmware`	索引版本高於韌體支援的版本	升級韌體，或用相符版本的產生器重新製作
`Assets file size ... is larger than partition size`	檔案超過 `assets` 分區大小	減少表情數量、降低字號或 bpp，或換用更大的分區表
字型不生效（`Ignoring invalid text font asset`）	字型檔無效或與顯示不相容	重新轉換字型，檢查字號與 bpp

來源

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

自定義開發板指南 BluFi 配網指南