Руководство по пользовательским Assets: слово пробуждения, шрифты, эмодзи и фон чата

Прошивка XiaoZhi упаковывает модель слова пробуждения, текстовый шрифт, изображения эмодзи и фон чата в один файл assets.bin, который находится в разделе assets флеш-памяти. Замените этот файл — и вы измените внешний вид и слово пробуждения устройства, не трогая код приложения. В руководстве объясняется, что входит в assets.bin, как его собрать и как записать на устройство.

I. Что можно настроить

Всё это описывается файлом index.json внутри assets.bin; см. «V. Структура index.json».

II. Раздел assets

Таблица разделов v2 резервирует раздел assets (тип data, подтип spiffs) для каждого размера флеш-памяти. Размеры из partitions/v2/README.md upstream:

assets.bin не должен превышать размер раздела. При загрузке устройство проверяет заголовок и контрольную сумму; если проверка не проходит, раздел не включается.

III. Сборка assets.bin

Способ 1: Assets Generator (рекомендуется)

xiaozhi-assets-generator — одностраничное приложение. Оно собирает assets.bin локально в браузере, бэкенд не нужен. Шагов три:

1. Выберите чип (esp32s3, esp32c3, esp32p4, esp32c6), тип экрана и разрешение. Цвет ограничен 16-битным RGB565.
2. Оформите тему на четырёх вкладках: слово пробуждения, шрифт, эмодзи и фон чата.
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.

Набор эмодзи

В наборе 21 изображение. neutral — по умолчанию; остальные: happy, laughing, funny, sad, angry, crying, loving, embarrassed, surprised, shocked, thinking, winking, cool, relaxed, delicious, kissy, confident, sleepy, silly, confused.

• Предустановленные: Twemoji, PNG 32x32 или 64x64.
• Пользовательские: одинаковые ширина и высота (не больше экрана), GIF-анимация или PNG с прозрачностью. neutral обязателен; любая отсутствующая эмоция заменяется на neutral.

Фон чата

Светлый и тёмный режимы настраиваются отдельно. Значения по умолчанию — #ffffff (светлый) и #121212 (тёмный). Можно изменить цвета или использовать статичное изображение. Изображения подгоняются под разрешение экрана; формат обычно — растр RGB565 с 64-байтовым заголовком, содержащим lv_image_dsc_t.

Способ 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/

Все три аргумента необязательны, поэтому можно упаковать только то, что нужно. Папка с эмодзи принимает .png и .gif. Скрипт пересоздаёт папку build/ и выдаёт:

• build/assets/: все файлы ресурсов и index.json
• build/assets.bin: итоговый файл ресурсов SPIFFS
• build/config.json, build/output/: конфигурация сборки и промежуточные файлы

IV. Запись на устройство

Выберите один из трёх способов.

1. Прошить при сборке

В idf.py menuconfig откройте «Xiaozhi Assistant», установите Flash Assets в Flash Custom Assets и заполните Custom Assets File. Значением может быть локальный файл либо URL с http:// или https://. Следующий 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 в вашей таблице разделов, например 0x800000 и 8 МБ в partitions/v2/16m.csv, затем выполните:

# 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 для управления IoT.

V. Структура index.json

index.json внутри assets.bin описывает каждый ресурс. Это пример из документации генератора (часть эмодзи опущена):

{
    "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 не нужен. Задайте Wake Word Implementation Type в разделе «Xiaozhi Assistant» menuconfig:

При выбранном пользовательском слове пробуждения можно задать также:

• 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