Skip to Content
Add a character

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" } }
FieldRequiredRules
idyesLowercase [a-z0-9_], at most 13 characters (stored in NVS as c_<id>). Unique; never rename it later.
nameyesDisplay name. Users can say it to switch.
voiceyesA Gemini Live prebuilt voice: Leda, Aoede, Kore, Zephyr, Puck, Charon, Fenrir, Orus, Achird…
personayesWho the character is, how it addresses itself and the user. A short paragraph; common_rules is appended automatically.
look.shapeyescloud, corn, avocado, mochi or robot
look.body/accent/ink/cheekrecommended#RRGGBB. The screen background is dark (#15131F), so check contrast.
kind, taglinerecommendedShort description and the line shown when choosing the character
python3 firmware/scripts/validate_data.py

2. 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.sh

3. 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.local

Rotate 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.