Add a character
A new character that reuses one of the existing body shapes needs no C++ changes: only an entry
in firmware/data/assistant.json.
1. Add the entry
{
"id": "na",
"name": "Na",
"kind": "a green custard apple",
"voice": "Zephyr",
"tagline": "Curious, asks a lot, loves exploring",
"persona": "You are Na, a curious little custard apple... You call yourself \"Na\" and the user \"bạn\".",
"look": {
"shape": "mochi",
"body": "#A8D88A",
"accent": "#6FA556",
"ink": "#2F4022",
"cheek": "#F5A77B"
}
}| Field | Required | Rules |
|---|---|---|
id | yes | Lowercase [a-z0-9_], at most 13 characters (stored in NVS as c_<id>). Unique; never rename it later. |
name | yes | Display name. Users can say it to switch. |
voice | yes | A Gemini Live prebuilt voice: Leda, Aoede, Kore, Zephyr, Puck, Charon, Fenrir, Orus, Achird… |
persona | yes | Who the character is, how it addresses itself and the user. A short paragraph; common_rules is appended automatically. |
look.shape | yes | cloud, corn, avocado, mochi or robot |
look.body/accent/ink/cheek | recommended | #RRGGBB. The screen background is dark (#15131F), so check contrast. |
kind, tagline | recommended | Short description and the line shown when choosing the character |
python3 firmware/scripts/validate_data.py2. Web previews (optional)
The device draws faces natively. The web settings show GIF previews generated by
firmware/assets/make_faces.py; add your character to its CHARACTERS table, then:
uv run --with pillow python firmware/assets/make_faces.py firmware/assets/faces --only na
firmware/build_assets.sh && firmware/flash_assets.sh3. A new body shape (only if needed)
Add a branch to BuildBody() in firmware/src/assistant/assistant_face.cc using the Shape(),
Arc() and Hex() helpers in the 320×320 design space, add the name to KNOWN_SHAPES in
validate_data.py, and a matching drawer in make_faces.py. Check all 23 expressions; the
/screen.jpg endpoint gives you a screenshot.
4. Try it
firmware/build.sh && firmware/ota.sh bap-xxxx.localRotate the wheel, or say “let me talk to Na”.
Persona tips
- Fix how the character addresses itself and the user.
- Describe tone in a few words; long lists of catchphrases get overused.
- Everything is spoken: no emoji, no formatting.
- Keep it under about 1,500 bytes; it is sent with every session.