Getting started
Bắp runs on the Seeed SenseCAP Watcher. You build the firmware on a Linux computer with Docker, flash it once over USB, and from then on update it over Wi-Fi.
What you need
- Seeed SenseCAP Watcher (W1-A, W1-B or the “for XiaoZhi” edition): ESP32-S3, 32 MB flash, 8 MB PSRAM, 1.45” round 412×412 touch screen, scroll wheel with a button, camera with a Himax HX6538 AI chip, microphone and speaker.
- A USB-C data cable. The Watcher’s CH342 dual serial chip shows up as
/dev/serial/by-id/usb-1a86_USB_Dual_Serial_...-if02(interface 02 is the ESP32-S3). - A Linux computer with Docker and uv (used to run
esptool). - A Gemini API key from Google AI Studio .
Back up the stock firmware
Do this once, before the first flash. The dump lets you go back to the original firmware at any time.
mkdir -p backup
uv run --with esptool esptool --chip esp32s3 --port /dev/serial/by-id/usb-1a86_USB_Dual_Serial_*-if02 \
--baud 921600 read-flash 0x0 0x2000000 backup/watcher-w1a-esp32s3-full-32MB.bin
( cd backup && sha256sum watcher-w1a-esp32s3-full-32MB.bin > watcher-w1a-esp32s3-full-32MB.bin.sha256 )The dump contains the device’s private keys. Never commit or share the backup/ folder.
Get the upstream source and apply the patch
Bắp is a small patch plus its own modules on top of a pinned xiaozhi-esp32 commit.
firmware/scripts/apply_patch.sh # clones xiaozhi-esp32 into vendor/ and applies firmware/patches/xiaozhi-esp32.patchBuild
mkdir -p secrets && chmod 700 secrets
printf '%s' 'YOUR_GEMINI_API_KEY' > secrets/GEMINI_API_KEY && chmod 600 secrets/GEMINI_API_KEY
firmware/build.sh # firmware, in the espressif/idf:release-v6.1 Docker image
firmware/build_assets.sh # fonts, character faces and the wake word modelOptional variables for build.sh: GEMINI_MODEL, GEMINI_VOICE, WAKE_WORD (default
wn9_hilili_tts, “Hi Lili”) and LANG_CODE (default vi-VN).
You can leave the key empty at build time (create an empty secrets/GEMINI_API_KEY) and enter it
later in the web settings. CI builds never contain a key.
Free key plus paid fallback (optional). Put a key from a project without billing in
secrets/GEMINI_API_KEY, and a key from a project with billing in
secrets/GEMINI_API_KEY_PAID. The device always tries the free key first and only uses the paid
key when the free one is rejected. After a rejection the free key is retried after 1, 2, 4, 8 and
at most 15 minutes. Both keys can be changed in the web settings, which also show how many
sessions each key has served since boot.
Flash
firmware/flash.sh # first time: bootloader, partition table, otadata, app, assets
firmware/flash_app.sh # later: the app only (fast)
firmware/flash_assets.sh # the assets partition only
firmware/ota.sh bap-xxxx.local # update over Wi-Fi, no cableThe scripts find the Watcher on USB by themselves. With several Watchers connected, pick one with
PORT=/dev/serial/by-id/... firmware/flash.sh.
Connect to Wi-Fi
- On first boot the device opens a Wi-Fi hotspot named
Bap-XXXX. Join it with your phone; the setup page opens by itself (or browse tohttp://192.168.4.1). Pick your home network and enter its password. - Once online, open
http://bap-xxxx.local(or the IP shown on screen) from a computer on the same network.xxxxis the last four hex digits of the device’s MAC address, so every device has its own name. - Enter the Gemini API key if you did not build it in, then choose your city and a character.
Say hello
Say the wake word “Hi Lili”, press the wheel, or double-tap the screen. The face switches to listening; just talk. The session closes by itself after 30 seconds of silence.
Go back to the stock firmware
firmware/restore_stock.shThe script checks the SHA-256 of backup/watcher-w1a-esp32s3-full-32MB.bin and writes the whole
32 MB back from address 0x0. Without your own dump you can reinstall the official SenseCraft
firmware with Seeed’s tools: Bắp never writes the nvsfactory partition (0x9000), so the device
keys are still there.