Skip to main content

Modding & Customization

For owners and builders who want to go beyond the stock behaviour: custom sounds, custom animations, enclosure remixes, and repurposing the Kamoji hardware platform for other projects.

Custom sounds​

Sound effects normally stream from .wav files stored on Kamoji's internal LittleFS storage via kamoji_wav_player. Critical sounds — like the boot chime — can also be baked directly into the firmware itself, so they play even if the stored file is missing:

  1. Drop your .wav file(s) into scripts/audio/. Starting from an .mp3 instead? Run ./convert_mp3_to_wav.sh <file.mp3> first to convert it to a 16-bit, 16kHz mono WAV.
  2. Run ./convert_wav_to_headers.sh to batch-convert everything in that folder into matching .h header files.
  3. #include the generated header in your ESPHome YAML and reference it by name from kamoji_wav_player.

Custom animations​

Eye and display animations normally load as GIF files from LittleFS, so they can be swapped out over OTA without reflashing. Critical animations — the boot logo, sleeping animation — are additionally baked into the firmware as a fallback, in case the stored file is corrupted or missing:

  1. Drop your .gif file(s) into scripts/gifs/.
  2. Run ./convert_all_gifs.sh to generate a matching .h header for each one inside generated_gifs/.
  3. #include the generated header in your ESPHome YAML and reference it from kamoji_gif_player.

To make a GIF smaller without changing how it looks, see Optimizing GIFs.

note

kamoji_gif_player and LVGL share the same display hardware but can't render to it at the same time — LVGL is paused while a GIF plays and resumed once it finishes. See Firmware Architecture for more on this trade-off.

Controlling Kamoji over Bluetooth​

The Kamoji app's Bluetooth commands are open to your own code too: read the device's info and settings, switch modes, play stored animations and sounds, or show your own photo or GIF on its screen. See Bluetooth Protocol for the commands and a ready-to-run Python script.

Repurposing the hardware​

Because Kamoji is built on ESPHome, the same board can run a very different device profile by swapping the top-level YAML configuration. See Firmware Architecture for the component building blocks, or start from ESPHome Hello World for the smallest config that just gets the display working.

You can also leave ESPHome behind entirely and run a different application on the same hardware. Two guides here take that route, both building xiaozhi-esp32 firmware with a new Kamoji board definition and the microphone fix upstream is missing: XiaoZhi voice assistant uses the upstream project and its own server, and VietBot voice assistant uses a Vietnamese-hosted fork of it.

Community projects​

See Community projects for a growing list of projects the community has built on Kamoji's hardware, like the Kamoji Claw Meter Claude Code usage dashboard.